Condividi tramite

Aggiungere un'estensione personalizzata dell'attività pipeline

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Questo articolo illustra come installare le estensioni all'organizzazione per attività di compilazione o rilascio personalizzate in Azure DevOps. Per altre informazioni, vedere Che cos'è Azure Pipelines?

Nota

Questo articolo illustra le attività degli agenti nelle estensioni basate su agenti. Per altre informazioni sulle attività del server e sulle estensioni basate su server, vedere Creazione attività server.

Prerequisiti

  • Un'organizzazione in Azure DevOps. Creare un'organizzazione.

  • Un editor di testo. Per molte esercitazioni viene usato Visual Studio Code, che offre supporto per intelliSense e debug.

  • Versione più recente di Node.js.

  • npmjs.com 4.0.2 o versione successiva. Installare la versione più recente di questo compilatore TypeScript.

  • Interfaccia della riga di comando multipiattaforma per Azure DevOps (tfx-cli) per impacchettare le tue estensioni.

    • Tfx-cli può essere installato usando npm, un componente di Node.js, eseguendo npm i -g tfx-cli.

  • SDK dell'estensione Azure DevOps. Installare il pacchetto azure-devops-extension-sdk .

  • Una directory home per il tuo progetto. La home directory di un'estensione dell'attività di compilazione o rilascio deve avere la struttura seguente dopo aver completato i passaggi descritti in questo articolo:

    |--- README.md    
|--- images                        
    |--- extension-icon.png  
|--- buildandreleasetask            // where your task scripts are placed
|--- vss-extension.json             // extension's manifest

Importante

Il computer di sviluppo deve eseguire la versione più recente di Node per assicurarsi che il codice scritto sia compatibile con l'ambiente di produzione nell'agente e la versione non di anteprima più recente di azure-pipelines-task-lib. Aggiornare il task.json file in base al comando seguente:

"execution": {
   "Node20_1": {
     "target": "index.js"
   }
 }

1. Creare un'attività personalizzata

Eseguire tutte le parti di questa procedura all'interno della cartella buildandreleasetask all'interno della directory home.

Nota

Questa procedura dettagliata di esempio usa Windows con PowerShell. I passaggi sono generici per tutte le piattaforme, ma la sintassi per ottenere variabili di ambiente è diversa. Se si usa un Mac o Linux, sostituire qualsiasi istanza di $env:<var>=<val> con export <var>=<val>.

Creare la struttura di supporto per le attività

  1. Creare la struttura di cartelle per l'attività e installare le librerie e le dipendenze necessarie.

  2. Aprire una finestra di comando di PowerShell, passare alla buildandreleasetask cartella ed eseguire il comando seguente.

    npm init --yes

    npm init crea il package.json file. È stato aggiunto il --yes parametro per accettare tutte le opzioni predefinite npm init .

    Suggerimento

    L'agente non installa automaticamente i moduli necessari perché prevede che la cartella attività includa i moduli del nodo. Per attenuare il problema, copiare il node_modules in buildandreleasetask. Man mano che l'attività diventa più grande, è facile superare il limite di dimensioni (50 MB) di un file VSIX. Prima di copiare la cartella node, è possibile eseguire npm install --production o npm prune --productionoppure è possibile scrivere uno script per compilare e comprimere tutti gli elementi.

  3. Aggiungere azure-pipelines-task-lib alla libreria.

    npm install azure-pipelines-task-lib --save

  4. Assicurarsi che le tipizzazioni TypeScript siano installate per le dipendenze esterne.

    npm install @types/node --save-dev
npm install @types/q --save-dev

  5. Creare un file .gitignore e aggiungere node_modules al suo interno. Il processo di compilazione dovrebbe eseguire un'operazione di npm install e typings install in modo che i node_modules vengano ricostruiti ogni volta e non sia necessario eseguirne il check-in.

    echo node_modules > .gitignore

  6. Installare Mocha come dipendenza di sviluppo.

    npm install mocha --save-dev -g
npm install sync-request --save-dev
npm install @types/mocha --save-dev

  7. Scegliere TypeScript versione 2.3.4 o 4.6.3.

    npm install typescript@4.6.3 -g --save-dev

    Nota

    Assicurarsi che TypeScript sia installato a livello globale con npm nell'ambiente di sviluppo, quindi il tsc comando è disponibile. Se si ignora questo passaggio, TypeScript versione 2.3.4 viene usato per impostazione predefinita e è comunque necessario installare il pacchetto a livello globale per avere il tsc comando disponibile.

  8. Creare tsconfig.json opzioni del compilatore. Questo file garantisce che i file TypeScript vengano compilati in file JavaScript.

    tsc --init --target es2022

