NuGet task

Version 2.

Azure Pipelines | 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, e.g.: '$(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: Under Options set the build number format to be '$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)'.
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.
Control options

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 System.ArtifactsDirectory directory. packagesToPush value can be set to $(System.ArtifactsDirectory)/**/*.nupkg in your release pipeline.

  • 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 a project scoped

    # Push a project
    - task: NuGetCommand@2
      inputs:
        command: 'push'
        feedsToUse: 'select'
        vstsFeed: 'my-project/my-project-scoped-feed'
        publishVstsFeed: 'myTestFeed'
    
  • 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?

How do I modify other parts of my build pipeline?

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 Environment variables for more details.

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.