Criar e testar .NET

Introdução

Este guia mostra como criar, testar e publicar um pacote no .NET.

Os executores hospedados no GitHub têm um cache de ferramentas com programas de software pré-instalados, que incluem o SDK do .NET Core. Para ver a lista completa de programas de software atualizados e as versões pré-instaladas do SDK do .NET Core, confira Programas de software instalados nos executores hospedados no GitHub.

Pré-requisitos

Você já deve estar familiarizado com a sintaxe YAML e como é usado com GitHub Actions. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Recomendamos que você tenha um entendimento básico do .NET Core SDK. Para obter mais informações, confira Introdução ao .NET.

Usando o fluxo de trabalho inicial do .NET

GitHub fornece um fluxo de trabalho inicial do .NET que deve funcionar na maior parte dos projetos do .NET e este guia inclui exemplos que mostram como personalizar este fluxo de trabalho inicial. Para obter mais informações, confira o fluxo de trabalho inicial do .NET.

Para experimentar uma introdução rápida, adicione o fluxo de trabalho inicial ao diretório .github/workflows do repositório.

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 .NET Core SDK ${{ matrix.dotnet-version }}
        uses: actions/setup-dotnet@v3
        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

Especificando uma versão do .NET

Para usar uma versão pré-instalada do SDK do .NET Core em um executor hospedado no GitHub, use a ação setup-dotnet. Essa ação localiza uma versão específica do .NET no cache de ferramentas em cada executor e adiciona os binários necessários a PATH. Estas alterações persistirão para o resto do trabalho.

A ação setup-dotnet é a maneira recomendada de usar o .NET com o GitHub Actions, pois garante um comportamento consistente entre diferentes executores e diferentes versões do .NET. Se você estiver usando um executor auto-hospedado, precisará instalar o .NET e adicioná-lo a PATH. Para obter mais informações, confira a ação setup-dotnet.

Usar múltiplas versões do .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

Usar uma versão específica do .NET

Você pode configurar seu trabalho para usar uma versão específica do .NET, como 3.1.3. Como alternativa, você pode usar a sintaxe da versão semântica para obter a última versão secundária. Este exemplo usa a versão mais recente do .NET 3.

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

Instalar dependências

Os executores hospedados em GitHub têm o gerenciador do pacote NuGet instalado. Você pode usar o dotnet CLI para instalar dependências do registro do pacote NuGet antes de criar e testar seu código. Por exemplo, o YAML abaixo instala o pacote 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

Memorizar dependências

Você pode armazenar em cache as dependências do NuGet usando uma chave exclusiva, o que permite restaurar as dependências em fluxos de trabalho futuros com a ação cache. Por exemplo, o YAML abaixo instala o pacote Newtonsoft.

Para obter mais informações, confira "Memorizar dependências para acelerar os fluxos de trabalho".

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

Criar e testar seu código

Você pode usar os mesmos comandos usados localmente para criar e testar seu código. Este exemplo demonstra como usar dotnet build e dotnet test em um trabalho:

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

Empacotar dados do fluxo de trabalho como artefatos

Após a conclusão de um fluxo de trabalho, você poderá fazer o upload dos artefatos resultantes para análise. Por exemplo, é possível que você precise salvar os arquivos de registro, os despejos de núcleo, os resultados de teste ou capturas de tela. O exemplo a seguir demonstra como você pode usar a ação upload-artifact para carregar os resultados do teste.

Para obter mais informações, confira "Armazenar dados do fluxo de trabalho como artefatos".

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() }}

Publicar nos registros do pacote

É possível configurar o seu fluxo de trabalho para publicar o pacote .NET em um pacote de registro quando o CI teste é aprovado. Você pode usar segredos do repositório para armazenar quaisquer tokens ou credenciais necessárias para publicar seu binário. O exemplo a seguir cria e publica um pacote no GitHub Packages usando dotnet core cli.

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