Crea attività

Ora che lo scaffolding è completo, è possibile creare l'attività personalizzata.

  1. Creare un task.json file nella buildandreleasetask cartella . Il task.json file descrive l'attività di compilazione/rilascio ed è ciò che il sistema di compilazione/versione usa per eseguire il rendering delle opzioni di configurazione all'utente e per sapere quali script eseguire in fase di compilazione/rilascio.

  2. Copia il codice seguente e sostituisci {{placeholders}} con le informazioni della tua attività. Il segnaposto più importante è il taskguid e deve essere univoco.

    {
 "$schema": "https://raw.githubusercontent.com/Microsoft/azure-pipelines-task-lib/master/tasks.schema.json",
 "id": "{{taskguid}}",
 "name": "{{taskname}}",
 "friendlyName": "{{taskfriendlyname}}",
 "description": "{{taskdescription}}",
 "helpMarkDown": "",
 "category": "Utility",
 "author": "{{taskauthor}}",
 "version": {
     "Major": 0,
     "Minor": 1,
     "Patch": 0
 },
 "instanceNameFormat": "Echo $(samplestring)",
 "inputs": [
     {
         "name": "samplestring",
         "type": "string",
         "label": "Sample String",
         "defaultValue": "",
         "required": true,
         "helpMarkDown": "A sample string"
     }
 ],
 "execution": {
     "Node20_1": {
         "target": "index.js"
     }
 }
 }

  3. Creare un index.ts file usando il codice seguente come riferimento. Questo codice viene eseguito quando viene chiamata l'attività.

    import tl = require('azure-pipelines-task-lib/task');

 async function run() {
     try {
         const inputString: string | undefined = tl.getInput('samplestring', true);
         if (inputString == 'bad') {
             tl.setResult(tl.TaskResult.Failed, 'Bad input was given');
             return;
         }
         console.log('Hello', inputString);
     }
     catch (err:any) {
         tl.setResult(tl.TaskResult.Failed, err.message);
     }
 }

 run();

  4. Per compilare un file index.js da index.ts, immettere tsc dalla cartella buildandreleasetask.

componenti di task.json

Vedere le descrizioni seguenti di alcuni componenti del task.json file.

Proprietà Descrizione
id Un GUID univoco per l'attività.
name Nome senza spazi.
friendlyName Nome descrittivo (spazi consentiti).
description Descrizione dettagliata di cosa fa il tuo compito.
author Stringa breve che descrive l'entità che sviluppa l'attività di compilazione o rilascio, ad esempio Microsoft Corporation
instanceNameFormat Modalità di visualizzazione del task all'interno dell'elenco delle fasi di compilazione/rilascio. È possibile usare i valori delle variabili usando $(variablename).
groups Descrive il raggruppamento logico delle proprietà delle attività nell'interfaccia utente.
inputs Input da usare quando viene eseguita l'attività di compilazione o rilascio. Questa attività prevede un input con il nome samplestring.
execution Sono disponibili più opzioni di esecuzione per questa attività, inclusi gli script, ad esempio Node, PowerShell, PowerShell3o Process.
restrictions Restrizioni applicate all'attività sui comandi GitHub Codespaces che l'attività può chiamare e variabili che l'attività può impostare. È consigliabile specificare la modalità di restrizione per le nuove attività.

Nota

Creare un oggetto id con il comando seguente in PowerShell:

(New-Guid).Guid

Per altre informazioni, vedere le informazioni di riferimento sulle attività di compilazione/rilascio.

Esegui l'attività

Eseguire l'attività usando node index.js da PowerShell.

Nell'esempio seguente l'attività ha esito negativo perché gli input non sono stati forniti (samplestring è un input obbligatorio).

 node index.js
 ##vso[task.debug]agent.workFolder=undefined
 ##vso[task.debug]loading inputs and endpoints
 ##vso[task.debug]loaded 0
 ##vso[task.debug]task result: Failed
 ##vso[task.issue type=error;]Input required: samplestring
 ##vso[task.complete result=Failed;]Input required: samplestring

Come correzione, impostare l'input samplestring ed eseguire di nuovo l'attività.

$env:INPUT_SAMPLESTRING="Human"
node index.js
##vso[task.debug]agent.workFolder=undefined
##vso[task.debug]loading inputs and endpoints
##vso[task.debug]loading INPUT_SAMPLESTRING
##vso[task.debug]loaded 1
##vso[task.debug]Agent.ProxyUrl=undefined
##vso[task.debug]Agent.CAInfo=undefined
##vso[task.debug]Agent.ClientCert=undefined
##vso[task.debug]Agent.SkipCertValidation=undefined
##vso[task.debug]samplestring=Human
Hello Human

