title	description	ms.topic	ms.assetid	ms.reviewer	ms.date	ms.custom	monikerRange
Build, test, and deploy .NET Core apps	Use .NET Core to build apps with Azure Pipelines, Azure DevOps, & Team Foundation Server	conceptual	95ACB249-0598-4E82-B155-26881A5AA0AA	vijayma	07/29/2021	contperf-fy20q4	>= tfs-2017

Build, test, and deploy .NET Core apps

[!INCLUDE version-tfs-2017-rtm]

Use a pipeline to automatically build and test your .NET Core projects. Learn how to:

Set up your build environment with Microsoft-hosted or self-hosted agents.
Restore dependencies, build your project, and test with the .NET Core CLI task or a script.
Use the publish code coverage task to publish code coverage results.
Package and deliver your code with the .NET Core CLI task and the publish build artifacts task.
Publish to a NuGet feed.
Deploy your web app to Azure.

Note

For help with .NET Framework projects, see Build ASP.NET apps with .NET Framework.

[!INCLUDE temp]

::: moniker range="tfs-2017"

Note

This guidance applies to TFS version 2017.3 and newer.

::: moniker-end

Create your first pipeline

::: moniker range=">=azure-devops-2020"

Are you new to Azure Pipelines? If so, then we recommend you try this section before moving on to other sections.

::: moniker-end

Get the code

::: moniker range=">=azure-devops-2020"

[!INCLUDE include]

::: moniker-end

::: moniker range="azure-devops-2019"

Import this repo into your Git repo in Azure DevOps Server 2019:

::: moniker-end

::: moniker range="< azure-devops-2019"

Import this repo into your Git repo in TFS:

::: moniker-end

https://github.com/MicrosoftDocs/pipelines-dotnet-core

::: moniker range=">=azure-devops-2020"

Sign in to Azure Pipelines

[!INCLUDE include]

::: moniker-end

Create the pipeline

::: moniker range=">=azure-devops-2020"

[!INCLUDE include]

When the Configure tab appears, select ASP.NET Core.

When your new pipeline appears, take a look at the YAML to see what it does. When you're ready, select Save and run.

[!div class="mx-imgBorder"]
You're prompted to commit a new azure-pipelines.yml file to your repository. After you're happy with the message, select Save and run again.

If you want to watch your pipeline in action, select the build job.

You just created and ran a pipeline that we automatically created for you, because your code appeared to be a good match for the ASP.NET Core template.

You now have a working YAML pipeline (azure-pipelines.yml) in your repository that's ready for you to customize!
When you're ready to make changes to your pipeline, select it in the Pipelines page, and then Edit the azure-pipelines.yml file.
See the sections below to learn some of the more common ways to customize your pipeline.

::: moniker-end

::: moniker range="azure-devops-2019"

YAML

Add an azure-pipelines.yml file in your repository. Customize this snippet for your build.

trigger:
- master

pool: Default

variables:
  buildConfiguration: 'Release'

# do this before all your .NET Core tasks
steps:
- task: DotNetCoreInstaller@2
  inputs:
    version: '2.2.402' # replace this value with the version that you need for your project
- script: dotnet build --configuration $(buildConfiguration)
  displayName: 'dotnet build $(buildConfiguration)'

