TeamCity On-Premises 2024.03 Help

.NET

TeamCity提供了内置的.NET工具链支持，包括.NET构建步骤，构建代理上的.NET检测，以及您的存储库中构建步骤的自动发现功能。

这个页面详细介绍了如何配置 .NET 运行器。 关于教程和演示，请参见此 博客文章系列。

要求

.NET 运行器需要在构建代理机器上安装以下软件：

命令

所需软件

.NET CLI 命令
（包括跨平台 msbuild 和 vstest）

msbuild 命令通过 msbuild.exe
（如果选择了仅限 Windows 的 MSBuild 版本）

  • Visual Studio（版本2010或更高版本）
    或

  • Visual Studio 构建工具（2010 或更晚版本）
    或

  • .NET Framework 开发者包（版本 4.5 或更高）和 .NET SDK

vstest 命令通过 VSTests.Console.exe
（如果选择了仅限 Windows 的 VSTest 版本）

  • Visual Studio（版本2010或更高版本）

devenv 命令

  • Visual Studio（版本2010或更高版本）

.NET 版本检测算法

TeamCity 按以下顺序搜索 .NET 可执行文件：

  1. 在环境变量 DOTNET_HOME 中定义的目录中的 TeamCity 代理。 例如， DOTNET_HOME=D:\SDK\dotnet\。

  2. 在 .NET 可执行文件的默认目录中：

    • Windows： C:\Program Files\dotnet 或 C:\Program Files (x86)\dotnet ，或者其它默认的程序文件目录（依赖于环境变量 ProgramW6432）

    • Unix： /usr/share/dotnet

    • Mac： /usr/local/share/dotnet

  3. 在由 PATH 环境变量指定的路径中。

TeamCity 将使用其找到的第一个 .NET 版本。 如果您已安装了多个 .NET 版本，我们建议您在 DOTNET_HOME 变量中指定最新的版本。

构建运行程序选项

目前，.NET 运行器支持以下命令：

* msbuild 和 vstest 在使用跨平台 .NET SDK 构建项目时会作为 CLI 命令 执行。 否则，它们将分别使用 msbuild 或 VSTest.Console 工具运行。

或者，您可以指定任何自定义 .NET 命令 ，TeamCity 将原样运行它。

基本命令

.NET 运行器的选项集取决于所选的命令。 基本的 .NET CLI 命令可用的选项包括：

选项

描述

项目

到项目和解决方案的路径，用新行分隔。 支持使用通配符。 支持参数引用。 如果您有已完成的构建，您可以在此处使用文件 / 目录选择器。

工作目录

可选，如果与 checkout directory 不同，请设置。 支持参数引用。 如果您有已完成的构建，您可以在此处使用文件 / 目录选择器。

框架

目标框架. 例如， netcoreapp 或 netstandard。 支持参数引用。

所需的 SDK

允许指定必须在构建代理上安装的 SDK，以便它能运行此构建。 TeamCity 会自动为此字段中指定的每个 SDK 创建一个 代理要求。

期望一个由 SDK 或定向包版本构成的空格分隔的列表。 例如， 5 4.8 只有在拥有 .NET 5.0 和 .NET 4.8 的情况下，代理才能运行构建。

配置

目标配置，例如， 发布 或 调试。 支持参数引用。

运行时

目标运行时.

支持参数引用。 如果指定的 项目文件 中提到了任何 运行时 ID，您可以通过点击 切换至 Sakura UI 按钮快速选择此运行时。

选项

Do not build the projects"复选框声明是否在打包或测试前构建项目。

如果您在 test 或 vstest 命令中将多个测试程序集列为目标，请使用 "在单次会话中运行测试" 复选框来指定 TeamCity 是否应为每个目标调用单独的测试命令。

NuGet 包源

在恢复过程中使用的 NuGet 包源。

输出目录

放置输出的目录。 支持参数引用。 如果您有已完成的构建，您可以在此处使用文件 / 目录选择器。

版本后缀

项目中 $(VersionSuffix) 属性的值。 支持参数引用。

命令行形参

额外的命令行参数用于 dotnet 命令。

日志详细程度

可用的日志模式： <默认>、 最小、 普通、 详细 或 诊断。

高级指令

msbuild

msbuild 命令用于使用 Microsoft Build Engine 构建一个项目及其所有依赖项。
根据选择的 MSBuild 版本， msbuild 可以作为跨平台的 .NET CLI命令 运行，或者作为 仅限 Windows 的 msbuild.exe 工具 运行。

msbuild 命令与 .NET 运行器的基础 CLI 命令共享一些常见选项（详见 相应部分了解更多细节）。

支持的 MSBuild 版本：4 或更高版本 / 12 或更高版本。

MSBuild 特定的设置如下：

选项

描述

目标

