Erstellen eines Pipeline-Decorators

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022

Mithilfe von Pipelinedekortoren können Sie am Anfang und Ende jedes Auftrags Schritte hinzufügen. Der Prozess der Erstellung eines Pipelinedekorors unterscheidet sich von dem Hinzufügen von Schritten zu einer einzelnen Definition, da er für alle Pipelines in einer Organisation gilt.

Angenommen, Ihre Organisation erfordert, dass ein Virenscanner für alle Buildausgaben ausgeführt wird, die freigegeben werden können. Pipelineautoren müssen sich nicht daran erinnern, diesen Schritt hinzuzufügen. Wir erstellen einen Dekorateur, der den Schritt automatisch injiziert. Unser Pipelinedekoror fügt einen benutzerdefinierten Vorgang ein, der Virenscans am Ende jedes Pipelineauftrags durchführt.

Tipp

Sehen Sie sich unsere neueste Dokumentation zur Erweiterungsentwicklung mithilfe des Azure DevOps-Erweiterungs-SDK an.

1. Hinzufügen von Beiträge zu einer Erweiterung

Im folgenden Beispiel wird davon ausgegangen, dass Sie mit den Beitragsmodellen vertraut sind.

  1. Erstellen Sie eine Erweiterung. Sobald Die Erweiterung erstellt wurde, haben Sie eine vss-extension.json Datei.
  2. Fügen Sie Beiträge zur vss-extension.json Datei für unseren neuen Pipelinedekoror hinzu.

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"
        }
    ]
}

Beitragsoptionen

Werfen wir einen Blick auf die Eigenschaften und deren Verwendung:

Eigenschaft Beschreibung
id Beitragsbezeichner. Muss unter Beiträge in dieser Erweiterung eindeutig sein.
type Gibt an, dass dieser Beitrag ein Pipelinedekoror ist. Muss die Zeichenfolge ms.azure-pipelines.pipeline-decoratorsein.
targets Dekorateure können vor Ihrem Auftrag/angegebenen Vorgang nach oder nach oder beides ausgeführt werden. In der folgenden Tabelle finden Sie verfügbare Optionen.
properties.template (Erforderlich) Die Vorlage ist eine YAML-Datei, die in Ihrer Erweiterung enthalten ist, die die Schritte für Ihren Pipelinedekoror definiert. Es ist ein relativer Pfad vom Stamm des Erweiterungsordners.
properties.targettask Die Zielaufgaben-ID, die für ms.azure-pipelines-agent-job.pre-task-tasks oder ms.azure-pipelines-agent-job.post-task-tasks ziele verwendet wird. Muss eine GUID-Zeichenfolge sein, z. B. 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Targets

Target Beschreibung
ms.azure-pipelines-agent-job.pre-job-tasks Führen Sie vor anderen Aufgaben in einer klassischen Build- oder YAML-Pipeline aus. Aufgrund von Unterschieden beim Auschecken von Quellcode wird dieses Ziel nach dem Auschecken in einer YAML-Pipeline, aber vor dem Auschecken in einer klassischen Buildpipeline ausgeführt.
ms.azure-pipelines-agent-job.post-checkout-tasks Führen Sie nach der letzten checkout Aufgabe in einer klassischen Build- oder YAML-Pipeline aus.
ms.azure-pipelines-agent-job.post-job-tasks Führen Sie nach anderen Aufgaben in einer klassischen Build- oder YAML-Pipeline aus.
ms.azure-pipelines-agent-job.pre-task-tasks Führen Sie vor der angegebenen Aufgabe in einer klassischen Build- oder YAML-Pipeline aus.
ms.azure-pipelines-agent-job.post-task-tasks Führen Sie die Ausführung nach der angegebenen Aufgabe in einer klassischen Build- oder YAML-Pipeline aus.
ms.azure-release-pipelines-agent-job.pre-task-tasks Führen Sie vor dem angegebenen Vorgang in einer klassischen RM-Pipeline aus.
ms.azure-release-pipelines-agent-job.post-task-tasks Führen Sie nach dem angegebenen Vorgang in einer klassischen RM-Pipeline aus.
ms.azure-release-pipelines-agent-job.pre-job-tasks Führen Sie vor anderen Aufgaben in einer klassischen RM-Pipeline aus.
ms.azure-release-pipelines-agent-job.post-job-tasks Führen Sie nach anderen Aufgaben in einer klassischen RM-Pipeline aus.

