Creare un elemento Decorator della pipeline

Azure DevOps Services | Azure DevOps Server 2022

Gli elementi decorator della pipeline consentono di aggiungere passaggi all'inizio e alla fine di ogni processo. Il processo di creazione di un elemento Decorator della pipeline è diverso dall'aggiunta di passaggi a una singola definizione perché si applica a tutte le pipeline di un'organizzazione.

Si supponga che l'organizzazione richieda l'esecuzione di uno scanner di virus in tutti gli output di compilazione che potrebbero essere rilasciati. Gli autori della pipeline non devono ricordare di aggiungere tale passaggio. Viene creato un elemento Decorator che inserisce automaticamente il passaggio. L'elemento Decorator della pipeline inserisce un'attività personalizzata che esegue l'analisi di virus alla fine di ogni processo della pipeline.

Suggerimento

Vedere la documentazione più recente sullo sviluppo di estensioni con Azure DevOps Extension SDK.

1. Aggiungere contributi a un'estensione

L'esempio seguente presuppone che si abbia familiarità con i modelli di contributo.

1. Creare un'estensione. Dopo aver creato l'estensione, si dispone di un vss-extension.json file.
2. Aggiungere contributi al file per la vss-extension.json nuova pipeline decorator.

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

Opzioni di contributo

Di seguito vengono esaminate le proprietà e le relative funzionalità:

Proprietà	Descrizione
id	Identificatore del contributo. Deve essere univoco tra i contributi in questa estensione.
type	Specifica che questo contributo è un elemento decorator della pipeline. Deve essere la stringa ms.azure-pipelines.pipeline-decorator.
targets	Gli elementi Decorator possono essere eseguiti prima del processo o dell'attività specificata, dopo o entrambi. Per le opzioni disponibili, vedere la tabella seguente.
properties.template	(Obbligatorio) Il modello è un file YAML incluso nell'estensione, che definisce i passaggi per l'elemento Decorator della pipeline. Si tratta di un percorso relativo dalla radice della cartella dell'estensione.
properties.targettask	ID attività di destinazione usato per ms.azure-pipelines-agent-job.pre-task-tasks o ms.azure-pipelines-agent-job.post-task-tasks destinazioni. Deve essere una stringa GUID come 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Target

Destinazione	Descrizione
ms.azure-pipelines-agent-job.pre-job-tasks	Eseguire prima di altre attività in una pipeline YAML o di compilazione classica. A causa delle differenze nella modalità di estrazione del codice sorgente, questa destinazione viene eseguita dopo il checkout in una pipeline YAML, ma prima di eseguire il checkout in una pipeline di compilazione classica.
ms.azure-pipelines-agent-job.post-checkout-tasks	Eseguire dopo l'ultima checkout attività in una pipeline YAML o di compilazione classica.
ms.azure-pipelines-agent-job.post-job-tasks	Eseguire dopo altre attività in una pipeline di compilazione classica o YAML.
ms.azure-pipelines-agent-job.pre-task-tasks	Eseguire prima dell'attività specificata in una pipeline YAML o di compilazione classica.
ms.azure-pipelines-agent-job.post-task-tasks	Eseguire dopo l'attività specificata in una pipeline YAML o di compilazione classica.
ms.azure-release-pipelines-agent-job.pre-task-tasks	Eseguire prima dell'attività specificata in una pipeline RM classica.
ms.azure-release-pipelines-agent-job.post-task-tasks	Eseguire dopo l'attività specificata in una pipeline RM classica.
ms.azure-release-pipelines-agent-job.pre-job-tasks	Eseguire prima di altre attività in una pipeline RM classica.
ms.azure-release-pipelines-agent-job.post-job-tasks	Eseguire dopo altre attività in una pipeline RM classica.

Nota

I processi di distribuzione in una pipeline YAML supportano ms.azure-pipelines-agent-job.pre-job-tasks solo e ms.azure-pipelines-agent-job.post-job-tasks destinazioni. I processi supportano tutte le destinazioni della pipeline YAML.

In questo esempio viene usato ms.azure-pipelines-agent-job.post-job-tasks perché si vuole eseguire alla fine di tutti i processi di compilazione.

Questa estensione contribuisce a un elemento Decorator della pipeline. Verrà quindi creato un file YAML di modello per definire il comportamento dell'elemento Decorator.

2. Creare un file YAML decorator

Nelle proprietà dell'estensione è stato scelto il nome "my-decorator.yml". Creare il file nella radice del contributo. Contiene il set di passaggi da eseguire dopo ogni processo. Si inizia con un esempio di base e si lavora fino all'attività completa.

my-decorator.yml (versione iniziale)

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

Nota

Le attività decorator della pipeline con utilizzo della connessione al servizio non sono supportate per le pipeline di versione classiche.

3. Installare l'decorator

