Building and testing.NET

Introduction

This guide shows you how to build, test, and publish a.NET package.

GitHub-hosted runners have a tools cache with preinstalled software, which includes the.NET Core SDK. For a full list of up-to-date software and the preinstalled versions of.NET Core SDK, seesoftware installed on GitHub-hosted runners.

Prerequisites

You should already be familiar with YAML syntax and how it's used with GitHub Actions. For more information, see "Workflow syntax for GitHub Actions."

We recommend that you have a basic understanding of the.NET Core SDK. For more information, seeGetting started with.NET.

Using a.NET workflow template

To get started quickly, add a workflow template to the.github/workflowsdirectory of your repository.

GitHub provides a workflow template for.NET that should work for most.NET projects. The subsequent sections of this guide give examples of how you can customize this workflow template.

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, clickActions.

   

3. If you already have a workflow in your repository, clickNew workflow.

4. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "dotnet".

5. On the ".NET" workflow, clickConfigure.

6. Edit the workflow as required. For example, change the.NET version.

7. ClickCommit changes.

   Thedotnet.ymlworkflow file is added to the.github/workflowsdirectory of your repository.

Specifying a.NET version

To use a preinstalled version of the.NET Core SDK on a GitHub-hosted runner, use thesetup-dotnetaction. This action finds a specific version of.NET from the tools cache on each runner, and adds the necessary binaries toPATH.These changes will persist for the remainder of the job.

Thesetup-dotnetaction is the recommended way of using.NET with GitHub Actions, because it ensures consistent behavior across different runners and different versions of.NET. If you are using a self-hosted runner, you must install.NET and add it toPATH.For more information, see thesetup-dotnetaction.

Using multiple.NET versions

name:dotnetpackage

on:[push]

jobs:
build:

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

steps:
-uses:actions/checkout@v4
-name:Setupdotnet${{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:Displaydotnetversion
run:dotnet--version

Using a specific.NET version

You can configure your job to use a specific version of.NET, such as6.0.22.Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest minor release of.NET 6.

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

Installing dependencies

GitHub-hosted runners have the NuGet package manager installed. You can use the dotnet CLI to install dependencies from the NuGet package registry before building and testing your code. For example, the YAML below installs theNewtonsoftpackage.

steps:
-uses:actions/checkout@v4
-name:Setupdotnet
uses:actions/setup-dotnet@v3
with:
dotnet-version:'6.0.x'
-name:Installdependencies
run:dotnetaddpackageNewtonsoft.Json--version12.0.1

Caching dependencies

You can cache NuGet dependencies for future workflows using the optionalcacheinput. For example, the YAML below caches the NuGetglobal-packagesfolder, and then installs theNewtonsoftpackage. A second optional input,cache-dependency-path,can be used to specify the path to a dependency file:packages.lock.json.

For more information, see "Caching dependencies to speed up workflows."

steps:
-uses:actions/checkout@v4
-name:Setupdotnet
uses:actions/setup-dotnet@v3
with:
dotnet-version:'6.x'
cache:true
-name:Installdependencies
run:dotnetaddpackageNewtonsoft.Json--version12.0.1

Building and testing your code

You can use the same commands that you use locally to build and test your code. This example demonstrates how to usedotnet buildanddotnet testin a job:

steps:
-uses:actions/checkout@v4
-name:Setupdotnet
uses:actions/setup-dotnet@v3
with:
dotnet-version:'6.0.x'
-name:Installdependencies
run:dotnetrestore
-name:Build
run:dotnetbuild
-name:TestwiththedotnetCLI
run:dotnettest

Packaging workflow data as artifacts

After a workflow completes, you can upload the resulting artifacts for analysis. For example, you may need to save log files, core dumps, test results, or screenshots. The following example demonstrates how you can use theupload-artifactaction to upload test results.

For more information, see "Storing and sharing data from a workflow."

name:dotnetpackage

on:[push]

jobs:
build:

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

steps:
-uses:actions/checkout@v4
-name:Setupdotnet
uses:actions/setup-dotnet@v3
with:
dotnet-version:${{matrix.dotnet-version}}
-name:Installdependencies
run:dotnetrestore
-name:Testwithdotnet
run:dotnettest--loggertrx--results-directory"TestResults-${{ matrix.dotnet-version }}"
-name:Uploaddotnettestresults
uses:actions/upload-artifact@v4
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()}}

Publishing to package registries

You can configure your workflow to publish your.NET package to a package registry when your CI tests pass. You can use repository secrets to store any tokens or credentials needed to publish your binary. The following example creates and publishes a package to GitHub Packages usingdotnet core cli.

name:Uploaddotnetpackage

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 /<owner>/index.json
env:
NUGET_AUTH_TOKEN:${{secrets.GITHUB_TOKEN}}
-run:dotnetbuild--configurationRelease<myproject>
-name:Createthepackage
run:dotnetpack--configurationRelease<myproject>
-name:PublishthepackagetoGPR
run:dotnetnugetpush<myproject>/bin/Release/*.nupkg