Hinzufügen einer benutzerdefinierten Pipelines-Aufgabenerweiterung

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019 | TFS 2018

Erfahren Sie, wie Sie Erweiterungen in Ihrer Organisation für benutzerdefinierte Build- oder Releaseaufgaben in Azure DevOps installieren.

Weitere Informationen zum neuen plattformübergreifenden Build-/Releasesystem finden Sie unter Was ist Azure Pipelines?.

Hinweis

In diesem Artikel werden Agentaufgaben in agentbasierten Erweiterungen behandelt. Informationen zu Servertasks/serverbasierten Erweiterungen finden Sie in der GitHub-Dokumentation zu Servertasks.

Voraussetzungen

Zum Erstellen von Erweiterungen für Azure DevOps benötigen Sie die folgenden Software und Tools.

  • Eine Organisation in Azure DevOps. Weitere Informationen finden Sie unter Erstellen einer Organisation.

  • Ein Texteditor Für viele der Tutorials verwenden wir Visual Studio Code, das IntelliSense- und Debugunterstützung bietet. Wechseln Sie zu code.visualstudio.com , um die neueste Version herunterzuladen.

  • Die neueste Version von Node.js.

  • TypeScript Compiler 2.2.0 oder höher, obwohl wir Version 4.0.2 oder höher empfehlen. Wechseln Sie zu npmjs.com , um den Compiler herunterzuladen.

  • Plattformübergreifende CLI für Azure DevOps zum Packen Ihrer Erweiterungen. Sie können tfx-cli mithilfe npmvon installieren, einer Komponente von Node.js, indem Sie ausführen npm i -g tfx-cli.

  • Ein home Verzeichnis für Ihr Projekt. Das home Verzeichnis einer Build- oder Releasetaskerweiterung sollte wie im folgenden Beispiel aussehen, nachdem Sie die Schritte in diesem Tutorial ausgeführt haben:

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

Wichtig

Der Entwicklungscomputer muss die neueste Version von Node ausführen, um sicherzustellen, dass der geschriebene Code mit der Produktionsumgebung auf dem Agent und der neuesten Nicht-Vorschauversion von azure-pipelines-task-lib kompatibel ist.

1. Erstellen einer benutzerdefinierten Aufgabe

Machen Sie jeden Teil von 1. Erstellen Sie eine benutzerdefinierte Aufgabe innerhalb des Ordners buildandreleasetask .

Hinweis

Dieses Beispiel für die exemplarische Vorgehensweise wird unter Windows mit PowerShell ausgeführt. Wir haben es für alle Plattformen generisch gemacht, aber die Syntax zum Abrufen von Umgebungsvariablen ist anders. Wenn Sie einen Mac oder Linux verwenden, ersetzen Sie alle Instanzen von $env:<var>=<val> durch export <var>=<val>.

