.NET Core CLI task

Article
10/30/2019

TFS 2017

Note

The NuGet Authenticate task is the new recommended way to authenticate with Azure Artifacts and other NuGet repositories. The restore and push commands of this task no longer take new features and only critical bugs are addressed.

Azure Pipelines

Use this task to build, test, package, or publish a dotnet application, or to run a custom dotnet command. For package commands, this task supports NuGet.org and authenticated feeds like Package Management and MyGet.

If your .NET Core or .NET Standard build depends on NuGet packages, make sure to add two copies of this step: one with the restore command and one with the build command.

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.

Arguments

Task control options

Argument	Description
`command` Command	The dotnet command to run. Select `custom` to add arguments or use a command not listed here. Options: `build`, `push`, `pack`, `publish`, `restore`, `run`, `test`, `custom`
`selectOrConfig` Feeds to use	You can either choose to select a feed from Azure Artifacts and/or NuGet.org here, or commit a NuGet.config file to your source code repository and set its path using the `nugetConfigPath` argument. Options: `select`, `config` Argument aliases: `feedsToUse`
`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`,
`arguments` Arguments	Arguments to the selected command. For example, build configuration, output folder, runtime. The arguments depend on the command selected Note: This input only currently accepts arguments for `build`, `publish`, `run`, `test`, `custom`. If you would like to add arguments for a command not listed, use `custom`.
`projects` Path to project(s)	The path to the csproj file(s) to use. You can use wildcards (e.g. `*/.csproj` for all .csproj files in all subfolders), see file matching patterns.
`noCache` Disable local cache	Prevents NuGet from using packages from local machine caches.
`restoreArguments` Restore arguments	Write the additional arguments to be passed to the `restore` command.
`packagesDirectory` Destination directory	Specifies the folder in which packages are installed. If no folder is specified, packages are restored into the default NuGet package cache Argument aliases: `restoreDirectory`
`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
`verbosityPack` Verbosity	Specifies the amount of detail displayed in the output for the `pack` command.
`verbosityRestore` Verbosity	Specifies the amount of detail displayed in the output for the `restore` command.
`workingDirectory` Working Directory	Current working directory where the script is run. Empty is the root of the repo (build) or artifacts (release), which is $(System.DefaultWorkingDirectory)
`searchPatternPush` Path to NuGet package(s) to publish	The pattern to match or path to nupkg files to be uploaded. Multiple patterns can be separated by a semicolon, and you can make a pattern negative by prefixing it with `!`. Example: `*/.nupkg;!*/.Tests.nupkg.` Argument aliases: `packagesToPush`
`nuGetFeedType` Target feed location	Specifies whether the target feed is internal or external. Options: `internal`, `external`
`feedPublish` Target feed	Select a feed hosted in your organization. You must have Package Management installed and licensed to select a feed here Argument aliases: `publishVstsFeed`
`publishPackageMetadata` Publish pipeline metadata	Associate this build/release pipeline’s metadata (run ID, source code information) with the package
`externalEndpoint` NuGet server	The NuGet service connection that contains the external NuGet server’s credentials. Argument aliases: `publishFeedCredentials`
`searchPatternPack` Path to csproj or nuspec file(s) to pack	Pattern to search for csproj or nuspec files 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` Argument aliases: `packagesToPack`
`configurationToPack` Configuration to Package	When using a csproj file this specifies the configuration to package. Argument aliases: `configuration`
`outputDir` Package Folder	Folder where packages will be created. If empty, packages will be created alongside the csproj file. Argument aliases: `packDirectory`
`nobuild` Do not build	Don't build the project before packing. Corresponds to the `--no-build` parameter of the `build` command.
`includesymbols` Include Symbols	Additionally creates symbol NuGet packages. Corresponds to the `--include-symbols` command line parameter.
`includesource` Include Source	Includes source code in the package. Corresponds to the `--include-source` command line parameter.
`publishWebProjects` Publish Web Projects	If `true`, the `projects` property value will be skipped and the task will try to find the web projects in the repository and run the publish command on them. Web projects are identified by presence of either a web.config file or wwwroot folder in the directory. In the absence of a web.config file or wwwroot folder, projects that use a web SDK, like Microsoft.NET.Sdk.Web, are selected. Note that this argument defaults to `true` if not specified.
`zipAfterPublish` Zip Published Projects	If `true`, folder created by the publish command will be zipped and deleted.
`modifyOutputPath` Add project name to publish path	If `true`, folders created by the publish command will have project file name prefixed to their folder names when output path is specified explicitly in arguments. This is useful if you want to publish multiple projects to the same folder.
`publishTestResults` Publish test results	Enabling this option will generate a test results TRX file in `$(Agent.TempDirectory)` and results will be published to the server. This option appends `--logger trx --results-directory $(Agent.TempDirectory)` to the command line arguments. Code coverage can be collected by adding `--collect "Code coverage"` to the command line arguments.
`testRunTitle` Test run title	Provides a name for the test run
`custom` Custom command	The command to pass to dotnet.exe for execution. For a full list of available commands, see the dotnet CLI documentation
`feedRestore` Use packages from this Azure Artifacts/TFS feed	Include the selected feed in the generated NuGet.config. You must have Package Management installed and licensed to select a feed here. projectName/feedName for project-scoped feed. FeedName only for organization-scoped feed. Note that this is not supported for the test command. Argument aliases: `vstsFeed`
`includeNuGetOrg` Use packages from NuGet.org	Include NuGet.org in the generated NuGet.config000 0.
`nugetConfigPath` Path to NuGet.config	The NuGet.config in your repository that specifies the feeds from which to restore packages.
`externalEndpoints` Credentials for feeds outside this organization/collection	Credentials to use for external registries located in the selected NuGet.config. For feeds in this organization/collection, leave this blank; the build’s credentials are used automatically Argument aliases: `externalFeedCredentials`
`versionEnvVar` Environment variable	Enter the variable name without $, $env, or %
`requestedMajorVersion` Major	The 'X' in version X.Y.Z. Argument aliases: `majorVersion`
`requestedMinorVersion` Minor	The 'Y' in version X.Y.Z. Argument aliases: `minorVersion`
`requestedPatchVersion` Patch	The 'Z' in version X.Y.Z. Argument aliases: `patchVersion`

