Azure DevOps を使用して継続的インテグレーションと継続的配置を実装する
Azure DevOps (Visual Studio Team Services / Team Foundation Server) には、開発者が開発プロジェクト用に DevOps、継続的インテグレーション、継続的配置を実装するのを支援する一連のツールとサービスが備わっています。
この記事では、SharePoint Framework のビルド、単体テスト、配置を自動化するための継続的インテグレーションと継続的配置を使用した Azure DevOps 環境のセットアップに関係する手順を説明します。
Azure Multi-stage Pipelines (プレビュー) と Azure DevOps のビルドおよびリリースのどちらかを選択する
現在、継続的インテグレーションと Azure DevOps での展開を実装するには、次の 2 つのアプローチがあります。 Azure のビルドとリリースは歴史的なもので、グラフィカルなエディションのエクスペリエンスを特徴とし、ユーザーには表示されない JSON ドキュメントに定義を保存します。
どちらのアプローチも、SharePoint フレームワークのために記述されています。
- Azure ビルドとリリース (この記事)
- Azure の複数のステージ パイプライン
継続的インテグレーション
開発者は継続的インテグレーション (CI) を使用すると、単体テストを使用したビルドの検証や、新しいコード変更を送信するたびにソリューションをパッケージ化する処理を自動化することによって、共有リポジトリにコードを統合できます。
SharePoint Framework を使用した継続的インテグレーション向けに Azure DevOps をセットアップするには、次の手順を実行する必要があります。
- ビルド定義の作成
- NodeJS のインストール
- 依存関係の復元
- 単体テストの実行
- テスト結果のインポート
- コード カバレッジ情報のインポート
- ソリューションのバンドル
- ソリューションのパッケージ化
- 成果物の準備
- 成果物の発行
ビルド定義の作成
ビルド定義には、その名前が示すとおり、ビルドのためのすべての定義と構成が含まれます。 継続的インテグレーションのセットアップを開始するには、まず、新しいビルド定義を作成し、それをリポジトリにリンクします。
注:
ビルド定義は、プロセス テンプレートとして記述することができます。 それは、ビルドがトリガーされるたびにソース コード上で次々に実行されることになる構成済みタスクの集合です。 複数のタスクをフェーズでグループ化することができます。既定では、1 つのビルド定義には少なくとも 1 つのフェーズが含まれます。 フェーズ名の隣にある大きなプラス記号をクリックすると、新しいタスクをフェーズに追加できます。
NodeJS バージョン 10 のインストール
ビルド定義を作成したら、最初に NodeJS をインストールする必要があります。 SharePoint Framework はバージョン 10 に依存しているため、必ずバージョン 10 をインストールしてください。
注:
10.x
を Version Spec
フィールドで指定してください。 プロジェクトが SharePoint Framework 1.7.1 以前に基づいている場合は、バージョン 8.x を使用します。
依存関係の復元
サード パーティの依存関係はソース管理に格納されないため、プロジェクトのビルドを開始する前に依存関係を復元する必要があります。 そのためには、npm
タスクを追加し、コマンドを install
に設定します。
単体テストの実行
SharePoint Framework は既定値 (1.8.0以降) によるテスト フレームワークは提供せず、このサンプルで Jest を活用します。 これらのモジュールは後の手順でインストールされ、可能性のある問題や不具合に関するフィードバックを可能な限り早急に取得するため、少なくともご使用のコードのビジネス ロジックのテストを実行することをぜひお勧めします。 Azure DevOps で単体テストを実行するには、npm
タスクを追加します。 command
を custom
とcustom command
フィールドに設定し、test
と入力します。 それからWorking Directory
オプションを$(Build.SourcesDirectory)
に設定します。
Jest の構成
既定値では、SharePoint Framework プロジェクトには Framework のテストは含まれていません。 このサンプルでJestを活用します。
npm i jest jest-junit @voitanos/jest-preset-spfx-react16 -D
注:
SharePoint Framework 1.7.1 以前で生成されたプロジェクトは React バージョン 15 に依存します。 React 15 を使用している場合は、代わりにインストール@voitanos/jest-preset-spfx-react15する必要があります。 他の Framework (Knockout、...) の場合は、代わりに別のプリセットのインストールが必要になる場合があります。
Jest を設定することも必要です。この設定を行うには、config/jest.config.json
ファイルを作成し、以下のコンテンツを追加します。
{
"preset": "@voitanos/jest-preset-spfx-react16",
"rootDir": "../src",
"coverageReporters": [
"text",
"json",
"lcov",
"text-summary",
"cobertura"
],
"reporters": [
"default",
["jest-junit", {
"suiteName": "jest tests",
"outputDirectory": "temp/test/junit",
"outputName": "junit.xml"
}]
]
}
コマンドを入力する場合、Jest を活用するにはプロジェクトを構成することも必要です。 この構成を行うには、package.json
ファイルを作成し、これら2つのscripts
を次の値で追加/置換します。
"test": "./node_modules/.bin/jest --config ./config/jest.config.json",
"test:watch": "./node_modules/.bin/jest --config ./config/jest.config.json --watchAll"
単体テストの作成
最初の単体テストを作成するには、新しいファイルを作成src/webparts/webPartName/tests/webPartName.spec.ts
し、次の内容を追加します。
import 'jest'
describe("webPartName", () => {
test("should add numbers Sync fluent", () => {
const result = 1 + 3;
expect(result).toBe(4); // fluent API
});
});
注:
Jest を使用して単体テストを作成するにはここを参照してください。 Jest と Enzyme を使用したリアクション アプリケーションのテストの詳細については、ここを参照してください (セットアップ パートは無視できます)。
テスト結果のインポート
ビルド結果に添付されたテスト結果の情報を取得するには、テスト ランナーからのテスト結果を Azure DevOps へインポートする必要があります。 このためには、新しいPublish Test Results
タスクを追加します。 Test results files
フィールドを**/junit.xml
に、Search folder
を$(Build.SourcesDirectory)
に設定します。
コード カバレッジ情報のインポート
コード カバレッジがビルドの状態と一緒にレポートされるようにするには、その情報をインポートするためのタスクを追加する必要があります。 コード カバレッジ情報を構成するには、publish code coverage results
タスクを追加します。 ツールを Cobertura
に、Summary files
を $(Build.SourcesDirectory)/**/*-coverage.xml
にそれぞれ設定してください。
ソリューションのバンドル
Web ブラウザーが認識できる静的アセットを取得するには、最初にソリューションをバンドルする必要があります。 もう 1 つの gulp
タスクを追加し、gulpfile
パスを設定します。また、Gulp Tasks
フィールドを bundle に設定し、--ship
を Arguments
に追加します。
ソリューションのパッケージ化
静的アセットを取得できたので、次の手順として、SharePoint が配置できるパッケージにそれらのアセットを結合します。 もう 1 つの gulp
タスクを追加し、gulpfile
パスを設定します。また、Gulp Tasks
フィールドを package-solution
に設定し、--ship
を Arguments
に追加します。
成果物の準備
既定で、Azure DevOps ビルドでは、ファイルはまったく保持されません。 リリースに必要なファイルを確実に保持するには、保持するファイルを明示的に指示する必要があります。
Copy Files
タスクを追加し、Contents
を **\*.sppkg
(前のタスクで作成された SharePoint パッケージ) に、ターゲット フォルダーを $(build.artifactstagingdirectory)/drop
にそれぞれ設定します。
成果物の発行
この時点で、配置に必要なすべてのファイルが特別な成果物フォルダーに収集されました。次に、Azure DevOps に対して、ビルドの実行後にもこれらのファイルを保持するよう指示する必要があります。 そのためには、Publish artifacts
タスクを追加し、Path to publish
を $(build.artifactstagingdirectory)/drop
に、Artifact name
を drop
にそれぞれ設定します。
継続的配置
継続的配置 (CD) では、ビルド プロセスから検証済みコード パッケージを取得して、それをステージング環境または運用環境に配置します。 開発者は、配置が成功したかどうかを追跡して、特定のパッケージ バージョンに問題を絞り込むことができます。
SharePoint Framework ソリューションを伴う継続的配置向けに Azure DevOps をセットアップするには、次の手順を実行する必要があります。
- リリース定義の作成
- ビルド成果物のリンク
- 環境の作成
- NodeJS のインストール
- Microsoft 365 の CLI のインストール
- アプリ カタログへの接続
- アプリ カタログへのソリューション パッケージの追加
- アプリケーションの配置
- 環境用変数の設定
リリース定義の作成
最初に空のテンプレートを使用して、新しいリリース定義を作成します。 リリース定義は、次に示す配置用の要素を識別するために使用するプロセスです。
- 環境
- 配置タスク
- ビルド成果物
ビルド成果物のリンク
Add an artifact
をクリックし、作成済みのビルド定義を選択します。 後続のタスクで使用することになるので、設定した Source Alias
の名前をメモします。
環境の作成
継続的配置環境を作成する場合、名前を指定し、配置前承認や成果物フィルター (つまり、ビルドが特定のブランチに基づいている場合にのみ配置する) などの構成を行えます。その場合には、環境ボックスの周囲にあるボタンをクリックするか、タイトルを直接クリックします。
NodeJS のインストール
1 job, 0 tasks
をクリックすると、ビルド定義と同様に機能するタスク構成ビューにアクセスできます。 このビューでは、特定の環境でのみ実行するタスク セットを選択できます。 それには、NodeJS バージョン 10 以降のインストールも含まれます。
Node tool installer
タスクを追加し、10.X
を Version Spec
フィールドで定義します。 プロジェクトが SharePoint Framework バージョン 1.7.1 以前に基づいている場合は、バージョン 8.X を使用します。
Microsoft 365 の CLI のインストール
Microsoft 365 共通言語インターフェイス (CLI) は Microsoft 365 PnP コミュニティが構築したオープン ソース プロジェクトです。 リリース定義の一部として CLI を利用するには、まず CLI をインストールする必要があります。 インストールすると、配置を扱うコマンドを利用できるようになります。 npm
タスクを追加し、Custom
コマンドを選択して、install -g @pnp/cli-microsoft365
と Command and Arguments
フィールドに入力します。
注:
Microsoft 365 の CLI について詳しく見る
SharePoint Online への接続
配置環境でアプリ カタログを使用するには、その前にテナントのアプリ カタログに照らして認証する必要があります。 そのためには、Command Line
タスクを追加し、以下のコマンドを script
m365 login -t password -u $(username) -p $(password)
フィールドに貼り付けます。
注:
Microsoft 365 の CLI を使用して初めてテナントに接続する場合は、まずアカウントで対話型ログオンを実行する必要があります。 アカウントに代わってテナントにアクセスする Microsoft 365 の CLI で使われる PnP Office 365 管理シェル アプリケーションへのアクセスを許可するには、これが必要となります。 これを行わない場合、非対話的なログオンに失敗します。 詳細については、Microsoft 365 の CLI の ユーザー ガイド をご覧ください。
注:
CLI for Microsoft 365 はオープン ソース ソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープン ソース ツールのサポート SLA はありません。
アプリ カタログへのソリューション パッケージの追加
ソリューション パッケージをアプリ カタログにアップロードします。そのためには、別の Command Line
タスクを追加し、以下のコマンド ラインを Script
フィールドに貼り付けます。m365 spo app add -p $(System.DefaultWorkingDirectory)/SpFxDevOps/drop/SharePoint/solution/sp-fx-devops.sppkg --overwrite
注:
パッケージのパスは、ご使用のソリューション名や (プロジェクト構成を確認してください)、以前に定義した Source Alias
によって異なります。一致していることを確認してください。
注:
--appCatalogUrl https://$(tenant).sharepoint.com/$(catalogsite) --scope sitecollection
を追加することで、サイト コレクション アプリ カタログにソリューションをアップロードできます。
アプリケーションの配置
セットアップの最後の手順では、アプリケーションをアプリ カタログに配置し、対象テナント内のすべてのサイト コレクションで最新バージョンとして利用できるようにします。 別の Command Line
タスクを追加して、Script
フィールドにコマンド ライン m365 spo app deploy --name sp-fx-devops.sppkg
を貼り付けます
注:
パッケージ名を更新してください。
注:
--appCatalogUrl https://$(tenant).sharepoint.com/$(catalogsite) --scope sitecollection
を追加することで、サイト コレクション アプリ カタログからソリューションを展開できます。
環境用変数の設定
最後の手順で構成したタスクは、Azure DevOps プロセス変数 ($(variableName)
構文で簡単に識別できます) に依存しています。 ビルド定義を実行するには、その前にそれらの変数を定義しておく必要があります。 これを行うには、Variables
タブをクリックします。次の変数を追加します
名前 | 値 |
---|---|
catalogsite | 省略可能です。 サイト コレクション アプリ カタログにアップロードする場合のアプリ カタログ サイトのサーバー相対パス (例: sites/appcatalog ) |
password | テナントで管理者アクセス許可を持つユーザーのパスワード。他のユーザーに対してマスクするため、ロックパッドを必ず有効にしてください |
username | テナントで管理者アクセス許可を持つユーザーのユーザー名 |
tenant | 省略可能です。 サイト コレクション アプリ カタログにアップロードする場合の https://tenant.sharepoint.com のテナント名 (例: tenant ) |
注:
リリース定義を保存してください。
テスト
新しく作成した継続的配置プロセスをテストするには、Azure DevOps の [Builds
] セクションに戻り、ビルド定義を選択して [Queue
] をクリックします。 ブランチを選択して、[Queue
] をクリックします。 新しいビルドが作成され、ビルドが開始されます。
数分でビルドが完了し、次のような結果ページが表示されます。
Azure DevOps の [Release
] セクションに移動すると、新しいリリースが自動的に開始されているはずです。 数分後にリリースが完了し、SharePoint Framework ソリューションが対象テナントに配置されます。
Azure DevOps で SharePoint Framework ソリューション向けの DevOps パイプラインがセットアップされ、シナリオに合わせてさらにカスタマイズできるようになります。