Delen via

Een taakextensie voor aangepaste pijplijnen toevoegen

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

In dit artikel wordt uitgelegd hoe u extensies voor uw organisatie installeert voor aangepaste build- of releasetaken in Azure DevOps. Zie Wat is Azure Pipelines voor meer informatie ?

Notitie

In dit artikel worden taken van agents behandeld in agent-gebaseerde extensies. Zie de servertaakcreatie voor meer informatie over servertaken en serverextensies.

Vereisten

  • Een organisatie in Azure DevOps. Maak een organisatie.

  • Een teksteditor. Voor veel zelfstudies gebruiken we Visual Studio Code, dat ondersteuning biedt voor intellisense en foutopsporing.

  • De nieuwste versie van Node.js.

  • npmjs.com 4.0.2 of hoger. Installeer de nieuwste versie van deze TypeScript-compiler.

  • Platformoverschrijdende CLI voor Azure DevOps (tfx-cli) om uw extensies te verpakken.

    • tfx-cli kan worden geïnstalleerd met behulp van npm, een onderdeel van Node.js, door npm i -g tfx-cli uit te voeren.

  • Azure DevOps-extensie-SDK. Installeer het pakket azure-devops-extension-sdk .

  • Een home map voor uw project. De home map van een build- of release-taakextensie moet de volgende structuur hebben nadat u de stappen in dit artikel hebt voltooid:

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

Belangrijk

De ontwikkelcomputer moet de nieuwste versie van Node uitvoeren om ervoor te zorgen dat de geschreven code compatibel is met de productieomgeving op de agent en de nieuwste niet-preview-versie van azure-pipelines-task-lib. Werk het task.json bestand bij volgens de volgende opdracht:

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

1. Een aangepaste taak maken

Voer elk deel van deze procedure uit in de buildandreleasetask map in uw home map.

Notitie

In deze voorbeeld-walkthrough wordt Windows gebruikt met PowerShell. De stappen zijn algemeen voor alle platforms, maar de syntaxis voor het verkrijgen van omgevingsvariabelen is anders. Als u een Mac of Linux gebruikt, vervangt u elke keer dat $env:<var>=<val> verschijnt door export <var>=<val>.

Taakstructuur maken

  1. Maak de mapstructuur voor de taak en installeer de vereiste bibliotheken en afhankelijkheden.

  2. Open een PowerShell-opdrachtvenster, ga naar uw buildandreleasetask map en voer de volgende opdracht uit.

    npm init --yes

    npm init maakt het package.json bestand. We hebben de --yes parameter toegevoegd om alle standaardopties npm init te accepteren.

    Aanbeveling

    De agent installeert de vereiste modules niet automatisch omdat hij verwacht dat de taakmap de node modules bevat. Als u dit wilt beperken, kopieert u de node_modules naar buildandreleasetask. Naarmate uw taak groter wordt, is het eenvoudig om de maximale grootte (50 MB) van een VSIX-bestand te overschrijden. Voordat u de knooppuntmap kopieert, wilt u mogelijk npm install --production of npm prune --productionuitvoeren, of u kunt een script schrijven om alles te bouwen en in te pakken.

  3. Toevoegen azure-pipelines-task-lib aan uw bibliotheek.

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

  4. Zorg ervoor dat TypeScript-typings zijn geïnstalleerd voor externe afhankelijkheden.

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

  5. Maak een .gitignore bestand en voeg er node_modules aan toe. Uw buildproces moet een npm install en een typings install zodanig uitvoeren dat node_modules elke keer worden gebouwd en niet hoeven te worden ingecheckt.

    echo node_modules > .gitignore

  6. Installeer Mocha als ontwikkelingsdependency.

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

  7. Kies TypeScript-versie 2.3.4 of 4.6.3.

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

    Notitie

    Zorg ervoor dat TypeScript globaal is geïnstalleerd in npm uw ontwikkelomgeving, zodat het tsc commando beschikbaar is. Als u deze stap overslaat, wordt TypeScript-versie 2.3.4 standaard gebruikt en moet u het pakket nog steeds globaal installeren om de tsc opdracht beschikbaar te maken.

  8. Maak compileropties tsconfig.json. Dit bestand zorgt ervoor dat uw TypeScript-bestanden worden gecompileerd naar JavaScript-bestanden.

    tsc --init --target es2022