由空格或分号分隔的目标列表。 目标是为您的项目目的设定的任意脚本。 点击字段旁边的列表图标以查看可用的目标。

MSBuild 版本

指定已安装的 MSBuild 引擎的版本。 为了确保使用特定版本的本地 MSBuild（例如，在 Docker 容器中），您需要在 PATH 环境变量中设置 MSBuild.exe 的路径。

参阅 要求 部分以获取更多细节。

如果您在此字段中设置了版本，并选择使用 Docker （带有 容器包装器 ）运行当前步骤，确保在 PATH 环境变量中指定到 MSBuild.exe 的路径。 这样，.NET 运行器甚至能在 Docker 容器内找到所需的可执行文件。

vstest

vstest 命令用于使用 VSTest 引擎测试项目，并自动导入测试结果。 根据选择的 VSTest 版本， vstest 可以作为跨平台 .NET CLI 命令运行，也可以作为VSTest 控制台运行。

支持的 VSTest 版本：2013 或更晚。

vstest 命令与 .NET 运行器的基础 CLI 命令共享一些常见选项（详见 相应部分了解更多细节）。

VSTest特定的字段包括：

选项

描述

测试程序集

指定要在其上运行测试的程序集路径的换行符分隔列表。 通配符得到了支持。

程序集的路径必须相对于构建检出目录。

排除的测试程序集

vstest 命令应忽略的程序集路径的新行分隔列表。 通配符得到了支持。

程序集的路径必须相对于构建检出目录。

VSTest 版本

指定已安装的 VSTest 版本。 参阅 要求 部分以获取更多细节。

平台

如有必要，指定目标平台：x86，x64 或 ARM。 将 <Auto> 保留为 VSTest 选择的平台。

在隔离中运行

选择在独立的进程中运行测试。

测试过滤

选择测试过滤模式：

  • 测试名称：在所有被发现的包含在汇编中的测试里，仅有与提供的值匹配的测试名称会被运行。 对于多个值，请用新行进行分隔。 如果该字段为空，将会运行所有的测试。 请参阅 Microsoft 文档 中的详细信息。

  • 测试用例过滤器：运行与给定表达式匹配的测试。 请参阅 Microsoft 文档 中的详细信息。

另见：运行选定的单元测试

测试重试次数

如果测试失败，TeamCity 可以在同一构建运行期间无缝启动所述测试的自动重新运行。 失败的测试将重新启动，直到它们成功或达到最大尝试次数。 这种技术可以让您识别 flaky tests，并将它们与真正有问题的、无论尝试执行多少次都会一直失败的测试区分开来。

最初失败但在后续重运行中成功完成的测试会被自动静音。 您可以检查构建结果页面的 Tests tab，以查看每个测试需要重复运行多少次。

在重新运行期间的不稳定测试

设置文件

将路径设置为 .runsettings 文件。

nuget delete

TeamCity 提供了对 nuget delete 命令的全面支持。

nuget push

TeamCity 提供了对 nuget push 命令的全面支持。

Visual Studio 命令行模式

.Net 运行器 支持使用 devenv 命令的 Visual Studio 命令行模式。

Devenv 允许使用不同的 开关 来配置 IDE 的自定义选项，从命令行构建、调试和部署项目。

devenv 与 .NET 运行器的基本 CLI 命令共享了一些常见选项（有关更多详细信息，请参阅 对应部分）。

Devenv 特定的字段有：

选项

描述

构建操作

选择支持的开关之一： 清理， 重新构建， 构建 或 部署。

Visual Studio 版本

如有必要，指定已安装的 Visual Studio 的版本。 保留 <Any> 以使用最新的已安装版本。

参阅 要求 部分以获取更多细节。

自定义命令

自 TeamCity 2020.1.1 版本起，.NET 运行器可以按原样启动任何自定义 .NET 命令或可执行文件。

运行器为 <custom> 命令选项提供以下设置：

Executables 字段期待具有 .com， .exe， .cmd， .bat， .sh ，以及 .dll 扩展名的文件，以及没有扩展名的文件。 您可以指定多个可执行文件，每个文件之间用新行分隔。

Command line parameters 字段允许输入任何自定义命令或参数来补充指定的可执行文件。

根据输入的设置， .NET 运行器将透明地处理每个自定义命令。 参考以下列表以获得常见用例示例：

使用案例

可执行文件

命令行形参

结果

安装 指定的 .NET Core 工具到您的机器上

工具安装 <工具名称>

以指定的参数运行 dotnet。 例如，在 Windows 上， dotnet.exe tool install <工具名>。

使用参数运行 .NET 应用程序

MyApp.dll

-- arg1 arg2 arg3

运行 MyApp.dll -- arg1 arg2 arg3。

显示一个用户

whoami.exe

