.NET

.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 CLI 2.1.400+ 以在 私有源中进行身份验证)

• pack

• publish

• run

• test

• msbuild

• vstest

• nuget delete
  (需要 .NET CLI 2.1.500+ 以在 私有源进行身份验证)

• nuget push
  (需要 .NET CLI 2.1.500+ 以在 私有源进行身份验证)

• devenv （详细内容请参阅 Visual Studio 参考文档）

• 自定义 .NET 命令

项目

按换行符分隔的项目和解决方案路径列表。 支持 * 通配符。 不支持参数引用。

工作目录

构建步骤启动的目录。 默认情况下，这是代理签出远程资源的根目录。 有关更多信息，请参阅此主题： 构建工作目录。

框架

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

所需的 SDK

按空格分隔的 SDK 列表，必须安装在构建代理上。 例如， 8 4.8.2。

未安装对应 SDK 的代理将被 标记为不兼容 ，无法运行此次构建。

配置

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

运行时

目标运行时. 支持参数引用。

如果指定的 项目文件 中提到了任何 运行时 ID ，您可以通过点击 按钮快速选择此运行时。

选项

特定命令可用的附加选项。

• 不要构建项目 — 允许在不先构建的前提下发布或测试项目。

• 在单个会话中运行测试 — 当多个测试程序集作为 test 或 vstest 命令的目标列出时，TeamCity 会为每个目标分别调用一次测试命令。

NuGet 包源

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

输出目录

放置输出的目录。 支持参数引用。

版本后缀

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

命令行形参

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

日志详细程度

允许您选择以下日志详细模式之一：

• <默认>

• Minimal

• Normal

• Detailed

• Diagnostic

'msbuild' 命令选项

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

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

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

目标

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

MSBuild 版本

已安装的 MSBuild 引擎版本。 为了确保使用特定版本的本地 MSBuild（例如，在 Docker 容器中），您需要在 PATH 环境变量中设置 MSBuild.exe 的路径。 有关详细信息，请参阅 Agent Requirements（代理要求） 部分。

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

'vstest' 命令选项

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

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

测试程序集

按换行符分隔的路径列表（相对于 构建检出目录 ），指定要运行测试的程序集。 支持 通配符。

排除的测试程序集

按换行符分隔的路径列表（相对于 构建检出目录 ），指定 vstest 命令应忽略的程序集。 支持 通配符。

VSTest 版本

要使用的 VSTest 版本。 有关更多信息，请参阅 Agent Requirements（代理要求） 部分。

平台

目标平台。 例如， x86、 x64 或 ARM。 保留 <自动> ，以便 VSTest 自动选择平台。

在隔离中运行

允许 TeamCity 在隔离进程中运行测试。

测试过滤

允许您选择以下测试过滤模式之一：

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

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

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

测试重试次数

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

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

设置文件

.runsettings 文件的路径。

'devenv' 命令选项

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

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

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

构建操作

支持的值如下：

• 清理

• 重新构建

• 构建

• 部署

Visual Studio 版本

已安装的 Visual Studio 版本。 保留 <Any> 以使用最新的已安装版本。

有关详细信息，请参阅 Agent Requirements（代理要求） 部分。

容器设置

此构建步骤可在由 Docker 或 Podman 部署的容器中运行。

传统构建配置步骤显示一组属性，允许您指定镜像名称、平台和附加运行参数。 显式拉取镜像 可确保 TeamCity 每次运行此步骤时都从目标容器拉取镜像。

要为 TeamCity 指定拉取镜像的注册表，请将 Docker/Podman 连接 添加到项目中。 默认情况下，此连接允许 TeamCity 以匿名模式从 Docker Hub 拉取镜像，但您可以将其配置为使用任何容器注册表。

有关更多信息，请参阅以下文章： 容器包装器。

启用 在 Docker 中运行 以在容器中运行步骤。 启用后，此元素会显示两个选项。

• Docker 镜像 — 允许您从 Docker 或 Podman 注册表中拉取镜像。 默认情况下，TeamCity 可在匿名模式下从 Docker Hub 拉取镜像。 对于其他情况（私有镜像、自定义镜像注册表、非匿名模式以避免违反 Docker Hub 速率限制），请在流水线或作业级别配置 Docker 集成。

• Dockerfile — 允许您从 Dockerfile 构建自定义镜像。

Code Coverage（代码覆盖率）

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

从已弃用的 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。

如何传递包含空格的参数

将包含空格字符的参数值传递的最佳方式是使用 系统属性。 例如，您可以在 构建配置设置 | 参数 中添加带有 Any CPU 值的 system.Platform 参数，然后在 .NET 步骤中将此值引用为 %system.Platform%。

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