Taak aanmaken

Nu de steigers voltooid zijn, kunt u uw eigen taak aanpassen.

  1. Maak een task.json bestand in de buildandreleasetask map. Het task.json bestand beschrijft de build/release-taak en is wat het build-/releasesysteem gebruikt om configuratieopties voor de gebruiker weer te geven en om te weten welke scripts moeten worden uitgevoerd op build-/releasetijd.

  2. Kopieer de volgende code en vervang {{placeholders}} met de informatie van uw taak. De belangrijkste tijdelijke aanduiding is de taskguiden moet uniek zijn.

    {
 "$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. Maak een index.ts bestand met behulp van de volgende code als verwijzing. Deze code wordt uitgevoerd wanneer de taak wordt aangeroepen.

    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. Als u een index.js-bestand wilt compileren vanuit index.ts, voert u tsc uit de map buildandreleasetask in.

task.json onderdelen

Zie de volgende beschrijvingen van enkele onderdelen van het task.json bestand.

Eigendom Beschrijving
id Een unieke GUID voor uw taak.
name Naam zonder spaties.
friendlyName Beschrijvende naam (toegestane spaties).
description Gedetailleerde beschrijving van wat uw taak doet.
author Korte tekenreeks die de entiteit beschrijft die de build- of releasetaak ontwikkelt, bijvoorbeeld: Microsoft Corporation
instanceNameFormat Hoe de taak wordt weergegeven in de lijst met build-/releasestappen. U kunt variabele waarden gebruiken met behulp van $(variablename).
groups Beschrijft de logische groepering van taakeigenschappen in de gebruikersinterface.
inputs Invoer die moet worden gebruikt wanneer uw build- of releasetaak wordt uitgevoerd. Deze taak verwacht een invoer met de naam samplestring.
execution Er zijn meerdere uitvoeringsopties voor deze taak, waaronder scripts, zoals Node, PowerShell, PowerShell3of Process.
restrictions Beperkingen die worden toegepast op de taak over GitHub Codespaces-opdrachten die door de taak kunnen worden aangeroepen en variabelen die de taak kan instellen. U wordt aangeraden de beperkingsmodus voor nieuwe taken op te geven.

Notitie

Maak een id met de volgende opdracht in PowerShell:

(New-Guid).Guid

Zie de naslaginformatie over build-/releasetaken voor meer informatie.

De taak uitvoeren

Voer de taak uit met behulp van node index.js PowerShell.

In het volgende voorbeeld mislukt de taak omdat er geen invoer is opgegeven (samplestring is een vereiste invoer).

 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

Als oplossing stelt u de samplestring invoer in en voert u de taak opnieuw uit.

$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

Deze keer slaagt de taak omdat samplestring deze is opgegeven, en wordt hallo mens correct uitgevoerd .

Aanbeveling

Voor informatie over verschillende taaklopers en het opnemen van de nieuwste nodeversie in de task.json, zie de richtlijnen voor het bijwerken van Node-runners voor Azure Pipelines-taakauteurs.

2. Test uw taakscripts per eenheid

Voer eenheidstests uit om het taakscript snel te testen en niet de externe hulpprogramma's die worden aanroepen. Test alle aspecten van zowel geslaagde als mislukte paden.

  1. Testhulpprogramma's installeren. In deze procedure gebruiken we Mocha als teststuurprogramma.

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

  2. Maak een tests map met een _suite.ts bestand met de volgende inhoud:

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

    Aanbeveling

    De testmap moet zich in de buildandreleasetask map bevinden. Als er een synchronisatieaanvraagfout optreedt, kunt u deze omzeilen door een synchronisatieaanvraag toe te voegen aan de buildandreleasetask map met de opdracht npm i --save-dev sync-request.

  3. Maak een success.ts bestand in uw testmap met de volgende inhoud. Dit bestand simuleert het uitvoeren van de taak en bootst alle oproepen naar externe methoden na.

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

    De geslaagde test valideert dat, met de juiste invoer, het slaagt zonder fouten of waarschuwingen en retourneert de juiste uitvoer.

  4. Om de mockrunner uit te voeren, voegt u de volgende voorbeeldsuccesstest toe aan uw _suite.ts-bestand.

         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. Maak een failure.ts bestand in uw testmap als uw taaksimulator met de volgende inhoud:

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

    De mislukkingstest valideert dat, wanneer het hulpprogramma slechte of onvolledige invoer krijgt, het op de verwachte manier faalt met behulpzame output.

  6. Als u de mockrunner van de taak wilt uitvoeren, voegt u de volgende code toe aan uw _suite.ts-bestand.

    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. Voer de tests uit.

    tsc
mocha tests/_suite.js

    Beide tests moeten slagen. Als u de tests wilt uitvoeren met uitgebreidere uitvoer (wat u in de build-console zou zien), stelt u de omgevingsvariabele in: TASK_TEST_TRACE=1.

    $env:TASK_TEST_TRACE=1

3. Maak het extensiemanifestbestand

Het extensiemanifest bevat alle informatie over uw extensie. Het bevat koppelingen naar uw bestanden, waaronder uw taakmappen en afbeeldingenmappen. Zorg ervoor dat u een map met afbeeldingen hebt gemaakt met extension-icon.png. Het volgende voorbeeld is een uitbreidingsmanifest dat de build- of releasetaak bevat.

Kopieer de volgende .json code en sla deze op als uw vss-extension.json bestand in uw home map.

Maak dit bestand niet in de map 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"
            }
        }
    ]
}