Questa volta, l'attività ha esito positivo perché samplestring è stata fornita e restituisce correttamente Hello Human!

Suggerimento

Per informazioni sui vari strumenti di esecuzione delle attività e su come includere la versione più recente del nodo in , vedere Linee guida per l'aggiornamento task.jsondi Node Runner per gli autori di attività di Azure Pipelines.

2. Esegui test unitari degli script delle attività

Eseguire test unitari per testare rapidamente lo script del compito e non gli strumenti esterni. Testare tutti gli aspetti dei percorsi di esito positivo e negativo.

  1. Installare gli strumenti di test. In questa procedura viene usato Mocha come driver di test.

    npm install mocha --save-dev -g
npm install sync-request --save-dev
npm install @types/mocha --save-dev

  2. Creare una tests cartella contenente un _suite.ts file con il contenuto seguente:

    import * as path from 'path';
import * as assert from 'assert';
import * as ttm from 'azure-pipelines-task-lib/mock-test';

describe('Sample task tests', function () {

    before( function() {

    });

    after(() => {

    });

    it('should succeed with simple inputs', function(done: Mocha.Done) {
        // Add success test here
    });

    it('it should fail if tool returns 1', function(done: Mocha.Done) {
        // Add failure test here
    });    
});

    Suggerimento

    La cartella di test deve trovarsi nella buildandreleasetask cartella . Se viene visualizzato un errore di richiesta di sincronizzazione, è possibile risolvere il problema aggiungendo la richiesta di sincronizzazione alla buildandreleasetask cartella con il comando npm i --save-dev sync-request.

  3. Creare un success.ts file nella directory di test con il contenuto seguente. Questa creazione di file simula l'esecuzione dell'attività e replica tutte le chiamate a metodi esterni.

    import ma = require('azure-pipelines-task-lib/mock-answer');
import tmrm = require('azure-pipelines-task-lib/mock-run');
import path = require('path');

let taskPath = path.join(__dirname, '..', 'index.js');
let tmr: tmrm.TaskMockRunner = new tmrm.TaskMockRunner(taskPath);

tmr.setInput('samplestring', 'human');

tmr.run();

    Il test di esito positivo convalida che, con gli input appropriati, ha esito positivo senza errori o avvisi e restituisce l'output corretto.

  4. Per eseguire l'esecuzione simulata dell'attività, aggiungere il seguente test di successo al file _suite.ts.

         it('should succeed with simple inputs', function(done: Mocha.Done) {
     this.timeout(1000);

     let tp: string = path.join(__dirname, 'success.js');
     let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp);

     // tr.run(); //current, old function.
     tr.runAsync().then(() => {
         console.log(tr.succeeded);
         assert.equal(tr.succeeded, true, 'should have succeeded');
         assert.equal(tr.warningIssues.length, 0, "should have no warnings");
         assert.equal(tr.errorIssues.length, 0, "should have no errors");
         console.log(tr.stdout);
         assert.equal(tr.stdout.indexOf('Hello human') >= 0, true, "should display Hello human");
         done();
     }).catch((error) => {
         done(error); // Ensure the test case fails if there's an error
     });
 });

  5. Creare un file failure.ts nella directory dei test come strumento di simulazione dell'attività con il seguente contenuto:

    import ma = require('azure-pipelines-task-lib/mock-answer');
import tmrm = require('azure-pipelines-task-lib/mock-run');
import path = require('path');

let taskPath = path.join(__dirname, '..', 'index.js');
let tmr: tmrm.TaskMockRunner = new tmrm.TaskMockRunner(taskPath);

tmr.setInput('samplestring', 'bad');

tmr.run();

    Il test di errore convalida che, quando lo strumento ottiene un input errato o incompleto, ha esito negativo nel modo previsto con un output utile.

  6. Per eseguire il corridore di attività simulato, aggiungere questo codice al file _suite.ts.

    it('should fail if tool returns 1', function(done: Mocha.Done) {
    this.timeout(1000);

    const tp = path.join(__dirname, 'failure.js');
    const tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp);

    tr.runAsync().then(() => {
        console.log(tr.succeeded);
        assert.equal(tr.succeeded, false, 'should have failed');
        assert.equal(tr.warningIssues.length, 0, 'should have no warnings');
        assert.equal(tr.errorIssues.length, 1, 'should have 1 error issue');
        assert.equal(tr.errorIssues[0], 'Bad input was given', 'error issue output');
        assert.equal(tr.stdout.indexOf('Hello bad'), -1, 'Should not display Hello bad');
        done();
    });
});

  7. Esegui i test.

    tsc
