在 Azure DevOps 中构建 PowerShell 管道的深入指南

---

您是否知道可以在 Azure DevOps (AzDo) 管道中本机运行 PowerShell 等脚本来创建 PowerShell 管道？通过使用您将在本文中学到的技巧和技术，您将能够顺利地编写脚本以实现自动化的伟大成就。

如果您使用 Azure Pipelines 构建管道，您就会熟悉任务。任务是 Azure DevOps (AzDo) 管道的构建块。 AzDo 有许多内置任务，还允许您通过扩展市场中的扩展下载其他任务。但是，不可避免地会有这样的时候，您需要执行一些没有可用任务的操作。

是时候制定一个剧本了。

AzDo 可以本机运行三种类型的脚本 - PowerShell、Bash 和批处理文件。使用这些脚本语言/技术中的一种或多种，您几乎可以完成任何事情。

在本深入教程中，您将了解 PowerShell 脚本如何在 AzDo 管道中工作以创建 PowerShell 管道。您将了解如何调用代码、在源代码控制存储库中保存的脚本，以及如何在脚本中使用管道变量。

脚本如何在 AzDo 管道中工作

每个 AzDo 管道内部都有一系列任务。任务被定义为一个步骤。这些任务代表特定的操作，例如运行 .NET 构建、部署 Web 应用程序、运行测试等。任务是管道的构建块。

AzDo 使用任务的概念来运行 YAML 管道本身中的现有脚本或代码。更具体地说，任务可以在 Windows、Linux 和 macOS 等管道代理上运行 PowerShell、Bash 或批处理文件脚本。调用任务时，您可以指定运行脚本的代理 (OS) 以及代码/脚本具有的任何参数。

您可以在 Web 界面的任务选择器中找到 PowerShell 或 Bash 脚本任务，就像任何其他任务一样。

您可以在使用 Windows PowerShell 的 Windows、Linux 和使用 PowerShell (Core) 的 macOS 上运行 PowerShell 任务。

每个脚本任务都被定义为管道中的一个步骤，您可以通过几种不同的方式来分配任务来执行脚本，例如传递参数、出错时失败、获取最后的退出代码等。您将在以下部分中详细了解如何构建这些任务。

另一个需要学习的基本概念是管道变量如何与脚本集成。您仍然可以在 PowerShell 中定义和管理“脚本变量”（例如 $var=123）并维护环境变量，而无需 AzDo 参与。但是，AzDo 也允许您在脚本中设置和引用管道变量。

内联代码与脚本

在本文中，您将看到有关运行“脚本”的参考。虽然准确，但它读起来就像您必须创建自己的文本文件，插入您想要执行的代码，然后管道才会运行该脚本。这不是真的。

您还可以运行内联代码。内联代码直接在 YAML 管道中运行。您不必提前创建脚本来运行 PowerShell 或 Bash 代码。相反，您可以直接在 YAML 中插入代码。没有对 PS1 文件的引用。 AzDo 在管道运行时创建临时脚本。

一条线

您可以通过单行或多行在管道中以两种方式之一运行内联代码。如果您有一个简短的单行代码片段，则可以指定任务类型，后跟引号中的代码，如下所示。

- powershell: "I'm running PowerShell on a pipeline agent. Woohoo!!"

多行代码

如果您有一个跨越几行的代码片段，或者您可能不想使用引号，则可以使用竖线 (|) 符号后跟一个或其下方有更多行，如下所示。

- powershell: |
      This is script line 1
        This is script line 2

通常最好只对少于五行左右的小任务使用内联代码。任何其他需要更多任务的任务可能都应该放在源代码控制存储库中的脚本中。

使用内联代码的好处是将所有功能保留在一个位置，从而更容易查看正在发生的一切。但是，如果您有大型管道，这种方法很快就会变得混乱。

在哪里存储您的脚本

如果您不使用内联代码任务来运行脚本，则必须将脚本保存在某处。您有几个选项可以存储通过管道执行的脚本。

源代码控制存储库

