Erstellen und Testen eines .NET-Projekts

Note

Auf GitHub gehostete Runner werden aktuell nicht auf GitHub Enterprise Server unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Einführung

In dieser Anleitung erfährst du, wie du ein .NET-Paket erstellst, testest und veröffentlichst.

GitHub-gehostete Runner haben einen Toolcache mit vorinstallierter Software, die .NET Core SDK einschließt. Eine umfassende Liste mit aktueller Software und den vorinstallierten Versionen von .NET Core SDK findest du unter Auf GitHub-gehosteten Runnern installierte Software.

Voraussetzungen

Du solltest bereits mit der YAML-Syntax vertraut sein und wissen, wie sie mit GitHub Actions verwendet wird. Weitere Informationen finden Sie unter Workflowsyntax für GitHub Actions.

Du solltest über grundlegende Kenntnisse in Bezug auf das .NET Core SDK verfügen. Weitere Informationen findest du unter Erste Schritte mit .NET.

Verwenden einer .NET-Workflowvorlage

Fügen Sie für einen schnellen Einstieg dem Verzeichnis .github/workflows Ihres Repositorys eine Workflowvorlage hinzu.

GitHub bietet eine Workflowvorlage für .NET, die für die meisten .NET-Projekte funktionieren sollte. In den nachfolgenden Abschnitten dieser Anleitung finden Sie Beispiele dafür, wie diese Workflowvorlage angepasst werden kann.

Navigieren Sie auf GitHub zur Hauptseite des Repositorys.
Klicke unter dem Namen deines Repositorys auf Aktionen.
Wenn du bereits über einen Workflow im Repository verfügst, klicke auf Neuer Workflow.
Auf der Seite „Workflow auswählen“ wird eine Auswahl empfohlener Workflowvorlagen angezeigt. Suchen Sie nach "dotnet".

Klicken Sie im Workflow „.NET“ auf Konfigurieren.

Wenn Sie die Workflowvorlage „.NET“ nicht finden, kopieren Sie den folgenden Workflowcode in eine neue Datei namens dotnet.yml im Verzeichnis .github/workflows Ihres Repositorys.

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

Bearbeiten Sie den Workflow nach Bedarf. Ändern Sie beispielsweise die .NET-Version.
Klicke auf Änderungen committen.

Angeben einer .NET-Version

Verwende die Aktion setup-dotnet, um eine vorinstallierte Version des .NET Core SDK für einen von GitHub gehosteten Runner zu verwenden. Mit dieser Aktion wird im Toolcache der jeweiligen Runner nach einer bestimmten Version von .NET gesucht, und die erforderlichen Binärdateien werden zu PATH hinzugefügt. Diese Änderungen bleiben für den Rest des Auftrags beibehalten.

Die Aktion setup-dotnet wird als Methode zur Verwendung von .NET mit GitHub Actions empfohlen, da damit ein konsistentes Verhalten bei verschiedenen Runnern und verschiedenen Version von .NET gewährleistet wird. Wenn du einen selbst gehosteten Runner verwendest, musst du .NET installieren und zu PATH hinzufügen. Weitere Informationen findest du unter der Aktion setup-dotnet.

Verwenden mehrerer .NET-Versionen

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

Verwenden einer bestimmten .NET-Version

Du kannst einen Auftrag so konfigurieren, dass eine bestimmte Version von .NET verwendet wird, z. B. 6.0.22. Alternativ kannst du auch Syntax für semantische Versionierung verwenden, um die neuste Nebenversion abzurufen. In diesem Beispiel wird die neueste Nebenversion von .NET 6 verwendet.

    - 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'

Installieren von Abhängigkeiten

Auf von GitHub gehosteten Runnern ist der Paketmanager NuGet installiert. Du kannst die dotnet-CLI verwenden, um Abhängigkeiten aus der NuGet-Paketregistrierung zu installieren, bevor du deinen Code erstellst und testest. Mit dem folgenden YAML-Code wird beispielsweise das Newtonsoft-Paket installiert.

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

Abhängigkeiten „cachen“ (zwischenspeichern)

Sie können NuGet-Abhängigkeiten für zukünftige Workflows anhand der optionalen Eingabe cache zwischenspeichern. So nimmt zum Beispiel das folgende YAML eine Zwischenspeicherung des NuGet-Ordners global-packages vor und installiert dann das Newtonsoft-Paket. Mit einer zweiten optionalen Eingabe, cache-dependency-path, kann der Pfad zu einer Abhängigkeitsdatei angegeben werden: packages.lock.json.

Weitere Informationen finden Sie unter Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen.

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

Je nach Anzahl der Abhängigkeiten ist es möglicherweise schneller, den Abhängigkeitscache zu verwenden. Bei Projekten mit vielen umfangreichen Abhängigkeiten sollte sich die Leistung erhöhen, da die zum Herunterladen erforderliche Zeit reduziert wird. Bei Projekten mit weniger Abhängigkeiten ist möglicherweise keine signifikante Leistungssteigerung, sondern aufgrund der Art und Weise, wie zwischengespeicherte Abhängigkeiten von NuGet installiert werden, sogar eine geringfügige Leistungsabnahme zu verzeichnen. Die Leistung variiert je nach Projekt.

Deinen Code bauen und testen

Du kannst die gleichen Befehle verwenden, die Du auch lokal verwendest, um Deinen Code zu bauen und zu testen. In diesem Beispiel wird veranschaulicht, wie die Befehle dotnet build und dotnet test in einem Auftrag verwendet werden:

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

Workflow-Daten als Artefakte paketieren

Nach Abschluss eines Workflows kannst du die resultierenden Artefakte für die Analyse hochladen. Zum Beispiel kann es notwendig sein, Logdateien, Core Dumps, Testergebnisse oder Screenshots zu speichern. Im folgenden Beispiel wird gezeigt, wie die Aktion upload-artifact zum Hochladen von Testergebnissen verwendet werden kann.

Weitere Informationen finden Sie unter Speichern und Freigeben von Daten aus einem Workflow.

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

In Paket-Registries veröffentlichen

Du kannst deinen Workflow so konfigurieren, dass das .NET-Paket in einer Paketregistrierung veröffentlicht wird, wenn deine CI-Tests bestanden werden. Du kannst Repositorygeheimnisse verwenden, um alle Token oder Anmeldeinformationen zu speichern, die zum Veröffentlichen deiner Binärdatei erforderlich sind. Im folgenden Beispiel wird ein Paket erstellt und mithilfe von dotnet core cli in GitHub Packages veröffentlicht.

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

In diesem Artikel