PowerShell

PowerShell 构建运行程序是专门设计用于运行 PowerShell 脚本的。

负责 PowerShell 集成的插件已经在 GitHub 上开源。

跨平台 PowerShell

跨平台 PowerShell（PowerShell Core）支持 Windows、macOS 和 Linux：为您的平台下载一个 PowerShell 软件包，并将其安装在 TeamCity 代理上。
在 Windows 下，支持并存安装 PowerShell Desktop 和 PowerShell Core。

构建代理上已安装 PowerShell 的检测

在启动过程中，TeamCity 代理会在标准位置，例如 程序文件 和 Windows 目录，或者在 ARM64 系统中的 ~/powershell 和 /opt/microsoft/powershell/<版本>/ 中，寻找 PowerShell 安装。您可以在 teamcity.powershell.detector.search.paths 代理属性中指定一个自定义位置，这样代理就可以检测到此目录（及其子目录）中的 PowerShell。
要列出多个位置，可以用 ; 分隔它们的路径。

PowerShell 设置

选项	描述
版本	TeamCity 支持的 PowerShell 版本列表。它被传递给 `powershell.exe` 作为 `-版本` 命令行参数。
PowerShell 运行模式	在 x64 机器上选择所需的执行模式：版本指定一个版本（例如，1.0 或 2.0）。将会与代理上安装的版本进行比较，并将添加适当的要求。对于 Core 版本，它将被用作下限。在桌面版中，将使用确切的版本（会添加 `-版本` 命令行参数）。如果版本字段留空，将不会添加版本要求的下限，Desktop 版本的 PowerShell 也不会使用 `-版本` 参数。平台选择平台位数： `x64` — 64 位，默认情况下，将会添加相应的要求 `x86` — 32 位，将会添加相应的需求 `自动` — 当选中后，构建配置中不会添加任何平台要求，如果同时安装了 32 位和 64 位的 PowerShell，将优先选择 64 位。版本选择要使用的 PowerShell 版本：桌面版 — 配套 Windows 的闭源版，仅在 Windows 平台上可用。核心 - 基于 .NET Core 的开源版本，跨平台，仅64位
将 stderr 输出格式化为：	指定运行器如何处理错误输出：错误：任何输出到 `stderr` 都会被处理为错误警告：默认；任何输出到 `stderr` 都将作为警告处理要使构建失败，如果"构建运行程序记录错误消息"（请参见构建失败条件），请将错误输出选择器的默认设置从警告更改为错误。
工作目录	指定到构建工作目录的路径。
脚本	选择您是希望直接在 TeamCity 中输入脚本，还是指定脚本的路径： File：输入 PowerShell 文件的路径。路径必须相对于签出目录。源：请输入 PowerShell 脚本源。请注意，TeamCity 参数引用将在代码中被替换。如果您的 PowerShell 脚本源是通过储存在 VCS 中的 Kotlin DSL 配置定义的，注意在 Kotlin 中，PowerShell 变量引用被视为字符串模板。为了解决这个问题，TeamCity 会自动转义在源字段中输入的所有引用，并在 VCS 中更新源代码。然而，如果您直接在 VCS 中修改脚本源码，我们建议您手动转义变量引用为 `${'$'}reference_name`. 或者，您可以将脚本存储在一个单独的文件中，并在 File 字段中引用。这样，TeamCity 在导入文件时也会正确处理参考引用。 PowerShell 2.0 在脚本中包含明确定义的参数时，无法返回正确的退出代码，出现了一个问题。作为一种替代方案，您可以选择升级 PowerShell 或使用 `[Environment]::Exit(code)`。
脚本执行模式	指定 PowerShell 脚本的执行模式。默认情况下，PowerShell 可能不允许执行任意的 `.ps1` 文件。 TeamCity 将尝试提供 `-ExecutionPolicy ByPass` 参数。如果您已选择从外部文件执行 .ps1 脚本，您的脚本应该被签名，或者您应该让 PowerShell 允许执行任意的 `.ps1` 文件。如果执行策略不允许运行您的脚本，请选择将脚本放入 PowerShell stdin 模式以避免这个问题。 `-命令` 模式已被弃用，不建议和版本高于1.0的PowerShell一起使用。
脚本实参	如果"脚本执行模式"选项设置为"从外部文件执行 .ps1 脚本"，则此选项可用。指定构建参数以作为参数传递到 PowerShell 脚本中。使用命名参数时，遵循此模式： `-"<script_argument1> %build_parameter1% -<script_argument2> %build_parameter2%`。转义特殊符号 TeamCity 在您的操作系统的控制台中调用 `powershell.exe` （在 Windows 上是命令提示符，Linux 上是 bash 或其他）。如果将包含特殊符号的参数传递给您的 PowerShell 脚本，在双引号中，确保这些字符被正确地转义：根据您的解释器使用转义规则，例如，在 Windows 上，如果一个 PowerShell 脚本参数以反斜杠结束，使用反斜杠作为 TeamCity 的转义符号以正确解释它： `"foo\\"`。
附加命令行参数	指定要传递给 PowerShell 可执行文件的参数。

