撰寫管線裝飾專案

  • 發行項

Azure DevOps Services |Azure DevOps Server 2022

管線裝飾專案可讓您將步驟新增至每個作業的開頭和結尾。 撰寫管線裝飾項目的程式與將步驟新增至單一定義不同，因為它適用於組織中的所有管線。

假設您的組織需要在所有可能發行的組建輸出上執行病毒掃描器。 管線作者不需要記住新增該步驟。 我們會建立自動插入步驟的裝飾專案。 我們的管線裝飾專案會插入自定義工作，以在每個管線作業結束時執行病毒掃描。

提示

請參閱使用 Azure DevOps 擴充功能 SDK 進行擴充功能開發的最新檔。

1.將貢獻新增至延伸模組

下列範例假設您已熟悉 貢獻模型。

  1. 建立延伸模組。 建立擴充功能之後，您就會有檔案 vss-extension.json 。
  2. 為新的管線裝飾專案新增檔案貢獻 vss-extension.json 。

vss-extension.json

{
    "manifestVersion": 1,
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.post-job-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml"
            }
        }
    ],
    "files": [
        {
            "path": "my-decorator.yml",
            "addressable": true,
            "contentType": "text/plain"
        }
    ]
}

參與選項

讓我們看看屬性及其用途：

屬性 說明
id 貢獻標識碼。 此延伸模組中的貢獻必須是唯一的。
type 指定此貢獻是管線裝飾專案。 必須是字串 ms.azure-pipelines.pipeline-decorator。
targets 裝飾專案可以在作業/指定的工作、之後或兩者之前執行。 如需可用的選項，請參閱下表。
properties.template （必要）範本是延伸模組中包含的 YAML 檔案，其會定義管線裝飾專案的步驟。 這是延伸模組資料夾根目錄中的相對路徑。
properties.targettask 用於 ms.azure-pipelines-agent-job.pre-task-tasks 或 ms.azure-pipelines-agent-job.post-task-tasks 目標的目標工作識別碼。 必須是 GUID 字串，例如 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

目標

Target 描述
ms.azure-pipelines-agent-job.pre-job-tasks 在傳統組建或 YAML 管線中的其他工作之前執行。 由於原始程式碼簽出方式的差異，此目標會在 YAML 管線簽出之後執行，但在簽出傳統組建管線之前執行。
ms.azure-pipelines-agent-job.post-checkout-tasks 在傳統組建或 YAML 管線的最後一個工作之後 checkout 執行。
ms.azure-pipelines-agent-job.post-job-tasks 在傳統組建或 YAML 管線中的其他工作之後執行。
ms.azure-pipelines-agent-job.pre-task-tasks 在傳統組建或 YAML 管線中指定的工作之前執行。
ms.azure-pipelines-agent-job.post-task-tasks 在傳統組建或 YAML 管線中指定的工作之後執行。
ms.azure-release-pipelines-agent-job.pre-task-tasks 在傳統 RM 管線中指定的工作之前執行。
ms.azure-release-pipelines-agent-job.post-task-tasks 在傳統 RM 管線中指定的工作之後執行。
ms.azure-release-pipelines-agent-job.pre-job-tasks 在傳統 RM 管線中的其他工作之前執行。
ms.azure-release-pipelines-agent-job.post-job-tasks 在傳統 RM 管線中的其他工作之後執行。

注意

YAML 管線中的部署作業 僅支援 ms.azure-pipelines-agent-job.pre-job-tasks 和 ms.azure-pipelines-agent-job.post-job-tasks 目標。 作業 支援所有 YAML 管線目標。

在此範例中，我們會使用 ms.azure-pipelines-agent-job.post-job-tasks ，因為我們想要在所有建置作業結束時執行。

此延伸模組會提供管線裝飾專案。 接下來，我們會建立範本 YAML 檔案，以定義裝飾項目的行為。

2.建立裝飾專案 YAML 檔案

在延伸模組的屬性中，我們選擇了名稱 「my-decorator.yml」。。 在參與專案的根目錄中建立該檔案。 它會保留每個作業之後要執行的步驟集。 我們從基本範例開始，並完成完整的工作。

my-decorator.yml （初始版本）

steps:
- task: CmdLine@2
  displayName: 'Run my script (injected from decorator)'
  inputs:
    script: dir

注意

