Erstellen eines Pipeline-Decorators

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.

1. Hinzufügen von Beiträgen 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 Pipeline-Dekorateur 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:

Targets

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

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.

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 vss-extension.json Manifestdatei 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.

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

vss-extension.json (injizierte 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.

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.

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

Verwandte Artikel

• Informationen zur YAML-Ausdruckssyntax
• Kontext des Pipelinedekororausdrucks
• Entwickeln einer Weberweiterung
• Authentifizierungsleitfaden