mirror of
https://github.com/actions/setup-dotnet.git
synced 2026-11-21 11:06:28 +00:00
Add support for installing .NET runtimes alongside SDKs (#806)
* Add support for installing .NET runtimes alongside SDKs * Add tests for preview runtime pairing and fallback logic in installer
This commit is contained in:
1 parent
0f4a354dd5
commit
84bc3a3451
8 files changed
+821
-40
No files matched your search
@@ -53,15 +53,41 @@ steps:
|
||||
9.0.x
|
||||
- run: dotnet build <my project>
|
||||
```
|
||||
|
||||
## Installing additional runtimes
|
||||
|
||||
The `dotnet-runtime` input allows you to install .NET runtimes separately from SDKs. This is useful for multi-targeting scenarios where you need one SDK version but multiple runtime versions.
|
||||
|
||||
When `dotnet-runtime` is specified, both the .NET Runtime (Microsoft.NETCore.App) and the ASP.NET Core Runtime (Microsoft.AspNetCore.App) are installed for each specified version. Before .NET Core 2.1, only the base runtime is installed.
|
||||
|
||||
For exact preview/RC versions, release metadata selects the matching ASP.NET Core build. If the mapping is unavailable, the action warns and tries the same exact version; installer failures remain fatal. `dotnet-quality` continues to apply to both SDKs and runtimes.
|
||||
|
||||
`dotnet-runtime` doesn't change how the SDK is selected, so it doesn't suppress the SDK installation from `global.json`. For example, if only `dotnet-runtime` is set and the repository root contains a `global.json` file, the SDK version specified in that file is installed as well, and the `dotnet-version` output contains that SDK version.
|
||||
|
||||
**Example: Install SDK 10 with runtimes 8 and 9**:
|
||||
```yml
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- name: Setup dotnet
|
||||
uses: actions/setup-dotnet@v6
|
||||
with:
|
||||
dotnet-version: '10.0.x'
|
||||
dotnet-runtime: |
|
||||
8.0.x
|
||||
9.0.x
|
||||
- run: dotnet build <my project>
|
||||
- run: dotnet test <my project>
|
||||
```
|
||||
|
||||
## Supported version syntax
|
||||
|
||||
The `dotnet-version` input supports following syntax:
|
||||
The `dotnet-version` and `dotnet-runtime` inputs support the 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.B.C** (e.g 9.0.308 for an SDK, 9.0.9 for a runtime, 10.0.100-preview.1.25120.13) - installs exact version of .NET SDK or runtime
|
||||
- **A.B** or **A.B.x** (e.g. 8.0, 8.0.x) - installs the latest patch version 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).
|
||||
- **latest** - dynamically resolves to the highest active .NET SDK version. By default, it installs the latest **stable (GA)** version (excluding previews and end-of-life releases). Can be combined with `dotnet-channel` and `dotnet-quality`.
|
||||
- **A.B.Cxx** (e.g. 8.0.4xx) - `dotnet-version` only, available since `.NET 5.0` release. Installs the latest version of the specific SDK feature band, including prerelease versions (preview, rc). Feature bands apply only to SDKs, so `dotnet-runtime` rejects this syntax; use **A.B** or **A.B.x** (e.g. 8.0.x) for the latest runtime patch instead.
|
||||
- **latest** - dynamically resolves to the highest active .NET version. By default, it installs the latest **stable (GA)** version (excluding previews and end-of-life releases). For both `dotnet-version` and `dotnet-runtime`, it can be combined with `dotnet-channel` and `dotnet-quality`.
|
||||
|
||||
## Using with `dotnet-channel` input
|
||||
|
||||
@@ -74,7 +100,7 @@ The optional `dotnet-channel` input specifies the source channel for the install
|
||||
| `A.B` (e.g. `8.0`) | A specific release channel |
|
||||
| `A.B.Cxx` (e.g. `8.0.1xx`) | A specific SDK release (available since 5.0) |
|
||||
|
||||
> **Note**: The `dotnet-channel` input is only applied when `dotnet-version` is set to `latest`. If used with a specific version, a warning will be logged and the channel input will be ignored.
|
||||
> **Note**: The `dotnet-channel` input applies to `latest` entries in `dotnet-version` or `dotnet-runtime`; otherwise it is ignored with a warning. For `dotnet-runtime`, an `A.B.Cxx` channel uses its `A.B` channel (e.g. `8.0.1xx` installs the latest `8.0` runtime), without affecting SDK installation.
|
||||
|
||||
**Install latest LTS version:**
|
||||
```yaml
|
||||
@@ -357,6 +383,8 @@ An installed SDK is reused only when it matches the requested spec (`A.B.C`, `A.
|
||||
|
||||
When the request comes from `global.json`, the SDK is picked the way the .NET resolver picks one: `latestPatch`, `latestFeature`, `latestMinor` and `latestMajor` take the **highest** SDK the policy allows, while `feature`, `minor` and `major` roll forward to the **nearest** higher feature band, minor or major and then take its latest patch. `patch` — the default when `rollForward` is omitted — prefers the declared version, otherwise the latest patch in its band. `disable` and a prerelease `sdk.version` require an exact match, and `allowPrerelease` is not used: `dotnet-quality` is the only prerelease control.
|
||||
|
||||
`check-latest: false` also reuses matching runtime pairs, including those installed by an SDK. Reuse requires each framework's `.deps.json` and a runnable `dotnet` executable; a preview ASP.NET Core runtime pairs with the .NET runtime named in its `runtimeconfig.json`, and before .NET Core 2.1, only the base framework is required. Incomplete pairs, cross-architecture requests, LTS/STS channels and bare wildcards use the online path, so this is not a guarantee of offline operation. The online installer skips versions that are already present, so falling back does not repair a damaged installation.
|
||||
|
||||
### Setting `check-latest` from the environment
|
||||
|
||||
When the input is not set, the action reads the `DOTNET_CHECK_LATEST` environment variable (`true` or `false`, case-insensitive; an unsupported value warns and is ignored), which covers workflows you cannot edit. Setting it on a self-hosted runner alongside SDKs preinstalled under [`DOTNET_INSTALL_DIR`](#environment-variables) lets those workflows run without reaching `aka.ms`, `builds.dotnet.microsoft.com` or `ci.dot.net`. It applies to every job on that runner, so a dedicated runner is recommended; any workflow can still override it with an explicit `check-latest` input.
|
||||
|
||||
Reference in new issue
Block a user