傳統發行管線不支援具有服務連線使用量的管線裝飾工作。

3.安裝裝飾專案

若要將管線裝飾專案新增至您的組織，您必須 安裝延伸模組。 只有私人延伸模組可以參與管線裝飾專案。 延伸模組必須撰寫並與您的組織共用，才能使用它。

一旦與組織共用延伸模塊之後， 請搜尋延伸模組 並加以安裝。

儲存盤案，然後 建置並安裝延伸模組。 建立並執行基本管線。 裝飾專案會自動在每個作業結束時插入我們的 dir 腳本。 管線執行看起來類似下列範例。

Pipeline decorator running a simple script

注意

裝飾專案會在組織中每個管線中的每個作業上執行。 在後續步驟中，我們會新增邏輯來控制裝飾專案執行的時間和方式。

4. 插入條件

在我們的範例中，只有在組建輸出可能發行至公用時，我們才需要執行病毒掃描器。 假設只會發行預設分支的組建（通常是 main）。 我們應該將裝飾專案限制為針對預設分支執行的作業。

更新的檔案看起來像這樣：

my-decorator.yml （修訂版本）

steps:
- ${{ if eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

您可以開始查看此擴充點的強大功能。 使用目前作業的內容，在運行時間有條件地插入步驟。 使用 YAML 運算式 來決定要插入和時機的步驟。 如需可用數據的完整清單，請參閱 管線裝飾項目表達式內容 。

我們需要考慮的另一個情況：如果用戶已經包含病毒掃描步驟，該怎麼辦？ 我們不應該浪費時間再次執行它。 在此簡單範例中，我們將假裝作業中找到的任何 script 工作正在執行病毒掃描器。 （在實際的實作中，您會有自定義工作可改為檢查該工作。

文稿工作的識別碼為 d9bafed4-0b18-4f58-968d-86655b4d2ce9。 如果看到另一個文稿工作，則不應該插入 。

my-decorator.yml （最終版本）

steps:
- ${{ if and(eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch), not(containsValue(job.steps.*.task.id, 'd9bafed4-0b18-4f58-968d-86655b4d2ce9'))) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

5.指定目標工作

您可以指定目標 工作識別碼，並在這個目標工作之前或之後插入工作。 若要指定目標工作，您可以修改 vss-extension.json 指令清單檔案，例如下列範例。

vss-extension.json

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id"
            }
        }
    ],
    ...
}

當您設定 'targettask' 屬性時，您可以指定目標工作的標識碼。 工作會在指定之目標工作的所有實例之前/之後插入。

指定目標工作的輸入插入

您可以指定要插入做為插入工作之輸入的目標工作輸入清單。

這項功能的設計目的是要處理 自定義管線工作。 它的目的不是透過管線變數提供目標管線工作輸入的存取權。

若要存取目標管線工作輸入（具有target_前置詞的輸入），插入的管線工作應該使用來自 azure-pipelines-tasks-task-lib 的方法，而不是管線變數，例如 const inputString = tl.getInput('target_targetInput')）。

若要這樣做，您可以建立自己的自定義管線 工作 ，並在該處使用目標輸入。 如果您需要其中一個現成工作的功能，例如 CmdLine@2，您可以建立CmdLine@2工作的複本，並使用您的裝飾延伸模塊發佈它。

注意

這項功能僅適用於在目標工作之前或之後插入的工作。

若要指定此輸入清單，您可以修改 vss-extension.json 指令清單檔案，例如下列範例。

vss-extension.json （插入的工作輸入版本）

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id",
                "targettaskinputs": ["target-task-input", "target-task-second-input"]
            }
        }
    ],
    ...
}

藉由設定 'targettaskinputs' 屬性，您可以指定預期要插入的輸入清單。 這些輸入會插入到具有前置詞 「target_的工作中，並可在插入的工作中使用，例如 target_target-task-input。

注意

以變數取得秘密值或從其他工作取得秘密值的目標工作輸入將不會插入。

偵錯

建立裝飾專案時，您可能需要進行偵錯。 您可能也想要查看內容中可用的數據。

您可以在將管線排入佇列時， system.debugContext 將變數設定為 true 。 然後，查看管線摘要頁面。

您會看到類似下圖的內容。

View pipeline decorator context

選取工作以查看記錄，其中顯示運行時間值，以及內容可供使用。