Update README.md
This commit is contained in:
Johnsp123
GitHub
parent
a6be55a915
commit
d7eb0af48a
316
README.md
316
README.md
|
|
@ -1,317 +1 @@
|
|||
# setup-dotnet
|
||||
|
||||
[](https://github.com/actions/setup-dotnet/actions/workflows/basic-validation.yml)
|
||||
[](https://github.com/actions/setup-dotnet/actions/workflows/e2e-tests.yml)
|
||||
|
||||
This action sets up a [.NET CLI](https://github.com/dotnet/sdk) 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](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software)
|
||||
for .NET SDK versions that are currently available.
|
||||
|
||||
## Usage
|
||||
|
||||
See [action.yml](action.yml)
|
||||
|
||||
**Basic**:
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: '3.1.x'
|
||||
- run: dotnet build <my project>
|
||||
```
|
||||
> **Warning**: Unless a concrete version is specified in the [`global.json`](https://learn.microsoft.com/en-us/dotnet/core/tools/global-json) file, **_the latest .NET version installed on the runner (including preinstalled versions) will be used [by default](https://learn.microsoft.com/en-us/dotnet/core/versions/selection#the-sdk-uses-the-latest-installed-version)_**. Please refer to the [documentation](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software) for the currently preinstalled .NET SDK versions.
|
||||
|
||||
**Multiple version installation**:
|
||||
```yml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Setup dotnet
|
||||
uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: |
|
||||
3.1.x
|
||||
5.0.x
|
||||
- run: dotnet build <my project>
|
||||
```
|
||||
## Supported version syntax
|
||||
|
||||
The `dotnet-version` input supports following syntax:
|
||||
|
||||
- **A.B.C** (e.g 6.0.400, 7.0.100-preview.7.22377.5) - installs exact version of .NET SDK
|
||||
- **A.B** or **A.B.x** (e.g. 3.1, 3.1.x) - installs the latest patch version of .NET SDK on the channel `3.1`, including prerelease versions (preview, rc)
|
||||
- **A** or **A.x** (e.g. 3, 3.x) - installs the latest minor version of the specified major tag, including prerelease versions (preview, rc)
|
||||
- **A.B.Cxx** (e.g. 6.0.4xx) - available since `.NET 5.0` release. Installs the latest version of the specific SDK release, including prerelease versions (preview, rc).
|
||||
|
||||
|
||||
## 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 `dotnet-quality` 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.
|
||||
|
||||
```yml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: '6.0.x'
|
||||
dotnet-quality: 'preview'
|
||||
- run: dotnet build <my project>
|
||||
```
|
||||
|
||||
## Using the `global-json-file` input
|
||||
`setup-dotnet` 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.
|
||||
|
||||
```yml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
global-json-file: csharp/global.json
|
||||
- run: dotnet build <my project>
|
||||
working-directory: csharp
|
||||
```
|
||||
|
||||
## Caching NuGet Packages
|
||||
The action has a built-in functionality for caching and restoring dependencies. It uses [toolkit/cache](https://github.com/actions/toolkit/tree/main/packages/cache) under the hood for caching global packages data but requires less configuration settings. The `cache` input is optional, and caching is turned off by default.
|
||||
|
||||
The action searches for [NuGet Lock files](https://learn.microsoft.com/nuget/consume-packages/package-references-in-project-files#locking-dependencies) (`packages.lock.json`) 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](https://learn.microsoft.com/nuget/consume-packages/package-references-in-project-files#locking-dependencies) only for NuGet 4.9 and above.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: 6.x
|
||||
cache: true
|
||||
- run: dotnet restore --locked-mode
|
||||
```
|
||||
|
||||
> **Note**: This action will only restore `global-packages` folder, so you will probably get the [NU1403](https://learn.microsoft.com/nuget/reference/errors-and-warnings/nu1403) error when running `dotnet restore`.
|
||||
> To avoid this, you can use [`DisableImplicitNuGetFallbackFolder`](https://github.com/dotnet/reproducible-builds/blob/abfe986832aa28597d3340b92469d1a702013d23/Documentation/Reproducible-MSBuild/Techniques/DisableImplicitNuGetFallbackFolder.md) option.
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
### Reduce caching size
|
||||
|
||||
> **Note**: Use [`NUGET_PACKAGES`](https://learn.microsoft.com/nuget/reference/cli-reference/cli-ref-environment-variables) environment variable if available. Some action runners already has huge libraries. (ex. Xamarin)
|
||||
|
||||
```yaml
|
||||
env:
|
||||
NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: 6.x
|
||||
cache: true
|
||||
- run: dotnet restore --locked-mode
|
||||
```
|
||||
|
||||
### Caching NuGet packages in monorepos
|
||||
|
||||
```yaml
|
||||
env:
|
||||
NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: 6.x
|
||||
cache: true
|
||||
cache-dependency-path: subdir/packages.lock.json
|
||||
- run: dotnet restore --locked-mode
|
||||
```
|
||||
|
||||
## Matrix Testing
|
||||
Using `setup-dotnet` it's possible to use [matrix syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) to install several versions of .NET SDK:
|
||||
```yml
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
dotnet: [ '2.1.x', '3.1.x', '5.0.x' ]
|
||||
name: Dotnet ${{ matrix.dotnet }} sample
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Setup dotnet
|
||||
uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: ${{ matrix.dotnet }}
|
||||
- name: Execute dotnet
|
||||
run: dotnet build <my project>
|
||||
```
|
||||
>**Note**: Unless a concrete version is specified in the [`global.json`](https://learn.microsoft.com/en-us/dotnet/core/tools/global-json) file, the latest .NET version installed on the runner (including preinstalled versions) will be used [by default](https://learn.microsoft.com/en-us/dotnet/core/versions/selection#the-sdk-uses-the-latest-installed-version). To control this behavior you may want to use temporary `global.json` files:
|
||||
|
||||
**Matrix testing with temporary global.json creation**
|
||||
```yml
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
dotnet: [ '2.1.x', '3.1.x', '5.0.x' ]
|
||||
name: Dotnet ${{ matrix.dotnet }} sample
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Setup dotnet
|
||||
uses: actions/setup-dotnet@v3
|
||||
id: stepid
|
||||
with:
|
||||
dotnet-version: ${{ matrix.dotnet }}
|
||||
- name: Create temporary global.json
|
||||
run: echo '{"sdk":{"version": "${{ steps.stepid.outputs.dotnet-version }}"}}' > ./global.json
|
||||
- name: Execute dotnet
|
||||
run: dotnet build <my project>
|
||||
```
|
||||
## Setting up authentication for nuget feeds
|
||||
|
||||
### Github Package Registry (GPR)
|
||||
```yml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: '3.1.x'
|
||||
source-url: https://nuget.pkg.github.com/<owner>/index.json
|
||||
env:
|
||||
NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
|
||||
- run: dotnet build <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
|
||||
```
|
||||
|
||||
### Azure Artifacts
|
||||
```yml
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
source-url: https://pkgs.dev.azure.com/<your-organization>/_packaging/<your-feed-name>/nuget/v3/index.json
|
||||
env:
|
||||
NUGET_AUTH_TOKEN: ${{secrets.AZURE_DEVOPS_PAT}} # Note, create a secret with this name in Settings
|
||||
- name: Publish the package to Azure Artifacts
|
||||
run: dotnet nuget push <my project>/bin/Release/*.nupkg
|
||||
```
|
||||
|
||||
### nuget.org
|
||||
```yml
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: 3.1.x
|
||||
- name: Publish the package to nuget.org
|
||||
run: dotnet nuget push */bin/Release/*.nupkg -k $NUGET_AUTH_TOKEN -s https://api.nuget.org/v3/index.json
|
||||
env:
|
||||
NUGET_AUTH_TOKEN: ${{ secrets.NUGET_TOKEN }}
|
||||
```
|
||||
> **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.
|
||||
|
||||
# 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 `dotnet-version` output contains the version that is installed by the action.
|
||||
|
||||
```yaml
|
||||
- uses: actions/setup-dotnet@v3
|
||||
id: stepid
|
||||
with:
|
||||
dotnet-version: 3.1.422
|
||||
- run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 3.1.422
|
||||
```
|
||||
|
||||
**Multiple version installation**
|
||||
|
||||
In case of a multiple version installation, the `dotnet-version` output contains the latest version that is installed by the action.
|
||||
|
||||
```yaml
|
||||
- uses: actions/setup-dotnet@v3
|
||||
id: stepid
|
||||
with:
|
||||
dotnet-version: |
|
||||
3.1.422
|
||||
5.0.408
|
||||
- run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 5.0.408
|
||||
```
|
||||
**Installation from global.json**
|
||||
|
||||
When the `dotnet-version` input is used along with the `global-json-file` input, the `dotnet-version` output contains the version resolved from the `global.json`.
|
||||
|
||||
```yaml
|
||||
- uses: actions/setup-dotnet@v3
|
||||
id: stepid
|
||||
with:
|
||||
dotnet-version: |
|
||||
3.1.422
|
||||
5.0.408
|
||||
global-json-file: "./global.json" # contains version 2.2.207
|
||||
- run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 2.2.207
|
||||
```
|
||||
|
||||
### `cache-hit`
|
||||
A boolean value to indicate an exact match was found for the cache key (follows [actions/cache](https://github.com/actions/cache#outputs))
|
||||
|
||||
## 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
|
||||
|
||||
| **Env.variable** | **Description** | **Default value** |
|
||||
| ----------- | ----------- | ----------- |
|
||||
| DOTNET_INSTALL_DIR |Specifies a directory where .NET SDKs should be installed by the action.|*default value for each OS* |
|
||||
| DOTNET_NOLOGO |Removes logo and telemetry message from first run of dotnet cli|*false*|
|
||||
| DOTNET_CLI_TELEMETRY_OPTOUT |Opt-out of telemetry being sent to Microsoft|*false*|
|
||||
| DOTNET_MULTILEVEL_LOOKUP |Configures whether the global install location is used as a fall-back|*true*|
|
||||
| NUGET_PACKAGES |Configures a path to the [NuGet `global-packages` folder](https://learn.microsoft.com/nuget/consume-packages/managing-the-global-packages-and-cache-folders)|*default value for each OS* |
|
||||
|
||||
The default values of the `DOTNET_INSTALL_DIR` and `NUGET_PACKAGES` environment variables depend on the operation system which is used on a runner:
|
||||
| **Operation system** | `DOTNET_INSTALL_DIR` | `NUGET_PACKAGES` |
|
||||
| ----------- | ----------- | ----------- |
|
||||
| **Windows** | `C:\Program Files\dotnet` | `%userprofile%\.nuget\packages` |
|
||||
| **Ubuntu** | `/usr/share/dotnet` | `~/.nuget/packages` |
|
||||
| **macOS** | `/Users/runner/.dotnet` | `~/.nuget/packages` |
|
||||
|
||||
**Example usage of environment variable**:
|
||||
```yml
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
DOTNET_INSTALL_DIR: "path/to/directory"
|
||||
NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
|
||||
steps:
|
||||
- uses: actions/checkout@main
|
||||
- uses: actions/setup-dotnet@v3
|
||||
with:
|
||||
dotnet-version: '3.1.x'
|
||||
cache: true
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
The scripts and documentation in this project are released under the [MIT License](LICENSE)
|
||||
|
||||
## Contributions
|
||||
|
||||
Contributions are welcome! See [Contributor's Guide](docs/contributors.md)
|
||||
|
|
|
|||
Loading…
Reference in New Issue