mocha tests/_suite.js

    Entrambi i test devono essere superati. Se si vogliono eseguire i test con un output più dettagliato (quello visualizzato nella console di compilazione), impostare la variabile di ambiente: TASK_TEST_TRACE=1.

    $env:TASK_TEST_TRACE=1

3. Creare il file manifesto dell'estensione

Il manifesto dell'estensione contiene tutte le informazioni sull'estensione. Include collegamenti ai file, incluse le cartelle delle attività e le cartelle delle immagini. Assicurarsi di aver creato una cartella images con extension-icon.png. L'esempio seguente è un manifesto dell'estensione che contiene l'attività di compilazione o versione.

Copiare il codice .json seguente e salvarlo come vss-extension.json file nella home directory.

Non creare questo file nella cartella buildandreleasetask.

{
    "manifestVersion": 1,
    "id": "build-release-task",
    "name": "Fabrikam Build and Release Tools",
    "version": "0.0.1",
    "publisher": "fabrikam",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],    
    "description": "Tools for building/releasing with Fabrikam. Includes one build/release task.",
    "categories": [
        "Azure Pipelines"
    ],
    "icons": {
        "default": "images/extension-icon.png"        
    },
    "files": [
        {
            "path": "buildandreleasetask"
        }
    ],
    "contributions": [
        {
            "id": "custom-build-release-task",
            "type": "ms.vss-distributed-task.task",
            "targets": [
                "ms.vss-distributed-task.tasks"
            ],
            "properties": {
                "name": "buildandreleasetask"
            }
        }
    ]
}

Nota

Cambiare l'editore con il nome del tuo editore. Per altre informazioni, vedere Creare un server di pubblicazione.

Contributi

Proprietà Descrizione
id Identificatore del contributo. Deve essere univoco all'interno dell'estensione. Non è necessario che corrisponda al nome dell'attività di compilazione o versione. In genere il nome dell'attività di compilazione o versione è nell'ID del contributo.
type Tipo di contributo. deve essere ms.vss-distributed-task.task.
targets Contributi destinati a questo contributo. deve essere ms.vss-distributed-task.tasks.
properties.name Nome dell'attività. Questo nome deve corrispondere al nome della cartella dell'attività di compilazione autonoma o rilascio della pipeline corrispondente.

File

Proprietà Descrizione
path Percorso del file o della cartella rispetto alla home directory.

Per altre informazioni sul file manifesto dell'estensione, ad esempio le relative proprietà e le relative operazioni, vedere il riferimento al manifesto dell'estensione.

Confeziona la tua estensione

Impacchetta tutti i tuoi file per portare la tua estensione nel Visual Studio Marketplace. Tutte le estensioni vengono impacchettate come file compatibili con VSIX 2.0 .vsix. Microsoft offre un'interfaccia multipiattaforma a riga di comando per impacchettare la tua estensione.

Dopo aver creato tfx-cli, passare alla home directory dell'estensione ed eseguire il comando seguente:

tfx extension create --manifest-globs vss-extension.json

Nota

È necessario incrementare la versione di un'estensione o di un'integrazione in ogni aggiornamento. Quando si aggiorna un'estensione esistente, aggiornare la versione nel file manifest o passare l'opzione della riga di comando --rev-version. In questo modo viene incrementato il numero di versione patch dell'estensione e la nuova versione viene salvata nel manifesto. È necessario rivedere sia la versione dell'attività che la versione dell'estensione affinché si verifichi un aggiornamento. tfx extension create --manifest-globs vss-extension.json --rev-version aggiorna solo la versione dell'estensione e non la versione dell'attività. Per altre informazioni, vedere Attività di compilazione in GitHub.

Quando l'estensione in pacchetto si trova in un file con estensione vsix, è possibile pubblicare l'estensione nel Marketplace.

5. Pubblicare l'estensione

Per pubblicare l'estensione, creare prima il server di pubblicazione, quindi caricare l'estensione e infine condividerla.

Crea il tuo editore

Tutte le estensioni, incluse le estensioni di Microsoft, vengono identificate come fornite da un editore. Se non si è già membri di un editore esistente, ne crei uno.

  1. Accedere al portale di pubblicazione di Visual Studio Marketplace.

  2. Se non si è già membri di un server di pubblicazione esistente, viene richiesto di creare un server di pubblicazione. Se non viene richiesto di creare un editore, scorrere verso il basso fino alla fine della pagina e selezionare Pubblica estensioni sotto Siti correlati.

    • Specificare un identificatore per il server di pubblicazione, ad esempio : mycompany-myteam.
      • Questo identificatore viene usato come valore per l'attributo publisher nel file manifesto delle estensioni.
    • Specificare un nome visualizzato per il tuo editore, ad esempio: My Team.

  3. Esaminare il Contratto di pubblicazione del Marketplace e selezionare Crea.