Hinweis

Bereitstellungsaufträge in einer YAML-Pipeline unterstützen ms.azure-pipelines-agent-job.pre-job-tasks und ms.azure-pipelines-agent-job.post-job-tasks zielen nur. Aufträge unterstützen alle YAML-Pipelineziele.

In diesem Beispiel wird verwendet ms.azure-pipelines-agent-job.post-job-tasks , da wir am Ende aller Buildaufträge ausgeführt werden möchten.

Diese Erweiterung trägt zu einem Pipelinedekoror bei. Als Nächstes erstellen wir eine YaML-Vorlagedatei, um das Verhalten des Dekorators zu definieren.

2. Erstellen einer Dekorateur-YAML-Datei

In den Eigenschaften der Erweiterung haben wir den Namen "my-decorator.yml" ausgewählt. Erstellen Sie diese Datei im Stammverzeichnis Ihres Beitrags. Er enthält die Schritte, die nach jedem Auftrag ausgeführt werden sollen. Wir beginnen mit einem einfachen Beispiel und arbeiten bis zur vollständigen Aufgabe.

my-decorator.yml (Ursprüngliche Version)

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

Hinweis

Pipelinedekororaufgaben mit Dienstverbindungsverwendung werden für klassische Releasepipelinen nicht unterstützt.

3. Installieren Sie den Dekorateur

Um Ihrer Organisation einen Pipelinedekoror hinzuzufügen, müssen Sie eine Erweiterung installieren. Nur private Erweiterungen können Pipelinedekortoren beitragen. Die Erweiterung muss erstellt und für Ihre Organisation freigegeben werden, bevor sie verwendet werden kann.

Nachdem die Erweiterung für Ihre Organisation freigegeben wurde, suchen Sie nach der Erweiterung , und installieren Sie sie.

Speichern Sie die Datei, erstellen Sie dann die Erweiterung, und installieren Sie sie. Erstellen und Ausführen einer einfachen Pipeline. Der Dekorateur fügt unser dir Skript automatisch am Ende jedes Auftrags ein. Eine Pipelineausführung ähnelt dem folgenden Beispiel.

Pipeline decorator running a simple script

Hinweis

Der Dekorateur wird auf jedem Auftrag in jeder Pipeline in der Organisation ausgeführt. In späteren Schritten fügen wir Logik hinzu, um zu steuern, wann und wie der Dekorateur ausgeführt wird.

4. Einspritzbedingungen

In unserem Beispiel müssen wir den Virenscanner nur ausführen, wenn die Buildausgabe möglicherweise für die Öffentlichkeit freigegeben wird. Nehmen wir an, dass nur Builds aus dem Standardbranch (in der Regelmain) jemals veröffentlicht werden. Wir sollten den Dekorateur auf Aufträge beschränken, die gegen die Standardbranch ausgeführt werden.

Die aktualisierte Datei sieht wie folgt aus:

my-decorator.yml (überarbeitete Version)

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

Sie können damit beginnen, die Leistungsfähigkeit dieses Erweiterungspunkts zu sehen. Verwenden Sie den Kontext des aktuellen Auftrags, um Schritte zur Laufzeit bedingt einzugeben. Verwenden Sie YAML-Ausdrücke , um Entscheidungen darüber zu treffen, welche Schritte eingefügt werden sollen und wann. Eine vollständige Liste der verfügbaren Daten finden Sie im Kontext des Pipelinedekororausdrucks.