Examples

Build

Build a project

# Build project
- task: DotNetCoreCLI@2
  inputs:
    command: 'build'

Build Multiple Projects

# Build multiple projects
- task: DotNetCoreCLI@2
  inputs:
    command: 'build'
    projects: |
      src/proj1/proj1.csproj 
      src/proj2/proj2.csproj 
      src/other/other.sln    # Pass a solution instead of a csproj.

Push

Push NuGet packages to internal feed

# Push non test NuGet packages from a build to internal organization Feed
- task: DotNetCoreCLI@2
  inputs:
    command: 'push'
    searchPatternPush: '$(Build.ArtifactStagingDirectory)/*.nupkg;!$(Build.ArtifactStagingDirectory)/*.Tests.nupkg'
    feedPublish: 'FabrikamFeed'

Push NuGet packages to external feed

# Push all NuGet packages from a build to external Feed
- task: DotNetCoreCLI@2
  inputs:
    command: 'push'
    nugetFeedType: 'external'
    externalEndPoint: 'MyNuGetServiceConnection'

Pack

Pack a NuGetPackage to a specific output directory

# Pack a NuGet package to a test directory
- task: DotNetCoreCLI@2
  inputs: 
    command: 'pack'
    outputDir: '$(Build.ArtifactStagingDirectory)/TestDir'

Pack a Symbol Package

# Pack a symbol package along with NuGet package
- task: DotNetCoreCLI@2
  inputs: 
    command: 'pack'
    includesymbols: true

Publish

Publish projects to specified folder

# Publish projects to specified folder.
- task: DotNetCoreCLI@2
  displayName: 'dotnet publish'
  inputs:
    command: 'publish'
    publishWebProjects: false
    projects: '**/*.csproj'
    arguments: '-o $(Build.ArtifactStagingDirectory)/Output'
    zipAfterPublish: true
    modifyOutputPath: true

Restore

#Restore packages with the .NET Core CLI task
- task: DotNetCoreCLI@2
  displayName: 'dotnet restore'
  inputs:
    command: 'restore'
    feedsToUse: 'select'
    feedRestore: 'projectName/feedName'
    projects: '**/*.csproj'
    includeNuGetOrg: true

Test

Run tests in your repository

# Run tests and auto publish test results.
- task: DotNetCoreCLI@2
  inputs:
    command: 'test'

FAQ

Why is my build, publish, or test step failing to restore packages?

Most dotnet commands, including build, publish, and test include an implicit restore step. This will fail against authenticated feeds, even if you ran a successful dotnet restore in an earlier step, because the earlier step will have cleaned up the credentials it used.

To fix this issue, add the --no-restore flag to the Arguments textbox.

In addition, the test command does not recognize the feedRestore or vstsFeed arguments and feeds specified in this manner will not be included in the generated NuGet.config file when the implicit restore step runs. It is recommended that an explicit dotnet restore step be used to restore packages. The restore command respects the feedRestore and vstsFeed arguments.

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.

Troubleshooting

File structure for output files is different from previous builds

Azure DevOps hosted agents are configured with .NET Core 3.0, 2.1 and 2.2. CLI for .NET Core 3.0 has a different behavior while publishing projects using output folder argument. When publishing projects with the output folder argument (-o), the output folder is created in the root directory and not in the project file’s directory. Hence while publishing more than one project, all the files are published to the same directory, which causes an issue.

To resolve this issue, use the Add project name to publish path parameter (modifyOutputPath in YAML) in the .NET Core CLI task. This creates a sub folder with project file’s name, inside the output folder. Hence all your projects will be published under different subfolder’s inside the main output folder.

steps:
- task: DotNetCoreCLI@2
  displayName: 'dotnet publish'
  inputs:
    command: publish
    publishWebProjects: false
    projects: '**/*.csproj'
    arguments: '-o testpath'
    zipAfterPublish: false
    modifyOutputPath: true

Project using Entity Framework has stopped working on Hosted Agents

The latest .NET Core: 3.0 does not have Entity Framework(EF) built-in. You will have to either install EF before beginning execution or add global.json to the project with required .NET Core SDK version. This will ensure that correct SDK is used to build EF project. If the required version is not present on the machine, add UseDotNetV2 task to your pipeline to install the required version. Learn more about EF with .NET Core 3.0

Open Source

This task is open source on GitHub. Feedback and contributions are welcome.