NuGet task

Article
04/05/2022
11 minutes to read

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?

Azure Artifacts Documentation

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.