Exemplarische Vorgehensweise: Veröffentlichen einer Visual Studio-Erweiterung über die Befehlszeile

In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie mithilfe der Befehlszeile eine Visual Studio Erweiterung auf dem Visual Studio Marketplace veröffentlichen. Wenn Sie Ihre Erweiterung zum Marketplace hinzufügen, können Entwickler das Dialogfeld "Erweiterungen und Updates " verwenden, um dort nach neuen und aktualisierten Erweiterungen zu suchen.

VsixPublisher.exe ist das Befehlszeilentool zum Veröffentlichen von Visual-Studio-Erweiterungen auf dem Marketplace. Auf sie kann über ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\VsixPublisher.exe zugegriffen werden. Befehle, die für dieses Tool verfügbar sind: publish, deletePublisher, deleteExtension, login, logout.

Commands

Veröffentlichen

Veröffentlicht eine Erweiterung im Marketplace. Die Erweiterung kann ein vsix, eine exe/msi-Datei oder ein Link sein. Wenn die Erweiterung bereits in derselben Version vorhanden ist, überschreibt die neue Erweiterung die vorhandene. Wenn die Erweiterung noch nicht vorhanden ist, wird eine neue Erweiterung erstellt.

VsixPublisher.exe publish -payload "{path to vsix}" -publishManifest "{path to vs-publish.json}" -ignoreWarnings "VSIXValidatorWarning01,VSIXValidatorWarning02" -personalAccessToken "{Your PAT}"

Um aus einem GitHub Actions Workflow zu veröffentlichen, der für die vertrauenswürdige Veröffentlichung konfiguriert ist, verwenden Sie -oidc anstelle von-personalAccessToken:

VsixPublisher.exe publish -payload "{path to vsix}" -publishManifest "{path to vs-publish.json}" -oidc

deletePublisher

Löscht einen Publisher auf dem Marketplace.

VsixPublisher.exe deletePublisher -publisherName "{Publisher Name}" -personalAccessToken "{Personal Access Token}"

deleteExtension

Löscht eine Erweiterung aus dem Marketplace.

VsixPublisher.exe deleteExtension -extensionName "{Extension Name}" -publisherName "{Publisher Name}"

login

Meldet einen Herausgeber am Computer an.

VsixPublisher.exe login -personalAccessToken "{Personal Access Token}" -publisherName "{Publisher Name}"

Abmelden

Meldet einen Publisher vom Gerät ab.

VsixPublisher.exe logout -publisherName "{Publisher Name}"

createPublisher

Veröffentlichen aus GitHub Actions mit vertrauenswürdigem Veröffentlichen

Mit vertrauenswürdiger Veröffentlichung kann ein GitHub Actions Workflow Ihre Visual Studio-Erweiterung veröffentlichen, ohne ein persönliches Zugriffstoken (Personal Access Token, PAT) zu speichern. Verwenden Sie das -oidc Flag mit dem publish Befehl, um sich mithilfe der OpenID Connect(OIDC)-Identität des Workflows zu authentifizieren.

VsixPublisher.exe fordert ein OIDC-Token von GitHub Actions mit der Zielgruppe marketplace.visualstudio.com an und tauscht es dann gegen ein kurzlebiges Marketplace-Sitzungstoken aus. Das Tool verwendet dieses Sitzungstoken, um die Erweiterung zu veröffentlichen.

Voraussetzungen für vertrauenswürdige Veröffentlichungen

Vor der Veröffentlichung mithilfe von -oidc:

• Verwenden Sie eine Version von VsixPublisher.exe, die die Option oidc unterstützt.
• Erstellen Sie einen Publisher im Visual Studio Marketplace, und konfigurieren Sie eine vertrauenswürdige Veröffentlichungsrichtlinie, die Ihr GitHub-Repository und Ihren Workflow autorisiert.
• Legen Sie die publisher Eigenschaft in Ihrem Veröffentlichungsmanifest auf den Marketplace-Herausgeberbezeichner fest, der dieser Richtlinie zugeordnet ist.
• Erteilen Sie dem Veröffentlichungsjob id-token: write die Berechtigung, damit er ein OIDC-Token von GitHub Actions anfordern kann.
• Stellen Sie die Erweiterungsnutzlast, das Veröffentlichungsmanifest, die Übersichtsdatei und alle anderen referenzierten Ressourcen auf dem Windows Runner zur Verfügung.

Workflow konfigurieren

Fügen Sie die folgenden Berechtigungen zum GitHub Actions Auftrag hinzu, der Ihre Erweiterung veröffentlicht:

permissions:
  contents: read
  id-token: write

Die Berechtigung id-token: write ermöglicht es dem Auftrag, ein OIDC-Token anzufordern. Dies allein autorisiert die Veröffentlichung auf dem Marketplace nicht; das Repository und der Workflow müssen auch mit der vertrauenswürdigen Veröffentlichungsrichtlinie des Herausgebers übereinstimmen.