Erstellen eines Aufgabengerüsts

  1. Erstellen Sie die Ordnerstruktur für den Task, und installieren Sie die erforderlichen Bibliotheken und Abhängigkeiten.

  2. Führen Sie in Ihrem buildandreleasetask Ordner den folgenden Befehl aus.

    npm init --yes
    

    npm init erstellt die package.json Datei. Wir haben den --yes Parameter hinzugefügt, um alle Standardoptionen npm init zu akzeptieren.

    Tipp

    Der Agent installiert die erforderlichen Module nicht automatisch, da er erwartet, dass Ihr Aufgabenordner die Knotenmodule enthält. Um dies zu verringern, kopieren Sie in node_modulesbuildandreleasetask. Wenn Ihre Aufgabe größer wird, ist es einfach, den Größengrenzwert (50 MB) einer VSIX-Datei zu überschreiten. Bevor Sie den Knotenordner kopieren, sollten Sie oder npm prune --productionausführen npm install --production oder ein Skript schreiben, um alles zu erstellen und zu packen.

  3. Fügen Sie Ihrer Bibliothek hinzu azure-pipelines-task-lib .

    npm install azure-pipelines-task-lib --save
    
  4. Stellen Sie sicher, dass TypeScript-Eingaben für externe Abhängigkeiten installiert sind.

    npm install @types/node --save-dev
    npm install @types/q --save-dev
    
  5. Erstellen Sie eine .gitignore Datei, und fügen Sie ihr node_modules hinzu. Ihr Buildprozess sollte eine npm install und eine typings install ausführen, damit node_modules jedes Mal erstellt werden und nicht eingecheckt werden müssen.

    echo node_modules > .gitignore
    
  6. Installieren Sie Mocha als Entwicklungsabhängigkeit.

    npm install mocha --save-dev -g
    npm install sync-request --save-dev
    npm install @types/mocha --save-dev
    
  7. Wählen Sie TypeScript Version 2.3.4 oder 4.0.2 aus.

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

    Hinweis

    Damit der tsc Befehl verfügbar ist, stellen Sie sicher, dass TypeScript global mit npm in Ihrer Entwicklungsumgebung installiert ist. Wenn Sie diesen Schritt überspringen, wird Die TypeScript-Version 2.3.4 standardmäßig verwendet, und Sie müssen das Paket weiterhin global installieren, damit der tsc Befehl verfügbar ist.

  8. Erstellen sie tsconfig.json Compileroptionen. Diese Datei stellt sicher, dass Ihre TypeScript-Dateien in JavaScript-Dateien kompiliert werden.

    tsc --init --target es6
    

    Um sicherzustellen, dass der ES6-Standard (anstelle von ES5) verwendet wird, haben wir den --target es6 -Parameter hinzugefügt.

Erstellen einer benutzerdefinierten Aufgabe

Nachdem das Gerüst nun fertig ist, können wir unsere benutzerdefinierte Aufgabe erstellen.

  1. Erstellen Sie eine task.json Datei im buildandreleasetask Ordner. Die task.json Datei beschreibt den Build-/Releasetask und verwendet das Build-/Releasesystem, um dem Benutzer Konfigurationsoptionen zu rendern und zu wissen, welche Skripts zur Build-/Releasezeit ausgeführt werden sollen.

  2. Kopieren Sie den folgenden Code, und ersetzen Sie durch die {{placeholders}} Informationen Ihrer Aufgabe. Der wichtigste Platzhalter ist der taskguid, und er muss eindeutig sein.

    {
     "$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": {
         "Node": {
             "target": "index.js"
         }
     }
     }
    

task.json-Komponenten

Sehen Sie sich die folgenden Beschreibungen einiger Komponenten der Datei an task.json .

Eigenschaft BESCHREIBUNG
id Eine eindeutige GUID für Ihre Aufgabe.
name Name ohne Leerzeichen.
friendlyName Beschreibender Name (zulässige Leerzeichen).
description Detaillierte Beschreibung der Aufgabenausführung.
author Kurze Zeichenfolge, die die Entität beschreibt, die den Build- oder Releasetask entwickelt, z. B. "Microsoft Corporation".
instanceNameFormat So wird die Aufgabe in der Build-/Releaseschrittliste angezeigt. Sie können Variablenwerte mithilfe von $(variablename) verwenden.
groups Beschreibt Gruppen, nach denen Aufgabeneigenschaften in der Benutzeroberfläche logisch gruppiert werden können.
inputs Eingaben, die verwendet werden sollen, wenn Der Build- oder Releasetask ausgeführt wird. Diese Aufgabe erwartet eine Eingabe mit dem Namen samplestring.
execution Ausführungsoptionen für diese Aufgabe, einschließlich Skripts.
restrictions Einschränkungen, die auf die Aufgabe angewendet werden, über gitHub Codespaces-Befehlstask können aufgerufen werden, und variablen Task kann festgelegt werden. Es wird empfohlen, den Einschränkungsmodus für neue Aufgaben anzugeben.

Hinweis

Einen ausführlicheren Einblick in die Datei task.json oder informationen zum Bündeln mehrerer Versionen in Ihrer Erweiterung finden Sie in der Build/Release-Aufgabenreferenz.

  1. Erstellen Sie eine index.ts Datei, indem Sie den folgenden Code als Verweis verwenden. Dieser Code wird ausgeführt, wenn der Task aufgerufen wird.
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) {
        tl.setResult(tl.TaskResult.Failed, err.message);
    }
}

