TFS2017

2017年7月30日 (日)

TFS/VSTSのビルドタスク作成:拡張機能のアンインストール/おまけ情報

「TFS/VSTSのビルドタスク作成:拡張機能インストーラーの作成/展開」の続きです。

 通常、機能を変更した場合はバージョン番号を変更して再インストールすればOKですが、お試しで動かしてみた後など、クリーンな状態にしたいときは拡張機能をアンインストールする必要があります。ストアアイコンから「拡張機能の管理」を選択し、管理画面の一覧で3点リーダーメニューから「アンインストール」を選択します。
015

 アンインストールの理由を選択し(ここでは「この拡張機能のビルドを支援し、テストのみを行った」でよいかと)、「アンインストールの続行」をクリックします。
016

 インストール時と同様、「ローカルの拡張機能の参照」-「拡張機能の管理」で管理画面に移動し、拡張機能一覧の3点リーダーメニューから「削除」を選択します。
017
 確認メッセージが表示されるので、「OK」をクリックします。
018


☆おまけ
〇vss-extension.jsonやtask.jsonの設定内容がおかしいと、インストール時にエラーが発生し、その後一覧には表示されないが、再度インストールしようとすると「Already installed」と怒られることがあります。名前やバージョン番号を変えればインストールはできますが、TFSのDB(SQL Server)から管理情報を削除することでも対応可能です。
 拡張機能のインストール情報は、Tfs_ConfigurationデータベースにあるGallery.tbl_Extensionテーブルに格納されています。このテーブルに対して、「delete from [Tfs_Configuration].[Gallery].[tbl_Extension] where ExtensionName='[vss-extension.jsonの"id"に設定した名称]'」を実行して情報を削除すれば、再度インストールができます。
 ※Undocumentで、かつサポートに確認した内容ではありませんので、自己責任で。

〇拡張機能を同一バージョン番号で再インストールしたときは、エージェントに展開されている拡張機能(タスク)のフォルダを削除したほうがよさそうです。
 (エージョエントにキャッシュされた状態なので、サーバから再インストールした内容がダウンロードされないことがあります)
 タスクの展開先は「(エージェントのインストールフォルダ)\_work\_tasks」フォルダに、task.jsonのnameに指定したタスク名称で始まるサブフォルダになります。


visualstudio.comのドキュメント「Add a Build Task」にはVSS.SDK.jsのインストールが記載されてなくて、しかもnpmのvss-sdkパッケージは古くてvss-web-extensionパッケージにしないといけないとか、実はGitHubに別ライブラリがあって、しかもサンプル/ドキュメントが充実してるとか、task.jsonとvss-extension.jsonとで整合性を合わせないといけない項目が明記されていないとか、TFSのビルドエージェントで使われるNodeのバージョン問題(固定化されるので最新化できない)とかで結構引っ掛かったので、これでいろいろ整理できてよかったです。
(本当に作りたいのはこれから・・・)

TFS/VSTSのビルドタスク作成:拡張機能インストーラーの作成/展開

「TFS/VSTSのビルドタスク作成:前準備/各種ファイルの作成」の続きです。

〇sampletaskフォルダでtscコマンドを実行し、.jsファイルを作成します。

〇(base folder)で「& "$env:APPDATA\npm\tfx.cmd" extension create --manifest-globs vss-extension.json」でインストーラーファイルを作成します。tfx-cliをインストールしたときに、「tfx.cmd」がnpmのインストール先に展開されますが、npmのパスが環境変数PATHに設定されているのであれば、"$env:APPDATA\npm\"は不要です。作成されたインストーラーファイル(.vsix)をTFSサーバにコピーしておきます。

〇TFSのサイトに拡張機能をインストールします。
 TFSのサイトで、右上にあるストアアイコンから「拡張機能の管理」を選択します。
001

 拡張機能の管理画面で「ローカルの拡張機能参照」をクリックします。
002

 拡張機能の管理画面で、一番下にある「拡張機能の管理」をクリックします。
003

 画面の右上にある「拡張機能をアップロードする」をクリックします。
004

 ファイルの選択画面が表示されるので、先ほどコピーしておいた.vsixファイルを指定し、「アップロード」をクリックします。
005
006

 アップロードが完了すると、管理画面に拡張機能が追加表示されます。