Create a pipeline (if you don't know how, see Create your first pipeline), and for the template select YAML.
Set the Agent pool and YAML file path for your pipeline.
Save the pipeline and queue a build. When the Build #nnnnnnnn.n has been queued message appears, select the number link to see your pipeline in action.
When you're ready to make changes to your pipeline, Edit it.
See the sections below to learn some of the more common ways to customize your pipeline.

::: moniker-end ::: moniker range="< azure-devops"

Classic

Create a pipeline (if you don't know how, see Create your first pipeline). Select Empty Pipeline for the template.
In the task catalog, find and add the .NET Core task. This task will run dotnet build to build the code in the sample repository.
Save the pipeline and queue a build. When the Build #nnnnnnnn.n has been queued message appears, select the number link to see your pipeline in action.

You now have a working pipeline that's ready for you to customize!
When you're ready to make changes to your pipeline, Edit it.
See the sections below to learn some of the more common ways to customize your pipeline.

::: moniker-end

Build environment

::: moniker range=">=azure-devops-2020"

Use Azure Pipelines to build your .NET Core projects on Windows, Linux, or macOS without needing to set up any infrastructure of your own. The Microsoft-hosted agents in Azure Pipelines include several released versions of the .NET Core SDKs preinstalled.

Ubuntu 18.04 is set here in the YAML file.

pool:
  vmImage: 'ubuntu-18.04' # examples of other options: 'macOS-10.15', 'windows-2019'

See Microsoft-hosted agents for a complete list of images and Pool for further examples.

The Microsoft-hosted agents don't include some of the older versions of the .NET Core SDK. They also don't typically include prerelease versions. If you need these kinds of SDKs on Microsoft-hosted agents, add the UseDotNet@2 task to your YAML file.

To install the preview version of the 5.0.x SDK for building and 3.0.x for running tests that target .NET Core 3.0.x, add this snippet:

steps:
- task: UseDotNet@2
  inputs:
    version: '5.0.x'
    includePreviewVersions: true # Required for preview versions

- task: UseDotNet@2
  inputs:
    version: '3.0.x'
    packageType: runtime

Windows agents already include a .NET Core runtime. To install a newer SDK, set performMultiLevelLookup to true in this snippet:

steps:
- task: UseDotNet@2
  displayName: 'Install .NET Core SDK'
  inputs:
    version: 5.0.x
    performMultiLevelLookup: true
    includePreviewVersions: true # Required for preview versions

Tip

As an alternative, you can set up a self-hosted agent and save the cost of running the tool installer. See Linux, MacOS, or Windows. You can also use self-hosted agents to save additional time if you have a large repository or you run incremental builds. A self-hosted agent can also help you in using the preview or private SDKs that are not officially supported by Azure DevOps or you have available on your corporate or on-premises environments only.

::: moniker-end

::: moniker range="< azure-devops"

You can build your .NET Core projects by using the .NET Core SDK and runtime on Windows, Linux, or macOS. Your builds run on a self-hosted agent. Make sure that you have the necessary version of the .NET Core SDK and runtime installed on the agent.

::: moniker-end

Restore dependencies

NuGet is a popular way to depend on code that you don't build. You can download NuGet packages and project-specific tools that are specified in the project file by running the dotnet restore command either through the .NET Core task or directly in a script in your pipeline.

::: moniker range=">= tfs-2018"

You can download NuGet packages from Azure Artifacts, NuGet.org, or some other external or internal NuGet repository. The .NET Core task is especially useful to restore packages from authenticated NuGet feeds.

This pipeline uses an artifact feed for dotnet restore in the .NET Core CLI task.

trigger:
- master

pool:
  vmImage: 'windows-latest'

variables:
  buildConfiguration: 'Release'

steps:
- task: DotNetCoreCLI@2
  inputs:
    command: 'restore'
    feedsToUse: 'select'
    vstsFeed: 'my-vsts-feed' # A series of numbers and letters

- task: DotNetCoreCLI@2
  inputs:
    command: 'build'
    arguments: '--configuration $(buildConfiguration)'
  displayName: 'dotnet build $(buildConfiguration)'

::: moniker-end

::: moniker range="< tfs-2018"

You can download NuGet packages from NuGet.org.

::: moniker-end

dotnet restore internally uses a version of NuGet.exe that is packaged with the .NET Core SDK. dotnet restore can only restore packages specified in the .NET Core project .csproj files. If you also have a Microsoft .NET Framework project in your solution or use package.json to specify your dependencies, you must also use the NuGet task to restore those dependencies.

::: moniker range="< tfs-2018"

In .NET Core SDK version 2.0 and newer, packages are restored automatically when running other commands such as dotnet build.

::: moniker-end

::: moniker range=">= tfs-2018"

In .NET Core SDK version 2.0 and newer, packages are restored automatically when running other commands such as dotnet build. However, you might still need to use the .NET Core task to restore packages if you use an authenticated feed.

::: moniker-end

::: moniker range=">= tfs-2018"

If your builds occasionally fail when restoring packages from NuGet.org due to connection issues, you can use Azure Artifacts with upstream sources and cache the packages. The credentials of the pipeline are automatically used when connecting to Azure Artifacts. These credentials are typically derived from the Project Collection Build Service account.

If you want to specify a NuGet repository, put the URLs in a NuGet.config file in your repository. If your feed is authenticated, manage its credentials by creating a NuGet service connection in the Services tab under Project Settings.

::: moniker-end

::: moniker range=">=azure-devops-2020"

If you use Microsoft-hosted agents, you get a new machine every time your run a build, which means restoring the packages every time. This restoration can take a significant amount of time. To mitigate this issue, you can either use Azure Artifacts or a self-hosted agent, in which case, you get the benefit of using the package cache.

::: moniker-end

::: moniker range=">=azure-devops-2020"

To restore packages from an external custom feed, use the .NET Core task:

# do this before your build tasks
steps:
- task: DotNetCoreCLI@2
  displayName: Restore
  inputs:
    command: restore
    projects: '**/*.csproj'
    feedsToUse: config
    nugetConfigPath: NuGet.config    # Relative to root of the repository
    externalFeedCredentials: <Name of the NuGet service connection>
# ...

For more information about NuGet service connections, see publish to NuGet feeds.

::: moniker-end

::: moniker range="< azure-devops"

Select Tasks in the pipeline. Select the job that runs your build tasks. Then select + to add a new task to that job.
In the task catalog, find and add the .NET Core task.
Select the task and, for Command, select restore.
Specify any other options you need for this task. Then save the build.

Note

Make sure the custom feed is specified in your NuGet.config file and that credentials are specified in the NuGet service connection.

::: moniker-end

Build your project

You build your .NET Core project either by running the dotnet build command in your pipeline or by using the .NET Core task.

::: moniker range=">=azure-devops-2020"

To build your project by using the .NET Core task, add the following snippet to your azure-pipelines.yml file:

steps:
- task: DotNetCoreCLI@2
  displayName: Build
  inputs:
    command: build
    projects: '**/*.csproj'
    arguments: '--configuration $(buildConfiguration)' # Update this to match your need

You can run any custom dotnet command in your pipeline. The following example shows how to install and use a .NET global tool, dotnetsay:

steps:
- task: DotNetCoreCLI@2
  displayName: 'Install dotnetsay'
  inputs:
    command: custom
    custom: tool
    arguments: 'install -g dotnetsay'

::: moniker-end

::: moniker range="< azure-devops"

Build

Select Tasks in the pipeline. Select the job that runs your build tasks. Then select + to add a new task to that job.
In the task catalog, find and add the .NET Core task.
Select the task and, for Command, select build or publish.
Specify any other options you need for this task. Then save the build.

Install a tool

To install a .NET Core global tool like dotnetsay in your build running on Windows, take the following steps:

Add the .NET Core task and set the following properties:
- Command: custom.
  - Path to projects: leave empty.
- Custom command: tool.
- Arguments: install -g dotnetsay.
Add a Command Line task and set the following properties:
- Script: dotnetsay.

::: moniker-end

Run your tests

If you have test projects in your repository, then use the .NET Core task to run unit tests by using testing frameworks like MSTest, xUnit, and NUnit. For this functionality, the test project must reference Microsoft.NET.Test.SDK version 15.8.0 or higher. Test results are automatically published to the service. These results are then made available to you in the build summary and can be used for troubleshooting failed tests and test-timing analysis.

::: moniker range=">=azure-devops-2020"

Add the following snippet to your azure-pipelines.yml file:

steps:
# ...
# do this after other tasks such as building
- task: DotNetCoreCLI@2
  inputs:
    command: test
    projects: '**/*Tests/*.csproj'
    arguments: '--configuration $(buildConfiguration)'

An alternative is to run the dotnet test command with a specific logger and then use the Publish Test Results task:

steps:
# ...
# do this after your tests have run
- script: dotnet test <test-project> --logger trx
- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testRunner: VSTest
    testResultsFiles: '**/*.trx'

::: moniker-end

::: moniker range="< azure-devops"

Use the .NET Core task with Command set to test. Path to projects should refer to the test projects in your solution.

::: moniker-end

Collect code coverage

If you're building on the Windows platform, code coverage metrics can be collected by using the built-in coverage data collector. For this functionality, the test project must reference Microsoft.NET.Test.SDK version 15.8.0 or higher. If you use the .NET Core task to run tests, coverage data is automatically published to the server. The .coverage file can be downloaded from the build summary for viewing in Visual Studio.

::: moniker range=">=azure-devops-2020"

Add the following snippet to your azure-pipelines.yml file:

steps:
# ...
# do this after other tasks such as building
- task: DotNetCoreCLI@2
  inputs:
    command: test
    projects: '**/*Tests/*.csproj'
    arguments: '--configuration $(buildConfiguration) --collect "Code coverage"'

If you choose to run the dotnet test command, specify the test results logger and coverage options. Then use the Publish Test Results task:

steps:
# ...
# do this after your tests have run
- script: dotnet test <test-project> --logger trx --collect "Code coverage"
- task: PublishTestResults@2
  inputs:
    testRunner: VSTest
    testResultsFiles: '**/*.trx'

::: moniker-end

::: moniker range="< azure-devops"

Add the .NET Core task to your build job and set the following properties:
- Command: test.
- Path to projects: Should refer to the test projects in your solution.
- Arguments: --configuration $(BuildConfiguration) --collect "Code coverage".
Ensure that the Publish test results option remains selected.

::: moniker-end

Collect code coverage metrics with Coverlet

If you're building on Linux or macOS, you can use Coverlet or a similar tool to collect code coverage metrics.

Code coverage results can be published to the server by using the Publish Code Coverage Results task. To use this functionality, the coverage tool must be configured to generate results in Cobertura or JaCoCo coverage format.

To run tests and publish code coverage with Coverlet:

Add a reference to the coverlet.msbuild NuGet package in your test project(s) for .NET projects below .NET 5. For .NET 5, add a reference to the coverlet.collector NuGet package.
Add this snippet to your azure-pipelines.yml file:

.NET 5

- task: UseDotNet@2
  inputs:
    version: '5.0.x'
    includePreviewVersions: true # Required for preview versions
  
- task: DotNetCoreCLI@2
  displayName: 'dotnet build'
  inputs:
    command: 'build'
    configuration: $(buildConfiguration)
  
- task: DotNetCoreCLI@2
  displayName: 'dotnet test'
  inputs:
    command: 'test'
    arguments: '--configuration $(buildConfiguration) --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=cobertura'
    publishTestResults: true
    projects: 'MyTestLibrary' # update with your test project directory
  
- task: PublishCodeCoverageResults@1
  displayName: 'Publish code coverage report'
  inputs:
    codeCoverageTool: 'Cobertura'
    summaryFileLocation: '$(Agent.TempDirectory)/**/coverage.cobertura.xml'

.NET < 5

- task: DotNetCoreCLI@2
  displayName: 'dotnet test'
  inputs:
    command: 'test'
    arguments: '--configuration $(buildConfiguration) --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=cobertura'
    publishTestResults: true
    projects: '**/test-library/*.csproj' # update with your test project directory

- task: PublishCodeCoverageResults@1
  displayName: 'Publish code coverage report'
  inputs:
    codeCoverageTool: 'Cobertura'
    summaryFileLocation: '$(Agent.TempDirectory)/**/coverage.cobertura.xml'

Package and deliver your code

After you've built and tested your app, you can upload the build output to Azure Pipelines or TFS, create and publish a NuGet package, or package the build output into a .zip file to be deployed to a web application.

::: moniker range=">=azure-devops-2020"

Publish artifacts to Azure Pipelines

To publish the output of your .NET build,

Run dotnet publish --output $(Build.ArtifactStagingDirectory) on CLI or add the DotNetCoreCLI@2 task with publish command.
Publish the artifact by using Publish artifact task.

Add the following snippet to your azure-pipelines.yml file:

steps:

- task: DotNetCoreCLI@2
  inputs:
    command: publish
    publishWebProjects: True
    arguments: '--configuration $(BuildConfiguration) --output $(Build.ArtifactStagingDirectory)'
    zipAfterPublish: True

# this code takes all the files in $(Build.ArtifactStagingDirectory) and uploads them as an artifact of your build.
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)' 
    artifactName: 'myWebsiteName'

Note

The dotNetCoreCLI@2 task has a publishWebProjects input that is set to true by default. This publishes all web projects in your repo by default. You can find more help and information in the open source task on GitHub.

To copy more files to Build directory before publishing, use Utility: copy files.

Publish to a NuGet feed

To create and publish a NuGet package, add the following snippet:

steps:
# ...
# do this near the end of your pipeline in most cases
- script: dotnet pack /p:PackageVersion=$(version)  # define version variable elsewhere in your pipeline
- task: NuGetAuthenticate@0
  input:
    nuGetServiceConnections: '<Name of the NuGet service connection>'
- task: NuGetCommand@2
  inputs:
    command: push
    nuGetFeedType: external
    publishFeedCredentials: '<Name of the NuGet service connection>'
    versioningScheme: byEnvVar
    versionEnvVar: version

For more information about versioning and publishing NuGet packages, see publish to NuGet feeds.

Deploy a web app

To create a .zip file archive that's ready for publishing to a web app, add the following snippet:

steps:
# ...
# do this after you've built your app, near the end of your pipeline in most cases
# for example, you do this before you deploy to an Azure web app on Windows
- task: DotNetCoreCLI@2
  inputs:
    command: publish
    publishWebProjects: True
    arguments: '--configuration $(BuildConfiguration) --output $(Build.ArtifactStagingDirectory)'
    zipAfterPublish: True

To publish this archive to a web app, see Azure Web Apps deployment.

::: moniker-end

::: moniker range="< azure-devops"

Publish artifacts to Azure Pipelines

Use the Publish Artifacts task to publish the output of your build to Azure Pipelines or TFS.

Publish to a NuGet feed

If you want to publish your code to a NuGet feed, take the following steps:

Use a .NET Core task with Command set to pack.
Publish your package to a NuGet feed.

Deploy a web app

Use a .NET Core task with Command set to publish.
Make sure you've selected the option to create a .zip file archive.
To publish this archive to a web app, see Azure Web Apps deployment.

::: moniker-end

Build an image and push to container registry

For your app, you can also build an image and push it to a container registry.

Troubleshooting

If you're able to build your project on your development machine, but you're having trouble building it on Azure Pipelines or TFS, explore the following potential causes and corrective actions:

::: moniker range=">=azure-devops-2020"

We don't install prerelease versions of the .NET Core SDK on Microsoft-hosted agents. After a new version of the .NET Core SDK is released, it can take a few weeks for us to roll it out to all the data centers that Azure Pipelines run on. You don't have to wait for us to finish this rollout. You can use the .NET Core Tool Installer, as explained in this guidance, to install the desired version of the .NET Core SDK on Microsoft-hosted agents.

::: moniker-end

Check that the versions of the .NET Core SDK and runtime on your development machine match those on the agent. You can include a command-line script dotnet --version in your pipeline to print the version of the .NET Core SDK. Either use the .NET Core Tool Installer, as explained in this guidance, to deploy the same version on the agent, or update your projects and development machine to the newer version of the .NET Core SDK.
You might be using some logic in the Visual Studio IDE that isn't encoded in your pipeline. Azure Pipelines or TFS runs each of the commands you specify in the tasks one after the other in a new process. Look at the logs from the Azure Pipelines or TFS build to see the exact commands that ran as part of the build. Repeat the same commands in the same order on your development machine to locate the problem.
If you have a mixed solution that includes some .NET Core projects and some .NET Framework projects, you should also use the NuGet task to restore packages specified in packages.config files. Similarly, you should add MSBuild or Visual Studio Build tasks to build the .NET Framework projects.
If your builds fail intermittently while restoring packages, either NuGet.org is having issues, or there are networking problems between the Azure datacenter and NuGet.org. These aren't under our control, and you might need to explore whether using Azure Artifacts with NuGet.org as an upstream source improves the reliability of your builds.
Occasionally, when we roll out an update to the hosted images with a new version of the .NET Core SDK or Visual Studio, something might break your build. This can happen, for example, if a newer version or feature of the NuGet tool is shipped with the SDK. To isolate these problems, use the .NET Core Tool Installer task to specify the version of the .NET Core SDK that's used in your build.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

dotnet-core.md

dotnet-core.md

Build, test, and deploy .NET Core apps

Create your first pipeline

Get the code

Sign in to Azure Pipelines

Create the pipeline

YAML

Classic

Build environment

Restore dependencies

Build your project

Build

Install a tool

Run your tests

Collect code coverage

Collect code coverage metrics with Coverlet

.NET 5

.NET < 5

Package and deliver your code

Publish artifacts to Azure Pipelines

Publish to a NuGet feed

Deploy a web app

Publish artifacts to Azure Pipelines

Publish to a NuGet feed

Deploy a web app

Build an image and push to container registry

Troubleshooting

FAQ

Where can I learn more about Azure Artifacts and the TFS Package Management service?

Where can I learn more about .NET Core commands?

Where can I learn more about running tests in my solution?

Where can I learn more about tasks?

Files

dotnet-core.md

Latest commit

History

dotnet-core.md

File metadata and controls

Build, test, and deploy .NET Core apps

Create your first pipeline

Get the code

Sign in to Azure Pipelines

Create the pipeline

YAML

Classic

Build environment

Restore dependencies

Build your project

Build

Install a tool

Run your tests

Collect code coverage

Collect code coverage metrics with Coverlet

.NET 5

.NET < 5

Package and deliver your code

Publish artifacts to Azure Pipelines

Publish to a NuGet feed

Deploy a web app

Publish artifacts to Azure Pipelines

Publish to a NuGet feed

Deploy a web app

Build an image and push to container registry

Troubleshooting

FAQ

Where can I learn more about Azure Artifacts and the TFS Package Management service?

Where can I learn more about .NET Core commands?

Where can I learn more about running tests in my solution?

Where can I learn more about tasks?