run();
  1. Geben Sie "tsc" aus dem buildandreleasetask Ordner ein, um eine index.js Datei aus index.tszu kompilieren.

Ausführen des Tasks

  1. Führen Sie die Aufgabe mit node index.js aus PowerShell aus.

    Im folgenden Beispiel schlägt der Task fehl, weil keine Eingaben angegeben wurden (samplestring ist eine erforderliche Eingabe).

     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 Korrektur können wir die samplestring Eingabe festlegen und die Aufgabe erneut ausführen.

     $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
    

Dieses Mal war die Aufgabe erfolgreich, weil samplestring angegeben wurde und ordnungsgemäß "Hallo Mensch" ausgegeben wurde!

2. Komponententest Ihrer Aufgabenskripts

Wir komponententesten, um das Aufgabenskript und nicht die externen Tools, die es aufruft, schnell zu testen. Wir möchten alle Aspekte von Erfolgs- und Fehlerpfaden testen.

  1. Installieren Sie Testtools. Wir verwenden Mocha als Testtreiber in dieser exemplarische Vorgehensweise.

    npm install mocha --save-dev -g
    npm install sync-request --save-dev
    npm install @types/mocha --save-dev
    
  2. Erstellen Sie einen tests Ordner, der eine _suite.ts Datei mit folgendem Inhalt enthält:

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

    Tipp

    Ihr Testordner sollte sich im Ordner buildandreleasetask befinden. Wenn Sie einen Synchronisierungsanforderungsfehler erhalten, können Sie ihn umgehen, indem Sie dem Ordner buildandreleasetask mit dem Befehl npm i --save-dev sync-requestsync-request hinzufügen.

  3. Erstellen Sie eine success.ts Datei in Ihrem Testverzeichnis mit dem folgenden Inhalt. Diese Dateierstellung simuliert die Ausführung der Aufgabe und simuliert alle Aufrufe von externen Methoden.

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

    Der Erfolgstest überprüft, ob er mit den entsprechenden Eingaben ohne Fehler oder Warnungen erfolgreich ist, und gibt die richtige Ausgabe zurück.

  4. Fügen Sie der _suite.ts Datei den folgenden Beispielerfolgstest hinzu, um den Aufgabenmodell-Runner auszuführen.

    it('should succeed with simple inputs', function(done: Mocha.Done) {
        this.timeout(1000);
    
        let tp = path.join(__dirname, 'success.js');
        let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp);
    
        tr.run();
        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();
    });
    
  5. Erstellen Sie eine failure.ts Datei in Ihrem Testverzeichnis als Aufgabenmodell-Runner mit dem folgenden Inhalt:

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

    Der Fehlertest überprüft, dass das Tool bei fehlerhafter oder unvollständiger Eingabe auf die erwartete Weise mit hilfreicher Ausgabe fehlschlägt.

  6. Fügen Sie der _suite.ts Datei den folgenden Code hinzu, um den Task-Mock-Runner auszuführen.

    it('it should fail if tool returns 1', function(done: Mocha.Done) {
        this.timeout(1000);
    
        let tp = path.join(__dirname, 'failure.js');
        let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp);
    
        tr.run();
        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. Führen Sie die Tests aus.

    tsc
    mocha tests/_suite.js
    

    Beide Tests sollten bestanden werden. Wenn Sie die Tests mit ausführlicheren Ausgaben ausführen möchten (was in der Buildkonsole angezeigt wird), legen Sie die Umgebungsvariable fest: TASK_TEST_TRACE=1.

    $env:TASK_TEST_TRACE=1
    

3. Erstellen der Erweiterungsmanifestdatei

Das Erweiterungsmanifest enthält alle Informationen zu Ihrer Erweiterung. Es enthält Links zu Ihren Dateien, einschließlich Ihrer Aufgabenordner und Bilderordner. Stellen Sie sicher, dass Sie einen Imageordner mit extension-icon.png erstellt haben. Das folgende Beispiel ist ein Erweiterungsmanifest, das den Build- oder Releasetask enthält.

  1. Kopieren Sie den folgenden JSON-Code, und speichern Sie ihn als Ihre vss-extension.json Datei in Ihrem home Verzeichnis. Erstellen Sie diese Datei nicht im Ordner 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"
            }
        }
    ]
}