Notitie

Wijzig uitgever naar de naam van uw uitgever. Zie Een uitgever maken voor meer informatie.

Bijdragen

Eigendom Beschrijving
id Id van de bijdrage. Moet uniek zijn binnen de extensie. Hoeft niet overeen te komen met de naam van de build- of releasetaak. Normaal gesproken bevindt de naam van de build- of releasetaak zich in de id van de bijdrage.
type Het type bijdrage. Moet ms.vss-distributed-task.task zijn.
targets Bijdragen waarop deze bijdrage is gericht . Moet ms.vss-distributed-task.tasks zijn.
properties.name Naam van de taak. Deze naam moet overeenkomen met de mapnaam van de bijbehorende zelfstandige build- of release-pijplijntaak.

Bestanden

Eigendom Beschrijving
path Pad van het bestand of de map ten opzichte van de home map.

Raadpleeg de handleiding voor het extensiemanifest voor meer informatie over het extensiemanifest, zoals de eigenschappen en hun functies.

4. Uw extensie verpakken

Pak al uw bestanden samen om uw extensie op te halen in Visual Studio Marketplace. Alle extensies zijn verpakt als VSIX 2.0-compatibele .vsix-bestanden. Microsoft biedt een platformoverschrijdende opdrachtregelinterface (CLI) om uw extensie te verpakken.

Zodra u de tfx-cli hebt, gaat u naar de basismap van uw extensie en voert u de volgende opdracht uit:

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

Notitie

De versie van een extensie of integratie moet bij elke update worden verhoogd. Wanneer u een bestaande extensie bijwerkt, werkt u de versie in het manifest bij of geeft u de --rev-version opdrachtregelswitch door. Hiermee wordt het patchversienummer van uw extensie verhoogd en wordt de nieuwe versie opgeslagen in uw manifest. U moet zowel de taakversie als de extensieversie verhogen om een update te laten plaatsvinden. tfx extension create --manifest-globs vss-extension.json --rev-version werkt alleen de extensieversie bij en niet de taakversie. Zie Build Task in GitHub voor meer informatie.