如果您使用来自运行 CI 管道的 GitHub 或 AzDo 源代码控制存储库的管道触发器，请尝试将脚本存储在同一存储库中。通过这种方式可以更轻松地管理与项目相关的所有文件。默认情况下，AzDo 将检查源存储库中的所有代码。签出代码会将所有文件从存储库下载到管道代理上，使它们立即可供执行。

如果您的脚本位于另一个 GitHub 存储库中，您还可以查看多个存储库来下载并运行存储在其他存储库中的脚本。

将脚本下载到管道代理后，您可以通过 [System.DefaultWorkingDirectory 预定义变量在任务中引用它们。

例如，如果您有一个名为 script.ps1 的 PowerShell 脚本存储在源存储库的根目录中，AzDo 将检出将其放置在 System.DefaultWorkingDirectory 文件夹中的文件小路。然后可以使用 PowerShell 任务引用它，如下所示。

- task: PowerShell@2
    inputs:
        filePath: "$(System.DefaultWorkingDirectory)\script.ps1"

别的地方

如果脚本不在源代码控制存储库中，您仍然可以在管道中运行它。不过，如何做到这一点很大程度上取决于具体情况。例如，您可以使用 PowerShell 任务下载另一个脚本并运行它。

steps:
- powershell: |
    Invoke-WebRequest -Uri <https://somesite.com/script.ps1> -OutFile script.ps1
    .\script.ps1

脚本存储在哪里并不重要。只要您可以使用任务或运行脚本来进行身份验证（如果需要）并下载脚本，PowerShell 任务就会为您运行它。

PowerShell CI/CD 管道中的管道变量

就像脚本中有变量一样，管道中也有变量。变量有几种不同的定义方式，并且可以根据上下文以不同的方式访问它们的值。

您不仅可以在 YAML 管道中定义和读取变量值，还可以在脚本中执行此操作。

读取管道变量

当脚本通过管道运行时，管道将所有当前定义的变量公开为每个管道代理上的环境变量。这意味着您可以像读取任何其他环境变量一样读取脚本中的管道变量。

例如，您可能在管道的 variables 部分下定义了一个名为 foo 的变量。

variables:
    - name: foo
      value: 'bar'

由于管道将此变量公开为环境变量，因此您可以像往常一样在脚本中引用该变量的值，例如$env:foo。

对于使用点 (.) 定义的管道变量，AzDo 会自动将这些点转换为下划线作为环境变量。例如，如果管道变量定义为 foo.bar，则环境变量将为 foo_bar。

设置管道变量

设置管道变量并不像读取它们那么简单。要通过脚本设置管道变量，您必须使用日志记录命令。日志记录命令是脚本与管道代理进行通信的方式。

要通过脚本设置管道变量，您必须将特制的字符串输出到脚本中的标准输出。该字符串的格式必须为 “##vso[task.setvariable variable=[variable_name];][variable_value]”。

例如，要将管道变量 foo 设置为 bar 的值，PowerShell 或 Bash 脚本必须输出如下所示的字符串。

echo "##vso[task.setvariable variable=foo;]bar"

自定义脚本扩展

AzDo 默认提供 PowerShell 和 Bash 脚本任务。但您也可以下载甚至以扩展的形式构建您自己的基于脚本的任务，使您的 PowerShell CI/CD 管道可自定义。

使用标准脚本任务，您可以自己编写所有代码并一次性调用它。代码没有真正的“接口”。 AzDo 会给你一个框，上面写着“在此处插入代码”，你输入代码，然后管道执行它。它周围没有真正的结构。

请注意，当您在下面创建 PowerShell 任务时，您没有太多选项。此任务的参数非常少。有一个 Arguments 字段用于将参数传递给脚本，但是如果 Arguments 不是一些通用名称，不是更容易理解吗？

也许您有一个经常用于查询一组机器并返回一些报告的脚本。该脚本名为 Get-AcmeServerReport。它具有 ServerName 等参数来指定要运行的服务器，以及 ReportFilePath 来指定保存报告的位置。

在 Web UI 中设置与脚本参数匹配的字段不是更直观吗？如下所示？

本文不会介绍构建自定义 AzDo 扩展，但您应该知道这是可能的。您可以将“接口”向上移动到管道级别，而不是向下移动到脚本级别，从而使您可以轻松地重用现有脚本。

构建 PowerShell 管道

够了。现在让我们实际构建一个示例 AzDo PowerShell 管道！

在你开始之前

本文将是教学和实践教程相结合的。如果您打算亲自尝试任何示例，请务必提前设置一些先决条件。

• 创建链接到存储库的现有 AzDo 管道 - 在此 Azure Pipelines 文章中了解如何通过 Web 界面或使用 Az CLI 创建管道。

你将要学到什么

在本实践教程中，您将学习有关在 AzDo Pipelines 中运行 PowerShell 和 Bash 脚本的所有知识。使用 PowerShell 和 Bash 任务，您将了解如何调用脚本、向脚本传递参数、控制错误以及如何在脚本中出现问题时使管道中的任务失败。

您还将学习如何在脚本中使用 AzDo 管道变量以及如何使用 AzDo 日志记录命令设置它们。

PowerShell 任务是你的朋友

要在管道中运行 PowerShell 脚本需要使用 PowerShell 任务。 PowerShell 任务从管道获取脚本或 PowerShell 代码，并在管道代理上运行它。根据所选的选项，管道代理将位于 Windows 或 Linux 上。

您还可以使用更具体的用例任务，例如 Azure PowerShell 任务，但此处不会介绍这些任务。

PowerShell 任务架构

PowerShell 任务称为 PowerShell@2 并具有如下所示的架构。您可以看到在 inputs 部分下您可以使用一些选项来运行脚本。

- task: PowerShell@2
  inputs:
    targetType:
    filePath: 
    arguments:
    script:
    errorActionPreference:
    failOnStderr: true
    ignoreLASTEXITCODE: true
    pwsh: true
    workingDirectory: 

您决定在输入中使用的每个属性都会影响 PowerShell 代码/脚本的运行方式。

NameMandatoryOptionsUsed withDefault ValueDescriptiontargetTypeNofilePath, inlineAllThe PowerShell task allows you to add PowerShell code directly within the YAML pipeline or execute an existing script in the source repo. Here you can specify either filePath providing the path to the script to run or use inline which indicates that you’ll be adding the PowerShell code directly int the YAML pipeline.filePathYestargetType: filePathThis attribute is where you specify the path of the script to execute. This path typically points to a script in your source repo that the pipeline checks out when it runs. For example, to tell the PowerShell task to execute a script called script.ps1 in the root of the source repo, you’d use a predefined variable like $(System.DefaultWorkingDirectory)\\script.ps1.argumentsNotargetType: filePathIf you’ve provided a script via the filePath attribute and that script is built with parameters, this is where you would pass in values to those parameters. Note that when using inline code, this option is not used. You should specify named parameters like `-Name someName -Path -Value “some value”`scriptYesinlineEnclosed in quotes, this is where you provide the PowerShell code to execute.errorActionPreferenceNoSilentlyContinue, Continue, Inquire, StopAllStopUse this to set $ErrorActionPreference in the script if you haven’t done so already.failOnStderrNotrueAllfalseSetting this value to true will fail the PowerShell task in the pipeline is an error is thrown via PowerShell. Otherwise, the task will only fail if the scripts exits with a non-zero exit code.ignoreLASTEXITCODENotrueAllfalseIf set to false, the line `if ((Test-Path -LiteralPath variable:"\LASTEXITCODE)) { exit $LASTEXITCODE }` is appended to the end of the script. This will cause the last exit code from an external command to be propagated as the exit code of PowerShell.pwshNotrueAllfalseIf the pipeline agent is running on Windows, this will force the code/script to be executed using pwsh.exe (PowerShell Core). If not set to true, the task will default to Windows PowerShell on Windows pipeline agents.workingDirectoryNoAll$(Build.SourcesDirectory)The working directory to execute the script in. This affects paths in the script like _.\\command.ps1_.envNoAllA list of additional items to map into the process’s environment. By default, pipeline variables are mapped but secret variables are not. Here is where you would specify them like `MySecret: $(Foo)`.

现在您已经知道什么是可能的，让我们深入研究每个属性，看看有什么可能。

运行简单的单行代码

在 PowerShell 任务最简单的形式中，您可以使用 inline 的 targetType 并通过 script 指定要运行的代码来运行单行 PowerShell 属性如下所示。

- task: PowerShell@2
    inputs:
      targetType: 'inline'
      script: 'Write-Host "This is me running PowerShell code!"'

当管道运行时，您将看到日志中显示的输出。

如果您想采用此方法的快捷方式，您可以节省几行代码，但也可以使用可选的 powershell 快捷任务。

要执行与上述完全相同的功能，您还可以简单地使用 powershell 术语，后跟要运行的代码，如下所示。

- powershell: 'Write-Host "This is me running PowerShell code!"'

如果您想了解有关内联运行 PowerShell 代码的更多信息，请查看本系列第一篇文章的代码与脚本部分。

旁注：Windows PowerShell 与 PowerShell（核心）

在深入讨论之前，有必要指出 Windows PowerShell 与 PowerShell（核心）中的一些行为差异以及如何控制脚本运行的 PowerShell 版本。

在上面的示例中，执行代码的 PowerShell 版本完全取决于运行代码的管道代理。管道足够智能，可以为您处理这个问题，但您有时会遇到这个问题。

例如，如果您有特定于 Windows PowerShell 的代码并使用 powershell 任务（假设它将在 Windows 上运行），该怎么办？可能是这样，但如果您定义了一个大型管道，并且忘记为该作业添加了 pool: ubunbu-latest 行怎么办？该任务仍将在 Linux 上运行，但别无选择，只能运行 PowerShell（核心）。

以上面的任务为例，现在假设您已经专门定义了在 Linux 上运行的管道代理，如下所示。任务完全相同，但管道代理不同。

pool:
  vmImage: "ubuntu-latest"

steps:
  - task: PowerShell@2
    inputs:
      targetType: 'inline'
      script: 'Write-Host "This is me running PowerShell code!'
	- powershell: 'Write-Host "This is me running PowerShell code!"'

然后，您将在作业日志中看到，管道自动选择了pwsh。您将在 Windows 中看到相同的情况，其中管道执行 powershell.exe。

明确 PowerShell 版本

如果您运行的代码可能依赖于特定版本的 PowerShell，请始终明确您想要运行的版本。

要运行 PowerShell（核心），请始终在 PowerShell@2 任务或 pwsh 快捷任务上使用 pwsh: true 属性。不要假设管道会为您选择正确的版本。您可能永远不会记得您通过在为时已晚之前更改管道代理来进行“快速更改以解决问题”。

- task: PowerShell@2
    inputs:
      targetType: 'inline'
      script: 'Write-Host "This is me running PowerShell code!'
      pwsh: true

- pwsh: 'Write-Host "This is me running PowerShell code!"'

运行脚本

如果您需要运行一些超过几行的 PowerShell 代码或需要将参数传递给代码，则需要逐步执行脚本。使用 PowerShell 任务，您可以通过将 targetType 设置为 filePath，然后通过 filePath 属性指定要运行的脚本的路径来完成此操作。

例如，您的源存储库的根目录中可能有一个名为 script_no_params.ps1 的 PowerShell 脚本。下面您可以看到调用位于 System.DefaultWorkingDirectory 管道变量路径中的 script.ps1 脚本的示例。这是管道运行时将源存储库文件下载到的目录。

- task: PowerShell@2
    inputs:
      targetType: 'filePath'
      filePath: '$(System.DefaultWorkingDirectory)\script_no_params.ps1'

注意正斜杠和反斜杠的不一致！如果您在 Linux 上运行脚本，请使用正斜杠。在 Windows 上，指定 filePath 时使用反斜杠。

该脚本包含一行。

[CmdletBinding()]
param()

Write-Host "I'm running in a PowerShell script!!"

当管道运行时，您将看到管道读取脚本内部的代码，创建自己的 PowerShell 脚本，然后执行代码。

如果您打算运行现有的 PowerShell 脚本，请确保管道中没有 - checkout: none 行。否则，脚本将永远不会下载到代理。

传递参数

如果您的脚本具有一个或多个参数，则可以使用 arguments 属性将参数传递给这些脚本。

请注意，您无法使用 arguments 属性将参数传递给内联代码。

arguments 属性接受参数的方式与您在 PowerShell 本身内使用 -[parameter_name] [parameter_value] 指定命名参数的方式完全相同。

例如，您的源存储库的根目录中可能有一个名为 script.ps1 的脚本。该脚本包含两个名为 $foo 和 $bar 的参数，如下所示。

[CmdletBinding()]
param(
  $foo,
  $bar
)

Write-Host "Value of foo is $foo and value of bar is $bar"

您可以通过 YAML 管道中的 arguments 属性向 $foo 和 $bar 参数提供值，如下所示。

- task: PowerShell@2
    inputs:
      targetType: 'filePath'
      filePath: '$(System.DefaultWorkingDirectory)/script.ps1'
      arguments: "-foo 'foovalue' -bar 'barvalue'"

然后，您可以在作业输出日志中看到这些值已传递给脚本。

处理错误和警告

当通过管道调用 PowerShell 并返回错误或警告时，管道行为很大程度上取决于您的配置方式。 PowerShell 脚本可以通过几种不同的方式“出错”，例如软终止、硬终止错误以及以非零退出代码退出。另外，不要忘记那个警告流！

错误

当 PowerShell 任务遇到错误时，它可能会也可能不会使管道中的任务失败。如果您的脚本可能返回错误，但还没有严重到导致整个管道任务失败，您可以使用 errorActionPreference 属性来管理此行为。

默认情况下，管道将所有 PowerShell 脚本的 $ErrorActionPreference 值设置为 Stop。这意味着所有软终止和硬终止错误都将迫使 PowerShell 返回非零退出代码，从而使管道任务失败。

为了演示，也许您有一个脚本返回像 Write-Error 那样的软终止错误或像 throw 那样的硬终止错误。

## Soft
Write-Error -Message 'This is a soft-terminating error'

## Hard
throw 'This is a hard-terminating error'

当管道遇到此脚本时，任务将失败，因为 PowerShell 没有返回零退出代码，如下所示。

尽管不推荐，但如果您希望脚本失败但不让管道任务失败，可以通过将 errorActionPreference 属性设置为 SilentyContinue 来实现。

- task: PowerShell@2
    inputs:
			targetType: 'filePath'
      filePath: '$(System.DefaultWorkingDirectory)/script.ps1'
			errorActionPreference: SilentlyContinue

修改退出代码行为

默认情况下，如果 PowerShell 返回非零退出代码，PowerShell 任务将失败。您在上面看到了一个例子。但是，如果您需要操纵该行为，可以使用 ignoreLASTEXITCODE 属性来实现。

每当 PowerShell 脚本启动时，它总是填充一个名为 $LASTEXITCODE 的变量。巧合的是，此退出代码返回 PowerShell 脚本返回的最后一个退出代码。这是管道任务读取的内容以指示成功或失败。

也许您会遇到这样的情况：您在脚本中运行的命令返回非零退出代码，但您知道无论如何它都是成功的。不要让我开始软件安装程序！如果您希望管道任务成功，您可以强制执行自己的退出代码。

假设您有一个名为 script.ps1 的脚本，如下所示，它修改 PowerShell 脚本退出时使用的退出代码。在下面的示例中，命令可能会返回零退出代码，这通常表示成功，但您知道这实际上是失败。

$output = ./some-command.exe
if ($LASTEXITCODE -eq 0) {
	exit 1
}

如果您在不使用 ignoreLastExitCode 属性的情况下运行此任务，您会发现该任务仍然显示成功。为什么？因为该任务并不关心 PowerShell 实际上返回什么退出代码。它使用 $LASTEXITCODE 的值来确定。

要删除对 $LASTEXITCODE 变量的依赖关系，请使用 ignoreLastExitCode 属性，如下所示。

- task: PowerShell@2
    inputs:
      targetType: 'filePath'
      filePath: '$(System.DefaultWorkingDirectory)/script.ps1'
      ignoreLastExitCode: true

在作业日志中显示自定义错误和警告

尽管使用频率较低，但您还可以使用 PowerShell 使用日志记录命令将警告和错误写入作业日志。下面是一个例子。

- task: PowerShell@2
    inputs:
      targetType: 'inline'
      script: |
        Write-Host "##vso[task.LogIssue type=warning;]This is the warning"
        Write-Host "##vso[task.LogIssue type=error;]This is the error"

将警告和错误直接添加到作业日志中不会影响任务本身的成功/失败状态。此功能对于将信息记录到作业日志非常有用。

管理管道变量

您要学习的最后一个主题是管理管道变量。 AzDo 可以轻松地在 PowerShell 脚本中设置和引用管道变量。

我们不会在本节中深入讨论变量。如果您想了解有关管道变量的更多信息，请务必查看了解 Azure DevOps 变量 [完整指南]。

读取管道变量

在管道中定义变量后，您可以使用环境变量在 PowerShell 脚本中读取这些变量的值。

也许您已经在管道中声明了一个变量，如下所示。 project_name 变量现在可在整个 YAML 管道中使用。

variables:
   - name: project_name
     value: "foo"

要在脚本中引用此变量的值，只需引用相同的名称，但作为环境变量，如下所示。这里的所有都是它的。所有管道变量将始终映射到管道代理中的环境变量。

Write-Host "The value of project_name is $env:project_name"

设置管道变量

也许您需要在 PowerShell 脚本中设置管道变量。尽管不太直观，但您可以使用日志记录命令来完成此操作。记录命令是管道与代理通信的方式。通过将特制的字符串写入“控制台”，您可以定义变量，如下所示。

## Creates a standard pipeline variable called foo and sets the value to bar
Write-Host "##vso[task.setvariable variable=foo;]bar"

## Creates an output variable called foo and sets the value to bar
Write-Host "##vso[task.setvariable variable=foo;isOutput=true]bar"

故障排除

事情并不总是按您希望的方式发展，因此了解一些解决问题的技巧很重要，可以帮助您摆脱困境。

注意你的报价！

如果您正在运行内联代码，引号将应用于两个位置 - YAML 管道和 PowerShell 中。很容易将报价放在错误的位置，使管道认为报价适合它，反之亦然。

防止这种情况的最简单方法之一是使用多行内联代码。而不是在带引号的单行中调用 PowerShell 代码，并且必须保持这样的直接：

powershell: '"This is some code."'

相反，您可以使用管道 (|) 符号并在其下方添加代码，从管道中一起删除所需的引号。这种方式消除了一些复杂性。

powershell: |
	"This is some code"

调试

如果您想更深入地了解管道代理在后台执行的操作，可以使用 system.debug 变量来调试管道。如果您在管道中将 system.debug 变量设置为 true，您将在作业日志中看到更详细的输出，如下所示。

枚举环境变量

在使用复杂的 YAML 管道时，您可能会遇到一种情况，您需要查看 PowerShell 将一个或多个管道变量的值视为什么。

由于管道将所有管道变量映射到环境变量，因此您可以使用 Get-ChildItem 列出所有当前环境变量（包括它们的值）。

PowerShell 将所有环境变量存储在名为 Env 的 PS 驱动器中。然后，您可以通过列出该 PS 驱动器的内容来读取所有环境变量，如下所示。

Get-ChildItem -Path Env:\