Hinweis

Ändern Sie den Herausgeber in Ihren Verlegernamen. Weitere Informationen finden Sie unter Erstellen eines Herausgebers.

Beiträge

Eigenschaft BESCHREIBUNG
id Bezeichner des Beitrags. Muss innerhalb der Erweiterung eindeutig sein. Muss nicht mit dem Namen des Build- oder Releasetasks übereinstimmen. In der Regel befindet sich der Name des Build- oder Releasetasks in der ID des Beitrags.
type Art des Beitrags. Sollte ms.vss-distributed-task.task sein.
targets Beiträge "gezielt" durch diesen Beitrag. Sollte ms.vss-distributed-task.tasks sein.
properties.name Der Name der Aufgabe. Dieser Name muss mit dem Ordnernamen des entsprechenden eigenständigen Build- oder Releasepipelinetasks übereinstimmen.

Dateien

Eigenschaft BESCHREIBUNG
path Pfad der Datei oder des Ordners relativ zum home Verzeichnis.

Hinweis

Weitere Informationen zur Erweiterungsmanifestdatei, z. B. zu ihren Eigenschaften und ihren Aufgaben, finden Sie im Verweis auf das Erweiterungsmanifest.

4. Packen Ihrer Erweiterung

Nachdem Sie Ihre Erweiterung geschrieben haben, besteht der nächste Schritt, um sie in den Visual Studio Marketplace zu bringen, darin, alle Ihre Dateien zusammenzupacken. Alle Erweiterungen werden als VSIX 2.0-kompatible VSIX-Dateien gepackt. Microsoft stellt eine plattformübergreifende Befehlszeilenschnittstelle (CLI) bereit, um Ihre Erweiterung zu packen.

  1. Wenn Sie über die tfx-cli verfügen, wechseln Sie zum Stammverzeichnis Ihrer Erweiterung, und führen Sie den folgenden Befehl aus:

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

Hinweis

Die Version einer Erweiterung oder Integration muss bei jedem Update erhöht werden. Wenn Sie eine vorhandene Erweiterung aktualisieren, aktualisieren Sie entweder die Version im Manifest, oder übergeben Sie den Befehlszeilenschalter --rev-version . Dadurch wird die Patchversionsnummer Ihrer Erweiterung erhöht und die neue Version in Ihrem Manifest gespeichert. Sie müssen sowohl die Aufgabenversion als auch die Erweiterungsversion überprüfen, damit ein Update durchgeführt wird. tfx extension create --manifest-globs vss-extension.json --rev-version aktualisiert nur die Erweiterungsversion und nicht die Aufgabenversion. Weitere Informationen finden Sie unter Buildtask in GitHub.

Nachdem Sie Ihre gepackte Erweiterung in einer VSIX-Datei haben, können Sie Ihre Erweiterung im Marketplace veröffentlichen.

5. Veröffentlichen Ihrer Erweiterung

Um Ihre Erweiterung zu veröffentlichen, erstellen Sie zuerst Ihren Herausgeber, laden dann Ihre Erweiterung hoch und geben sie schließlich weiter.

Erstellen Ihres Herausgebers

Alle Erweiterungen, einschließlich Erweiterungen von Microsoft, werden als von einem Herausgeber bereitgestellt. Wenn Sie noch kein Mitglied eines vorhandenen Herausgebers sind, erstellen Sie einen Herausgeber.

  1. Melden Sie sich beim Visual Studio Marketplace-Veröffentlichungsportal an.
  2. Wenn Sie noch kein Mitglied eines vorhandenen Herausgebers sind, werden Sie aufgefordert, einen Herausgeber zu erstellen. Wenn Sie nicht zum Erstellen eines Herausgebers aufgefordert werden, scrollen Sie nach unten zum Unteren Rand der Seite, und wählen Sie unter Verwandte Websitesdie Option Erweiterungen veröffentlichen aus.
    • Geben Sie einen Bezeichner für Ihren Herausgeber an, z. B.: mycompany-myteam.
      • Dieser Bezeichner wird als Wert für das Attribut in der publisher Manifestdatei Ihrer Erweiterungen verwendet.
    • Geben Sie einen Anzeigenamen für Ihren Herausgeber an, z. B.: My Team.
  3. Überprüfen Sie die Marketplace-Herausgebervereinbarung, und wählen Sie Erstellen aus.

