.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 |
|
|
|
|
|
|
|
.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
orC:\Program Files (x86)\dotnet
, or other default program files directory (depending on the environment variableProgramW6432
)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:
Advanced commands:
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):
* 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, |
Required SDK | Allows specifying SDKs that must be installed on a build agent, so that it can run this build. TeamCity automatically creates an agent requirement for each SDK specified in this field. Expects a space-separated list of SDK or targeting pack versions. For example, |
Configuration | Target configuration, for example, |
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 |
Options | The "Do not build the projects" checkbox declares whether to build the projects before packing or testing or not. If you list multiple test assemblies as targets for a |
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 |
Command line parameters | Additional command line parameters for the |
Logging verbosity | Available logging modes: |
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. To ensure that a specific version of native MSBuild is used (for example, in a Docker container), you need to set the path to See the Requirements section for more details. If you set the version in this field and choose to run the current step using Docker (with Container Wrapper), make sure to specify the path to |
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. |
Excluded test assemblies | The new-line separated list of paths to assemblies that the |
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:
See also: Run selected unit tests |
Settings file | Set the path to the |
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
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: |
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
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 | |
Run a .NET application with arguments | MyApp.dll | -- arg1 arg2 arg3 | Runs |
whoami.exe | Runs the Windows | ||
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 |
Run all CMD files in the | scripts/*.cmd | arg1 arg2 | Uses the default Windows command-line interpreter |
Run SH files with the same arguments | build_src.sh | -c release | Uses |
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 |
---|---|
| The .NET CLI version. |
| The path to .NET CLI executable. |
| The .NET SDK version. |
| Lists all .NET workloads installed on the agent machine. The In addition to these full SDK versions, agents also report workload parameters with shortened The parameter value is a string of comma-separated workload names, according to folders in the <dotnet_dir>/metadata/workloads/<sdk_version>/InstalledWorkloads directory. For instance, "android,maui-ios,wasm-tools". |
Migrating from Deprecated Runners to .NET Runner
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 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 Container 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
.
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 Container 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.
Parallel Testing
If the .NET runner executes test
or vstest
commands, TeamCity can split the workload into several batches. In this case testing is carried out in separate automatically generated builds (on separate build agents). To enable this behavior, add the Parallel Tests build feature to the TeamCity build configuration.
.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"
.