{ "id": "B0CE7256-7898-45D3-9CB5-176B752BFEA6", "name": "UseDotNet", "friendlyName": "Use .NET Core", "description": "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.", "category": "Tool", "helpUrl": "https://aka.ms/AA4xgy0", "helpMarkDown": "[Learn more about this task](https://aka.ms/AA4xgy0)", "runsOn": [ "Agent", "DeploymentGroup" ], "author": "Microsoft Corporation", "version": { "Major": 2, "Minor": 274, "Patch": 2 }, "satisfies": [ "DotNetCore" ], "demands": [], "minimumAgentVersion": "2.144.0", "ecosystem": "dotnet", "instanceNameFormat": "Use .NET Core $(packageType) $(version)", "releaseNotes": "
  • Support for installing multiple versions side by side.
  • Support for patterns in version to fetch latest in minor/major version.
  • Restrict Multi-level lookup
  • Installs NuGet and provides proxy support.
  • Installs sdk versions from `global.json` file(s)
    • ", "groups": [ { "name": "advanced", "displayName": "Advanced", "isExpanded": true } ], "inputs": [ { "name": "packageType", "type": "pickList", "label": "Package to install", "defaultValue": "sdk", "required": false, "helpMarkDown": "Please select whether to install only runtime or SDK.", "options": { "runtime": "Runtime", "sdk": "SDK (contains runtime)" } }, { "name": "useGlobalJson", "type": "boolean", "label": "Use global json", "defaultValue": false, "required": false, "helpMarkDown": "Select this option to install all SDKs from global.json files. These files are searched from system.DefaultWorkingDirectory. You can change the search root path by setting working directory input.", "visibleRule": "packageType = sdk" }, { "name": "workingDirectory", "type": "filePath", "label": "Working Directory", "helpMarkDown": "Specify path from where global.json files should be searched when using `Use global json`. If empty, `system.DefaultWorkingDirectory` will be considered as the root path.", "required": "false", "visibleRule": "useGlobalJson = true" }, { "name": "version", "type": "string", "label": "Version", "defaultValue": "", "required": false, "helpMarkDown": "Specify version of .NET Core SDK or runtime to install.
    Versions can be given in the following formats
  • 2.x => Install latest in major version.
  • 2.2.x => Install latest in major and minor version
  • 2.2.104 => Install exact version

    • Find the value of `version` for installing SDK/Runtime, from the releases.json. The link to releases.json of that major.minor version can be found in [**releases-index file.**](https://builds.dotnet.microsoft.com/dotnet/release-metadata/releases-index.json). Like link to releases.json for 2.2 version is https://builds.dotnet.microsoft.com/dotnet/release-metadata/2.2/releases.json", "visibleRule": "useGlobalJson = false || packageType = runtime" }, { "name": "vsVersion", "type": "string", "label": "Compatible Visual Studio version", "defaultValue": "", "required": false, "groupName": "advanced", "helpMarkDown": "Specify version of compatible visual studio for which .NET core sdk to install. Specifiy complete vs-version like 16.6.4 containing major version, minor version and patch number.Find the value of `version` for installing SDK/Runtime, from the releases.json. The link to releases.json of that major.minor version can be found in [**releases-index file.**](https://builds.dotnet.microsoft.com/dotnet/release-metadata/releases-index.json)" }, { "name": "checkForExistingVersion", "type": "boolean", "label": "Check for existing installation", "defaultValue": "false", "required": false, "helpMarkDown": "Select if you want to detect if the specified version is already installed before attempting to download. Use only when installationPath is Empty i.e. set to default value", "groupName": "advanced" }, { "name": "includePreviewVersions", "type": "boolean", "label": "Include Preview Versions", "defaultValue": "false", "required": false, "helpMarkDown": "Select if you want preview versions to be included while searching for latest versions, such as while searching 2.2.x. This setting is ignored if you specify an exact version, such as: 3.0.100-preview3-010431", "visibleRule": "useGlobalJson = false || packageType = runtime" }, { "name": "installationPath", "type": "string", "label": "Path To Install .Net Core", "defaultValue": "$(Agent.ToolsDirectory)/dotnet", "required": false, "groupName": "advanced", "helpMarkDown": "Specify where .Net Core SDK/Runtime should be installed. Different paths can have the following impact on .Net's behavior.
  • $(Agent.ToolsDirectory): This makes the version to be cached on the agent since this directory is not cleanup up across pipelines. All pipelines running on the agent, would have access to the versions installed previously using the agent.
  • $(Agent.TempDirectory): This can ensure that a pipeline doesn't use any cached version of .Net core since this folder is cleaned up after each pipeline.
  • Any other path: You can configure any other path given the agent process has access to the path. This will change the state of the machine and impact all processes running on it.
    Note that you can also configure Multi-Level Lookup setting which can configure .Net host's probing for a suitable version." }, { "name": "performMultiLevelLookup", "type": "boolean", "label": "Perform Multi Level Lookup", "groupName": "advanced", "defaultValue": false, "required": false, "helpMarkDown": "This input is only applicable to Windows based agents. This configures the behavior of .Net host process for looking up a suitable shared framework.
  • unchecked: Only versions present in the folder specified in this task would be looked by the host process.
  • checked: The host will attempt to look in pre-defined global locations using multi-level lookup.
    The default global locations are:
    For Windows:
    C:\\Program Files\\dotnet (64-bit processes)
    C:\\Program Files (x86)\\dotnet (32-bit process)
    • You can read more about it [**HERE**](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/multilevel-sharedfx-lookup.md).
    " }, { "name": "requestTimeout", "type": "int", "label": "Set timeout for package download request", "defaultValue": 300000, "required": false, "helpMarkDown": "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)." } ], "execution": { "Node10": { "target": "usedotnet.js" }, "Node16": { "target": "usedotnet.js", "argumentFormat": "" }, "Node20_1": { "target": "usedotnet.js", "argumentFormat": "" }, "Node24": { "target": "usedotnet.js", "argumentFormat": "" } }, "messages": { "ToolFailed": "Tool install failed: %s", "ImplicitVersionNotSupported": "Version should be a valid and explicit version: %s", "getMachinePlatformFailed": "Failed to get machine platform details. Error: %s.", "getDownloadUrlsFailed": "Failed to get download URLS. Error: %s.", "UsingCachedTool": "Cached copy of .NET Core exists. No need to install afresh. Cached tool location: %s.", "CheckingToolCache": "Checking if a cached copy exists for this version...", "InstallingAfresh": "The cache does not contain the requested version of .NET Core. Downloading and installing it now.", "GettingDownloadUrl": "Getting URL to download .NET Core %s version: %s.", "CouldNotDetectPlatform": "Could not detect the machine's OS", "NullDownloadUrls": "Could not construct download URL. Please ensure that specified version %s is valid.", "DownloadingUrl": "Downloading .NET Core package from URL: %s", "ExtractingPackage": "Extracting downloaded package %s.", "CachingTool": "Caching this installed tool.", "SuccessfullyInstalled": "Successfully installed .NET Core %s version %s.", "ToolToInstall": "Tool to install: .NET Core %s version %s.", "PrimaryPlatform": "Detected platform (Primary): %s", "LegacyPlatform": "Detected platform (Legacy): %s", "CouldNotDownload": "Could not download installation package from this URL: %s Error: %s", "FailedToDownloadPackage": "Failed to download package for installation", "PrependGlobalToolPath": "Creating global tool path and pre-pending to PATH.", "VersionsFileMalformed": "The specified version's download links are not correctly formed in the supported versions document => %s/", "MatchingVersionNotFound": "No matching %s version could be found for specified version: %s Kindly note the preview versions are only considered in latest version searches if Include Preview Versions checkbox is checked.", "UnableToAccessPath": "Unable to access path: %s. Error: %s. Please make sure that agent process has access to the path.", "VersionCanNotBeDownloadedFromUrl": "Version: %s cannot be downloaded from URL: %s. Either the URL or version is incorrect.", "CopyingFoldersIntoPath": "Copying all root folders into installation path: %s", "CopyingFilesIntoPath": "Copying root files (such as dotnet.exe) into installation path: %s", "FailedToCopyTopLevelFiles": "Failed to copy root files into installation path: %s. Error: %s", "FailedWhileInstallingVersionAtPath": "Failed while installing version: %s at path: %s with error: %s", "ExplicitVersionRequired": "Version: %s is not allowed. Versions to be installed should be of format: major.minor.patchversion. For example: 2.2.1", "VersionFoundInCache": "Version: %s was found in cache.", "VersionNotFoundInCache": "Version %s was not found in cache.", "CreatingInstallationCompeleteFile": "Creating installation complete marker file for .Net core %s version %s", "CannotFindRuntimeVersionForCompletingInstallation": "Cannot find runtime version for package type: %s with version: %s", "PathNotFoundException": "Path: %s could not be located/found. Make sure the path exists.", "VersionIsLocalLatest": "Version: %s is the latest among the versions present at path: %s", "VersionIsNotLocalLatest": "Version: %s is not the latest among the versions present at %s", "DownloadUrlForMatchingOsNotFound": "Download URL for .Net Core %s version %s could not be found for the following OS platforms (rid): %s", "ExceptionWhileDownloadOrReadReleasesIndex": "Failed to download or parse releases-index.json with error: %s", "MatchingVersionForUserInputVersion": "Found version %s in channel %s for user specified version spec: %s", "UrlForReleaseChannelNotFound": "Could not find URL for releases.json of channel version: %s", "NoSuitableChannelWereFound": "Channel corresponding to version %s could not be found.", "DetectingPlatform": "Detecting OS platform to find correct download package for the OS.", "FailedInDetectingMachineArch": "Failed while detecting machine OS platform with error: %s", "runtimeVersionPropertyNotFound": "runtime-version property could not be found for .Net Core %s version %s.", "VersionNotFound": "%s version matching: %s could not be found", "VersionNotAllowed": "Version %s is not allowed. Allowed version types are: majorVersion.x, majorVersion.minorVersion.x, majorVersion.minorVersion.patchVersion. More details: %s", "VersionsCanNotBeCompared": "Versions %s and %s cannot be compared. Both versions should be explicit.", "FileNameNotCorrectCompleteFileName": "File name %s is not a correct '.complete' file.", "ChannelVersionsNotComparable": "Channel versions %s and %s can not be compared. They both must have numeric major and minor versions.", "LookingForVersionInChannel": "Searching for version in channel %s", "FallingBackToAdjacentChannels": "Version %s could not be found in its channel, will now search in adjacent channels.", "ErrorWhileSettingDotNetToolPath": "Failed while prepending .Net Core Tool path to PATH envrionment variable. Error: %s", "RequiredChannelVersionForSpec": "Finding channel %s for version %s", "ErrorWhileGettingVersionFromChannel": "Failed while getting version %s from channel %s with error: %s", "ComparingInstalledFolderVersions": "Comparing if version being installed %s is greater than already installed version with folder name %s", "ComparingInstalledFileVersions": "Comparing if version being installed %s is greater than already installed version with version complete file name %s", "InvalidChannelObject": "Object cannot be used as Channel, required properties such as channel-version, releases.json is missing.", "ReleasesIndexBodyIncorrect": "Parsed releases index body is not correct. Kindly see if the releases-index section is not empty in the file.", "InvalidVersionObject": "Releases.json has a release with invalid %s object: %s", "InvalidVersion": "Invalid version specified %s", "FilesDataIsIncorrectInVersion": "In release %s for version %s, File data is incorrect (might have missing required fields, such as name, rid and url): %s", "VersionFilesDataIncorrect": "Version's files data is missing or has missing required fields.", "VersionInformationNotComplete": "Version: %s required information is not complete in releases.json file. Error: %s", "FailedWhileExtractingPacakge": "Failed while extracting downloaded package with error: %s", "InstallingNuGetVersion": "Installing NuGet version %s", "FailureWhileInstallingNuGetVersion": "Failed while installing NuGet version. Error: %s", "SettingUpNugetProxySettings": "Setting up proxy configuration for NuGet.", "GlobalJsonFound": "Found a global.json at path: %s", "GlobalJsonSdkVersion": "SDK version: %s is specified by global.json at path: %s", "GlobalJsonIsEmpty": "global.json at path: %s is empty. No version is specified.", "FailedToFindGlobalJson": "Failed to find global.json at and inside path: %s", "FailedToReadGlobalJson": "The global.json at path: '%s' has the wrong format. For information about global.json, visit here: https://docs.microsoft.com/en-us/dotnet/core/tools/global-json. Error while trying to read: %s", "VersionNumberHasTheWrongFormat": "The version number: %s doesn't have the correct format. Versions can be given in the following formats: 2.x => Install latest in major version. 2.2.x => Install latest in major and minor version. 2.2.104 => Install exact version. Find the value of `version` for installing SDK/Runtime, from the releases.json. The link to releases.json of that major.minor version can be found in [**releases-index file.**](https://builds.dotnet.microsoft.com/dotnet/release-metadata/releases-index.json). Like link to releases.json for 2.2 version is https://builds.dotnet.microsoft.com/dotnet/release-metadata/2.2/releases.json", "OnlyExplicitVersionAllowed": "Only explicit versions and accepted, such as: 2.2.301. Version: %s is not valid.", "SupportPhaseNotPresentInChannel": "support-phase is not present in the channel with channel-version %s.", "DepricatedVersionNetCore": "NET Core version you specfied %s is out of support and will be removed from hosted agents soon. Please refer to https://aka.ms/dotnet-core-support for more information about the .NET support policy.", "ApplyingRollForwardPolicy": "Applying rollForward policy '%s' to version '%s', resolved version spec: '%s'", "InvalidRollForwardPolicy": "Invalid rollForward policy '%s' in global.json at path: '%s'. Supported values are: disable, patch, feature, minor, major, latestPatch, latestFeature, latestMinor, latestMajor. The rollForward policy will be ignored.", "ResolvedVersionFromGlobalJson": "Resolved SDK version '%s' from global.json (original version: '%s', rollForward: '%s')", "InstallingFromGlobalJson": "Installing .NET Core SDK version %s resolved from global.json", "VersionSatisfiedByInstalledVersion": "An installed version satisfies the version spec '%s'. Skipping installation." } }