Ihr Herausgeber ist definiert. In einer zukünftigen Version können Sie Berechtigungen zum Anzeigen und Verwalten der Erweiterungen Ihres Herausgebers erteilen. Es ist einfacher und sicherer, Erweiterungen unter einem gemeinsamen Herausgeber zu veröffentlichen, ohne dass benutzerübergreifend eine Reihe von Anmeldeinformationen freigegeben werden müssen.

Hochladen Ihrer Erweiterung

  1. Suchen Sie die Schaltfläche Neue Erweiterung hochladen , wechseln Sie zu Ihrer gepackten VSIX-Datei, und wählen Sie Hochladen aus.

    Sie können Ihre Erweiterung auch über die Befehlszeile hochladen, indem Sie den tfx extension publish Befehl verwenden, anstatt Ihre Erweiterung in einem Schritt zu packen tfx extension create und zu veröffentlichen. Optional können --share-with Sie ihre Erweiterung nach der Veröffentlichung für ein oder mehrere Konten freigeben. Sie benötigen auch ein persönliches Zugriffstoken. Weitere Informationen finden Sie unter Erstellen eines persönlichen Zugriffstokens.

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

Teilen Ihrer Erweiterung

Nachdem Sie Ihre Erweiterung hochgeladen haben, befindet sie sich im Marketplace, aber niemand kann sie sehen. Teilen Sie es für Ihre Organisation, damit Sie es installieren und testen können.

  1. Klicken Sie mit der rechten Maustaste auf Ihre Erweiterung, wählen Sie Freigeben aus, und geben Sie Ihre Organisationsinformationen ein. Sie können es auch für andere Konten freigeben, die Zugriff auf Ihre Erweiterung haben möchten.

Wichtig

Herausgeber müssen überprüft werden, ob sie Erweiterungen öffentlich freigeben. Weitere Informationen finden Sie unter Paket/Veröffentlichen/Installieren.

Nachdem Ihre Erweiterung nun im Marketplace freigegeben ist, muss jeder, der sie verwenden möchte, sie installieren.

6. Erstellen einer Build- und Releasepipeline zum Veröffentlichen der Erweiterung im Marketplace

Erstellen Sie eine Build- und Releasepipeline in Azure DevOps, um die benutzerdefinierte Aufgabe im Marketplace zu verwalten.

Voraussetzungen

Erstellen Sie eine Variablengruppe der Pipelinebibliothek, die die von der Pipeline verwendeten Variablen enthält. Weitere Informationen zum Erstellen einer Variablengruppe finden Sie unter Hinzufügen und Verwenden von Variablengruppen. Beachten Sie, dass Sie variablen Gruppen über die Registerkarte Azure DevOps-Bibliothek oder über die CLI erstellen können. Nachdem eine Variablengruppe erstellt wurde, verwenden Sie alle Variablen innerhalb dieser Gruppe in Ihrer Pipeline. Weitere Informationen finden Sie unter Verwenden einer Variablengruppe.

Deklarieren Sie die folgenden Variablen in der Variablengruppe.

  • publisherId: ID Ihres Marketplace-Herausgebers
  • extensionId: ID Ihrer Erweiterung, wie in der Datei vss-extension.json deklariert
  • extensionName: Name der Erweiterung, wie in der Datei vss-extension.json deklariert
  • artifactName: Name des Artefakts, das für die VSIX-Datei erstellt wird

Erstellen Sie eine neue Visual Studio Marketplace-Dienstverbindung, und gewähren Sie Zugriffsberechtigungen für alle Pipelines. Weitere Informationen zum Erstellen einer Dienstverbindung finden Sie unter Dienstverbindungen.

Screenshot des neuen Dienstverbindungsbereichs

