UseDotNet@2 - Use dotnet v2 task

Use this task to acquire a specific version of the .NET Core SDK from the internet or the local cache and add it to the PATH. Use this task to change the version of .NET Core that is used in subsequent tasks. This task also provides proxy support.

Syntax

# Use .NET Core v2
# Acquires a specific version of the .NET Core SDK from the internet or the local cache and adds it to the PATH. Use this task to change the version of .NET Core used in subsequent tasks. Additionally provides proxy support.
- task: UseDotNet@2
  inputs:
    #packageType: 'sdk' # 'runtime' | 'sdk'. Package to install. Default: sdk.
    #useGlobalJson: false # boolean. Optional. Use when packageType = sdk. Use global json. Default: false.
    #workingDirectory: # string. Optional. Use when useGlobalJson = true. Working Directory. 
    #version: # string. Optional. Use when useGlobalJson = false || packageType = runtime. Version. 
    #includePreviewVersions: false # boolean. Optional. Use when useGlobalJson = false  || packageType = runtime. Include Preview Versions. Default: false.
    #requestTimeout: '300000' # string. Set timeout for package download request. Default: 300000.
  # Advanced
    #vsVersion: # string. Compatible Visual Studio version. 
    #installationPath: '$(Agent.ToolsDirectory)/dotnet' # string. Path To Install .Net Core. Default: $(Agent.ToolsDirectory)/dotnet.
    #performMultiLevelLookup: false # boolean. Perform Multi Level Lookup. Default: false.

Inputs

packageType - Package to install
string. Allowed values: runtime, sdk (SDK (contains runtime)). Default value: sdk.

Specifies whether to install only the .NET runtime or the SDK.

useGlobalJson - Use global json
boolean. Optional. Use when packageType = sdk. Default value: false.

Installs all SDKs from global.json files. These files are searched from system.DefaultWorkingDirectory. You can change the search root path by setting the working directory input.

The 6.x and 6.1.x format (using .x as a wildcard) described in the UseDotNet@2.version input is for use in the version input in the task, not the sdk.version parameter in global.json.

If you receive an error message like ##[error]Version 6.0.x is not allowed. Allowed version types are: majorVersion.x, majorVersion.minorVersion.x, majorVersion.minorVersion.patchVersion. More details: Only explicit versions and accepted, such as: 2.2.301. Version: 6.0.x is not valid. and you are using global.json, check the sdk.version in your global.json.

For more information on global.json, see Select the .NET version to use.

workingDirectory - Working Directory
string. Optional. Use when useGlobalJson = true.

Specifies the path from where global.json files should be searched when using useGlobalJson. If the value is empty, system.DefaultWorkingDirectory will be considered as the root path.

version - Version
string. Optional. Use when useGlobalJson = false || packageType = runtime.

Specifies the version of the .NET Core SDK or runtime to install. The version value formats are shown with examples:

• 2.x: Installs the latest SDK or runtime with the specified major version, 2.
• 3.1.x: Installs the latest SDK or runtime with the specified major and minor versions, 3 and 1.
• 3.1.402: Installs the specified SDK or runtime version, 3.1.402.

The version values for SDK or runtime installations are in the releases.json file. The link to the releases.json of a major/minor version is in the releases-index file. For example, the link to the releases.json file for version 3.1.

vsVersion - Compatible Visual Studio version
string.

Specifies a compatible Visual Studio version for a corresponding .NET Core SDK installation. The value must be a complete version number, such as 16.6.4, which contains a major version, a minor version, and a patch number.

The version values for SDK or runtime installations, which are used for the version string, are in the releases.json file. The link to the releases.json of a major/minor version is in the releases-index file. For example, the link to the releases.json file for version 3.1.

includePreviewVersions - Include Preview Versions
boolean. Optional. Use when useGlobalJson = false || packageType = runtime. Default value: false.

If set to true, includes preview versions when the task searches for latest runtime/SDK versions, such as searching for 2.2.x or 3.1.x. This setting is ignored if you specify an exact version, such as 3.0.100-preview3-010431.

installationPath - Path To Install .Net Core
string. Default value: $(Agent.ToolsDirectory)/dotnet.

Specifies where the .NET Core SDK/Runtime should be installed. Different paths can have the following impact on .NET's behavior.

• $(Agent.ToolsDirectory): Using this path caches the installation on the agent, as this directory is not cleaned across pipelines. All pipelines running on the agent have access to the previously installed versions.
• $(Agent.TempDirectory): Using this path ensures that a pipeline doesn't use a cached version of .NET Core, as this folder is cleaned after each pipeline.
• Another path: You can use any path if the agent process has access to the path. This will change the state of the machine and impact all processes running on it.

Note

You can use the Multi-Level Lookup setting, performMultiLevelLookup, to configure how the .NET host searches for versions.

performMultiLevelLookup - Perform Multi Level Lookup
boolean. Default value: false.

Configures the behavior of the .NET host process when it searches for a suitable shared framework. The values are:

• false: The host process searches only for versions that are present in the folder that is specified by the task.
• true: The host process will search in predefined global locations using multi-level lookup. The default global locations are:
  • C:\Program Files\dotnet (64-bit processes)
  • C:\Program Files (x86)\dotnet (32-bit processes)

Learn more about multi-level SharedFX lookup.

Note

performMultiLevelLookup is only applicable to Windows based agents.

requestTimeout - Set timeout for package download request
string. Default value: 300000.

Provide a timeout value for HTTP requests that the task makes to obtain the .NET package. The value is in milliseconds. Default is 300000 milliseconds (5 minutes). Cannot be more than 600000 milliseconds (10 minutes).

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

The Use .NET Core task acquires a specific version of .NET Core from internet or the tools cache and adds it to the PATH of the Azure Pipelines Agent (hosted or private). Use this task to change the version of .NET Core used in subsequent tasks like DotNetCoreCLI@2. Adding this task before the DotNetCoreCLI@2 in a build definition ensures that the version would be available at the time of building, testing and publishing your app.

The tool installer approach also allows you to decouple from the agent update cycles. If the .NET Core version you are looking for is missing from the Azure Pipelines agent (Hosted or Private), then you can use this task to get the right version installed on the agent.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	Running this task satisfies the following demands for any subsequent tasks in the same job: DotNetCore
Command restrictions	Any
Settable variables	Any
Agent version	2.144.0 or greater
Task category	Tool