007

 アップロードした拡張機能の3点リーダーメニューから「インストール」をクリックします。
008

 インストール先のチームプロジェクトコレクションを選択し、「確認」をクリックします。
009
 インストールが完了したら、「閉じる」をクリックします。
010

〇タスクの追加
 ビルド定義にタスクを追加してみます。「タスクの追加」一覧に作成したタスクが出てので、「追加」をクリックします。
011

〇タスク設定/実行
 「Sample Path」は必須項目にしていますので、右側の3点リーダーをクリックしてソースフォルダを選択します。
 「Sample String」には何かしらの文字列を入力しておきます。入力した内容がタスク定義名称(「Echo」の後ろ)とビルドログに出力されます。
012
013

 ビルド定義を保存し実行すると、「Sample String」に設定した文字列がコンソールに出力されます。
014

後は、自分がタスクとして作成したい処理をtaskmod.tsに実装することと、task.jsonでビルド定義で指定する項目を指定すればOKです。
次は補足みたいなもので、拡張機能のアンインストールとおまけ情報についてです。

TFS/VSTSのビルドタスク作成:前準備/各種ファイルの作成

「TFS/VSTSのビルドタスク作成:全体概要」の続きです。各種ライブラリの準備や構成ファイルの作成を行っていきます。

〇フォルダ/ファイル構成
 先ほどの「Add a build task」にサンプル構成がありますが、構成を最小限にしています。
 (base folder)
  ├─sampletask
  │  ├─node_modules
  │ index.ts
  │ taskmod.ts
  │ task.json
  │
  ├─images
  │
  licence-terms.md
  overview.md
  vss-extension.json

    sampletask:タスク単位で使用するファイルを格納するフォルダ
    images:拡張機能のイメージデータを格納するフォルダ

    index.ts/taskmod.ts:処理を実装するTypeScriptソースコード
    task.json:ビルドタスク情報を格納するjsonファイル
    license-terms.md:配布ライセンス
    overview.md:作成したタスクの説明文
    vss-extension.json:Visual Studio拡張機能インストーラー(.vsix)作成時の情報を格納するjsonファイル