Screenshot des Bereichs

Verwenden Sie das folgende Beispiel, um eine neue Pipeline mit YAML zu erstellen. Erfahren Sie mehr darüber, wie Sie Ihre erste Pipeline und ihr YAML-Schema erstellen.

trigger: 
- master

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'

Weitere Hilfe zu Triggern, z. B. CI- und PR-Triggern, finden Sie unter Angeben von Ereignissen, die Pipelines auslösen.

Hinweis

Jeder Auftrag verwendet einen neuen Benutzer-Agent und erfordert die Installation von Abhängigkeiten.

Pipelinestufen

In diesem Abschnitt erfahren Sie, wie die Pipelinephasen funktionieren.

Phase: Ausführen und Veröffentlichen von Komponententests

In dieser Phase werden Komponententests ausgeführt und Testergebnisse in Azure DevOps veröffentlicht.

Um Komponententests auszuführen, fügen Sie der Datei package.json ein benutzerdefiniertes Skript hinzu. Beispiel:

"scripts": {
    "testScript": "mocha ./TestFile --reporter xunit --reporter-option output=ResultsFile.xml"
},
  1. Fügen Sie "Use Node CLI for Azure DevOps (tfx-cli)" hinzu, um die tfx-cli auf Ihrem Build-Agent zu installieren.

  2. Fügen Sie den Task "npm" mit dem Befehl "install" hinzu, und richten Sie den Ordner mit der Datei package.json an.

  3. Fügen Sie die Aufgabe "Bash" hinzu, um typeScript in JavaScript zu kompilieren.

  4. Fügen Sie die Aufgabe "npm" mit dem Befehl "custom" hinzu, richten Sie den Ordner an, der die Komponententests enthält, und geben Sie als Befehl ein testScript . Verwenden Sie die folgenden Eingaben:

    • Befehl: custom
    • Arbeitsordner, der "package.json" enthält: /TestsDirectory
    • Befehl und Argumente: testScript
  5. Fügen Sie den Task "Testergebnisse veröffentlichen" hinzu. Wenn Sie den Mocha XUnit-Reporter verwenden, stellen Sie sicher, dass das Ergebnisformat "JUnit" und nicht "XUnit" ist. Legen Sie den Suchordner auf das Stammverzeichnis fest. Verwenden Sie die folgenden Eingaben:

    • Testergebnisformat: JUnit
    • Testergebnisdateien: **/ResultsFile.xml
    • Suchordner: $(System.DefaultWorkingDirectory)

Nachdem die Testergebnisse veröffentlicht wurden, sollte die Ausgabe auf der Registerkarte Tests wie im folgenden Beispiel aussehen.

Screenshot des Beispiels für das Testergebnis.