Zodra uw pakketextensie zich in een VSIX-bestand bevindt, kunt u de extensie publiceren naar Marketplace.

5. Uw extensie publiceren

Als u uw extensie wilt publiceren, maakt u eerst uw uitgever, uploadt u vervolgens uw extensie en deelt u deze ten slotte.

Uw uitgever maken

Alle extensies, inclusief extensies van Microsoft, worden geïdentificeerd als geleverd door een uitgever. Als u nog geen lid bent van een bestaande uitgever, maakt u er een.

  1. Meld u aan bij de Visual Studio Marketplace-publicatieportal.

  2. Als u nog geen lid bent van een bestaande uitgever, wordt u gevraagd een uitgever te maken. Als u niet wordt gevraagd om een uitgever te maken, schuift u omlaag naar de onderkant van de pagina en selecteert u Extensies publiceren onder Verwante sites.

    • Geef een id op voor uw uitgever, bijvoorbeeld: mycompany-myteam.
      • Deze id wordt gebruikt als de waarde voor het kenmerk in het publisher manifestbestand van uw extensies.
    • Geef een weergavenaam op voor uw uitgever, bijvoorbeeld: My Team.

  3. Controleer de Marketplace Publisher-overeenkomst en selecteer Aanmaken.

Uw uitgever is gedefinieerd. In een toekomstige release kunt u machtigingen verlenen om de extensies van uw uitgever weer te geven en te beheren. Het is eenvoudiger en veiliger om extensies te publiceren onder een gemeenschappelijke uitgever, zonder dat u een set referenties hoeft te delen tussen gebruikers.

Uw extensie uploaden

Zoek de knop Nieuwe extensie uploaden, ga naar het verpakte .vsix-bestand en selecteer Uploaden.

U kunt uw extensie ook uploaden via de opdrachtregelinterface (CLI) met behulp van de tfx extension publish opdracht in plaats van tfx extension create uw extensie in één stap te verpakken en uw extensie te publiceren. U kunt eventueel --share-with gebruiken om uw extensie te delen met een of meer accounts nadat deze is gepubliceerd.

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

Uw extensie delen

Nu u uw extensie hebt geüpload, bevindt deze zich in Marketplace, maar niemand kan deze zien. Deel het met uw organisatie, zodat u deze kunt installeren en testen.

Selecteer met de rechtermuisknop uw extensie en selecteer Delen en voer uw organisatiegegevens in. U kunt deze ook delen met andere accounts die u toegang wilt geven tot uw extensie.

Belangrijk

Uitgevers moeten worden geverifieerd om extensies openbaar te delen. Zie Package/Publish/Install voor meer informatie.

Nadat uw extensie is gedeeld in Marketplace, moet iedereen die deze wil gebruiken, de extensie installeren.

6. Maak een build- en release-pijplijn om de extensie te publiceren naar Marketplace

Als u de aangepaste taak op Marketplace wilt onderhouden, maakt u een build- en release-pijplijn in Azure DevOps.

Vereisten voor publicatie

  • Een Azure DevOps-project. Maak een project.

  • Azure DevOps Extension Tasks-extensie. Installeer deze gratis in uw organisatie.

  • Pijplijnbibliotheekvariabelegroep. Maak een pijplijnbibliotheekvariabelegroep voor het opslaan van de variabelen die door de pijplijn worden gebruikt. Zie Variabelengroepen toevoegen en gebruiken voor meer informatie. U kunt variabele groepen maken via het tabblad Azure DevOps Library of via de CLI. Gebruik de variabelen in deze groep in uw pijplijn. Declareer ook de volgende variabelen in de variabelegroep:

    • publisherId: id van uw marketplace-uitgever
    • extensionId: Id van uw extensie, zoals gedeclareerd in het bestand vss-extension.json
    • extensionName: Naam van uw extensie, zoals gedeclareerd in het vss-extension.json-bestand
    • artifactName: Naam van het artefact dat wordt gemaakt voor het VSIX-bestand

  • Verbindingsdienst. Maak een nieuwe Marketplace-serviceverbinding en verleen toegangsmachtigingen voor alle pijplijnen.

  • YAML-pijplijn. Gebruik het volgende voorbeeld om een nieuwe pijplijn te maken met YAML. Zie Uw eerste pijplijn en YAML-schema maken voor meer informatie.

        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'

