TeamCity On-Premises 2024.12 Help

.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)

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:

  1. In the directory defined in the environment variable DOTNET_HOME for a TeamCity agent. For example, DOTNET_HOME=D:\SDK\dotnet\.

  2. 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

  3. 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:

* 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.

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, 5 4.8 will allow an agent to run the build only if it has .NET 5.0 and .NET 4.8 installed.

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 Switch to the Sakura UI button.

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 test or vstest command, use the " Run tests in a single session " checkbox to specify whether TeamCity should invoke a separate testing command for each target.

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. To ensure that a specific version of native MSBuild is used (for example, in a Docker container), you need to set the path to MSBuild.exe in the PATH environment variable.

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 MSBuild.exe in the PATH environment variable. This way, the .NET runner will be able to find the required executable file even within the Docker container.

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.

Excluded test assemblies

The new-line separated list of paths to assemblies that the vstest command should ignore. 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.

See also: Run selected unit tests

Test retry count

In the event of a test failure, TeamCity can seamlessly initiate automated re-runs of said test during the same build run. Failed tests are re-launched until they either achieve success or exhaust the maximum number of attempts. This technique allows you to identify flaky tests and distinguish them from genuinely problematic tests that consistently fail regardless of the number of launch attempts.

Tests that initially failed but managed to finish successfully during subsequent re-runs are automatically muted. You can check the Tests tab of a build results page to see how many re-runs were required for each test.

Flaky tests during a re-run

Settings file

Set the path to the .runsettings file.

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: 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:

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. To merge snapshots produced by multiple individual .NET runners into one consolidated report, add the dotCover to your configuration.

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:

DotNetCLI

The .NET CLI version.

DotNetCLI_Path

The path to .NET CLI executable.

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 the DotNetFrameworkTargetingPack<version>_Path parameter instead.

DotNetFrameworkSDK<version>[_x86|_x64]

Defined if the corresponding version(s) of .NET Framework SDK is installed.

DotNetFrameworkSDK<version>[_x86|_x64]_Path

The path to the corresponding framework SDK version.

DotNetFrameworkTargetingPack<version>_Path

The path to the corresponding Reference assemblies (AKA Targeting Pack) location.

DotNetCoreSDKx.x_Path

The .NET SDK version.

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 shortened major.minor suffixes. For example, if an agent machine has 7.0.100, 7.0.200, and 7.0.300 .NET SDKs installed, the DotNetWorkloads_7.0 parameter 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".

WindowsSDK<version>

Defined only if the corresponding version of Windows SDK is installed.

WindowsSDK<version>_Path

The path of the corresponding version of Windows SDK.

VS<Version>

Defined if the corresponding version(s) of Visual Studio is installed

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 dll providing the NUnit task for MSBuild, Visual Studio (sln).

teamcity.dotnet.msbuild.extensions2.0

The path to the directory that contains MSBuild 2.0 listener and tasks assemblies.

teamcity.dotnet.msbuild.extensions4.0

The path to the directory that contains MSBuild 4.0 listener and tasks assemblies.

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:

  1. Remember/copy the values of your Visual Studio (sln) runner's settings and command-line parameters.

  2. Switch the Visual Studio (sln) build step to the .NET runner and select the msbuild command.

  3. 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".

Last modified: 03 November 2024
NAntMono Support