{"meta":{"title":"Building and testing .NET","intro":"Learn how to create a continuous integration (CI) workflow to build and test your .NET project.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/enterprise-server@3.19/actions","title":"GitHub Actions"},{"href":"/en/enterprise-server@3.19/actions/tutorials","title":"Tutorials"},{"href":"/en/enterprise-server@3.19/actions/tutorials/build-and-test-code","title":"Build and test code"},{"href":"/en/enterprise-server@3.19/actions/tutorials/build-and-test-code/net","title":".NET"}],"documentType":"article"},"body":"# Building and testing .NET\n\nLearn how to create a continuous integration (CI) workflow to build and test your .NET project.\n\n> \\[!NOTE]\n> GitHub Enterprise Server users should use self-hosted runners. GitHub-hosted runners are **not** supported.\n\n## Introduction\n\nThis guide shows you how to build, test, and publish a .NET package.\n\nGitHub-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, see [software installed on GitHub-hosted runners](/en/enterprise-server@3.19/actions/using-github-hosted-runners/about-github-hosted-runners).\n\n## Prerequisites\n\nYou should already be familiar with YAML syntax and how it's used with GitHub Actions. For more information, see [Workflow syntax for GitHub Actions](/en/enterprise-server@3.19/actions/using-workflows/workflow-syntax-for-github-actions).\n\nWe recommend that you have a basic understanding of the .NET Core SDK. For more information, see [Getting started with .NET](https://dotnet.microsoft.com/learn).\n\n## Using a .NET workflow template\n\nTo get started quickly, add a workflow template to the `.github/workflows` directory of your repository.\n\nGitHub 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.\n\n1. On GitHub, navigate to the main page of the repository.\n\n2. Under your repository name, click ** Actions**.\n\n \n\n3. If you already have a workflow in your repository, click **New workflow**.\n\n4. The \"Choose a workflow\" page shows a selection of recommended workflow templates. Search for \"dotnet\".\n\n5. On the \".NET\" workflow, click **Configure**.\n\n If you don't find the \".NET\" workflow template, copy the following workflow code to a new file called `dotnet.yml` in the `.github/workflows` directory of your repository.\n\n ```yaml copy\n name: .NET\n\n on:\n push:\n branches: [ \"main\" ]\n pull_request:\n branches: [ \"main\" ]\n\n jobs:\n build:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n - name: Setup .NET\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: 6.0.x\n - name: Restore dependencies\n run: dotnet restore\n - name: Build\n run: dotnet build --no-restore\n - name: Test\n run: dotnet test --no-build --verbosity normal\n ```\n\n6. Edit the workflow as required. For example, change the .NET version.\n\n7. Click **Commit changes**.\n\n## Specifying a .NET version\n\nTo use a preinstalled version of the .NET Core SDK on a GitHub-hosted runner, use the `setup-dotnet` action. This action finds a specific version of .NET from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job.\n\nThe `setup-dotnet` action 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 to `PATH`. For more information, see the [`setup-dotnet`](https://github.com/marketplace/actions/setup-net-core-sdk) action.\n\n### Using multiple .NET versions\n\n```yaml\nname: dotnet package\n\non: [push]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n strategy:\n matrix:\n dotnet-version: [ '3.1.x', '6.0.x' ]\n\n steps:\n - uses: actions/checkout@v6\n - name: Setup dotnet ${{ matrix.dotnet-version }}\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: ${{ matrix.dotnet-version }}\n # You can test your matrix by printing the current dotnet version\n - name: Display dotnet version\n run: dotnet --version\n```\n\n### Using a specific .NET version\n\nYou can configure your job to use a specific version of .NET, such as `6.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.\n\n```yaml\n - name: Setup .NET 6.x\n uses: actions/setup-dotnet@v4\n with:\n # Semantic version range syntax or exact version of a dotnet version\n dotnet-version: '6.x'\n```\n\n## Installing dependencies\n\nGitHub-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 the `Newtonsoft` package.\n\n```yaml\nsteps:\n- uses: actions/checkout@v6\n- name: Setup dotnet\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: '6.0.x'\n- name: Install dependencies\n run: dotnet add package Newtonsoft.Json --version 12.0.1\n```\n\n### Caching dependencies\n\nYou can cache NuGet dependencies for future workflows using the optional `cache` input. For example, the YAML below caches the NuGet `global-packages` folder, and then installs the `Newtonsoft` package. A second optional input, `cache-dependency-path`, can be used to specify the path to a dependency file: `packages.lock.json`.\n\nFor more information, see [Dependency caching reference](/en/enterprise-server@3.19/actions/using-workflows/caching-dependencies-to-speed-up-workflows).\n\n```yaml\nsteps:\n- uses: actions/checkout@v6\n- name: Setup dotnet\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: '6.x'\n cache: true\n- name: Install dependencies\n run: dotnet add package Newtonsoft.Json --version 12.0.1\n```\n\n> \\[!NOTE]\n> Depending on the number of dependencies, it may be faster to use the dependency cache. Projects with many large dependencies should see a performance increase as it cuts down the time required for downloading. Projects with fewer dependencies may not see a significant performance increase and may even see a slight decrease due to how NuGet installs cached dependencies. The performance varies from project to project.\n\n## Building and testing your code\n\nYou can use the same commands that you use locally to build and test your code. This example demonstrates how to use `dotnet build` and `dotnet test` in a job:\n\n```yaml\nsteps:\n- uses: actions/checkout@v6\n- name: Setup dotnet\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: '6.0.x'\n- name: Install dependencies\n run: dotnet restore\n- name: Build\n run: dotnet build --no-restore\n- name: Test with the dotnet CLI\n run: dotnet test --no-build\n```\n\n## Packaging workflow data as artifacts\n\nAfter 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 the `upload-artifact` action to upload test results.\n\nFor more information, see [Store and share data with workflow artifacts](/en/enterprise-server@3.19/actions/using-workflows/storing-workflow-data-as-artifacts).\n\n```yaml\nname: dotnet package\n\non: [push]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n strategy:\n matrix:\n dotnet-version: [ '3.1.x', '6.0.x' ]\n\n steps:\n - uses: actions/checkout@v6\n - name: Setup dotnet\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: ${{ matrix.dotnet-version }}\n - name: Install dependencies\n run: dotnet restore\n - name: Test with dotnet\n run: dotnet test --no-restore --logger trx --results-directory \"TestResults-${{ matrix.dotnet-version }}\"\n - name: Upload dotnet test results\n uses: actions/upload-artifact@v3\n with:\n name: dotnet-results-${{ matrix.dotnet-version }}\n path: TestResults-${{ matrix.dotnet-version }}\n # Use always() to always run this step to publish test results when there are test failures\n if: ${{ always() }}\n```\n\n## Publishing to package registries\n\nYou 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 using `dotnet core cli`.\n\n```yaml\nname: Upload dotnet package\n\non:\n release:\n types: [created]\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n permissions:\n packages: write\n contents: read\n steps:\n - uses: actions/checkout@v6\n - uses: actions/setup-dotnet@v4\n with:\n dotnet-version: '6.0.x' # SDK Version to use.\n source-url: https://nuget.pkg.github.com//index.json\n env:\n NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}\n - run: dotnet build --configuration Release \n - name: Create the package\n run: dotnet pack --configuration Release \n - name: Publish the package to GPR\n run: dotnet nuget push /bin/Release/*.nupkg\n```"}