Zie Gebeurtenissen opgeven die pijplijnen activeren voor meer informatie.

Notitie

Elke taak maakt gebruik van een nieuwe gebruikersagent en vereist dat afhankelijkheden worden geïnstalleerd.

Pijplijnfasen

In de volgende sectie leert u hoe de pijplijnfasen werken.

Fase 1: Eenheidstests uitvoeren en publiceren

In deze fase worden eenheidstests uitgevoerd en testresultaten gepubliceerd naar Azure DevOps.

Als u eenheidstests wilt uitvoeren, voegt u een aangepast script toe aan het package.json bestand, zoals in het volgende voorbeeld.

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

  1. Voeg Node CLI gebruiken voor Azure DevOps (tfx-cli) toe om de tfx-cli te installeren op uw buildagent.

  2. Voeg de npm taak toe met de install opdracht en richt u op de map met het package.json bestand.

  3. Voeg de Bash taak toe om het TypeScript te compileren in JavaScript.

  4. Voeg de npm taak toe met de custom opdracht, doel op de map die de eenheidstests bevat en voer testScript in als de opdracht. Gebruik de volgende invoer:

    • Bevelen: custom
    • Werkmap met package.json: /TestsDirectory
    • Opdracht en argumenten: testScript

  5. Voeg de taak Testresultaten publiceren toe. Als u de Mocha XUnit-rapporter gebruikt, moet u ervoor zorgen dat de resultaatindeling is JUnit en niet XUnit. Stel de zoekmap in op de hoofdmap. Gebruik de volgende invoer:

    • Indeling van testresultaat: JUnit
    • Testresultatenbestanden: **/ResultsFile.xml
    • Zoekmap: $(System.DefaultWorkingDirectory)

    Nadat de testresultaten zijn gepubliceerd, moet de uitvoer op het tabblad Tests eruitzien als in het volgende voorbeeld.

    Schermopname van het voorbeeld van het testresultaat.

Fase 2: De extensie verpakken en buildartefacten publiceren

  1. Voeg Node CLI gebruiken voor Azure DevOps (tfx-cli) toe om de tfx-cli te installeren op uw buildagent.

  2. Voeg de npm taak toe met de install opdracht en richt u op de map met het package.json bestand.

  3. Voeg de Bash taak toe om het TypeScript te compileren in JavaScript.

  4. Om de bestaande versie op te vragen, voegt u de taak Query Extension Version toe met behulp van de volgende invoer:

    • Verbinding maken met: Visual Studio Marketplace
    • Visual Studio Marketplace (Serviceverbinding): Serviceverbinding
    • Uitgever-id: id van uw Visual Studio Marketplace-uitgever
    • Extensie-id: id van uw extensie in het vss-extension.json bestand
    • Versie-update: Patch
    • Uitvoervariabele: Task.Extension.Version

  5. Als u de extensies wilt verpakken op basis van manifest-Json, voegt u de pakketextensietaak toe met behulp van de volgende invoer:

    • Hoofdmap voor manifesten: wijst naar de hoofdmap die het manifestbestand bevat. Bijvoorbeeld, $(System.DefaultWorkingDirectory) is de hoofdmap
    • Manifestbestand: vss-extension.json
    • Uitgever-id: id van uw Visual Studio Marketplace-uitgever
    • Extensie-id: id van uw extensie in het vss-extension.json bestand
    • Extensienaam: naam van uw extensie in het vss-extension.json bestand
    • Extensieversie: $(Task.Extension.Version)
    • Takenversie overschrijven: aangevinkt (waar)
    • Overridetype: Alleen patch vervangen (1.0.r)
    • Zichtbaarheid van extensies: als de extensie nog in ontwikkeling is, stelt u de waarde in op privé. Als u de extensie wilt vrijgeven aan het publiek, stelt u de waarde in op openbaar.

  6. Als u naar gepubliceerde bestanden wilt kopiëren, voegt u de taak Bestanden kopiëren toe met behulp van de volgende invoer:

    • Inhoud: Alle bestanden die moeten worden gekopieerd voor publicatie als artefact
    • Doelmap: de map waarnaar de bestanden worden gekopieerd
      • Bijvoorbeeld: $(Build.ArtifactStagingDirectory)

  7. Voeg bouwartefacten publiceren toe om de artefacten te publiceren voor gebruik in andere taken of in pijplijnen. Gebruik de volgende invoer:

    • Pad om te publiceren: het pad naar de map met de bestanden die worden gepubliceerd
      • Bijvoorbeeld: $(Build.ArtifactStagingDirectory)
    • Artefactnaam: de naam die aan het artefact is gegeven
    • Publicatielocatie voor artefacten: Kies Azure Pipelines om het artefact in toekomstige taken te gebruiken