Il tuo editore è definito. In una versione futura è possibile concedere le autorizzazioni per visualizzare e gestire le estensioni dell'editore. È più semplice e più sicuro pubblicare le estensioni in un server di pubblicazione comune, senza la necessità di condividere un set di credenziali tra gli utenti.

Caricare l'estensione

Trovare il pulsante Carica nuova estensione, vai al file .vsix in pacchetto e selezionare Carica.

È anche possibile caricare l'estensione tramite l'interfaccia della riga di comando utilizzando il comando tfx extension publish invece di tfx extension create per creare un pacchetto e pubblicare l'estensione in un unico passaggio. Facoltativamente, è possibile usare --share-with per condividere l'estensione con uno o più account dopo la pubblicazione.

tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization

Condividere l'estensione

Ora che l'estensione è stata caricata, si trova nel Marketplace, ma nessuno può vederla. Condividerlo con l'organizzazione in modo che sia possibile installarlo e testarlo.

Selezionare con il pulsante destro del computer l'estensione e selezionare Condividi e immettere le informazioni dell'organizzazione. Puoi condividerlo anche con altri account ai quali vuoi dare accesso alla tua estensione.

Importante

Gli editori devono essere verificati per condividere le estensioni pubblicamente. Per altre informazioni, vedere Package/Publish/Install.For more information, see Package/Publish/Install.

Dopo aver condiviso l'estensione nel Marketplace, chiunque voglia usarla deve installarla.

6. Creare una pipeline di compilazione e versione per pubblicare l'estensione in Marketplace

Per mantenere l'attività personalizzata nel Marketplace, creare una pipeline di compilazione e rilascio in Azure DevOps.

Prerequisiti per la pubblicazione

  • Un progetto Azure DevOps. Creare un progetto.

  • Estensione Attività dell'estensione DevOps di Azure. Installarlo gratuitamente nell'organizzazione.

  • Gruppo di variabili della libreria della pipeline. Creare un gruppo di variabili della libreria di pipeline per contenere le variabili usate dalla pipeline. Per altre informazioni, vedere Aggiungere e usare gruppi di variabili. È possibile creare gruppi di variabili dalla scheda Azure DevOps Library o tramite l'interfaccia della riga di comando. Usa le variabili all'interno di questo gruppo nelle tue pipeline. Dichiarare anche le variabili seguenti nel gruppo di variabili:

    • publisherId: ID dell'editore del marketplace
    • extensionId: ID dell'estensione, come dichiarato nel file vss-extension.json
    • extensionName: nome dell'estensione, come dichiarato nel file vss-extension.json
    • artifactName: nome dell'artefatto creato per il file VSIX

  • Connessione al servizio. Creare una nuova connessione al servizio Marketplace e concedere le autorizzazioni di accesso per tutte le pipeline.

  • Pipeline YAML. Usare l'esempio seguente per creare una nuova pipeline con YAML. Per altre informazioni, vedere Creare la prima pipeline e lo schema YAML.

        trigger: 
    - main
    pool:
      vmImage: "ubuntu-latest"
    variables:
      - group: variable-group # Rename to whatever you named your variable group in the prerequisite stage of step 6
    stages:
      - stage: Run_and_publish_unit_tests
        jobs:
          - job:
            steps:
              - task: TfxInstaller@4
                inputs:
                  version: "v0.x"
              - task: Npm@1
                inputs:
                  command: 'install'
                  workingDir: '/TaskDirectory' # Update to the name of the directory of your task
              - task: Bash@3
                displayName: Compile Javascript
                inputs:
                  targetType: "inline"
                  script: |
                    cd TaskDirectory # Update to the name of the directory of your task
                    tsc
              - task: Npm@1
                inputs:
                  command: 'custom'
                  workingDir: '/TestsDirectory' # Update to the name of the directory of your task's tests
                  customCommand: 'testScript' # See the definition in the explanation section below - it may be called test
              - task: PublishTestResults@2
                inputs:
                  testResultsFormat: 'JUnit'
                  testResultsFiles: '**/ResultsFile.xml'
      - stage: Package_extension_and_publish_build_artifacts
        jobs:
          - job:
            steps:
              - task: TfxInstaller@4
                inputs:
                  version: "0.x"
              - task: Npm@1
                inputs:
                  command: 'install'
                  workingDir: '/TaskDirectory' # Update to the name of the directory of your task
              - task: Bash@3
                displayName: Compile Javascript
                inputs:
                  targetType: "inline"
                  script: |
                    cd TaskDirectory # Update to the name of the directory of your task
                    tsc
              - task: QueryAzureDevOpsExtensionVersion@4
                name: QueryVersion
                inputs:
                  connectTo: 'VsTeam'
                  connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection
                  publisherId: '$(PublisherID)'
                  extensionId: '$(ExtensionID)'
                  versionAction: 'Patch'
              - task: PackageAzureDevOpsExtension@4
                inputs:
                  rootFolder: '$(System.DefaultWorkingDirectory)'
                  publisherId: '$(PublisherID)'
                  extensionId: '$(ExtensionID)'
                  extensionName: '$(ExtensionName)'
                  extensionVersion: '$(QueryVersion.Extension.Version)'
                  updateTasksVersion: true
                  updateTasksVersionType: 'patch'
                  extensionVisibility: 'private' # Change to public if you're publishing to the marketplace
                  extensionPricing: 'free'
              - task: CopyFiles@2
                displayName: "Copy Files to: $(Build.ArtifactStagingDirectory)"
                inputs:
                  Contents: "**/*.vsix"
                  TargetFolder: "$(Build.ArtifactStagingDirectory)"
              - task: PublishBuildArtifacts@1
                inputs:
                  PathtoPublish: '$(Build.ArtifactStagingDirectory)'
                  ArtifactName: '$(ArtifactName)'
                  publishLocation: 'Container'
      - stage: Download_build_artifacts_and_publish_the_extension
        jobs:
          - job:
            steps:
              - task: TfxInstaller@4
                inputs:
                  version: "v0.x"
              - task: DownloadBuildArtifacts@0
                inputs:
                  buildType: "current"
                  downloadType: "single"
                  artifactName: "$(ArtifactName)"
                  downloadPath: "$(System.DefaultWorkingDirectory)"
              - task: PublishAzureDevOpsExtension@4
                inputs:
                  connectTo: 'VsTeam'
                  connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection
                  fileType: 'vsix'
                  vsixFile: '$(PublisherID).$(ExtensionName)/$(PublisherID)..vsix'
                  publisherId: '$(PublisherID)'
                  extensionId: '$(ExtensionID)'
                  extensionName: '$(ExtensionName)'
                  updateTasksVersion: false
                  extensionVisibility: 'private' # Change to public if you're publishing to the marketplace
                  extensionPricing: 'free'

