NuGet task
Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018
Note
The NuGet Authenticate task is the new recommended way to authenticate with Azure Artifacts and other NuGet repositories. This task no longer takes new features and only critical bugs are addressed.
Use this task to install and update NuGet package dependencies, or package and publish NuGet packages. Uses NuGet.exe and works with .NET Framework apps. For .NET Core and .NET Standard apps, use the .NET Core task.
Note
In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.
If your code depends on NuGet packages, make sure to add this step before your Visual Studio Build step. Also make sure to clear the deprecated Restore NuGet Packages checkbox in that step.
If you are working with .NET Core or .NET Standard, use the .NET Core task, which has full support for all package scenarios and it's currently supported by dotnet.
Tip
This version of the NuGet task uses NuGet 4.1.0 by default. To select a different version of NuGet, use the Tool Installer.
YAML snippet
# NuGet
# Restore, pack, or push NuGet packages, or run a NuGet command. Supports NuGet.org and authenticated feeds like Azure Artifacts and MyGet. Uses NuGet.exe and works with .NET Framework apps. For .NET Core and .NET Standard apps, use the .NET Core task.
- task: NuGetCommand@2
inputs:
#command: 'restore' # Options: restore, pack, push, custom
#restoreSolution: '**/*.sln' # Required when command == Restore
#feedsToUse: 'select' # Options: select, config
#vstsFeed: # Required when feedsToUse == Select
#includeNuGetOrg: true # Required when feedsToUse == Select
#nugetConfigPath: # Required when feedsToUse == Config
#externalFeedCredentials: # Optional
#noCache: false
#disableParallelProcessing: false
restoreDirectory:
#verbosityRestore: 'Detailed' # Options: quiet, normal, detailed
#packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg;!$(Build.ArtifactStagingDirectory)/**/*.symbols.nupkg' # Required when command == Push
#nuGetFeedType: 'internal' # Required when command == Push# Options: internal, external
#publishVstsFeed: # Required when command == Push && NuGetFeedType == Internal
#publishPackageMetadata: true # Optional
#allowPackageConflicts: # Optional
#publishFeedCredentials: # Required when command == Push && NuGetFeedType == External
#verbosityPush: 'Detailed' # Options: quiet, normal, detailed
#packagesToPack: '**/*.csproj' # Required when command == Pack
#configuration: '$(BuildConfiguration)' # Optional
#packDestination: '$(Build.ArtifactStagingDirectory)' # Optional
#versioningScheme: 'off' # Options: off, byPrereleaseNumber, byEnvVar, byBuildNumber
#includeReferencedProjects: false # Optional
#versionEnvVar: # Required when versioningScheme == ByEnvVar
#majorVersion: '1' # Required when versioningScheme == ByPrereleaseNumber
#minorVersion: '0' # Required when versioningScheme == ByPrereleaseNumber
#patchVersion: '0' # Required when versioningScheme == ByPrereleaseNumber
#packTimezone: 'utc' # Required when versioningScheme == ByPrereleaseNumber# Options: utc, local
#includeSymbols: false # Optional
#toolPackage: # Optional
#buildProperties: # Optional
#basePath: # Optional, specify path to nuspec files
#verbosityPack: 'Detailed' # Options: quiet, normal, detailed
#arguments: # Required when command == Custom
Arguments
Argument | Description |
---|---|
command Command |
The NuGet command to run. Select 'Custom' to add arguments or to use a different command. Options: restore , pack , custom , push |
restoreSolution Path to solution, packages.config, or project.json |
The path to the solution, packages.config, or project.json file that references the packages to be restored. |
feedsToUse Feeds to use |
You can either select a feed from Azure Artifacts and/or NuGet.org, or commit a nuget.config file to your source code repository and set its path here. Options: select , config . |
vstsFeed Use packages from this Azure Artifacts/TFS feed |
Include the selected feed in the generated NuGet.config. You must have Azure Artifacts installed and licensed to select a feed here. |
includeNuGetOrg Use packages from NuGet.org |
Include NuGet.org in the generated NuGet.config. Default value is true .Required when feedsToUse == Select . |
nugetConfigPath Path to NuGet.config |
The NuGet.config in your repository that specifies the feeds from which to restore packages. Required when feedsToUse == Config |
externalFeedCredentials Credentials for feeds outside this organization/collection |
Credentials to use for external registries located in the selected NuGet.config. This is the name of your NuGet service connection. For feeds in this organization/collection, leave this blank; the build’s credentials are used automatically. |
noCache Disable local cache |
Prevents NuGet from using packages from local machine caches. |
disableParallelProcessing Disable parallel processing |
Prevents NuGet from installing multiple packages in parallel. |
restoreDirectory Destination directory |
Specifies the folder in which packages are installed. If no folder is specified, packages are restored into a packages/ folder alongside the selected solution, packages.config, or project.json. |
verbosityRestore Verbosity |
Specifies the amount of detail displayed in the output. Options: Quiet , Normal , Detailed |
nuGetFeedType Target feed location |
Specifies whether the target feed is an internal feed/collection or an external NuGet server. Options: internal , external .Required when command == Push |
publishVstsFeed Target feed |
Select a feed hosted in this account. You must have Azure Artifacts installed and licensed to select a feed here. |
packagesToPush Packages location |
The pattern to match or path to the nupkg files. Example: '$(Build.ArtifactStagingDirectory)/*.nupkg'. Required when command == Push |
publishPackageMetadata Publish pipeline metadata |
If you continually publish a set of packages and only change the version number of the subset of packages that changed, use this option. |
allowPackageConflicts |
It allows the task to report success even if some of your packages are rejected with 409 Conflict errors. If NuGet.exe encounters a conflict, the task will fail. This option will not work and publish will fail if you are within a proxy environment. |
publishFeedCredentials NuGet server |
The NuGet service connection that contains the external NuGet server’s credentials. |
verbosityPush Verbosity |
Specifies the amount of detail displayed in the output. Options: Quiet , Normal , Detailed |
packagesToPack Path to csproj or nuspec file(s) to pack |
Pattern to search for csproj directories to pack. You can separate multiple patterns with a semicolon, and you can make a pattern negative by prefixing it with !. Example: **\\*.csproj;!**\\*.Tests.csproj |
configuration Configuration to package |
When using a csproj file this specifies the configuration to package. |
packDestination Package folder |
Folder where packages will be created. If empty, packages will be created at the source root. |
versioningScheme Automatic package versioning |
Cannot be used with include referenced projects. If you choose Use the date and time , this will generate a SemVer-compliant version formatted as X.Y.Z-ci-datetime where you choose X, Y, and Z.If you choose Use an environment variable , you must select an environment variable and ensure it contains the version number you want to use.If you choose Use the build number , this will use the build number to version your package.Note: You can set the build number format using the name property as follows: name: $(BuildDefinitionName)_$(Date:yyyyMMdd)$(Rev:.rr). Options: off , byPrereleaseNumber , byEnvVar , byBuildNumber |
includeReferencedProjects Environment variable |
Enter the variable name without $, $env, or %. |
majorVersion Major |
The 'X' in version X.Y.Z |
minorVersion Minor |
The 'Y' in version X.Y.Z |
patchVersion Patch |
The 'Z' in version X.Y.Z |
packTimezone Time zone |
Specifies the desired time zone used to produce the version of the package. Selecting UTC is recommended if you're using hosted build agents as their date and time might differ. Options: utc , local |
includeSymbols Create symbols package |
Specifies that the package contains sources and symbols. When used with a .nuspec file, this creates a regular NuGet package file and the corresponding symbols package. |
toolPackage Tool Package |
Determines if the output files of the project should be in the tool folder. |
buildProperties Additional build properties |
Specifies a list of token=value pairs, separated by semicolons, where each occurrence of $token$ in the .nuspec file will be replaced with the given value. Values can be strings in quotation marks. |
basePath Base path |
The base path of the files defined in the nuspec file. |
verbosityPack Verbosity |
Specifies the amount of detail displayed in the output. Options: Quiet , Normal , Detailed |
arguments Command and arguments |
The command and arguments which will be passed to NuGet.exe for execution. If NuGet 3.5 or later is used, authenticated commands like list, restore, and publish against any feed in this organization/collection that the Project Collection Build Service has access to will be automatically authenticated. |
Versioning schemes
For byPrereleaseNumber, the version will be set to whatever you choose for major, minor, and patch, plus the date and time in the format yyyymmdd-hhmmss
.
For byEnvVar, the version will be set to the value of the environment variable that has the name specified by the versionEnvVar parameter, e.g. MyVersion
(no $, just the environment variable name). Make sure the environment variable is set to a proper SemVer e.g. 1.2.3
or 1.2.3-beta1
.
For byBuildNumber, the version will be set using the pipeline run's build number. This is the value specified for the pipeline's name
property, which gets saved to the BUILD_BUILDNUMBER
environment variable). Ensure that the build number being used contains a proper SemVer e.g. 1.0.$(Rev:r)
. When using byBuildNumber, the task will extract the dotted version, 1.2.3.4
from the build number string, and use only that portion. The rest of the string will be dropped. If you want to use the build number as is, you can use byEnvVar as described above, and set versionEnvVar to BUILD_BUILDNUMBER
.
Examples
Restore
Restore all your solutions with packages from a selected feed.
# Restore from a project scoped feed in the same organization
- task: NuGetCommand@2
inputs:
command: 'restore'
feedsToUse: 'select'
vstsFeed: 'my-project/my-project-scoped-feed'
includeNuGetOrg: false
restoreSolution: '**/*.sln'
# Restore from an organization scoped feed in the same organization
- task: NuGetCommand@2
inputs:
command: 'restore'
feedsToUse: 'select'
vstsFeed: 'my-organization-scoped-feed'
restoreSolution: '**/*.sln'
# Restore from a feed in a different organization
- task: NuGetCommand@2
inputs:
command: 'restore'
feedsToUse: config
nugetConfigPath: ./nuget.config
restoreSolution: '**/*.sln'
externalFeedCredentials: 'MyServiceConnectionName'
noCache: true
continueOnError: true
# Restore from feed(s) set in nuget.config
- task: NuGetCommand@2
inputs:
command: 'restore'
feedsToUse: 'config'
nugetConfigPath: 'nuget.config'
Package
Create a NuGet package in the destination folder.
# Package a project
- task: NuGetCommand@2
inputs:
command: 'pack'
packagesToPack: '**/*.csproj'
packDestination: '$(Build.ArtifactStagingDirectory)'
Push
Note
Pipeline artifacts are downloaded to the Pipeline.Workspace
directory, and to the System.ArtifactsDirectory
directory for classic release pipelines. packagesToPush
value can be set to $(Pipeline.Workspace)/**/*.nupkg
or $(System.ArtifactsDirectory)/**/*.nupkg
respectively.
Push/Publish a package to a feed defined in your NuGet.config.
# Push a project - task: NuGetCommand@2 inputs: command: 'push' packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg' feedsToUse: 'config' nugetConfigPath: '$(Build.WorkingDirectory)/NuGet.config'
Push/Publish a package to an organization scoped feed
# Push a project - task: NuGetCommand@2 inputs: command: 'push' nuGetFeedType: 'internal' publishVstsFeed: 'my-organization-scoped-feed'
Push/Publish a package to a project scoped feed
# Push a project - task: NuGetCommand@2 inputs: command: 'push' nuGetFeedType: 'internal' publishVstsFeed: 'my-project/my-project-scoped-feed'
Push/Publish a package to NuGet.org
# Push a project - task: NuGetCommand@2 inputs: command: 'push' feedsToUse: 'config' includeNugetOrg: 'true'
Custom
Run any other NuGet command besides the default ones: pack, push, and restore.
# list local NuGet resources.
- task: NuGetCommand@2
displayName: 'list locals'
inputs:
command: custom
arguments: 'locals all -list'
Open-source
Check out the Azure Pipelines and Team Foundation Server out-of-the-box tasks on GitHub. Feedback and contributions are welcome.
FAQ
Why should I check in a NuGet.Config?
Checking a NuGet.Config into source control ensures that a key piece of information needed to build your project, the location of its packages, is available to every developer that checks out your code.
However, for situations where a team of developers works on a large range of projects, it's also possible to add an Azure Artifacts feed to the global NuGet.Config on each developer's machine. In these situations, using the "Feeds I select here" option in the NuGet task replicates this configuration.
Where can I learn about Azure Artifacts?
Where can I learn more about NuGet?
NuGet Docs Overview
NuGet Create Packaging and publishing
NuGet Consume Setting up a solution to get dependencies
What other kinds of apps can I build?
Build and deploy your app examples
What other kinds of build tasks are available?
Build and release tasks catalog
How do we protect our codebase from build breaks?
Git: Improve code quality with branch policies with an option to require that code builds before it can be merged to a branch. For GitHub repositories, similar policies are available in GitHub's repository settings under Branches.
TFVC: Use gated check-in.
How do I modify other parts of my build pipeline?
Build and release tasks to run tests, scripts, and a wide range of other processes.
Specify build options such as specifying how completed builds are named, building multiple configurations, creating work items on failure.
Supported source repositories to pick the source of the build and modify options such as how the agent workspace is cleaned.
Set build triggers to modify how your CI builds run and to specify scheduled builds.
Specify build retention policies to automatically delete old builds.
I selected parallel multi-configuration, but only one build is running at a time.
If you're using Azure Pipelines, you might need more parallel jobs. See Parallel jobs in Azure Pipelines.
How do I see what has changed in my build pipeline?
View the change history of your build pipeline
Do I need an agent?
You need at least one agent to run your build or release.
I'm having problems. How can I troubleshoot them?
See Troubleshoot Build and Release.
I can't select a default agent pool and I can't queue my build or release. How do I fix this?
See Agent pools.
My NuGet push task is failing with the following error: "Error: unable to get local issuer certificate". How can I fix this?
This can be fixed by adding a trusted root certificate. You can either add the NODE_EXTRA_CA_CERTS=file
environment variable to your build agent, or you can add the NODE.EXTRA.CA.CERTS=file
task variable in your pipeline. See Node.js documentation for more details about this variable. See Set variables in a pipeline for instructions on setting a variable in your pipeline.
I use TFS on-premises and I don't see some of these features. Why not?
Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.
My Pipeline needs to access a feed in a different project
If the pipeline is running in a different project than the project hosting the feed, you must set up the other project to grant read/write access to the build service. See Package permissions in Azure Pipelines for more details.
Feedback
Submit and view feedback for