Fase 3: Build-artefacten downloaden en de extensie publiceren

  1. Als u de tfx-cli wilt installeren op uw buildagent, voegt u Node CLI gebruiken voor Azure DevOps (tfx-cli) toe.

  2. Om de bouwartefacten op een nieuwe taak te downloaden, voegt u de taak Download bouwartefacten toe met de volgende invoer:

    • Download artifacts die zijn gemaakt door: Als u het artifact in een nieuwe job uit dezelfde pijplijn downloadt, selecteert u Huidige build. Als u aan het downloaden bent via een nieuwe pijplijn, selecteert u Specifieke build
    • Downloadtype: Kies Specifiek artefact om alle bestanden te downloaden die zijn gepubliceerd.
    • Artefactnaam: de naam van het gepubliceerde artefact
    • Doelmap: de map waarin de bestanden gedownload moeten worden

  3. Gebruik de volgende invoer om de Publiceer Extensie taak op te halen:

    • Verbinding maken met: Visual Studio Marketplace
    • Visual Studio Marketplace-verbinding: ServiceConnection
    • Invoerbestandstype: VSIX-bestand
    • VSIX-bestand: /Publisher.*.vsix
    • Uitgever-id: id van uw Visual Studio Marketplace-uitgever
    • Extensie-id: id van uw extensie in het vss-extension.json bestand
    • Extensienaam: naam van uw extensie in het vss-extension.json bestand
    • Zichtbaarheid van extensies: privé of openbaar

Optioneel: Uw extensie installeren en testen

