Aggiungere un'estensione personalizzata dell'attività pipeline

Articolo
03/27/2025

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

Informazioni su 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 ulteriori informazioni sulle attività del server e sulle estensioni basate su server, consultare la documentazione di GitHub sulle attività del server.

Prerequisiti

Software/strumento	Informazioni
Organizzazione DevOps di Azure	Creare un'organizzazione.
Un editor di testo	Per molte procedure viene usato Visual Studio Code, che offre supporto per intelliSense e debug. Scaricare la versione più recente.
Node.js	Scaricare la versione più recente.
npmjs.com 4.0.2 o versione successiva	Compilatore TypeScript. Scaricare la versione più recente.
tfx-cli	Impacchetta la tua estensione con l'interfaccia a riga di comando multipiattaforma per Azure DevOps. utilizzando `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 versione dovrebbe essere simile all'esempio 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 file task.json 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 buildandreleasetask cartella .

Nota

In questo esempio viene usato Windows con PowerShell. È stato reso generico 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à

Creare la struttura di cartelle per l'attività e installare le librerie e le dipendenze necessarie.
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.
Aggiungere azure-pipelines-task-lib alla libreria.
```
npm install azure-pipelines-task-lib --save
```
Assicurarsi che le tipizzazioni TypeScript siano installate per le dipendenze esterne.
```
npm install @types/node --save-dev
npm install @types/q --save-dev
```
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
```

Installare Mocha come dipendenza di sviluppo.

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

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, in modo che il tsc comando sia 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.
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, possiamo creare la nostra attività personalizzata.

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.

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

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();

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 dell'attività all'interno dell'elenco dei passaggi 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`, `PowerShell3`o `Process`.
`restrictions`	Le restrizioni sono applicate ai comandi di GitHub Codespaces che il compito può chiamare e alle variabili che il compito 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.

Eseguire l'attività

Eseguire l'attività con 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, è possibile 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à è riuscita perché samplestring è stata fornita e ha restituito correttamente "Hello Human!"

Suggerimento

Per informazioni sui vari strumenti di esecuzione delle attività e su come includere la versione più recente del nodo nella task.json, vedere Indicazioni per l'aggiornamento di 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.

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

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 cartella buildandreleasetask. Se viene visualizzato un errore di richiesta di sincronizzazione, è possibile aggirarlo aggiungendo la richiesta di sincronizzazione alla cartella buildandreleasetask con il comando npm i --save-dev sync-request.

Creare un success.ts file nella directory di test con il contenuto seguente. Questa creazione di file simula l'esecuzione dell'attività e simula 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.

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
     });
 });

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 fallimento verifica che, quando lo strumento riceve un input non valido o incompleto, fallisce nel modo previsto con un output utile.

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();
    });
});

Esegui i test.
```
tsc
mocha tests/_suite.js
```
Entrambi i test devono superare. 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

Modificare il server di pubblicazione impostando il nome dell'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 oggetto di 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.

4. Creare un pacchetto dell'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 manifesto o passare l'opzione della --rev-version riga di comando. 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.

Creare il server di pubblicazione

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.

