构建和测试 .NET

Note

GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

简介

本指南介绍如何构建、测试和发布 .NET 包。

GitHub 托管的运行器具有预安装了软件的工具缓存，包括 .NET Core SDK。有关最新软件和 .NET Core SDK 预安装版本的完整列表，请参阅安装在 GitHub 托管的运行器上的软件。

先决条件

您应该已经熟悉 YAML 语法及其如何与 GitHub Actions 结合使用。有关详细信息，请参阅“GitHub Actions 的工作流语法”。

建议您对 .NET Core SDK 有个基本的了解。有关详细信息，请参阅 .NET 入门。

使用 .NET 工作流模板

若要快速开始使用，请将工作流模板添加到存储库的 .github/workflows 目录。

GitHub 为 .NET 提供了一个工作流模板，适用于大多数 .NET 项目。本指南的后续部分提供了如何自定义此工作流模板的示例。

在 GitHub 上，导航到存储库的主页面。
在存储库名称下，单击 “操作”。
如果存储库中已有工作流，请单击“新建工作流”。
“选择工作流”页面显示一系列推荐的工作流模板。搜索“dotnet”。

在“.NET”工作流上，单击“配置”。

如果未找到“.NET”工作流模板，请将以下工作流代码复制到存储库的 .github/workflows 目录中名为 dotnet.yml 的新文件。

YAML

name: .NET

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 6.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --no-restore
    - name: Test
      run: dotnet test --no-build --verbosity normal

name: .NET

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 6.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --no-restore
    - name: Test
      run: dotnet test --no-build --verbosity normal

根据需要编辑工作流。例如更改 .NET 版本。
单击“提交更改”。

指定 .NET 版本

若要在 GitHub 托管的运行器上使用预安装的 .NET Core SDK 版本，请使用 setup-dotnet 操作。此操作从每个运行器上的工具缓存中查找特定版本的 .NET，并将必要的二进制文件添加到 PATH。这些更改将持续用于作业的其余部分。

setup-dotnet 操作是 .NET 与 GitHub Actions 结合使用时的推荐方式，因为它能确保不同运行器和不同版本的 .NET 行为一致。如果使用自托管运行器，则必须安装 .NET 并将其添加到 PATH。有关详细信息，请参阅 setup-dotnet 一文。

使用多个 .NET 版本

name: dotnet package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup dotnet ${{ matrix.dotnet-version }}
        uses: actions/setup-dotnet@v3
        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 版本

可以将作业配置为使用 .NET 的特定版本，例如 6.0.22。或者，您也可以使用语义版本语法来获得最新的次要版本。此示例使用 .NET 6 最新的次要版本。

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

安装依赖关系

GitHub 托管的运行器安装了 NuGet 软件包管理器。在构建和测试代码之前，您可以使用 dotnet CLI 从 NuGet 软件包注册表安装依赖项。例如，下面的 YAML 会安装 Newtonsoft 包。

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

缓存依赖项

可以使用可选 cache 输入为未来的工作流缓存 NuGet 依赖项。例如，下面的 YAML 缓存 NuGet global-packages 文件夹，然后安装 Newtonsoft 包。第二个可选输入 cache-dependency-path 可用于指定依赖项文件的路径：packages.lock.json。

有关详细信息，请参阅“缓存依赖项以加快工作流程”。

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

Note

根据依赖项的数量，使用依赖项缓存可能会更快。有很多大型依赖项的项目应该能看到性能明显提升，因为下载所需的时间会缩短。依赖项较少的项目可能看不到明显的性提升，甚至可能由于 NuGet 安装缓存依赖项的方式而看到性能略有下降。性能因项目而异。

构建和测试代码

您可以使用与本地相同的命令来构建和测试代码。此示例演示如何在作业中使用 dotnet build 和 dotnet test：

steps:
- uses: actions/checkout@v4
- name: Setup dotnet
  uses: actions/setup-dotnet@v3
  with:
    dotnet-version: '6.0.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.1.x', '6.0.x' ]

      steps:
        - uses: actions/checkout@v4
        - name: Setup dotnet
          uses: actions/setup-dotnet@v3
          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() }}

发布到包注册表

您可以配置工作流程在 CI 测试通过后将 .NET 包发布到包注册表。您可以使用仓库机密来存储发布二进制文件所需的任何令牌或凭据。以下示例使用 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@v4
      - uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '6.0.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

构建和测试 .NET

本文内容