Phase: Packen der Erweiterung und Veröffentlichen von Buildartefakten

  1. Fügen Sie "Use Node CLI for Azure DevOps (tfx-cli)" hinzu, um die tfx-cli auf Ihrem Build-Agent zu installieren.

  2. Fügen Sie den Task "npm" mit dem Befehl "install" hinzu, und richten Sie den Ordner mit der Datei package.json an.

  3. Fügen Sie die Aufgabe "Bash" hinzu, um typeScript in JavaScript zu kompilieren.

  4. Fügen Sie den Task "Abfrageerweiterungsversion" hinzu, um die vorhandene Erweiterungsversion abzufragen. Verwenden Sie die folgenden Eingaben:

    • Herstellen einer Verbindung mit: Visual Studio Marketplace
    • Visual Studio Marketplace (Dienstverbindung): Dienstverbindung
    • Herausgeber-ID: ID Ihres Visual Studio Marketplace-Herausgebers
    • Erweiterungs-ID: ID Ihrer Erweiterung in der Datei vss-extension.json
    • Version erhöhen: Patch
    • Ausgabevariable: Task.Extension.Version
  5. Fügen Sie den Task "Paketerweiterung" hinzu, um die Erweiterungen basierend auf Manifest-JSON zu packen. Verwenden Sie die folgenden Eingaben:

    • Stammmanifestordner: Zeigt auf das Stammverzeichnis, das eine Manifestdatei enthält. Beispielsweise ist $(System.DefaultWorkingDirectory) das Stammverzeichnis.
    • Manifestdateien: vss-extension.json
    • Herausgeber-ID: ID Ihres Visual Studio Marketplace-Herausgebers
    • Erweiterungs-ID: ID Ihrer Erweiterung in der Datei vss-extension.json
    • Erweiterungsname: Name ihrer Erweiterung in der Datei vss-extension.json
    • Erweiterungsversion: $(Task.Extension.Version)
    • Überschreiben der Aufgabenversion: aktiviert (true)
    • Überschreibungstyp: Nur Patch ersetzen (1.0.r)
    • Sichtbarkeit der Erweiterung: Wenn sich die Erweiterung noch in der Entwicklung befindet, legen Sie den Wert auf privat fest. Um die Erweiterung für die Öffentlichkeit freizugeben, legen Sie den Wert auf public fest.
  6. Fügen Sie die Aufgabe "Dateien kopieren" hinzu, um veröffentlichte Dateien zu kopieren. Verwenden Sie die folgenden Eingaben:

    • Inhalt: Alle Dateien, die zum Veröffentlichen als Artefakt kopiert werden sollen
    • Zielordner: Der Ordner, in den die Dateien kopiert werden
      • Beispiel: $(Build.ArtifactStagingDirectory)
  7. Fügen Sie "Buildartefakte veröffentlichen" hinzu, um die Artefakte zur Verwendung in anderen Aufträgen oder Pipelines zu veröffentlichen. Verwenden Sie die folgenden Eingaben:

    • Pfad zur Veröffentlichung: Der Pfad zu dem Ordner, der die dateien enthält, die veröffentlicht werden
      • Beispiel: $(Build.ArtifactStagingDirectory)
    • Artefaktname: Der Name, der dem Artefakt zugewiesen wird
    • Veröffentlichungsort für Artefakte: Wählen Sie "Azure Pipelines" aus, um das Artefakt in zukünftigen Aufträgen zu verwenden.

Phase: Herunterladen von Buildartefakten und Veröffentlichen der Erweiterung

  1. Fügen Sie "Use Node CLI for Azure DevOps (tfx-cli)" hinzu, um die tfx-cli auf Ihrem Build-Agent zu installieren.

  2. Fügen Sie die Aufgabe "Buildartefakte herunterladen" hinzu, um die Artefakte auf einen neuen Auftrag herunterzuladen. Verwenden Sie die folgenden Eingaben:

    • Herunterladen von Artefakten erzeugt von: Wenn Sie das Artefakt für einen neuen Auftrag aus derselben Pipeline herunterladen, wählen Sie "Aktueller Build" aus. Wenn Sie eine neue Pipeline herunterladen, wählen Sie "Spezifischer Build" aus.
    • Downloadtyp: Wählen Sie "Spezifisches Artefakt" aus, um alle veröffentlichten Dateien herunterzuladen.
    • Artefaktname: Der Name des veröffentlichten Artefakts.
    • Zielverzeichnis: Der Ordner, in den die Dateien heruntergeladen werden sollen.
  3. Die letzte Aufgabe, die Sie benötigen, ist die Aufgabe "Erweiterung veröffentlichen". Verwenden Sie die folgenden Eingaben:

    • Herstellen einer Verbindung mit: Visual Studio Marketplace
    • Visual Studio Marketplace-Verbindung: ServiceConnection
    • Eingabedateityp: VSIX-Datei
    • VSIX-Datei: /Publisher.*.vsix
    • Herausgeber-ID: ID Ihres Visual Studio Marketplace-Herausgebers
    • Erweiterungs-ID: ID Ihrer Erweiterung in der Datei vss-extension.json
    • Erweiterungsname: Name ihrer Erweiterung in der Datei vss-extension.json
    • Erweiterungssichtbarkeit: Entweder privat oder öffentlich

Optional: Installieren und Testen der Erweiterung