Per altre informazioni, vedere Specificare gli eventi che attivano le pipeline.

Nota

Ogni lavoro utilizza un nuovo agente utente e richiede l'installazione delle dipendenze.

Le fasi della pipeline

La sezione seguente consente di comprendere il funzionamento delle fasi della pipeline.

Fase 1: Eseguire e pubblicare unit test

Questa fase esegue unit test e pubblica i risultati dei test in Azure DevOps.

Per eseguire unit test, aggiungere uno script personalizzato al package.json file come nell'esempio seguente.

"scripts": {
    "testScript": "mocha ./TestFile --reporter xunit --reporter-option output=ResultsFile.xml"
},

  1. Aggiungi Node CLI per Azure DevOps (tfx-cli) per installare tfx-cli sul tuo agente di build.

  2. Aggiungere l'attività npm utilizzando il comando install e indirizzare alla cartella il file package.json.

  3. Aggiungi il compito Bash per compilare TypeScript in JavaScript.

  4. Aggiungere l'attività npm con il custom comando , specificare come destinazione la cartella contenente gli unit test e immettere testScript come comando. Usare gli input seguenti:

    • Comando: custom
    • Cartella di lavoro contenente package.json: /TestsDirectory
    • Comandi e argomenti: testScript

  5. Aggiungere l'attività Pubblica risultati test . Se si usa il reporter Mocha XUnit, assicurarsi che il formato del risultato sia JUnit e non XUnit. Impostare la cartella di ricerca sulla directory principale. Usare gli input seguenti:

    • Formato dei risultati del test: JUnit
    • File dei risultati del test: **/ResultsFile.xml
    • Cartella di ricerca: $(System.DefaultWorkingDirectory)

    Dopo la pubblicazione dei risultati del test, l'output nella scheda test dovrebbe essere simile all'esempio seguente.

    Screenshot dell'esempio di risultato del test.

