.NETでのビルドとテスト

ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。

はじめに

このガイドは、.NETパッケージのビルド、テスト、公開の方法を紹介します。

GitHub ホストランナーには、.NET Core SDKを含むソフトウェアがプリインストールされたツールキャッシュがあります。最新のソフトウェアとプリインストールされたバージョンの.NET Core SDKの完全なリストについては、GitHubホストランナー上にインストールされているソフトウェアを参照してください。

必要な環境

YAMLの構文と、GitHub ActionsでのYAMLの使われ方に馴染んでいる必要があります。詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

.NET Core SDKの基本的な理解をしておくことをおすすめします。詳細は「Getting started with .NET」を参照してください。

Using the .NET starter workflow

GitHub provides a .NET starter workflow that should work for most .NET projects, and this guide includes examples that show you how to customize this starter workflow. For more information, see the .NET starter workflow.

To get started quickly, add the starter workflow to the .github/workflows directory of your repository.

name: dotnet package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        dotnet-version: ['3.0', '3.1.x', '5.0.x' ]

    steps:
      - uses: actions/checkout@v3
      - name: Setup .NET Core SDK ${{ matrix.dotnet-version }}
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: ${{ matrix.dotnet-version }}
      - name: Install dependencies
        run: dotnet restore
      - name: Build
        run: dotnet build --configuration Release --no-restore
      - name: Test
        run: dotnet test --no-restore --verbosity normal

.NETのバージョンの指定

GitHubホストランナーにプリインストールされたバージョンの.NET Core SDKを使うには、setup-dotnetアクションを使ってください。このアクションは各ランナーのツールキャッシュから指定されたバージョンの.NETを見つけ、必要なバイナリをPATHに追加します。これらの変更は、ジョブの残りの部分で保持されます。

setup-dotnetアクションは、GitHub Actionsで.NETを使うための推奨される方法です。これは、それによって様々なランナーや様々なバージョンの.NETに渡って一貫した振る舞いが保証されるためです。セルフホストランナーを使っている場合は、.NETをインストールしてPATHに追加しなければなりません。詳しい情報についてはsetup-dotnetアクションを参照してください。

複数の.NETバージョンの利用

name: dotnet package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        dotnet-version: [ '3.0', '3.1.x', '5.0.x' ]

    steps:
      - uses: actions/checkout@v3
      - name: Setup dotnet ${{ matrix.dotnet-version }}
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: ${{ matrix.dotnet-version }}
      # You can test your matrix by printing the current dotnet version
      - name: Display dotnet version
        run: dotnet --version

特定のバージョンの.NETの利用

3.1.3というような、特定のバージョンの.NETを使うようにジョブを設定できます。あるいは、最新のマイナーリリースを取得するためにセマンティックバージョン構文を使うこともできます。この例では.NET 3の最新のマイナーリリースを使っています。

    - name: Setup .NET 3.x
      uses: actions/setup-dotnet@v2
      with:
        # Semantic version range syntax or exact version of a dotnet version
        dotnet-version: '3.x'

依存関係のインストール

GitHubホストランナーには、NuGetパッケージマネージャーがインストールされています。コードをビルドしてテストする前に、dotnetCLIを使って依存関係をNuGetパッケージレジストリからインストールしておくことができます。たとえば、以下のYAMLはNewtonsoftパッケージをインストールします。

steps:
- uses: actions/checkout@v3
- name: Setup dotnet
  uses: actions/setup-dotnet@v2
  with:
    dotnet-version: '3.1.x'
- name: Install dependencies
  run: dotnet add package Newtonsoft.Json --version 12.0.1

依存関係のキャッシング

ユニークなキーを使ってNuGetｎ依存関係をキャッシュしておくことができ、そうすることで将来のワークフローでcacheアクションによってその依存関係をリストアできます。たとえば、以下のYAMLはNewtonsoftパッケージをインストールします。

詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。

steps:
- uses: actions/checkout@v3
- name: Setup dotnet
  uses: actions/setup-dotnet@v2
  with:
    dotnet-version: '3.1.x'
- uses: actions/cache@v3
  with:
    path: ~/.nuget/packages
    # Look to see if there is a cache hit for the corresponding requirements file
    key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
    restore-keys: |
      ${{ runner.os }}-nuget
- name: Install dependencies
  run: dotnet add package Newtonsoft.Json --version 12.0.1

ノート： 依存関係の数によっては、依存関係キャッシュを使う方が高速になることがあります。多くの大きな依存関係を持つプロジェクトでは、ダウンロードに必要な時間を節約できるので、パフォーマンスの向上が見られるでしょう。依存関係が少ないプロジェクトでは、大きなパフォーマンスの向上は見られないかもしれず、NuGetがキャッシュされた依存関係をインストールする方法のために、パフォーマンスがやや低下さえするかもしれません。パフォーマンスはプロジェクトによって異なります。

コードのビルドとテスト

ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。以下の例は、ジョブでdotnet buildとdotnet testを使う方法を示します。

steps:
- uses: actions/checkout@v3
- name: Setup dotnet
  uses: actions/setup-dotnet@v2
  with:
    dotnet-version: '3.1.x'
- name: Install dependencies
  run: dotnet restore
- name: Build
  run: dotnet build
- name: Test with the dotnet CLI
  run: dotnet test

成果物としてのワークフローのデータのパッケージ化

ワークフローが完了すると、結果の成果物を分析のためにアップロードできます。たとえば、ログファイル、コアダンプ、テスト結果、スクリーンショットを保存する必要があるかもしれません。以下の例は、upload-artifactアクションを使ってテスト結果をアップロードする方法を示しています。

詳しい情報については「成果物を利用してワークフローのデータを永続化する」を参照してください。

name: dotnet package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        dotnet-version: [ '3.0', '3.1.x', '5.0.x' ]

      steps:
        - uses: actions/checkout@v3
        - name: Setup dotnet
          uses: actions/setup-dotnet@v2
          with:
            dotnet-version: ${{ matrix.dotnet-version }}
        - name: Install dependencies
          run: dotnet restore
        - name: Test with dotnet
          run: dotnet test --logger trx --results-directory "TestResults-${{ matrix.dotnet-version }}"
        - name: Upload dotnet test results
          uses: actions/upload-artifact@v3
          with:
            name: dotnet-results-${{ matrix.dotnet-version }}
            path: TestResults-${{ matrix.dotnet-version }}
          # Use always() to always run this step to publish test results when there are test failures
          if: ${{ always() }}

パッケージレジストリへの公開

You can configure your workflow to publish your .NET package to a package registry when your CI tests pass. バイナリを公開するのに必要なトークンや認証情報を保存するために、リポジトリシークレットを使うことができます。以下の例では、dotnet core cliを使ってパッケージを作成し、GitHub Packagesに公開しています。

name: Upload dotnet package

on:
  release:
    types: [created]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-dotnet@v2
        with:
          dotnet-version: '3.1.x' # SDK Version to use.
          source-url: https://nuget.pkg.github.com/<owner>/index.json
        env:
          NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
      - run: dotnet build --configuration Release <my project>
      - name: Create the package
        run: dotnet pack --configuration Release <my project>
      - name: Publish the package to GPR
        run: dotnet nuget push <my project>/bin/Release/*.nupkg