运行 Windows whoami.exe 进程。

通过控制台运行 XUnit 测试

C:\XUnit\xunit.console.exe

C:\TestAssemblies\MyTests.dll -xml C:\TestResults\MyTests.xml

在 Windows 上通过 xunit.console.exe 运行 XUnit 测试。 此案例经常用于收集代码覆盖率统计数据。

使用相同的参数运行 脚本 目录中的所有 CMD 文件

scripts/*.cmd

arg1 arg2

使用默认的 Windows 命令行解释器 cmd.exe 来运行在指定目录中的所有脚本 .cmd ，并且使用相同的一组参数 arg1 arg2。

使用相同参数运行 SH 文件

build_src.sh
build_doc.sh

-c release

使用 /bin/sh 同时运行指定的 .sh 脚本，参数为 -c release。

Docker 设置

.NET CLI 构建步骤可以在指定的 Docker 容器 中运行。

Code Coverage（代码覆盖率）

JetBrains dotCover作为覆盖工具支持 msbuild、 test、 vstest ，以及一些自定义命令。 要将多个单独的 .NET 运行器生成的快照合并为一份综合报告，将 dotCover 添加到您的配置中。

私有 NuGet 源中的身份验证

TeamCity 允许您使用私有 NuGet 供稿进行身份验证。 在 NuGet 中阅读更多信息。

由代理报告的参数

在启动时，构建代理会报告以下参数：

DotNetCLI

.NET CLI 版本。

DotNetCLI_Path

.NET CLI可执行文件的路径。

DotNetFramework <版本>[_x86 | _X64]

仅当相应版本的 .NET Framework 运行时已安装，才会定义。

DotNetFramework<version>[_x86|_x64]_Path

此参数的值被设置为相应框架运行时版本的路径。

请注意，此参数仅为每个主要版本的最新安装版本定义。 例如，如果您安装了 3.5 、 4.5 和 4.8 的版本，此参数将仅为 3.5 和 4.8 定义。 版本/参数 4.5 将被省略，因为存在 .NET Framework 4 的较新版本。 要明确定义此类版本，请考虑改用 DotNetFrameworkTargetingPack<version>_Path 参数。

DotNetFrameworkSDK<version>[_x86|_x64]

定义是否已安装对应版本的 .NET Framework SDK 。

DotNetFrameworkSDK<version>[_x86|_x64]_Path

对应框架 SDK 版本的路径。

DotNetFrameworkTargetingPack<version>_Path

对应的参考程序集（又名目标包）位置的路径。

DotNetCoreSDKx.x_Path

.NET SDK 版本。

DotNetWorkloads_<版本>

列出代理机器上安装的所有 .NET 工作负载。

末尾的 <version> 是已安装的 .NET SDK 的版本。 例如，如果安装了版本 7.0.300，代理将报告 `DotNetWorkloads_7.0.300` 参数。

除了这些完整的 SDK 版本，代理还会报告带有缩短的 major.minor 后缀的工作负载参数。 例如，如果代理机器已安装了 7.0.100、7.0.200 和 7.0.300 的 .NET SDK，那么将报告引用最高版本 7.0.300 的 DotNetWorkloads_7.0 参数。

参数值是由逗号分隔的工作负载名称字符串，根据 <dotnet_dir>/metadata/workloads/<sdk_version>/InstalledWorkloads目录中的文件夹。 例如，"android,maui-ios,wasm-tools"。

WindowsSDK<version>

只有在安装了相应的 Windows SDK 版本后才会定义。

WindowsSDK<version>_Path

对应版本的 Windows SDK 的路径。

VS<Version>

定义是否已安装对应的 Visual Studio 版本

VS<Version>_Path

指向 Visual Studio 安装文件夹的路径（包含 devenv.exe 的目录）。

teamcity.dotnet.nunitlauncher<版本>

包含独立 NUnit 测试启动器的目录路径， NUnitLauncher.exe。 版本号是指测试将在其下运行的 .NET Framework 的版本。 版本等同于 .NET Framework 的版本。

teamcity.dotnet.nunitlauncher.msbuild.task

包含 MSBuild 任务 dll 的目录的路径，为 MSBuild 和 Visual Studio (sln) 提供 NUnit 任务。

teamcity.dotnet.msbuild.extensions2.0

包含 MSBuild 2.0 监听器和任务组件的目录的路径。

teamcity.dotnet.msbuild.extensions4.0

包含 MSBuild 4.0 监听器和任务程序集的目录路径。

从已弃用的 Runners 迁移到 .Net 运行器

从 MSBuild Runner 迁移

自 TeamCity 2019.2.3 起，.NET 运行器成为了使用 MSBuild 引擎构建项目的推荐方法。 我们已将 msbuild 命令包含在我们重构的 .NET 运行器中，以确保长期支持 .NET 平台开发策略。

您可以安全地将您现有的构建配置中的 MSBuild steps 切换到 .Net 运行器。 确保将所有额外的命令行参数和其他重要设置复制到新的运行器。 请查看 msbuild 部分，了解 .NET 运行器中可用的设置的更多详细信息。

您将在 .NET 运行器中获得的额外功能包括：

  • 对跨平台 MSBuild 进行 .NET 项目的支持。

  • 在 Runtime 字段中指定的不同平台上构建项目的能力。

  • 具有在 Docker 容器中运行项目的能力，使用我们的 容器包装器 扩展。

在迁移之前，请考虑以下注意事项：

  • .NET 运行器默认使用 x86 运行平台。 如果 x86 版本不可用，那么将会使用 x64。

  • .Net 运行器 仅为 dotCover 提供代码覆盖率。

  • Mono 不支持此运行程序。

如果您正在积极使用 Mono 或 NCover/PartCover 来进行 MSBuild 步骤，请通过任何反馈渠道告知我们。

从 Visual Studio （sln）Runner 迁移

Visual Studio (sln) 构建运行程序在其内部使用 MSBuild 引擎，并为 VS 用户提供了一些调整，以便于他们在 TeamCity 中构建项目的体验。 自 TeamCity 2019.2.3 版本以来，.Net 运行器 已成为使用 MSBuild 引擎构建项目的推荐方法，因此也是 Visual Studio （sln）步骤的用户迁移选项。

一般来说，如果您需要将每个现有的 Visual Studio （sln）构建步骤温和地切换到 .NET 运行器，您需要：

  1. 请记住/复制您的 Visual Studio （sln）运行器的设置值和命令行参数。

  2. 将 Visual Studio （sln）构建步骤切换至 .NET 运行器，并选择 msbuild 命令。

  3. 根据 msbuild 部分填写字段。
    请注意，某些字段在 .NET 运行器中有不同的对应项：

    • 应指定 MSBuild 的版本，而不是 Visual Studio 的版本和平台。 参见 版本参考。

    • 解决方案的路径应在 Projects 字段中指定。

有关迁移到 msbuild 的更多信息，请参阅 相关部分。

从 Visual Studio 测试运行器迁移

自 TeamCity 2019.2.3 起，推荐使用 .NET 运行器来代替 Visual Studio Tests 运行器进行 VSTest 项目测试。 我们已经在我们重构的 .NET 运行器中加入了 vstest 命令，以确保 .NET 平台开发策略的长期支持。

您可以安全地将现有的 Visual Studio Tests 构建步骤迁移到带有所选 vstest 命令的 .NET 运行器。 确保将所有额外的命令行参数和其他重要设置复制到新的运行器。 请查看 vstest 部分，了解 .NET 运行器中可用的设置的更多详细信息。

您将在 .NET 运行器中获得的额外功能包括：

  • 支持跨平台 VSTest 用于 .NET 项目。

  • 默认实时测试报告。

  • 对 ARM 平台的支持，以及 x86 和 x64。

  • 具有在 Docker 容器内运行和测试项目的能力，我们的 容器包装器 扩展。

在迁移之前，请考虑以下注意事项：

  • .Net 运行器 支持新的 .runsettings VSTest 设置文件的格式。 然而，它并不支持 Visual Studio Tests 运行器中使用的过时的运行配置文件格式。

  • 而不是框架版本，.NET 运行器要求指定 VSTest 版本。

  • .Net 运行器 仅为 dotCover 提供代码覆盖率。 如果您在 MSBuild 步骤中积极使用 NCover 或 PartCover，请通过任何一种反馈渠道告诉我们。

  • .NET 运行器不支持 MSTest 工具，因为其框架的所有特性都被 VSTest 所覆盖。 如果您之前使用 MSTest 作为 Visual Studio Tests 运行器的引擎，我们建议您在迁移到 .NET 运行器时切换到 VSTest。

并行测试

如果 .NET 运行器执行 test 或 vstest 命令，TeamCity 可以将工作负载分成几个批次。 在这种情况下，测试是在单独的自动生成构建（在单独的构建代理上）中进行的。 为了启用这种行为，将 并行测试 构建功能添加到 TeamCity 构建配置中。

.NET 运行器 常见问题解答

如何传递包含空格的参数

将包含空格字符的参数值传递的最佳方式是使用 系统属性。 例如，您可以在 Build Configuration Settings | Parameters 中添加带有 任何 CPU 值的 system.Platform 参数，然后在 .NET 步骤内部将此值作为 %system.Platform% 进行引用。

一种替代方法是按照如下方式封装命令行参数： """/p:Platform=Any CPU"""。

最后修改日期： 16日 7月 2024年
NAnt Mono 支持