〇TFS/VSTSの拡張機能を作成(というか、最終的には公開)するには、「TFS Cross Platform Command Line Interface(tfx-cli)」(https://github.com/Microsoft/tfs-cli)が必要です。 
 インストールは「npm install -g tfx-cli」を実行します。

〇sampletaskフォルダで「npm init」を実行し、package.jsonを作成します。
 ※nameやversionなど、package.jsonの初期値をいろいろ聞かれますが、author(作成者)以外はとりあえずデフォルト(Enterキーのみ)で問題ありません。

〇ビルドタスク用のライブラリである「vsts-task-lib」(https://github.com/Microsoft/vsts-task-lib)をインストールします。
 通常、タスク単位でインストールしますので、sampletaskフォルダで「npm install vsts-task-lib --save」「npm install @types/node --save-dev」「npm install @types/q --save-dev」を実行します。
 →sampletask\node_modules配下にvsts-task-libが作成されます。

〇後で作成するindex.tsのサンプルではTypeScriptでasync/awaitを使用しているのですが、現時点でのビルドエージェント環境で使用されるNodeのバージョンは6.10.3で変更できないため、そのままでは実行できません。(Node.jsがasync/awaitをデフォルトでサポートするのは7.6以降)
 TypeScriptはほとんど触ったことがないのですが、今後はasync/awaitが主流になりそうですので、今回はbabel(https://babeljs.io/)を使って動かすことにします。sampletaskフォルダで「npm install --save-dev babel-cli babel-preset-env」を実行してインストールします。その後、package.jsonに以下の内容を追加します。
 "babel": {
    "presets": ["env"]
  }

〇sampletaskフォルダで「tsc --init」を実行して、TypeScriptコンパイラの設定ファイルであるtsconfig.jsonを作成します。
 また、デフォルトのままだとコンパイル時にTypings関連でエラーになるので、tsconfig.jsonの"compilerOptions.lib"のコメントを外し、"es5", "dom", "es.2015.promise"を追加します。

〇task.jsonを作成します。サンプルは「Step by Step: Node Task with Typescript API」の「Sample Files」にあるリンク(「located here in this gist」のところです)の「sample_task.json」にあります。
 最低限変更する項目は以下になります。
 ・id
  タスクを認識するためのID(GUID)をセットします。GUIDはPowerShellで「[guid]::NewGuid()」を実行して生成します。
 ・name
  タスクの内部名称になります。後で出てくる'vss-extension.json'の「files.path」に一致していないといけません。
 ・frendlyName
  ビルド定義のタスク一覧で表示されるときの上側に表示される名称になります。
 ・description
  ビルド定義のタスク一覧で表示されるときの下側に表示される説明文になります。
 ・author
  作成者の名前を指定します。

〇vss-extension.jsonを作成します。サンプルは「Add a build task」の「Step 2: Create the extension manifest file」にあります。
 ここで変更する項目は以下になります。
 ・id
  変更しなくても動作しますが、ここに指定した内容がVisual Studio拡張機能インストーラー(.vsix)のファイル名に使用されますので、それなりの内容に変更しておきます。また、TFS/VSTSで拡張機能を管理する際の名称にもなります。
 ・name
  拡張機能の管理画面で表示される名称になります。
 ・publisher
  作成者の名前を指定します。なお、この内容も.vsixのファイル名に使用されます。
 ・decription
  拡張機能の管理画面で表示される説明文になります。
 ・icons.default
  タスクアイコンのファイル(PNGファイル)を指定します。自分は絵心がないので、Microsoftがクラウド関連の資料作成用として公開している「Microsoft Azure, Cloud and Enterprise Symbol / Icon Set - Visio stencil, PowerPoint, PNG, SVG」(https://www.microsoft.com/en-us/download/details.aspx?id=41937)にある「Azure Automation.png」を使ってみました。なお、Visual Studio拡張機能インストーラーの制限で、ファイル名にスペースが使えないので修正しておきます。
 ・files.path/contributions.properties.name
  task.jsonを格納したフォルダを指定します。
 ・content.details.path(追加)
  タスクの詳細情報を記述するoverview.mdファイルを指定します
 ・content.details.license(追加)
  ライセンス情報を記述するlicense-terms.mdファイルを指定します

 上記項目が画面上のどこになるのかをまとめてみました。(画面イメージにイタリック調で項目をマッピングしています)
019
020
021

〇index.ts/taskmod.tsを作成します。サンプルは「Step by Step: Node Task with Typescript API」の「Task Implementation」の内容をそのままコピペします。

次は作成した拡張機能のインストーラーの作成/展開についてです。

TFS/VSTSのビルドタスク作成:全体概要

ちょっとビルドタスクとして作ってみたい処理があったので、ビルドタスクの作成方法について調べてみたら、結構ハマったのでまとめてみました。

☆環境
〇Windows 10 Creator Update
〇Visual Studio Code:1.14.2
 ターミナルをPowerShellにしています。
〇nodist:0.8.8
 ・node:8.2.1/6.10.2
  開発環境としては現時点での最新版である8.2.1を使用します。6.10.2が必要な理由は後述します。
  nodistだと簡単に切り替えれるので楽ですね。
 ・npm:4.0.5
〇TypeScript:2.4.2
〇Team Foundation Server 2017 Update 2
 タスク作成はVisual Studio Team Services用でも同じですが、作成した拡張機能の展開手順が異なります。
〇TFSビルドエージェントはMac(sierra)を使用しています。
 ・vstsAgent:2.119.1
 ・Homebrew:1.0.9/Node:8.2.1/npm:5.3.0

☆全体概要
 基本的には、vsts-task-libのドキュメントで「Step by Step: Node Task with Typescript API」(https://github.com/Microsoft/vsts-task-lib/blob/master/node/docs/stepbystep.md)にありますが、現時点ではこれだけだと情報が足りないので、Microsoftの別ドキュメント「Add a build task」(https://www.visualstudio.com/ja-jp/docs/integrate/extensions/develop/add-build-task)の情報を参考にしつつ、いろいろミックスしています。
 大まかには
  ・いろいろなjsonファイルに各種情報(タスク名称など)を設定する
  ・TypeScriptで実現したい処理を実装する(今回はHello world+α)
  ・Visual Studio拡張機能インストーラー(.vsix)を作成し、TFSにインストールする
  ・ビルド定義で作成したタスクを使用する
 という内容です。

ちょっと長いので、続きは次に。