.NET

TeamCity comes with the built-in support of the .NET toolchain providing the .NET build step, .NET detection on the build agents, and autodiscovery of build steps in your repository.

This page gives details on configuring the .NET runner. For a tutorial and demo, see this blog post series.

Requirements

The .NET runner requires the following software to be installed on a build agent machine:

Command	Required software
.NET CLI commands (including cross-platform `msbuild` and `vstest`)	.NET Core SDK (versions 1–3.1) or .NET SDK (version 5.0)
`msbuild` command via `msbuild.exe` (if Windows-only MSBuild version is selected)	Visual Studio (version 2010 or later) or Visual Studio Build Tools (2010 or later) or .NET Framework Developer Pack (version 4.5 or later) with .NET SDK
`vstest` command via `VSTests.Console.exe` (if Windows-only VSTest version is selected)	Visual Studio (version 2010 or later)
`devenv` command	Visual Studio (version 2010 or later)

.NET Version Detection Algorithm

TeamCity searches for the .NET executable files in the following order:

In the directory defined in the environment variable DOTNET_HOME for a TeamCity agent. For example, DOTNET_HOME=D:\SDK\dotnet\.
In the default directory for the .NET executable file:
- Windows: C:\Program Files\dotnet or C:\Program Files (x86)\dotnet, or other default program files directory (depending on the environment variable ProgramW6432)
- Unix: /usr/share/dotnet
- Mac: /usr/local/share/dotnet
In paths specified in the PATH environment variable.

TeamCity will use the first .NET version it finds. If you have several .NET versions installed, we recommend that you specify the most recent version in the DOTNET_HOME variable.

Build Runner Options

Currently, the .NET runner supports the following commands:

Basic .NET CLI commands:
- build
- clean
- restore
  (requires .NET CLI 2.1.400+ for authentication in private feeds)
- pack
- publish
- run
- test
Advanced commands:
- msbuild*
- vstest*
- nuget delete
  (requires .NET CLI 2.1.500+ for authentication in private feeds)
- nuget push
  (requires .NET CLI 2.1.500+ for authentication in private feeds)
Visual Studio command-line mode (read more in the Visual Studio reference ):
- devenv

* msbuild and vstest are executed as CLI commands if cross-platform .NET SDK is used for building a project. Otherwise, they are run using the msbuild or VSTest.Console tool respectively.

Alternatively, you can specify any custom .NET command, and TeamCity will run it as is.

Basic Commands

The set of .NET runner's options depends on the selected command. Available options for basic .NET CLI commands are:

Option	Description
Projects	Paths to projects and solutions, new-line separated. Wildcards are supported. Parameter references are supported. If you have a finished build, you can use the file/directory selector here.
Working directory	Optional, set if differs from the checkout directory. Parameter references are supported. If you have a finished build, you can use the file/directory selector here.
Framework	Target framework. For example, `netcoreapp` or `netstandard`. Parameter references are supported.
Configuration	Target configuration, for example, `Release` or `Debug`. Parameter references are supported.
Runtime	Target runtime. Parameter references are supported. If the specified project file mentions any runtime ID, you can quickly select this runtime by clicking the button.
Options	The "Do not build the projects" checkbox declares whether to build the projects before packing or testing or not.
NuGet package sources	NuGet package sources to use during restoring.
Output directory	The directory where to place outputs. Parameter references are supported. If you have a finished build, you can use the file/directory selector here.
Version suffix	The value of the `$(VersionSuffix)` property in the project. Parameter references are supported.
Command line parameters	Additional command line parameters for the `dotnet` command.
Logging verbosity	Available logging modes: `<Default>`, `Minimal`, `Normal`, `Detailed`, or `Diagnostic`.

Advanced Commands

msbuild

The msbuild command is used for building a project and all its dependencies with the Microsoft Build Engine.
Depending on the selected MSBuild version, msbuild can either be run as the cross-platform .NET CLI command or as the Windows-only msbuild.exe tool.

The msbuild command shares some of the common options with the basic CLI commands of the .NET runner (see the corresponding section for more details).

Supported MSBuild versions: 4 or later / 12 or later.

MSBuild-specific settings are:

Option	Description
Targets	List of targets separated by a space or semicolon. A target is an arbitrary script for your project purposes. Click the list icon next to the field to view available targets.
MSBuild version	Specify the version of the installed MSBuild engine. See the Requirements section for more details.

Migrating from MSBuild Runner

Since TeamCity 2019.2.3, the .NET runner is the recommended method for building projects with the MSBuild engine. We have included the msbuild command to our refactored .NET runner to ensure a long-term support of the .NET platform development strategy.

You can safely switch MSBuild steps in your existing build configurations to the .NET runner. Make sure to copy all additional command-line parameters and other important settings to the new runner. See the msbuild section for more details on the settings available in the .NET runner.

Additional features you will get in the .NET runner are:

Support of cross-platform MSBuild for .NET projects
Ability to build a project for a different platform specified in the Runtime field
Ability to run the project in a Docker container with our Docker Wrapper extension

Consider the following notes before migrating:

The .NET runner uses x86 run platform by default. If the x86 version is not available, it will use x64.
The .NET runner provides code coverage only for dotCover.
Mono is not supported with this runner.

If you are actively using either Mono or NCover/PartCover in your MSBuild steps, please let us know about it via any of the feedback channels.

Migrating from Visual Studio (sln) Runner

The Visual Studio (sln) build runner is using the MSBuild engine under its hood and provides a few tweaks for the VS users to ease their experience with building projects in TeamCity. Since TeamCity 2019.2.3, the .NET runner is the recommended method for building projects with the MSBuild engine which makes it a migration option for the users of the Visual Studio (sln) step as well.

In general, to softly switch each existing Visual Studio (sln) build step to the .NET runner you need to:

Remember/copy the values of your Visual Studio (sln) runner's settings and command-line parameters.
Switch the Visual Studio (sln) build step to the .NET runner and select the msbuild command.
Fill in the fields according to the msbuild section.
Note that certain fields have different analogs in the .NET runner:
- The MSBuild version should be specified instead of the version and platform of Visual Studio. See the reference on versions.
- Paths to solutions should be specified in the Projects field.

Refer to the respective section for more information on migration to msbuild.

vstest

The vstest command is used for testing a project with the VSTest engine and automatically importing the test results. Depending on the selected VSTest version, vstest can either be run as the cross-platform .NET CLI command or as the VSTest console.

Supported VSTest versions: 2013 or later.

The vstest command shares some of the common options with the basic CLI commands of the .NET runner (see the corresponding section for more details).

VSTest-specific fields are:

Option	Description
Test assemblies	Specify the new-line separated list of paths to assemblies to run tests on. Wildcards are supported. Paths to the assemblies must be relative to the build checkout directory.
VSTest version	Specify the installed version of VSTest. See the Requirements section for more details.
Platform	If necessary, specify the target platform: x86, x64, or ARM. Leave <Auto> to use the platform selected by VSTest.
Run in isolation	Select to run the tests in an isolated process.
Test filtration	Select the test filtration mode: Test names: Of all tests discovered in the included assemblies, only the tests with the names matching the provided values will be run. For multiple values, separate them with a new line. If the field is empty, all tests will be run. See details in the Microsoft documentation. Test case filter: Run tests that match the given expression. See details in the Microsoft documentation.
Settings file	Set the path to the `.runsettings` file.

Migrating from Visual Studio Tests Runner

Since TeamCity 2019.2.3, the .NET runner is the recommended method for testing projects with VSTest instead of the Visual Studio Tests runner. We have included the vstest command to our refactored .NET runner to ensure a long-term support of the .NET platform development strategy.

You can safely migrate existing Visual Studio Tests build steps to the .NET runner with the selected vstest command. Make sure to copy all additional command-line parameters and other important settings to the new runner. See the vstest section for more details on the settings available in the .NET runner.

Additional features you will get in the .NET runner are:

Support of cross-platform VSTest for .NET projects
Real-time test reporting by default
Support of ARM platform, along with x86 and x64
Ability to run and test the project inside a Docker container with our Docker Wrapper extension

Consider the following notes before migrating:

The .NET runner supports the new .runsettings format of the VSTest settings file. However, it does not support the obsolete run configuration file format used in the Visual Studio Tests runner.
Instead of the framework version, the .NET runner requests to specify the VSTest version.
The .NET runner provides code coverage only for dotCover. If you are actively using NCover or PartCover in your MSBuild steps, please let us know about it via any of the feedback channels.
The .NET runner does not support the MSTest tool since all features of its framework are covered by VSTest. If you were using MSTest as the engine of the Visual Studio Tests runner, we suggest that you switch to VSTest when migrating to the .NET runner.

nuget delete

TeamCity provides full support for the nuget delete command.

nuget push

TeamCity provides full support for the nuget push command.

Visual Studio Command-Line Mode

Since TeamCity 2019.2.3, the .NET runner supports the Visual Studio command-line mode with the devenv command.

Devenv allows configuring custom options for the IDE, build, debug, and deploy projects from the command line using different switches.

devenv shares some of the common options with the basic CLI commands of the .NET runner (see the corresponding section for more details).

Devenv-specific fields are:

Option	Description
Build action	Select one of the supported switches: `clean`, `rebuild`, `build`, or `deploy`.
Visual Studio version	If necessary, specify the version of the installed Visual Studio. Leave <Any> to use the latest installed version. See the Requirements section for more details.

Option

Description

Build action

Select one of the supported switches: clean, rebuild, build, or deploy.

Visual Studio version

If necessary, specify the version of the installed Visual Studio. Leave <Any> to use the latest installed version.

See the Requirements section for more details.

Custom Commands

Since TeamCity 2020.1.1, the .NET runner allows launching any custom .NET command or executable file as is.

The runner provides the following settings for the <custom> command option:

Executables
Command line parameters
Working directory
.NET coverage
Docker settings

The Executables field expects files with the .com, .exe, .cmd, .bat, .sh, .dll extensions as well as files with no extension. You can specify multiple executable files, separated by a new line.

The Command line parameters field allows entering any custom command or arguments to complement the specified executable.

Depending on the entered settings, the .NET runner will transparently treat each custom command. Refer to the following list for common use case examples:

Use case	Executables	Command line parameters	Result
Install the specified .NET Core tool on your machine		tool install <toolname>	Runs `dotnet` with the specified parameters. For example, on Windows, `dotnet.exe tool install <toolname>`.
Run a .NET application with arguments	MyApp.dll	-- arg1 arg2 arg3	Runs `MyApp.dll -- arg1 arg2 arg3`.
Display a user	whoami.exe		Runs the Windows `whoami.exe` process.
Run XUnit tests via console	C:\XUnit\xunit.console.exe	C:\TestAssemblies\MyTests.dll -xml C:\TestResults\MyTests.xml	Runs XUnit tests on Windows via `xunit.console.exe`. This case if often used to collect code coverage statistics.
Run all CMD files in the `scripts` directory with the same arguments	scripts/*.cmd	arg1 arg2	Uses the default Windows command-line interpreter `cmd.exe` to run all `.cmd` scripts in the specified directory with the same set of parameters `arg1 arg2`.
Run SH files with the same arguments	build_src.sh build_doc.sh	-c release	Uses `/bin/sh` to run both specified `.sh` scripts with the same parameters `-c release`.

Docker Settings

The .NET CLI build step can be run in a specified Docker container.

Code Coverage

JetBrains dotCover is supported as a coverage tool for msbuild, test, vstest, and a number of custom commands.

Authentication in Private NuGet Feeds

TeamCity allows you to authenticate using private NuGet feeds. Read more in NuGet.

Parameters Reported by Agent

When starting, the build agent reports the following parameters:

Parameter	Description
`DotNetCLI`	The .NET CLI version.
`DotNetCLI_Path`	The path to .NET CLI executable.
`DotNetCoreSDKx.x_Path`	The .NET SDK version.

.NET runner F.A.Q.

How to pass parameters containing spaces

The best way to pass a parameter value containing space characters is to use system properties. For example, you can add the system.Platform parameter with the Any CPU value in Build Configuration Settings | Parameters and then refer to this value as %system.Platform% inside the .NET step.
An alternative approach is to wrap the command-line parameter as follows: "/p:Platform=Any CPU".

Last modified: 16 February 2021