Fase 2: Creare un pacchetto dell'estensione e pubblicare gli artefatti di compilazione

  1. Aggiungi Node CLI per Azure DevOps (tfx-cli) per installare tfx-cli sul tuo agente di build.

  2. Aggiungere l'attività npm utilizzando il comando install e indirizzare alla cartella il file package.json.

  3. Aggiungi il compito Bash per compilare TypeScript in JavaScript.

  4. Per eseguire una query sulla versione esistente, aggiungere l'attività Query Estensione Versione utilizzando i seguenti input:

    • Connettersi a: Visual Studio Marketplace
    • Visual Studio Marketplace (Connessione al Servizio): Connessione al Servizio
    • ID editore: ID dell'editore di Visual Studio Marketplace
    • ID dell'estensione: ID della tua estensione nel file vss-extension.json
    • Aggiorna versione: Patch
    • Variabile di output: Task.Extension.Version

  5. Per creare un pacchetto delle estensioni in base al file JSON del manifesto, aggiungere l'attività Estensione pacchetto usando gli input seguenti:

    • Cartella manifest principale: indica la directory root che contiene il file manifest. Ad esempio, $(System.DefaultWorkingDirectory) è la directory principale
    • File di manifesto: vss-extension.json
    • ID editore: ID dell'editore di Visual Studio Marketplace
    • ID dell'estensione: ID della tua estensione nel file vss-extension.json
    • Nome estensione: nome dell'estensione vss-extension.json nel file
    • La versione dell'estensione: $(Task.Extension.Version)
    • Sovrascrivere le versioni delle attività: selezionato (true)
    • Tipo di override: Sostituisci solo la patch (1.0.r)
    • Visibilità estensione: se l'estensione è ancora in fase di sviluppo, impostare il valore privato. Per rilasciare l'estensione al pubblico, impostare il valore su pubblico.

  6. Per copiare nei file pubblicati, aggiungere l'attività Copia file usando gli input seguenti:

    • Contenuto: tutti i file da copiare per pubblicarli come artefatto
    • Cartella di destinazione: cartella in cui vengono copiati i file
      • Ad esempio: $(Build.ArtifactStagingDirectory)

  7. Aggiungere Pubblicare gli artefatti di compilazione per pubblicare gli artefatti da usare in altri processi o pipeline. Usare gli input seguenti:

    • Percorso di pubblicazione: percorso della cartella che contiene i file da pubblicare
      • Ad esempio: $(Build.ArtifactStagingDirectory)
    • Nome artefatto: nome assegnato all'artefatto
    • Percorso di pubblicazione degli artefatti: scegliere Azure Pipelines per usare l'artefatto nei job futuri

Fase 3: Scaricare gli artefatti di compilazione e pubblicare l'estensione

  1. Per installare tfx-cli nell'agente di compilazione, aggiungere Usare l'interfaccia della riga di comando del nodo per Azure DevOps (tfx-cli).

  2. Per scaricare gli artefatti in un nuovo processo, aggiungere l'attività Scarica artefatti di compilazione usando gli input seguenti:

    • Scarica gli artefatti prodotti da: se stai scaricando l'artefatto in un nuovo compito dalla stessa pipeline, seleziona Compilazione corrente. Se si esegue il download in una nuova pipeline, selezionare Compilazione specifica
    • Tipo di download: scegliere Artefatto specifico per scaricare tutti i file pubblicati.
    • Nome artefatto: nome dell'artefatto pubblicato
    • Directory di destinazione: cartella in cui scaricare i file

  3. Per ottenere l'attività Pubblica estensione, usare gli input seguenti:

    • Connettersi a: Visual Studio Marketplace
    • Connessione a Visual Studio Marketplace: ServiceConnection
    • Tipo di file di input: file VSIX
    • File VSIX: /Publisher.*.vsix
    • ID editore: ID dell'editore di Visual Studio Marketplace
    • ID dell'estensione: ID della tua estensione nel file vss-extension.json
    • Nome estensione: nome dell'estensione vss-extension.json nel file
    • Visibilità dell'estensione: privata o pubblica

Facoltativo: installare e testare l'estensione

Installare un'estensione condivisa con l'utente in pochi passaggi:

  1. Dal pannello di controllo dell'organizzazione (https://dev.azure.com/{organization}/_admin), passare alla pagina di amministrazione della raccolta di progetti.
  2. Nella scheda Estensioni, trova la tua estensione nel gruppo Estensioni condivise con me e seleziona il link dell'estensione.
  3. Installare l'estensione .

