この記事では、CircleCI の Windows Executor を使用して、 ASP.NET Core で作成された簡単な電卓アプリケーションを Windows 仮想マシンでビルドしテストする方法を説明します。ここでは、電卓アプリケーション用のコンフィグファイルを題材に、関連する部分を詳しく説明していきます。
ASP.NET は、Microsoft が開発したオープンソースのサーバーサイド Web アプリケーションフレームワークです。Web およびアプリケーション開発に使用できるフレームワークは多くあり、それぞれ異なる機能と利点がありますが、ASP.NET を使用すると、開発者は、 Windows 上で稼働するWeb アプリケーション、Web サービス、および動的なコンテンツを組み入れた Web サイトを容易に開発することができます。ASP.NET Core はクロスプラットフォームな ASP.NET の強化版として開発されたもので、Windows、macOS、Linux を含むすべての主なコンピューティングプラットフォームで実行することができます。
さて、 CircleCI の Windows Executor には、以下のような特徴があります。
- Docker Engine - Enterprise により Docker ベースの Windows ワークフローを実行可能。
- Windows VM 環境によるビルドの完全な分離。
- デフォルトのシェルは PowerShell。Bash および cmd もコンフィグでの設定により使用可能。
- キャッシュ、ワークスペース、ジョブの承認、制限付きコンテキストなど CircleCI の機能が Windows 環境内ですべて利用可能。
前提条件
この記事では、下記がすでに準備されていることを前提とします。
- CircleCI の アカウント
- Free プランまたは Performance プランのいずれかが有効になっていること
- 対象のプロジェクトで パイプラインが有効になっていること
アプリケーションの詳細
このチュートリアルでは、簡単な電卓アプリケーションを使用します。ソースコードは ここからフォークできます。以下は、アプリケーションのディレクトリ構造です。
.
├── Dockerfile
├── LICENSE
├── README.md
├── SimpleCalc
│ ├── Controllers
│ ├── Models
│ ├── Program.cs
│ ├── Services
│ ├── SimpleCalc.csproj
│ ├── Startup.cs
│ ├── Views
│ ├── appsettings.Development.json
│ ├── appsettings.json
│ └── wwwroot
├── SimpleCalc.sln
└── test
└── SimpleCalc.Tests
8 directories, 9 files
プロジェクトをフォークしたら、 「CircleCI でビルドを設定」に指示に従って、プロジェクトを CircleCI に接続します。
CircleCI の構成
CircleCI を構成するために、プロジェクトのルートにある .circleci
フォルダに config.yml
ファイルを追加します。このプロジェクト用のコンフィグファイルは次のとおりです。
version: 2.1
orbs:
windows: circleci/windows@2.2.0
jobs:
test:
description: Setup and run application tests
executor:
name: windows/default
steps:
- checkout
- restore_cache:
keys:
- dotnet-packages-v1-{{ checksum "SimpleCalc/SimpleCalc.csproj" }}
- run:
name: "Install project dependencies"
command: dotnet.exe restore
- save_cache:
paths:
- C:\Users\circleci\.nuget\packages
key: dotnet-packages-v1-{{ checksum "SimpleCalc/SimpleCalc.csproj" }}
- run:
name: "Run Application Tests"
command: dotnet.exe test -v n --results-directory:test_coverage --collect:"Code Coverage"
- run:
name: "Print Working Directory"
command: pwd
- store_artifacts:
path: C:\Users\circleci\project\test_coverage
build:
description: Build application with Release configuration
executor:
name: windows/default
steps:
- checkout
- run:
name: "Build Application according to some given configuration"
command: dotnet.exe build --configuration Release
workflows:
test_and_build:
jobs:
- test
- build:
requires:
- test
それでは、このコンフィグを詳しく見ていきましょう。
OS/環境とランタイムの定義
Orbs を使用するため、コンフィグのバージョンは 2.1 とします。 Orbs は、ジョブ、コマンド、Executor などのコンフィグを共有できるパッケージです。このプロジェクトでは、Windows Orbを使用しています。この Orb は、ユニバーサル Windows プラットフォーム(UWP)アプリケーションや .NET 実行可能ファイル、 .NET Framework を使用した Windows のみで動作するアプリケーションのプロジェクトといった Windows プロジェクトをビルドするためのツールをユーザーに提供します。
version: 2.1
orbs:
windows: circleci/windows@2.2.0
このコンフィグでは、 test
と bulid
の二つのジョブが定義されています。そして、 build ジョブを実行するためには、すべてのテストにパスする必要があります。この順序を構成するために、CircleCI の機能であるワークフローを利用しています。ワークフローとは、複数のジョブの実行順序を定義する機能です。ワークフローの宣言は、サンプルコンフィグファイルの最後にあります。
workflows:
test_and_build:
jobs:
- test
- build:
requires:
- test
テストのセットアップと実行
Windows Executor には、Visual Studio 2019 やその他の多くの開発ツールにプリロードされています。ここではデフォルトの PowerShell シェルを使用するため、使用するシェルの宣言はしていません。
test:
description: Setup and run application tests
executor:
name: windows/default
ステップ には、ジョブ中に実行される実行可能なコマンドの一覧が宣言されています。下記のステップでは、コードをチェックアウトし、プロジェクトの依存関係をリストアします。
steps:
- checkout
- restore_cache:
keys:
- dotnet-packages-v1-{{ checksum "SimpleCalc/SimpleCalc.csproj" }}
- run:
name: "Install project dependencies"
command: dotnet.exe restore
- save_cache:
paths:
- C:\Users\circleci\.nuget\packages
key: dotnet-packages-v1-{{ checksum "SimpleCalc/SimpleCalc.csproj" }}
利用可能なキャッシングオプションとその使用方法については、 CircleCI の キャッシュに関するドキュメントで 詳細に説明されています。 dotnet.exe restore
コマンドは、NuGet を使用して、依存関係を復元するほか、プロジェクトファイルで指定されているプロジェクト固有のツールを復元します。デフォルトでは、依存関係の復元とツールの復元は並行して実行されます。
実際のソフトウェア開発に必要不可欠な行程が単体テスト(ユニット テスト)です。単体テストとは、ソースコードの個々のユニット(単体)をテストし、使用に適しているかどうかを判断するソフトウェアテストの手法です。単体テストからコードカバレッジを収集することもできます。ここでユニットとは、テスト可能な最小のソフトウェアの単位です。“dotnet.exe test” は、単体テストを実行する .NET のテスト ドライバです。このプロジェクトでは、xUnit テストフレームワークを使用しています。すべてのテストが成功した場合、テスト ドライバは終了ステータスとして 0 を返します。それ以外の場合、つまり、いずれかのテストが失敗すると、1 を返します。テスト ドライバと単体テストに必要なライブラリは NuGet パッケージとしてパッケージ化され、プロジェクトの通常の依存関係としてリストアされます。
- run:
name: "Run Application Tests"
command: dotnet.exe test -v n --results-directory:test_coverage --collect:"Code Coverage"
ここでは、テストを実行して収集されたカバレッジをアーティファクトとして test_coverage
フォルダに保存しています。ASP.NET Core プロジェクトのコードカバレッジレポートは、標準設定のままでは回収されません。
- store_artifacts:
path: C:\Users\circleci\project\test_coverage
プロジェクトのビルド
テストの正常実行に成功したら、プロジェクトをビルドします。コンフィグではビルド用に build
ジョブを定義しています。このプロジェクトで利用可能なビルド オプションは次のとおりです。
- リリース
- デバッグ 以下のコンフィグは、リリースを選択した場合を示しています。
build:
description: Build application with Release configuration
executor:
name: windows/default
steps:
- checkout
- run:
name: "Build Application according to some given configuration"
command: dotnet.exe build --configuration Release
.NET Core 2.0 以降の SDK では、“dotnet new”、“dotnet build”、“dotnet run” などリストアが必要なすべてのコマンドで “dotnet restore” が暗黙的に実行されるため、 “dotnet restore” を明示的に実行する必要はありません。
結論
CircleCI で Windows Executor を使用すると、ASP.NET Core アプリケーションを簡単にビルドおよびテストできます。CircleCI が承認している Windows Orb は、CircleCI によってテストされ、コミュニティによって検証されており、安心して利用できます。お使いのコンフィグで使用できる Orbs の詳細については、Orb レジストリを参照してください。
Orbs によって、以下ような時間のかかる作業を省略できます。
- Windows 仮想マシンの調査、テスト、セットアップ
- vs2019、Nuget などの開発ツールのインストール
- PowerShell などの Windowsツールの使用方法の習得
Orb を使用すると、コンフィグファイルの行数も削減できます。このプロジェクトのコンフィグファイルのコードはわずか 42 行であり、簡単に理解でる上に、高い保守性を実現しています。