Installieren Sie eine Erweiterung, die für Sie freigegeben wird, in nur wenigen Schritten:

  1. Navigieren Sie in der Systemsteuerung Ihrer Organisation (https://dev.azure.com/{organization}/_admin) zur Seite Projektsammlungsverwaltung.
  2. Suchen Sie auf der Registerkarte Erweiterungen ihre Erweiterung in der Gruppe "Für mich freigegebene Erweiterungen", und wählen Sie den Erweiterungslink aus.
  3. Installieren Sie die Erweiterung.

Wenn die Registerkarte Erweiterungen nicht angezeigt wird, stellen Sie sicher, dass Sie sich in der Systemsteuerung (der Verwaltungsseite auf Projektsammlungsebene) https://dev.azure.com/{organization}/_adminund nicht auf der Verwaltungsseite für ein Projekt befinden.

Wenn die Registerkarte Erweiterungen nicht angezeigt wird, sind Erweiterungen für Ihre Organisation nicht aktiviert. Sie können frühzeitig auf das Erweiterungsfeature zugreifen, indem Sie dem Visual Studio-Partnerprogramm beitreten.

Zum Packen und Veröffentlichen von Azure DevOps-Erweiterungen im Visual Studio Marketplace können Sie Azure DevOps-Erweiterungstasks herunterladen.

Häufig gestellte Fragen

Siehe die folgenden häufig gestellten Fragen (FAQs) zum Hinzufügen von benutzerdefinierten Build- oder Releasetasks in Erweiterungen für Azure DevOps

F: Wie kann ich die Verwendung von GitHub Codespaces-Befehlen für die Aufgabe einschränken?

Sie können die Verwendung von GitHub Codespaces-Befehlen und Variablen einschränken, die nach Aufgabe festgelegt werden können. Diese Aktion kann nützlich sein, um den uneingeschränkten Zugriff auf Variablen/vso-Befehle für benutzerdefinierte Skripts zu verhindern, die von der Aufgabe ausgeführt werden. Es wird empfohlen, sie für neue Aufgaben einzurichten. Zum Anwenden müssen Sie der Datei task.json möglicherweise die folgende Anweisung hinzufügen:

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

Wenn restricted wert für mode angegeben ist, können Sie nur die folgenden Befehle von der Aufgabe ausführen:

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

settableVariables Mit Einschränkungen können Sie eine Zulassungsliste von Variablen übergeben, die durch setvariable Befehle oder prependpath festgelegt werden können. Außerdem werden grundlegende reguläre Ausdrücke ermöglicht. Wenn Ihre Zulassungsliste z. B. folgendes lautet: ['abc', 'test*'], das Festlegen abcvon , testoder test1 als Variablen mit einem beliebigen Wert oder voranstellend für den Pfad wäre erfolgreich, aber wenn Sie versuchen, einen Variablenproxy festzulegen, würde eine Warnung angezeigt. Leere Liste bedeutet, dass keine Variablen nach Aufgabe geändert werden können.

Wenn entweder der settableVariables Schlüssel oder commands ausgelassen wird, wird keine relevante Einschränkung angewendet.

Das Einschränkungsfeature ist ab der Agentversion 2.182.1 verfügbar.

F: Wie wird das Abbruchsignal von einer Aufgabe behandelt?

Der Pipeline-Agent sendet SIGINT und sendet Signale SIGTERM an den relevanten untergeordneten Prozess. Es gibt keine expliziten Mittel in der Aufgabenbibliothek , die verarbeitet werden sollen. Weitere Informationen finden Sie unter Abbruch von Agentaufträgen.

F: Wie kann ich den Task aus der Projektsammlung entfernen?

Das automatische Löschen von Aufgaben wird nicht unterstützt. Das automatische Löschen ist nicht sicher und unterbricht vorhandene Pipelines, die solche Aufgaben bereits verwenden. Sie können Aufgaben jedoch als veraltet markieren. Heben Sie hierzu die Aufgabenversion auf, und markieren Sie den Vorgang als veraltet.

F: Wie kann ich ein Upgrade einer Aufgabe auf den neuesten Knoten durchführen?

Es wird empfohlen, ein Upgrade auf die neueste Node-Version durchzuführen. Beispielinformationen finden Sie unter Aktualisieren von Aufgaben auf Knoten 10.