Se non è possibile visualizzare la scheda Estensioni , assicurarsi di essere nel pannello di controllo (la pagina di amministrazione a livello di raccolta del progetto, https://dev.azure.com/{organization}/_admin) e non la pagina di amministrazione per un progetto.

Se non viene visualizzata la scheda Estensioni, le estensioni non sono abilitate per l'organizzazione. È possibile ottenere l'accesso anticipato alla funzionalità delle estensioni aggiungendo il Programma Per i partner di Visual Studio.

Per creare un pacchetto e pubblicare le estensioni di Azure DevOps in Visual Studio Marketplace, è possibile scaricare le attività dell'estensione Azure DevOps.

Domande frequenti

Vedere le domande frequenti seguenti sull'aggiunta di attività di compilazione o versione personalizzate nelle estensioni per Azure DevOps.

D: Come è possibile limitare l'utilizzo dei comandi di Azure Pipelines per l'attività?

È possibile limitare l'utilizzo e le variabili dei comandi di Azure Pipelines, che vengono impostati per attività. Questa azione può essere utile per impedire l'accesso senza restrizioni alle variabili o ai comandi vso per script personalizzati eseguiti dall'attività. È consigliabile configurarla per le nuove attività. Per applicare, potrebbe essere necessario aggiungere l'istruzione seguente al task.json file:

"restrictions": {
  "commands": {
    "mode": "restricted"
  },
  "settableVariables": {
    "allowed": ["variable1", "test*"]
  }
}

Se restricted il valore è specificato per mode, è possibile eseguire solo i comandi seguenti tramite l'attività.

  • logdetail
  • logissue
  • complete
  • setprogress
  • setsecret
  • setvariable
  • debug
  • settaskvariable
  • prependpath
  • publish

Le settableVariables restrizioni consentono di passare una lista di variabili consentite, che vengono impostate dai comandi setvariable o prependpath. Consente anche espressioni regolari di base. Ad esempio, se l'elenco di elementi consentiti è: ['abc', 'test*'], impostando abc, test o test1 come variabili con qualsiasi valore o anteponendole al percorso, l'operazione avrà esito positivo, ma se si tenta di impostare un proxy di variabile, verrà emesso un avviso. L'elenco vuoto indica che nessuna variabile viene modificata dall'attività.

Se la settableVariables chiave o commands viene omessa, la restrizione pertinente non viene applicata.

La funzionalità di restrizione è disponibile dalla versione dell'agente 2.182.1.

Q: Come viene gestito il segnale di annullamento da un'attività?

L'agente della pipeline invia i segnali SIGINT e SIGTERM al processo figlio pertinente. Non esistono mezzi espliciti nella libreria di attività per elaborare. Per maggiori informazioni, consultare Annullamento dei compiti di Agent.

D: Come posso rimuovere un'attività dalla collezione di progetti?

Non è supportata l'eliminazione automatica delle attività. L'eliminazione automatica non è sicura e interrompe le pipeline esistenti che già usano tali attività. Tuttavia, è possibile contrassegnare le attività come deprecate. A tale scopo, incrementare la versione dell'attività e contrassegnare l'attività come deprecata.

D: Come posso aggiornare la mia attività personalizzata alla versione più recente di Node.js?

È consigliabile eseguire l'aggiornamento alla versione più recente di Node. Per altre informazioni, vedere Aggiornamento delle attività al nodo 20.

Gli agenti ospitati da Microsoft e varie versioni di Azure DevOps Server hanno cicli di vita diversi, causando l'installazione di versioni di Node runner diverse a seconda della posizione in cui è in esecuzione un'attività. Per garantire la compatibilità tra agenti con versioni diverse dello strumento di esecuzione di Node, il task.json file può includere più sezioni di esecuzione. Nell'esempio seguente, gli agenti di Azure Pipeline con il runner Node 20 lo utilizzano per impostazione predefinita, mentre gli agenti senza di esso utilizzano come fallback l'implementazione di Node 10.

"execution": {
  "Node10": {
    "target": "bash.js",
    "argumentFormat": ""
  },
  "Node20_1": {
    "target": "bash.js",
    "argumentFormat": ""
  }
}

Per migliorare le tue attività:

  • Per assicurarsi che il codice si comporti come previsto, testare le attività nelle varie versioni di Node Runner.

  • Nella sezione esecuzione dell'attività aggiornare da Node o Node10 a Node16 o Node20.

  • Per supportare le versioni precedenti del server, è necessario lasciare il Node/Node10 target. Le versioni precedenti di Azure DevOps Server potrebbero non includere la versione più recente dello strumento di esecuzione dei nodi.

  • È possibile scegliere di condividere il punto di ingresso definito nella destinazione o avere destinazioni ottimizzate per la versione del nodo usata.

    "execution": {
   "Node10": {
     "target": "bash10.js",
     "argumentFormat": ""
   },
   "Node16": {
     "target": "bash16.js",
     "argumentFormat": ""
   },
   "Node20_1": {
     "target": "bash20.js",
     "argumentFormat": ""
   }
}

Importante

Se non si aggiunge il supporto per il runner Node 20 alle attività personalizzate, queste falliranno sugli agenti installati dal feed di rilascio delle versioni pipelines-agent-*.

Contenuti correlati