.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.
note
Since TeamCity 2019.2.3, the .NET CLI (dotnet) build runner has been refactored and renamed to .NET thus emphasizing that now it supports all .NET-related operations previously implemented in TeamCity as multiple build runners.
Note that we stop providing active support for the MSBuild, Visual Studio (sln), Visual Studio 2003, and Visual Studio Tests runners. These runners are left for compatibility of existing build configurations with new versions of TeamCity. To receive the following updates and use extra features of our .NET implementation, we suggest that you select the .NET runner instead of any listed runner in all corresponding build steps. This page describes the settings of all supported .NET commands and gives guidelines on migration from the obsolete build runners.
The .NET runner requires the following software to be installed on a build agent machine:
Command | Required software |
|---|---|
.NET CLI commands |
|
|
|
|
|
|
|
TeamCity searches for the .NET executable files in the following order:
In the directory defined in the environment variable
DOTNET_HOMEfor a TeamCity agent. For example,DOTNET_HOME=D:\SDK\dotnet\.In the default directory for the .NET executable file:
Windows:
C:\Program Files\dotnetorC:\Program Files (x86)\dotnet, or other default program files directory (depending on the environment variableProgramW6432)Unix:
/usr/share/dotnetMac:
/usr/local/share/dotnet
In paths specified in the
PATHenvironment 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.
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.
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: |
button.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 |
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 |
TeamCity provides full support for the nuget delete command.
TeamCity provides full support for the nuget push command.
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).
note
Before running Visual Studio from TeamCity under a specific user, we highly recommended launching it in the UI mode from this user's account at least once. On the first start, VS usually displays pop-up dialogs which might hang a build running the
devenvcommand. Once closed during the first launch, these dialogs won't be generated during the following launches in the devenv-mode and no hanging will occur.
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. |
note
Note that Devenv does not provide functionality for displaying a structured build log or test reports. Its main purpose is to allow using custom switches and add-ins for Visual Studio.
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 |
The .NET CLI build step can be run in a specified Docker container.
JetBrains dotCover is supported as a coverage tool for msbuild, test, vstest, and a number of custom commands.
TeamCity allows you to authenticate using private NuGet feeds. Read more in NuGet.
When starting, the build agent reports the following parameters:
DotNetFramework<version>[_x86|_x64]
Defined only if the corresponding version(s) of .NET Framework runtime is installed.
DotNetFramework<version>[_x86|_x64]_Path
This parameter's value is set to the corresponding framework runtime version(s) path(s).
Note that this parameter is defined only for the latest installed version per major release. For example, if you installed versions 3.5, 4.5, and 4.8, this parameter will only be defined for 3.5 and 4.8. Version/Parameter 4.5 will be omitted since a newer version of .NET Framework 4 is present. To explicitly define such a version, consider using theDotNetFrameworkTargetingPack<version>_Pathparameter instead.DotNetFrameworkSDK<version>[_x86|_x64]
Defined if the corresponding version(s) of .NET Framework SDK is installed.
DotNetFrameworkTargetingPack<version>_Path
The path to the corresponding Reference assemblies (AKA Targeting Pack) location.
DotNetWorkloads_<version>
Lists all .NET workloads installed on the agent machine.
The<version>suffix is the version of an installed .NET SDK. For instance, if version 7.0.300 is installed, the agent will report the `DotNetWorkloads_7.0.300` parameter.
In addition to these full SDK versions, agents report workload parameters with shortenedmajor.minorsuffixes. For example, if an agent machine has 7.0.100, 7.0.200, and 7.0.300 .NET SDKs installed, theDotNetWorkloads_7.0parameter that refers to the highest 7.0.300 version will be reported.
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".VS<Version>_Path
The path to the Visual Studio installation folder (the directory that contains devenv.exe).
teamcity.dotnet.nunitlauncher<version>
The path to the directory that contains the standalone NUnit test launcher,
NUnitLauncher.exe. The version number refers to the version of .NET Framework under which the test will run. The version equals the version of .NET Framework.teamcity.dotnet.nunitlauncher.msbuild.task
The path to the directory that contains the MSBuild task
dllproviding the NUnit task for MSBuild, Visual Studio (sln).
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.
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
msbuildcommand.Fill in the fields according to the
msbuildsection.
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.
note
Note that TeamCity provides a new way to run Visual Studio projects. The .NET runner supports a full-featured implementation of the VS command-line mode with the
devenvcommand (read more).
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
.runsettingsformat 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.
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.
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".
Thanks for your feedback!