diff --git a/README.md b/README.md index a8656e0..4b5f85d 100644 --- a/README.md +++ b/README.md @@ -14,56 +14,76 @@ 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 +## Usage See [action.yml](action.yml) -Basic: +**Basic**: ```yaml steps: - uses: actions/checkout@v3 -- uses: actions/setup-dotnet@v2 +- uses: actions/setup-dotnet@v3 with: - dotnet-version: '3.1.x' # SDK Version to use; x will use the latest version of the 3.1 channel + dotnet-version: '3.1.x' - run: dotnet build ``` -Multiple versions: -> Note: In case multiple versions are installed, the latest .NET version will be used by default unless another version is specified in the `global.json` file. +**Multiple version installation**: ```yml steps: - uses: actions/checkout@v3 - name: Setup dotnet - uses: actions/setup-dotnet@v2 + uses: actions/setup-dotnet@v3 with: dotnet-version: | 3.1.x 5.0.x - run: dotnet build ``` -Preview version: +> **Note**: In case multiple versions are installed, the latest .NET version will be used by default unless another version is specified in the `global.json` file. + +## 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) + + +## 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' and 'A.x' 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@v2 +- uses: actions/setup-dotnet@v3 with: dotnet-version: '6.0.x' - include-prerelease: true + dotnet-quality: 'preview' - run: dotnet build ``` -global.json in a subdirectory: + +## 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@v2 +- uses: actions/setup-dotnet@v3 with: global-json-file: csharp/global.json - run: dotnet build working-directory: csharp ``` -Matrix Testing: -```yaml +## 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 @@ -74,38 +94,20 @@ jobs: steps: - uses: actions/checkout@v3 - name: Setup dotnet - uses: actions/setup-dotnet@v2 + uses: actions/setup-dotnet@v3 with: dotnet-version: ${{ matrix.dotnet }} - run: dotnet build ``` +## Setting up authentication for nuget feeds -Side by Side Testing: -```yaml -jobs: - build: - runs-on: ubuntu-latest - name: Dotnet Side by Side testing sample - steps: - - uses: actions/checkout@v3 - - name: Setup dotnet - uses: actions/setup-dotnet@v2 - with: - dotnet-version: | - 2.1.x - 3.1.x - - run: dotnet build - - run: dotnet test -``` - -Authentication for nuget feeds: -```yaml +### Github Package Registry (GPR) +```yml steps: - uses: actions/checkout@v3 -# Authenticates packages to push to GPR -- uses: actions/setup-dotnet@v2 +- uses: actions/setup-dotnet@v3 with: - dotnet-version: '3.1.x' # SDK Version to use. + dotnet-version: '3.1.x' source-url: https://nuget.pkg.github.com//index.json env: NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} @@ -114,19 +116,22 @@ steps: run: dotnet pack --configuration Release - name: Publish the package to GPR run: dotnet nuget push /bin/Release/*.nupkg +``` -# Authenticates packages to push to Azure Artifacts -- uses: actions/setup-dotnet@v2 +### Azure Artifacts +```yml +- uses: actions/setup-dotnet@v3 with: source-url: https://pkgs.dev.azure.com//_packaging//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 /bin/Release/*.nupkg +``` -# Authenticates packages to push to nuget.org. -# It's only the way to push a package to nuget.org feed for macOS/Linux machines due to API key config store limitations. -- uses: actions/setup-dotnet@v2 +### nuget.org +```yml +- uses: actions/setup-dotnet@v3 with: dotnet-version: 3.1.x - name: Publish the package to nuget.org @@ -134,32 +139,35 @@ steps: 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. -## Environment Variables to use with dotnet +## 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 -- DOTNET_NOLOGO - removes logo and telemetry message from first run of dotnet cli (default: false) -- DOTNET_CLI_TELEMETRY_OPTOUT - opt-out of telemetry being sent to Microsoft (default: false) -- DOTNET_MULTILEVEL_LOOKUP - configures whether the global install location is used as a fall-back (default: true) +| **Env.variable** | **Description** | **Default value** | +| ----------- | ----------- | ----------- | +| 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*| -Example usage: -```yaml +**Example usage**: +```yml build: runs-on: ubuntu-latest env: DOTNET_NOLOGO: true steps: - uses: actions/checkout@main - - uses: actions/setup-dotnet@v2 + - uses: actions/setup-dotnet@v3 with: - dotnet-version: '3.1.x' # SDK Version to use. + dotnet-version: '3.1.x' ``` -# License +## License The scripts and documentation in this project are released under the [MIT License](LICENSE) -# Contributions +## Contributions -Contributions are welcome! See [Contributor's Guide](docs/contributors.md) +Contributions are welcome! See [Contributor's Guide](docs/contributors.md)