Przewodnik: publikowanie rozszerzenia Visual Studio za pomocą wiersza polecenia

W tym przewodniku pokazano, jak opublikować rozszerzenie Visual Studio w witrynie Visual Studio Marketplace przy użyciu wiersza polecenia. Po dodaniu rozszerzenia do witryny Marketplace deweloperzy mogą za pomocą okna dialogowego Rozszerzenia i aktualizacje przeglądać tam nowe i zaktualizowane rozszerzenia.

VsixPublisher.exe to narzędzie wiersza polecenia do publikowania rozszerzeń Visual Studio w witrynie Marketplace. Można uzyskać do niego dostęp z ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\VsixPublisher.exe. Polecenia dostępne w tym narzędziu to: publish, deletePublisher, deleteExtension, login, logout.

Commands

publikować

Publikuje rozszerzenie w Marketplace. Rozszerzenie może być plikiem vsix, plikiem exe/msi lub linkiem. Jeśli rozszerzenie już istnieje w tej samej wersji, zastąpi rozszerzenie. Jeśli rozszerzenie jeszcze nie istnieje, utworzy nowe rozszerzenie.

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

Aby opublikować z przepływu pracy GitHub Actions skonfigurowanego do zaufanego publikowania, użyj -oidc zamiast -personalAccessToken:

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

Usuń wydawcę

Usuwa wydawcę w witrynie Marketplace.

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

deleteExtension

Usuwa rozszerzenie z witryny Marketplace.

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

login

Loguje wydawcę do systemu.

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

wylogowanie

Wylogowuje wydawcę z komputera.

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

createPublisher

Publikowanie z GitHub Actions za pomocą zaufanego publikowania

Zaufane publikowanie umożliwia przepływowi pracy GitHub Actions publikowanie rozszerzenia Visual Studio bez przechowywania osobistego tokenu dostępu (PAT). Użyj flagi -oidc z poleceniem publish, aby uwierzytelnić się przy użyciu tożsamości OpenID Connect (OIDC) przepływu pracy.

VsixPublisher.exe żąda tokenu OIDC z GitHub Actions z atrybutem audience marketplace.visualstudio.com, a następnie wymienia go na krótkotrwały token sesji Marketplace. Narzędzie używa tego tokenu sesji do opublikowania rozszerzenia.

Wymagania wstępne dotyczące zaufanego publikowania

Przed opublikowaniem przy użyciu -oidc:

• Użyj wersji VsixPublisher.exe , która obsługuje oidc tę opcję.
• Utwórz publikatora w witrynie Visual Studio Marketplace i skonfiguruj zaufaną politykę publikowania, która autoryzuje repozytorium i przepływ pracy GitHub.
• Ustaw właściwość publisherPublisherID w manifeście publikowania na identyfikator wydawcy witryny Marketplace skojarzony z tą zasadą.
• Udziel zadaniu publikowania id-token: write uprawnienia, aby mogło zażądać tokenu OIDC z GitHub Actions.
• Udostępnij pakiet rozszerzenia, manifest publikacji, plik omówienia i wszystkie inne zasoby, do których istnieją odwołania, na runnerze Windows.

Konfigurowanie przepływu pracy

Dodaj następujące uprawnienia do zadania GitHub Actions, które publikuje rozszerzenie:

permissions:
  contents: read
  id-token: write

Uprawnienie id-token: write umożliwia zadaniu żądanie tokenu OIDC. Samo to nie autoryzuje publikowania w witrynie Marketplace; repozytorium i przepływ pracy muszą być również zgodne z zaufanymi zasadami publikowania wydawcy.

Gdy przepływ pracy skompiluje rozszerzenie lub pobierze jego artefakty kompilacji, dodaj krok publikowania podobny do poniższego. Zastąp ścieżki pliku wykonywalnego, payloadu i manifestu ścieżkami używanymi przez obieg pracy. Plik wykonywalny jest zwykle instalowany w katalogu <VSInstallDir>\VSSDK\VisualStudioIntegration\Tools\Bin\VsixPublisher.exe.

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

Nie musisz uruchamiać VsixPublisher.exe login ani podawać identyfikatora PAT w przypadku korzystania z polecenia -oidc. Narzędzie automatycznie uzyskuje token z zadania GitHub Actions.

Rozwiązywanie problemów z zaufanym publikowaniem aplikacji

plik manifestu publishManifest

Plik publishManifest jest używany przez polecenie publish. Reprezentuje wszystkie metadane rozszerzenia, które Marketplace musi znać. Jeśli przekazywane rozszerzenie pochodzi z rozszerzenia VSIX, właściwość "identity" musi mieć ustawioną tylko właściwość "internalName". Dzieje się tak, ponieważ pozostałe właściwości "identity" można wygenerować z pliku vsixmanifest. Jeśli rozszerzenie jest rozszerzeniem msi/exe lub rozszerzeniem łącza, użytkownik musi podać wymagane pola we właściwości "identity". Pozostała część manifestu zawiera informacje specyficzne dla witryny Marketplace (na przykład kategorie, czy pytania i odpowiedzi są włączone itp.).

Przykład pliku publishManifest rozszerzenia VSIX:

{
    "$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.
}

Przykład pliku MSI/EXE lub LINK publishManifest:

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

Pliki zasobów

Pliki zasobów można udostępnić do osadzania elementów, takich jak obrazy w pliku readme. Jeśli na przykład rozszerzenie ma następujący dokument markdown "przegląd":

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

Aby odnaleźć „images/testlogo.png” w poprzednim przykładzie, użytkownik może podać ciąg „assetFiles” w manifeście publikowania, jak pokazano poniżej:

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

Przewodnik po publikowaniu

Prerequisites

Aby wykonać czynności opisane w tym przewodniku, należy zainstalować zestaw Visual Studio SDK. Aby uzyskać więcej informacji, zobacz Instalowanie zestawu SDK Visual Studio.

Tworzenie rozszerzenia programu Visual Studio

W takim przypadku użyjemy domyślnego rozszerzenia VSPackage, ale te same kroki są prawidłowe dla każdego rodzaju rozszerzenia.

1. Utwórz pakiet VSPackage w języku C# o nazwie "TestPublish", który ma polecenie menu. Aby uzyskać więcej informacji, zobacz Tworzenie pierwszego rozszerzenia: Hello world.

Zapakuj swoje rozszerzenie

1. Zaktualizuj plik vsixmanifest, podając poprawne informacje o nazwie produktu, autorze i wersji.

   

2. Skompiluj rozszerzenie w trybie Release. Teraz rozszerzenie zostanie spakowane jako plik VSIX w folderze \bin\Release.

3. Możesz kliknąć dwukrotnie plik VSIX, aby zweryfikować instalację.

Testowanie rozszerzenia

Przed dystrybucją rozszerzenia, skompiluj je i przetestuj, aby upewnić się, że jest ono poprawnie zainstalowane w eksperymentalnym wystąpieniu Visual Studio.

1. W Visual Studio rozpocznij debugowanie. aby otworzyć eksperymentalne wystąpienie Visual Studio.

2. W instancji eksperymentalnej przejdź do menu Narzędzia i wybierz pozycję Rozszerzenia i aktualizacje.... Rozszerzenie TestPublish powinno pojawić się w środkowym okienku i być włączone.

3. W menu Narzędzia upewnij się, że jest wyświetlane polecenie testowe.

Opublikuj rozszerzenie w witrynie Marketplace za pomocą wiersza polecenia

1. Upewnij się, że utworzyłeś wersję Release swojego rozszerzenia i że jest ona aktualna.

2. Upewnij się, że utworzono pliki publishmanifest.json i overview.md.

3. Otwórz wiersz polecenia i przejdź do katalogu ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\.

4. Aby opublikować nowe rozszerzenie, wybierz metodę uwierzytelniania dla danego środowiska.

   • Aby uwierzytelnić się przy użyciu osobistego tokenu dostępu (PAT), użyj:

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

   • Pomiń -personalAccessToken, jeśli wcześniej zapisano dane logowania wydawcy przy użyciu polecenia login.

   • Aby uwierzytelnić się w przepływie pracy GitHub Actions skonfigurowanym do zaufanego publikowania, użyj:

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

5. Po pomyślnym opublikowaniu rozszerzenia zostanie wyświetlony następujący komunikat wiersza polecenia:

   Uploaded 'MyVsixExtension' to the Marketplace.
   

6. Możesz zweryfikować opublikowane nowe rozszerzenie, przechodząc do witryny Visual Studio Marketplace

Zainstaluj rozszerzenie z witryny Visual Studio Marketplace

Teraz, po opublikowaniu rozszerzenia, zainstaluj je w programie Visual Studio i przetestuj je tam.

1. W Visual Studio w menu Narzędzia wybierz pozycję Rozszerzenia i aktualizacje....

2. Wybierz pozycję Online , a następnie wyszukaj pozycję TestPublish.

3. Wybierz opcję Pobierz. Rozszerzenie zostanie następnie zaplanowane do zainstalowania.

4. Aby ukończyć instalację, zamknij wszystkie instancje programu Visual Studio.

Usuń rozszerzenie

Rozszerzenie można usunąć z witryny Visual Studio Marketplace i z komputera.

Aby usunąć rozszerzenie z witryny Marketplace za pośrednictwem wiersza polecenia

1. Jeśli chcesz usunąć rozszerzenie, użyj następującego polecenia:

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

2. Po pomyślnym usunięciu rozszerzenia zostanie wyświetlony następujący komunikat wiersza polecenia:

   Removed 'MyVsixExtension' from the Marketplace.
   

Aby usunąć rozszerzenie z komputera

1. W Visual Studio w menu Tools wybierz Rozszerzenia i aktualizacje.

2. Wybierz pozycję "MyVsixExtension", a następnie wybierz pozycję Odinstaluj. Rozszerzenie zostanie następnie zaplanowane do usunięcia.

3. Aby ukończyć odinstalowywanie, zamknij wszystkie wystąpienia programu Visual Studio.

Informacje dodatkowe

• Instalowanie zestawu VISUAL STUDIO SDK
• Tworzenie pierwszego rozszerzenia: Hello world