Es gibt eine weitere Bedingung, die wir berücksichtigen müssen: Was ist, wenn der Benutzer den Virenscanschritt bereits aufgenommen hat? Wir sollten nicht mehr zeitverwenden, um sie erneut auszuführen. In diesem einfachen Beispiel geben wir vor, dass jede script aufgabe, die im Auftrag gefunden wurde, den Virenscanner ausführt. (In einer echten Implementierung hätten Sie stattdessen eine benutzerdefinierte Aufgabe, um dies zu überprüfen.)

Die ID der Skriptaufgabe lautet d9bafed4-0b18-4f58-968d-86655b4d2ce9. Wenn eine andere Skriptaufgabe angezeigt wird, sollten wir unseren Vorgang nicht injizieren.

my-decorator.yml (endgültige Version)

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. Angeben einer Zielaufgabe

Sie können die Zielaufgaben-ID angeben und Vorgänge vor oder nach dieser Zielaufgabe einfügen. Zum Angeben der Zielaufgabe können Sie die Manifestdatei vss-extension.json wie im folgenden Beispiel ändern.

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"
            }
        }
    ],
    ...
}

Wenn Sie die Eigenschaft "targettask" einrichten, können Sie die ID einer Zielaufgabe angeben. Aufgaben werden vor/nach allen Instanzen der angegebenen Zielaufgabe eingefügt.

Eingabeeinfügung der Zielaufgabe angeben

Sie können eine Liste der Eingaben der Zielaufgabe angeben, die Sie als Eingaben in die eingefügte Aufgabe einfügen möchten.

Dieses Feature wurde entwickelt, um mit benutzerdefinierten Pipelineaufgaben zu arbeiten. Es ist nicht vorgesehen, Zugriff auf Zielpipelineaufgabeneingaben über Pipelinevariablen bereitzustellen.

Um Zugriff auf die Eingaben der Zielpipelineaufgaben (Eingaben mit dem target_ Präfix) zu erhalten, sollte die eingefügte Pipelineaufgabe Methoden aus der Azure-pipelines-tasks-task-lib und nicht die Pipelinevariablen verwenden, z const inputString = tl.getInput('target_targetInput'). B. ).

Dazu können Sie ihre eigene benutzerdefinierte Pipelineaufgabe erstellen und dort die Zieleingaben verwenden. Wenn Sie die Funktionalität einer der sofort einsatzbereiten Aufgaben benötigen, z CmdLine@2. B. können Sie eine Kopie der CmdLine@2 Aufgabe erstellen und mit Ihrer Dekorateurerweiterung veröffentlichen.

Hinweis

Diese Funktionalität ist nur für Vorgänge verfügbar, die vor oder nach dem Zielvorgang eingefügt werden.

Um diese Liste der Eingaben anzugeben, können Sie die Manifestdatei vss-extension.json wie im folgenden Beispiel ändern.

vss-extension.json (eingefügte Aufgabeneingabeversion)

{
    "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"]
            }
        }
    ],
    ...
}

Durch das Einrichten der Eigenschaft "targettaskinputs" können Sie die Liste der Eingaben angeben, die injiziert werden sollen. Diese Eingaben werden in die Aufgabe mit dem Präfix "target_" eingefügt und stehen in der eingefügten Aufgabe wie target_target-task-input.

Hinweis

Zielaufgabeneingaben, die geheime Werte mit Variablen abrufen oder aus anderen Aufgaben abrufen, werden nicht eingefügt.

Debug

Möglicherweise müssen Sie debuggen, wenn Sie Ihren Dekorateur erstellen. Möglicherweise möchten Sie auch sehen, welche Daten im Kontext verfügbar sind.

Sie können die system.debugContext Variable festlegen, true wenn Sie eine Pipeline in die Warteschlange stellen. Sehen Sie sich dann die Pipelinezusammenfassungsseite an.

Sie sehen etwas ähnliches wie in der folgenden Abbildung.

View pipeline decorator context

Wählen Sie die Aufgabe aus, um die Protokolle anzuzeigen, die Laufzeitwerte anzeigen und dass der Kontext verfügbar ist.