Per aggiungere un elemento Decorator pipeline all'organizzazione, è necessario installare un'estensione. Solo le estensioni private possono contribuire ai decorator della pipeline. L'estensione deve essere creata e condivisa con l'organizzazione prima di poterla usare.

Dopo aver condiviso l'estensione con l'organizzazione, cercare l'estensione e installarla.

Salvare il file, quindi compilare e installare l'estensione. Creare ed eseguire una pipeline di base. L'elemento Decorator inserisce automaticamente lo dir script alla fine di ogni processo. Un'esecuzione della pipeline è simile all'esempio seguente.

Nota

L'elemento Decorator viene eseguito in ogni processo in ogni pipeline dell'organizzazione. Nei passaggi successivi si aggiunge la logica per controllare quando e come viene eseguito l'elemento Decorator.

4. Inserire condizioni

In questo esempio, è necessario eseguire lo scanner antivirus solo se gli output di compilazione potrebbero essere rilasciati al pubblico. Si supponga che solo le build del ramo predefinito (in maingenere ) vengano rilasciate. È consigliabile limitare l'elemento Decorator ai processi in esecuzione nel ramo predefinito.

Il file aggiornato è simile al seguente:

my-decorator.yml (versione modificata)

---

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

È possibile iniziare a vedere la potenza di questo punto di estendibilità. Usare il contesto del processo corrente per inserire in modo condizionale i passaggi in fase di esecuzione. Usare le espressioni YAML per prendere decisioni sui passaggi da inserire e quando. Per un elenco completo dei dati disponibili, vedere il contesto dell'espressione decorator della pipeline.

C'è un'altra condizione da considerare: cosa succede se l'utente ha già incluso il passaggio di scansione del virus? Non dovremmo perdere tempo a correre di nuovo. In questo semplice esempio, si fa finta che qualsiasi script attività trovata nel processo esegua lo scanner di virus. In un'implementazione reale, è necessario avere un'attività personalizzata per verificarla.

L'ID dell'attività script è d9bafed4-0b18-4f58-968d-86655b4d2ce9. Se viene visualizzata un'altra attività script, non è consigliabile inserire i dati.

my-decorator.yml (versione finale)

---

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. Specificare un'attività di destinazione

È possibile specificare l'ID attività di destinazione e inserire attività prima o dopo questa attività di destinazione. Per specificare l'attività di destinazione, è possibile modificare il file manifesto vss-extension.json come nell'esempio seguente.

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

Quando si configura la proprietà 'targettask', è possibile specificare l'ID di un'attività di destinazione. Le attività verranno inserite prima/dopo tutte le istanze dell'attività di destinazione specificata.

Specificare l'inserimento degli input dell'attività di destinazione

È possibile specificare un elenco di input dell'attività di destinazione da inserire come input per l'attività inserita.

Questa funzionalità è progettata per lavorare con attività di pipeline personalizzate. Non è progettato per fornire l'accesso agli input dell'attività della pipeline di destinazione tramite le variabili della pipeline.

Per ottenere l'accesso agli input dell'attività della pipeline di destinazione (input con il target_ prefisso), l'attività della pipeline inserita deve usare i metodi di azure-pipelines-tasks-task-lib e non le variabili della pipeline, ad esempio const inputString = tl.getInput('target_targetInput').

A tale scopo, è possibile creare un'attività della pipeline personalizzata e usare gli input di destinazione. Se è necessaria la funzionalità di una delle attività predefinite, ad esempio CmdLine@2, è possibile creare una copia dell'attività CmdLine@2 e pubblicarla con l'estensione decorator.

Nota

Questa funzionalità è disponibile solo per le attività inserite prima o dopo l'attività di destinazione.

Per specificare questo elenco di input, è possibile modificare il file manifesto vss-extension.json come nell'esempio seguente.

vss-extension.json (versione input attività inseriti)

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

Impostando la proprietà 'targettaskinputs', è possibile specificare l'elenco di input che devono essere inseriti. Questi input verranno inseriti nell'attività con il prefisso "target_" e saranno disponibili nell'attività inserita come target_target-task-input.

Nota

Gli input dell'attività di destinazione che ottengono valori segreti con variabili o li ottengono da altre attività non verranno inseriti.

Debug

Potrebbe essere necessario eseguire il debug quando si crea l'elemento Decorator. È anche possibile visualizzare i dati disponibili nel contesto.

È possibile impostare la system.debugContext variabile su true quando si accoda una pipeline. Esaminare quindi la pagina di riepilogo della pipeline.

Viene visualizzato un aspetto simile all'immagine seguente.

Selezionare l'attività per visualizzare i log, che mostrano i valori di runtime e che il contesto è disponibile.

Articoli correlati

• Informazioni sulla sintassi delle espressioni YAML
• Contesto dell'espressione decorator della pipeline
• Sviluppare un'estensione Web
• Guida all'autenticazione