Installeer in slechts enkele stappen een extensie die met u wordt gedeeld:

  1. Ga vanuit het configuratiescherm van uw organisatie (https://dev.azure.com/{organization}/_admin) naar de beheerpagina van de projectverzameling.
  2. Zoek op het tabblad Extensies uw extensie in de groep Extensies die met mij is gedeeld en selecteer de extensiekoppeling.
  3. Installeer de extensie.

Als u het tabblad Extensies niet ziet, controleert u of u zich in het configuratiescherm bevindt (de beheerpagina op projectverzamelingsniveau https://dev.azure.com/{organization}/_admin) en niet de beheerpagina voor een project.

Als u het tabblad Extensies niet ziet, zijn extensies niet ingeschakeld voor uw organisatie. U kunt vroegtijdige toegang krijgen tot de uitbreidingsfunctie door deel te nemen aan het Visual Studio Partner Program.

Als u Azure DevOps-extensies wilt verpakken en publiceren in Visual Studio Marketplace, kunt u Azure DevOps-extensietaken downloaden.

Veelgestelde vragen

Zie de volgende veelgestelde vragen over het toevoegen van aangepaste build- of releasetaken in extensies voor Azure DevOps.

V: Hoe kan ik het gebruik van Azure Pipelines-opdrachten voor taken beperken?

U kunt het gebruik en de variabelen van Azure Pipelines-opdrachten beperken, die worden ingesteld op taak. Deze actie kan handig zijn om onbeperkte toegang tot variabelen of vso-opdrachten te voorkomen voor aangepaste scripts die door de taak worden uitgevoerd. U wordt aangeraden deze in te stellen voor nieuwe taken. Als u dit wilt toepassen, moet u mogelijk de volgende instructie toevoegen aan uw task.json bestand:

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

Als de waarde restricted is opgegeven voor mode, kunt u alleen de volgende opdrachten als taak uitvoeren:

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

Met de settableVariables beperkingen kunt u een acceptatielijst met variabelen doorgeven, die worden ingesteld door setvariable of prependpath opdrachten. Het maakt ook eenvoudige reguliere expressies mogelijk. Als uw acceptatielijst bijvoorbeeld is: ['abc', 'test*'], zou het instellen van abc, test of test1 als variabelen met een waarde of het vooraf plaatsen ervan aan het pad slagen, maar als u probeert een proxyvariabele in te stellen, wordt er een waarschuwing weergegeven. Lege lijst betekent dat er geen variabelen worden gewijzigd per taak.

Als de settableVariables of commands sleutel wordt weggelaten, wordt de relevante beperking niet toegepast.

De beperkingsfunctie is beschikbaar via agentversie 2.182.1.

V: Hoe wordt het annuleringssignaal door een taak afgehandeld?

De pijplijnagent verzendt SIGINT en SIGTERM signalen naar het relevante onderliggende proces. Er zijn geen expliciete middelen in de taakbibliotheek om te verwerken. Zie Annulering van agenttaken voor meer informatie.

V: Hoe kan ik de taak verwijderen uit de projectverzameling?

Het automatisch verwijderen van taken wordt niet ondersteund. Automatisch verwijderen is niet veilig en onderbreekt bestaande pijplijnen die al dergelijke taken gebruiken. Maar u kunt taken markeren als verouderd. U doet dit door de taakversie bij te werken en de taak als verouderd te markeren.

V: Hoe kan ik mijn aangepaste taak upgraden naar het nieuwste knooppunt?

U wordt aangeraden een upgrade uit te voeren naar de nieuwste Versie van Node. Zie voor voorbeeldinformatie Het upgraden van taken naar Node 20.

Microsoft-gehoste agents en verschillende versies van Azure DevOps Server hebben verschillende levenscycli, wat leidt tot verschillende runnerversies van Node die worden geïnstalleerd, afhankelijk van waar een taak wordt uitgevoerd. Om compatibiliteit tussen agents met verschillende runnerversies van Node te garanderen, kan het task.json bestand meerdere uitvoeringssecties bevatten. In het volgende voorbeeld gebruiken Azure Pipeline-agents met de Node 20-runner deze standaard, terwijl agents zonder deze terugvallen op de implementatie van Node 10.

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

Uw taken up te graden:

  • Test uw taken op de verschillende Node runner-versies om ervoor te zorgen dat uw code werkt zoals verwacht.

  • In de uitvoeringssectie van uw taak, werk bij van Node of Node10 naar Node16 of Node20.

  • Als u oudere serverversies wilt ondersteunen, moet u het Node/Node10 doel verlaten. Oudere Versies van Azure DevOps Server bevatten mogelijk niet de nieuwste versie van Node runner.

  • U kunt ervoor kiezen om het toegangspunt dat is gedefinieerd in het doel te delen of doelen te laten optimaliseren voor de knooppuntversie die wordt gebruikt.

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

Belangrijk

Als u geen ondersteuning voor de Node 20-runner toevoegt aan uw aangepaste taken, zullen ze mislukken op agents die zijn geïnstalleerd vanuit de releasefeed pipelines-agent-*.

Verwante inhoud