Accedere al portale di pubblicazione di Visual Studio Marketplace.
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.
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 a riga di comando usando il comando tfx extension publish anziché tfx extension create per creare il pacchetto e pubblicare l'estensione in un solo 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
```
Creare un token di accesso personale (PAT).
- Selezionare l'ambito "Marketplace (pubblicazione)". Questo ambito limita il token solo alla possibilità di pubblicare estensioni nel Marketplace.

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.

Ora che l'estensione è condivisa 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

Software/strumento

Informazioni

Progetto DevOps di Azure

Creare un progetto.

Attività dell'estensione di Azure DevOps

Installare gratuitamente le attività dell'estensione Azure DevOps nell'organizzazione.

Gruppo di variabili della libreria di 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 file package.json come nell'esempio seguente.

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

Aggiungere "Utilizza Node CLI per Azure DevOps (tfx-cli)" per installare il tfx-cli nell'agente di compilazione.
Aggiungere l'attività "npm" con il comando "install" e impostare come destinazione la cartella con il file package.json.
Aggiungi il compito "Bash" per convertire TypeScript in JavaScript.
Aggiungere l'attività "npm" con il comando "personalizzato", impostare come destinazione la cartella contenente gli unit test e immettere testScript come comando. Usare gli input seguenti:
- Comando: personalizzato
- Cartella di lavoro contenente package.json: /TestsDirectory
- Comandi e argomenti: testScript
Aggiungere l'attività "Pubblica risultati test". Se si usa il reporter Mocha XUnit, assicurarsi che il formato dei risultati sia "JUnit" e non "XUnit". Impostare la cartella di ricerca sulla directory radice. Usare gli input seguenti:
- Formato dei risultati del test: JUnit
- File dei risultati dei 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.

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

** Aggiungi "Usa Node CLI per Azure DevOps (tfx-cli)" per installare tfx-cli sul tuo agente di compilazione.
Aggiungere l'attività "npm" con il comando "install" e impostare come destinazione la cartella con il file package.json.
Aggiungere l'attività "Bash" per compilare il TypeScript in formato JavaScript.
Per eseguire una query sulla versione esistente, aggiungere l'attività "Query Versione Estensione" usando gli input seguenti.
- Connettersi a: Visual Studio Marketplace
- Visual Studio Marketplace (Connessione al Servizio): Connessione al Servizio
- ID editore: ID dell'editore di Visual Studio Marketplace
- ID estensione: ID dell'estensione nel file vss-extension.json
- Aumentare la versione: Patch
- Variabile di output: Task.Extension.Version
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 radice
- File manifest: vss-extension.json
- ID editore: ID dell'editore di Visual Studio Marketplace
- ID estensione: ID dell'estensione nel file vss-extension.json
- Nome estensione: nome dell'estensione nel file vss-extension.json
- Versione dell'estensione: $(Task.Extension.Version)
- Sovrascrivere le versioni delle attività: selezionato (true)
- Tipo di override: Sostituisci solo patch (1.0.r)
- Visibilità estensione: se l'estensione è ancora in fase di sviluppo, impostare il valore su privato. Per rilasciare l'estensione al pubblico, impostare il valore su public
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)
Aggiungi "Pubblica 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: Scegli "Azure Pipelines" per utilizzare l'artefatto nei processi futuri

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

Per installare il tfx-cli sul proprio agente di compilazione, aggiungere "Usare Node CLI per Azure DevOps (tfx-cli)".
Per scaricare gli artefatti in un nuovo lavoro, aggiungere l'attività "Scarica artefatti di compilazione" utilizzando gli input seguenti:
- Scaricare gli artefatti generati da: se si scarica l'artefatto in un nuovo processo dalla stessa pipeline, selezionare "Compilazione corrente". Se si scarica l'artefatto 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.
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 estensione: ID dell'estensione nel file vss-extension.json
- Nome estensione: nome dell'estensione nel file vss-extension.json
- Visibilità dell'estensione: privata o pubblica

Facoltativo: installare e testare l'estensione

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

Dal pannello di controllo dell'organizzazione (https://dev.azure.com/{organization}/_admin), passare alla pagina di amministrazione della raccolta di progetti.
Nella scheda Estensioni trovare l'estensione nel gruppo "Estensioni condivise con l'utente corrente" e selezionare il collegamento di estensione.
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 illimitato a variabili e comandi VSO nei script personalizzati che l'attività esegue. È consigliabile configurarla per le nuove attività. Per applicare, potrebbe essere necessario aggiungere l'istruzione seguente al file task.json:

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

Se il valore restricted è specificato per mode, è possibile eseguire solo i comandi seguenti nel contesto dell'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 .

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

R: 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 altre informazioni, vedere Annullamento dei processi di Agent.

D: Come è possibile rimuovere l'attività dalla raccolta di progetti?

R: 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, aggiornare 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?

R: È 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 file di task.json 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 eseguono il fallback all'implementazione in Node 10.

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

Per aggiornare le 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-*.

Condividi tramite

Aggiungere un'estensione personalizzata dell'attività pipeline

Prerequisiti

1. Creare un'attività personalizzata

Creare la struttura di supporto per le attività

Crea attività

componenti di task.json

Eseguire l'attività

2. Esegui test unitari degli script delle attività

3. Creare il file manifesto dell'estensione

Contributi

File

4. Creare un pacchetto dell'estensione

5. Pubblicare l'estensione

Creare il server di pubblicazione

Caricare l'estensione

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

Prerequisiti

Le fasi della pipeline

Fase 1: Eseguire e pubblicare unit test

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

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

Facoltativo: installare e testare l'estensione

Domande frequenti

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

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

D: Come è possibile rimuovere l'attività dalla raccolta di progetti?

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

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Aggiungere un'estensione personalizzata dell'attività pipeline

Prerequisiti

1. Creare un'attività personalizzata

Creare la struttura di supporto per le attività

Crea attività

componenti di task.json

Eseguire l'attività

2. Esegui test unitari degli script delle attività

3. Creare il file manifesto dell'estensione

Contributi

File

4. Creare un pacchetto dell'estensione

5. Pubblicare l'estensione

Creare il server di pubblicazione

Caricare l'estensione

Condividere l'estensione

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

Prerequisiti

Le fasi della pipeline

Fase 1: Eseguire e pubblicare unit test

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

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

Facoltativo: installare e testare l'estensione

Domande frequenti

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

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

D: Come è possibile rimuovere l'attività dalla raccolta di progetti?

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

Articoli correlati

Commenti e suggerimenti

Risorse aggiuntive