setup-dotnet

This action sets up a .NET CLI environment for use in actions by:

• optionally downloading and caching a version(s) of dotnet by SDK version(s) and adding to PATH
• registering problem matchers for error output
• setting up authentication to private package sources like GitHub Packages

Note: GitHub hosted runners have some versions of the .NET SDK preinstalled. Installed versions are subject to change. Please refer to the documentation: Software installed on github hosted runners for .NET SDK versions that are currently available.

Breaking changes in V5

• Upgraded action from node20 to node24

  Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release. see Release Notes

For more details, see the full release notes on the release page

Usage

See action.yml

Basic:

Warning: Unless a concrete version is specified in the

global.json

file, the latest .NET version installed on the runner (including preinstalled versions) will be used by default. Please refer to the documentation for the currently preinstalled .NET SDK versions.

Multiple version installation:

Supported version syntax

The

input supports following syntax:

• A.B.C (e.g 9.0.308, 10.0.100-preview.1.25120.13) - installs exact version of .NET SDK
• A.B or A.B.x (e.g. 8.0, 8.0.x) - installs the latest patch version of .NET SDK on the channel
  8.0
  , including prerelease versions (preview, rc)
• A or A.x (e.g. 8, 8.x) - installs the latest minor version of the specified major tag, including prerelease versions (preview, rc)
• A.B.Cxx (e.g. 8.0.4xx) - available since
  .NET 5.0
  release. Installs the latest version of the specific SDK release, including prerelease versions (preview, rc).

Using the

architecture

input

Using the architecture input, it is possible to specify the required .NET SDK architecture. Possible values:

,

x86

,

arm64

,

amd64

,

arm

,

s390x

,

ppc64le

,

riscv64

. If the input is not specified, the architecture defaults to the host OS architecture (not all of the architectures are available on all platforms).

Example: Install multiple SDK versions for a specific architecture

Using the

dotnet-quality

input

This input sets up the action to install the latest build of the specified quality in the channel. The possible values of

are: daily, signed, validated, preview, ga.

Note:

dotnet-quality

input can be used only with .NET SDK version in 'A.B', 'A.B.x', 'A', 'A.x' and 'A.B.Cxx' formats where the major version is higher than 5. In other cases,

dotnet-quality

input will be ignored.

Using the

global-json-file

input

action can read .NET SDK version from a

global.json

file. Input

global-json-file

is used for specifying the path to the

global.json

. If the file that was supplied to

global-json-file

input doesn't exist, the action will fail with error.

Note: In case both

dotnet-version

and

global-json-file

inputs are used, versions from both inputs will be installed.

Caching NuGet Packages

The action has a built-in functionality for caching and restoring dependencies. It uses toolkit/cache under the hood for caching global packages data but requires less configuration settings. The

input is optional, and caching is turned off by default.

The action searches for NuGet Lock files (

) in the repository root, calculates their hash and uses it as a part of the cache key. If lock file does not exist, this action throws error. Use

cache-dependency-path

for cases when multiple dependency files are used, or they are located in different subdirectories.

Warning: Caching NuGet packages is available since .NET SDK 2.1.500 and 2.2.100 as the NuGet lock file is available only for NuGet 4.9 and above.

Note: This action will only restore

global-packages

folder, so you will probably get the NU1403 error when running

dotnet restore

. To avoid this, you can use

DisableImplicitNuGetFallbackFolder

option.

Reduce caching size

Note: Use

NUGET_PACKAGES

environment variable if available. Some action runners already has huge libraries. (ex. Xamarin)

Caching NuGet packages in monorepos

Matrix Testing

Using

it's possible to use matrix syntax to install several versions of .NET SDK:

Note: Unless a concrete version is specified in the

global.json

file, the latest .NET version installed on the runner (including preinstalled versions) will be used by default. To control this behavior you may want to use temporary

global.json

files:

Matrix testing with temporary global.json creation

Note: When generating a temporary

global.json

within your workflow on Windows, ensure the command is executed using a shell such as PowerShell Core (

pwsh

) or

bash

(where supported) to avoid formatting inconsistencies that could cause .NET commands to fail.

Setting up authentication for nuget feeds

Github Package Registry (GPR)

Azure Artifacts

nuget.org

Note: It's the only way to push a package to nuget.org feed for macOS/Linux machines due to API key config store limitations.

Using the

workloads

input

The

input allows you to install .NET workloads as part of the SDK setup. Workloads provide additional platform tools and dependencies for frameworks. This action automatically runs

dotnet workload update

before installing the specified workloads to ensure manifests are refreshed and existing workloads are updated to their latest compatible versions.

Note: Ensure workloads are compatible with your runner's OS, architecture, and .NET SDK version before enabling workload installation. Some workloads may require additional installation time due to large toolchain downloads.

Outputs and environment variables

Outputs

dotnet-version

Using the dotnet-version output it's possible to get the installed by the action .NET SDK version.

Single version installation

In case of a single version installation, the

output contains the version that is installed by the action.

Multiple version installation

In case of a multiple version installation, the

output contains the latest version that is installed by the action.

Installation from global.json

When the

input is used along with the

global-json-file

input, the

dotnet-version

output contains the version resolved from the

global.json

.

cache-hit

A boolean value to indicate an exact match was found for the cache key (follows actions/cache)

Environment variables

Some environment variables may be necessary for your particular case or to improve logging. Some examples are listed below, but the full list with complete details can be found here: https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-environment-variables

The default values of the

and

NUGET_PACKAGES

environment variables depend on the operation system which is used on a runner:

Example usage of environment variable:

You can also set

to a value based on runtime variables, such as

$HOME/.dotnet

or

${{ runner.temp }}/.dotnet

before the

setup-dotnet

step:

Note: On some self-hosted or large Linux runners, installing .NET under the default

/usr/share/dotnet

location may fail due to insufficient permissions. To ensure successful installation, set

DOTNET_INSTALL_DIR

to a user-writable path.

Recommended permissions

When using the

action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:

License

The scripts and documentation in this project are released under the MIT License

Contributions

Contributions are welcome! See Contributor's Guide