Nachdem Ihr Workflow die Erweiterung erstellt oder die Buildartefakte heruntergeladen hat, fügen Sie einen Veröffentlichungsschritt wie folgt hinzu. Ersetzen Sie die Pfade für die ausführbare Datei, die Payload und das Manifest durch die Pfade, die von Ihrem Workflow verwendet werden. Die ausführbare Datei wird normalerweise unter <VSInstallDir>\VSSDK\VisualStudioIntegration\Tools\Bin\VsixPublisher.exeinstalliert.

- name: Publish extension to Visual Studio Marketplace
  shell: pwsh
  run: |
    & "C:\path\to\VsixPublisher.exe" publish `
      -payload ".\artifacts\TestPublish.vsix" `
      -publishManifest ".\publishManifest.json" `
      -oidc
    if ($LASTEXITCODE -ne 0) {
      exit $LASTEXITCODE
    }

Sie müssen -oidc nicht ausführen und bei Verwendung von VsixPublisher.exe login keinen PAT bereitstellen. Das Tool ruft das Token automatisch aus dem GitHub Actions Auftrag ab.

Fehlerbehebung für vertrauenswürdiges Veröffentlichen

publishManifest-Datei

Eine publishManifest-Datei wird vom Befehl publish verwendet. Es stellt alle Metadaten über die Erweiterung dar, die der Marketplace kennen muss. Wenn die hochgeladene Erweiterung von einer VSIX-Erweiterung stammt, darf die Eigenschaft „identity“ nur „internalName“ gesetzt haben. Dies liegt daran, dass die restlichen "Identity"-Eigenschaften aus der Vsixmanifest-Datei generiert werden können. Wenn es sich bei der Erweiterung um eine msi/exe- oder eine Linkerweiterung handelt, muss der Benutzer die erforderlichen Felder in der Eigenschaft "Identity" angeben. Der Rest des Manifests enthält Spezifische Informationen für den Marketplace (z. B. Kategorien, ob Q&A aktiviert ist usw.).

VSIX-Erweiterung publishManifest-Dateibeispiel:

{
    "$schema": "http://json.schemastore.org/vsix-publish",
    "categories": [ "build", "coding" ],  // The categories of the extension. Between 1 and 3 categories are required.
    "identity": {
        "internalName": "MyVsixExtension" // If not specified, we try to generate the name from the display name of the extension in the vsixmanifest file.
                                            // Required if the display name is not the actual name of the extension.
    },
    "overview": "overview.md",            // Path to the "readme" file that gets uploaded to the Marketplace. Required.
    "priceCategory": "free",              // Either "free", "trial", or "paid". Defaults to "free".
    "publisher": "MyPublisherName",       // The name of the publisher. Required.
    "private": false,                     // Specifies whether or not the extension should be public when uploaded. Defaults to false.
    "qna": true,                          // Specifies whether or not the extension should have a Q&A section. Defaults to true.
    "repo": "https://github.com/MyPublisherName/MyVsixExtension" // Not required.
}

MSI/EXE- oder LINK publishManifest-Dateibeispiel:

{
    "$schema": "http://json.schemastore.org/vsix-publish",
    "categories": [ "build", "coding" ],
    "identity": {
        "description": "My extension.", // The description of the extension. Required for non-vsix extensions.
        "displayName": "My Extension",  // The display name of the extension. Required for non-vsix extensions.
        "icon": "\\path\\to\\icon.ico", // The path to an icon file (can be relative to the json file location). Required for non-vsix extensions.
        "installTargets": [             // The installation targets for the extension. Required for non-vsix extensions.
            {
                "sku": "Microsoft.VisualStudio.Community",
                "version": "[10.0, 16.0)"
            }
        ],
        "internalName": "MyExtension",
        "language": "en-US",            // The default language id of the extension. Can be in the "1033" or "en-US" format. Required for non-vsix extensions.
        "tags": [ "tag1", "tag2" ],     // The tags for the extension. Not required.
        "version": "3.7.0",             // The version of the extension. Required for non-vsix extensions.
        "vsixId": "MyExtension",        // The vsix id of the extension. Not required but useful for showing updates to installed extensions.
    },
    "overview": "overview.md",
    "priceCategory": "free",
    "publisher": "MyPublisherName",
    "private": false,
    "qna": true,
    "repo": "https://github.com/MyPublisherName/MyVsixExtension"
}

Asset-Dateien

Asset-Dateien können zum Einbetten von Elementen wie Bildern in die Readme-Datei bereitgestellt werden. Wenn beispielsweise eine Erweiterung das folgende "Übersicht"-Markdown-Dokument aufweist:

TestExtension
...
This is test extension.
![Test logo](images/testlogo.png "Test logo")

Um „images/testlogo.png“ im vorangegangenen Beispiel aufzulösen, kann ein Benutzer in seinem Veröffentlichungs-Manifest „assetFiles“ wie folgt angeben:

{
    "assetFiles": [
        {
            "pathOnDisk": "\\path\\to\\logo.png",
            "targetPath": "images/logo.png"
        }
    ],
    // other required fields
}

Anleitung zur Veröffentlichung

Prerequisites

Um diese exemplarische Vorgehensweise zu befolgen, müssen Sie das Visual Studio SDK installieren. Weitere Informationen finden Sie unter Installieren des Visual Studio SDK.

Erstellen einer Visual Studio-Erweiterung

In diesem Fall verwenden wir eine standardmäßige VSPackage-Erweiterung, aber die gleichen Schritte gelten für jede Art von Erweiterung.

1. Erstellen Sie ein VSPackage in C# mit dem Namen "TestPublish", das über einen Menübefehl verfügt. Weitere Informationen finden Sie unter Creating your First Extension: Hallo Welt.

Verpacken Sie Ihre Erweiterung

1. Aktualisieren Sie die Datei „vsixmanifest“ mit den richtigen Informationen zu Produktname, Autor und Version.

   

2. Erstellen Sie Ihre Erweiterung im Releasemodus . Jetzt wird Ihre Erweiterung als VSIX im Ordner "\bin\Release" gepackt.

3. Sie können auf den VSIX doppelklicken, um die Installation zu überprüfen.

Testen der Erweiterung

Bevor Sie die Erweiterung verteilen, erstellen und testen Sie sie, um sicherzustellen, dass sie in der experimentellen Instanz von Visual Studio ordnungsgemäß installiert ist.

1. Starten Sie in Visual Studio das Debuggen. um eine experimentelle Instanz von Visual Studio zu öffnen.

2. Wechseln Sie in der experimentellen Instanz zum Menü "Extras ", und wählen Sie "Erweiterungen und Updates" aus. Die TestPublish-Erweiterung sollte im mittleren Bereich angezeigt und aktiviert sein.

3. Stellen Sie im Menü "Extras " sicher, dass der Befehl "Test" angezeigt wird.

Veröffentlichen Sie die Erweiterung über die Befehlszeile im Marketplace

1. Stellen Sie sicher, dass Sie die Release-Version Ihrer Erweiterung erstellt haben und dass sie aktuell ist.

2. Stellen Sie sicher, dass Sie publishmanifest.json und overview.md Dateien erstellt haben.

3. Öffnen Sie die Befehlszeile, und navigieren Sie zum Verzeichnis ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\.

4. Um eine neue Erweiterung zu veröffentlichen, wählen Sie die Authentifizierungsmethode für Ihre Umgebung aus.

   • Verwenden Sie Folgendes, um sich mit einem persönlichen Zugriffstoken (PAT) zu authentifizieren:

   VsixPublisher.exe publish -payload "{Path to vsix file}" -publishManifest "{path to publishManifest file}" -personalAccessToken "{Personal Access Token}"
   

   • Lassen Sie -personalAccessToken weg, wenn Sie zuvor Anmeldeinformationen für den Herausgeber mithilfe des login Befehls gespeichert haben.

   • Um sich von einem GitHub Actions Workflow zu authentifizieren, der für Trusted Publishing konfiguriert ist, verwenden Sie Folgendes:

   VsixPublisher.exe publish -payload "{Path to vsix file}" -publishManifest "{path to publishManifest file}" -oidc
   

5. Bei erfolgreicher Veröffentlichung der Erweiterung wird die folgende Befehlszeilenmeldung angezeigt:

   Uploaded 'MyVsixExtension' to the Marketplace.
   

6. Sie können die neue Erweiterung überprüfen, die Sie veröffentlicht haben, indem Sie zu Visual Studio Marketplace navigieren.

Installieren Sie die Erweiterung vom Visual Studio Marketplace

Nachdem die Erweiterung veröffentlicht wurde, installieren Sie sie in Visual Studio, und testen Sie sie dort.

1. Wählen Sie in Visual Studio im Menü ExtrasErweiterungen und Updates... aus.

2. Wählen Sie "Online" aus, und suchen Sie dann nach TestPublish.

3. Wählen Sie Herunterladen aus. Die Erweiterung wird dann zur Installation eingeplant.

4. Schließen Sie alle Instanzen von Visual Studio, um die Installation abzuschließen.

Erweiterung entfernen

Sie können die Erweiterung aus dem Visual Studio Marketplace und von Ihrem Computer entfernen.

So entfernen Sie die Erweiterung über die Befehlszeile aus dem Marketplace

1. Wenn Sie eine Erweiterung entfernen möchten, verwenden Sie den folgenden Befehl:

   VsixPublisher.exe deleteExtension -publisherName "TestVSIXPublisher" -extensionName "MyVsixExtension"
   

2. Beim erfolgreichen Löschen der Erweiterung wird die folgende Befehlszeilenmeldung angezeigt:

   Removed 'MyVsixExtension' from the Marketplace.
   

So entfernen Sie die Erweiterung von Ihrem Computer

1. Wählen Sie in Visual Studio im Menü ToolsExtensions and Updates aus.

2. Wählen Sie „MyVsixExtension“ aus, und klicken Sie dann auf Deinstallieren. Die Erweiterung wird dann zur Deinstallation eingeplant.

3. Schließen Sie alle Instanzen von Visual Studio, um die Deinstallation abzuschließen.

Siehe auch

• Installieren des Visual Studio SDK
• Erstellen Sie Ihre erste Erweiterung: Hallo Welt