Docker 设置

在此部分，您可以指定将被用于运行构建步骤的 Docker 镜像。

当前限制

在 Docker 下执行需要将 PowerShell 可执行文件添加到 PATH。
当使用 Docker 运行构建步骤时，只有与 Docker 相关的构建代理要求才适用于构建。
在 PowerShell 构建步骤中选择的 Edition 会影响使用的可执行文件（ powershell.exe 用于桌面， pwsh 用于 Core）。
<Auto> 默认为 pwsh （核心）。
要指定自定义的 PowerShell 可执行文件，必须将 teamcity.powershell.virtual.executable 配置参数设置为提供的镜像内此可执行文件的完整路径。
Container Wrapper 的当前限制不允许在 Windows 系统下运行 Linux 容器。

已知问题

如果通过 PowerShell Desktop 版本 5.1.17763 或更高版本运行 docker-compose 命令，尽管构建日志中只有误报警告，但 PowerShell 脚本可能会出现错误。
为了解决这个问题，我们建议您使用 PowerShell Core。另外，您可以通过在 docker-compose 命令中添加 --log-level ERROR 属性来限制其日志级别。

与 TeamCity 的交互

在使用 PowerShell 与 TeamCity 通过服务消息进行交互时，必须要格外注意。 PowerShell 倾向于使用像 Write-Output、 Write-Error 等命令将写入控制台的字符串进行包装（参见 TW-15080）。为了避免这种情况，您可以使用 Write-Host 命令，或者手动调整缓冲区长度：

function Set-PSConsole {
  if (Test-Path env:TEAMCITY_VERSION) {
    try {
      $rawUI = (Get-Host).UI.RawUI
      $m = $rawUI.MaxPhysicalWindowSize.Width
      $rawUI.BufferSize = New-Object Management.Automation.Host.Size ([Math]::max($m, 500), $rawUI.BufferSize.Height)
      $rawUI.WindowSize = New-Object Management.Automation.Host.Size ($m, $rawUI.WindowSize.Height)
    } catch {}
  }
}

错误处理

由于 PowerShell 问题导致始终向调用者返回零退出代码，TeamCity 无法始终检测脚本是否正确执行。我们推荐以下几种方法，可以帮助检测脚本执行失败：

手动捕获异常并明确返回退出代码
PowerShell 插件并未在 powershell.exe 周围使用 cmd 包装器。它使返回显式退出代码成为可能。
try { # your code here } Catch { $ErrorMessage = $_.Exception.Message Write-Output $ErrorMessage exit(1) }
设置并添加构建失败条件：
如果存在语法错误和异常，PowerShell 将它们写入 stderr。为了让 TeamCity 判定构建失败，将 错误输出 选项设置为 错误 ，并添加一个构建失败条件，以在任何错误输出时使构建失败。
构建日志中的特定信息导致构建失败：
添加一种构建失败条件，当构建日志中出现特定信息（例如 "POWERSHELL ERROR"）时，将导致构建失败。
$ErrorMessage = "POWERSHELL ERROR" try { # your code here } Catch { Write-Output $ErrorMessage exit(1) }

处理输出

为了正确处理 PowerShell 的非 ASCII 输出，必须同时在 PowerShell 端和 TeamCity 端设置正确的编码。

要将 PowerShell 的输出编码设置为 UTF-8，请在您的 PowerShell 脚本开头添加以下行：
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
要在 TeamCity 代理端设置编码，可以设置 Java 启动选项 -Dfile.encoding=UTF-8 ，或者将构建配置参数 teamcity.runner.commandline.stdstreams.encoding 的值设置为 UTF-8。

临时文件

TeamCity PowerShell 插件使用临时文件作为入口点；这些文件在构建临时目录中创建，并在 PowerShell 构建步骤完成后移除。为了保留这些文件，将 powershell.keep.generated 或 teamcity.dont.delete.temp.files 配置参数设置为 true。

开发链接

PowerShell 支持是以开源插件的形式实现的。对于开发链接，请参考插件的页面。

最后修改日期： 16日 7月 2024年