.NET Core

This guide explains how to build .NET Core projects. Before you read this topic, you should understand the kind of build definition that you're creating: designer or YAML.

Note

This guidance works for TFS version 2017.3 and newer.

Note

To use YAML you must have the Build YAML definitions preview feature enabled on your account.


Example

If you want some sample code that works with this guidance, import (into VSTS or TFS) or fork (into GitHub) this repo:

https://github.com/adventworks/dotnetcore-sample

Once you have the sample code in your own repository, create a build definition and select the ASP.NET Core template. This automatically adds some of the most commonly needed tasks. Save the definition and queue a build to see it in action. Then, read through the rest of this guidance to learn some of the more common changes that people make to customize a .NET Core build process.

Build environment

You can use VSTS to build your .NET Core projects on Windows, Linux, or macOS without the need to set up any infrastructure of your own. The Microsoft-hosted agents in VSTS have several released versions of the .NET Core SDKs preinstalled. Use the Hosted VS2017 agent queue (to build on Windows), the Hosted Linux Preview agent queue, or the Hosted macOS Preview queue.

In the build definition, select Tasks, then select the Process node, and finally select the Agent queue that you want to use.

The Microsoft-hosted agents do not include some of the older versions of the .NET Core SDK. They also do not typically include prerelease versions. If you need these kinds of SDKs and you prefer to use the Microsoft hosted agents, then add the .NET Core Tool Installer task to the beginning of your process.

If you need a version of the .NET Core SDK that is not already installed on the Microsoft-hosted agent:

  1. In the build definition, select Tasks, choose the phase that runs your build tasks, and then select + to add a new task to that phase.

  2. In the task catalog, find and add the .NET Core Tool Installer task.

  3. Select the task and specify the version of the .NET Core SDK or runtime that you want to install.

Tip

As an alternative to the above approach, you can set up a self-hosted agent and save the cost of running the tool installer. You can also use self-hosted agents to save additional time if you have a large repo or you run incremental builds. For example, you don't select the clean repo option. Or, you don't use the dotnet build --no-incremental or dotnet clean commands.

You can build your .NET Core projects 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.

Restore dependencies

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

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

You can download NuGet packages from NuGet.org.

dotnet restore internally uses 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 .NET Framework project in your solution or use package.json to specify your dependencies, then you must also use the NuGet task to restore those dependencies.

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

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

If your builds fail occasionally when restoring packages from NuGet.org due to connection issues, you can use VSTS Package Management in conjunction with upstream sources and cache the packages in VSTS. The credentials of the build pipeline are automatically used when connecting to VSTS Package Management. These credentials are derived from either the Project Collection Build Service account or the Project Build Service account depending on the option selected in your build definition.

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

If you're using Microsoft-hosted agents, then you get a new machine every time your run a build, which means you end up restoring the packages every time. In many cases, this can cost a significant amount of time. To mitigate this issue, you can either use VSTS Package Management, or use a self-hosted agent, in which case you'll get the benefit of using the package cache.

To restore packages in your build definition:

  1. Select Tasks in the build definition, select the phase that runs your build tasks, and then select + to add a new task to that phase.

  2. In the task catalog, find and add the .NET Core task.

  3. Select the task and for Command select restore.

  4. Specify any other options you need for this task and then save the build.

Build your project

You build your .NET Core project using the .NET Core task with the Command set to build. Running this task is equivalent to running dotnet build from a command prompt.

If you need to run additional .NET Core commands, you can specify other Command settings such as clean or publish. If you need a command not listed, then you can set Command to custom and then type the name of the command in the Custom command box. This is useful, for example, to install dotnet global tools that are available in .NET Core 2.1.300 and newer.

Build

  1. Select Tasks in the build definition, select the phase that runs your build tasks, and then select + to add a new task to that phase.

  2. In the task catalog, find and add the .NET Core task.

  3. Select the task and for Command select build or publish.

  4. Specify any other options you need for this task and then save the build.

Install a tool

To install a .NET Core global tool such as dotnetsay in your build running on Windows:

  1. Add .NET Core task and set the following properties:

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

    • Script: dotnetsay

Run your tests

Use the .NET Core task to run unit tests in your .NET Core solution using testing frameworks such as MSTest, xUnit, and NUnit. One benefit of using this built-in task to run your tests is that the results of the tests are automatically published to VSTS or TFS. These results are then made available to you in the build summary.

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

Package and deliver your code

The output of the dotnet build command is generally not transferable. To prepare your code to run on another machine, you need to package the code.

Publish to a NuGet feed

If you want to publish your code to a NuGet feed:

  1. Use a .NET Core task with the Command set to pack.

  2. Publish your package to a NuGet feed.

Deploy a web app

If you want to deploy a web app:

  1. Use a .NET Core task with the Command set to publish.

  2. Make sure you've selected the option to create a .zip file archive.

When the build is run, it will automatically search the folders in your solution for web projects and produce .zip file packages for each of them.

Troubleshooting

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

  • Check that the version of .NET Core SDK and runtime on your development machine match those on the agent. You can easily include a command line script in your build definition to print the version of .NET Core SDK. The script to use is dotnet --version. Use the .NET Core Tool Installer as explained in this guidance to use the same version on the agent. Or else, update your projects and development machine to the newer version of .NET Core SDK.

  • You may be using special logic in Visual Studio IDE that is not encoded in your build definition. VSTS or TFS run each of the commands specified by you in the tasks one after the other in a new process. Look at the logs from the VSTS/TFS build to note down the exact commands that ran as part of the build. Repeat the same commands in the same order on your machine.

  • If you have a mixed solution that include some .NET Core projects and some .NET Framework projects, then you should also use NuGet task to restore packages specified in package.json files. Similarly, you should add MSBuild or Visual Studio Build tasks to build the .NET Framework projects.

  • If your builds work sometimes and fail other times while restoring packages, then it is either that nuget.org is having issues, or there are networking problems between our data center and nuget.org. These are not in our control, and you may explore whether using VSTS Package Management 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 .NET Core SDK or Visual Studio, something may break with your build. This happens, for instance, because of a newer version or feature of NuGet tool that is shipped with the SDK. To isolate these problems, use the .NET Core Tool Installer task to pin down the version of .NET Core SDK used in your build.

Q&A

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

Package Management in VSTS and TFS

Where can I learn more about .NET Core commands?

.NET Core command-line interface (CLI) tools

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

Unit testing in .NET Core projects

Where can I learn more about tasks?

Build and release tasks