Procedura dettagliata: Pubblicazione di un'estensione Visual Studio tramite la riga di comando

Questa procedura dettagliata illustra come pubblicare un'estensione Visual Studio nel marketplace Visual Studio usando la riga di comando. Quando si aggiunge l'estensione al Marketplace, gli sviluppatori possono usare la finestra di dialogo Estensioni e aggiornamenti per cercare nel Marketplace le estensioni nuove e aggiornate.

VsixPublisher.exe è lo strumento da riga di comando per la pubblicazione di estensioni Visual Studio nel Marketplace. È possibile accedervi da ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\VsixPublisher.exe. I comandi disponibili in questo strumento sono: publish, deletePublisher, deleteExtension, login, logout.

Commands

Pubblica...

Pubblica un'estensione sul Marketplace. L'estensione può essere un vsix, un file exe/msi o un collegamento. Se l'estensione esiste già con la stessa versione, l'estensione verrà sovrascritta. Se l'estensione non esiste già, verrà creata una nuova estensione.

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

Per pubblicare da un flusso di lavoro GitHub Actions configurato per la pubblicazione attendibile, usare -oidc anziché -personalAccessToken:

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

deletePublisher

Elimina un publisher nel Marketplace.

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

deleteExtension

Elimina un'estensione dal Marketplace.

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

Accesso al sistema

Connette un editore al computer.

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

logout

Disconnette un publisher dal computer.

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

createPublisher

Pubblicare da GitHub Actions con pubblicazione attendibile

La pubblicazione attendibile consente a un flusso di lavoro di GitHub Actions di pubblicare l'estensione Visual Studio senza archiviare un token di accesso personale . Usare il -oidc flag con il publish comando per eseguire l'autenticazione usando l'identità OIDC (OpenID Connect) del flusso di lavoro.

VsixPublisher.exerichiede un token OIDC da GitHub Actions con l'audience marketplace.visualstudio.com, quindi lo scambia per un token di sessione del Marketplace di breve durata. Lo strumento usa tale token di sessione per pubblicare l'estensione.

Prerequisiti per la pubblicazione affidabile

Prima della pubblicazione tramite -oidc:

• Usare una versione di VsixPublisher.exe che supporta l'opzione oidc .
• Creare un publisher nel marketplace di Visual Studio e configurare un criterio di pubblicazione attendibile che autorizza il tuo repository e il flusso di lavoro GitHub.
• Impostare la publisher proprietà nel manifest di pubblicazione sul valore dell'identificatore dell'editore del Marketplace associato a tale criterio.
• Concedere l'autorizzazione del processo id-token: write di pubblicazione in modo che possa richiedere un token OIDC da GitHub Actions.
• Rendere disponibile il payload dell'estensione, pubblicare il manifest, il file di panoramica e tutti gli altri asset a cui si fa riferimento nel Windows runner.

Configurare il flusso di lavoro

Aggiungere le autorizzazioni seguenti al processo di GitHub Actions che pubblica l'estensione:

permissions:
  contents: read
  id-token: write

L'autorizzazione id-token: write consente al processo di richiedere un token OIDC. Non autorizza, di per sé, la pubblicazione nel Marketplace; anche il repository e il flusso di lavoro devono corrispondere ai criteri di pubblicazione attendibile del publisher.

Dopo che il flusso di lavoro compila l'estensione o scarica gli artefatti di compilazione, aggiungere un passaggio di pubblicazione simile al seguente. Sostituire i percorsi eseguibili, payload e manifest con i percorsi usati dal flusso di lavoro. L'eseguibile viene in genere installato in <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
    }

Non è necessario eseguire VsixPublisher.exe login o fornire un token di accesso personale quando si usa -oidc. Lo strumento ottiene automaticamente il token dal job GitHub Actions.

Risoluzione dei problemi di pubblicazione attendibile

file di publishManifest

Un file publishManifest viene usato dal comando publish . Rappresenta tutti i metadati relativi all'estensione che il Marketplace deve conoscere. Se l'estensione caricata proviene da un'estensione VSIX, la proprietà "identity" deve avere impostato solo "internalName". Ciò è dovuto al fatto che il resto delle proprietà "identity" può essere generato dal file vsixmanifest. Se l'estensione è msi/exe o un'estensione di collegamento, l'utente deve fornire i campi obbligatori nella proprietà "identity". Il resto del manifest contiene informazioni specifiche per il Marketplace (ad esempio, categorie, se Q&A è abilitato e così via).

Esempio di file publishManifest dell'estensione 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.
}

Esempio di file MSI/EXE o 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"
}

File delle risorse

I file di asset possono essere forniti per incorporare elementi come immagini nel file README. Ad esempio, se un'estensione include il documento Markdown "overview" seguente:

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

Per risolvere "images/testlogo.png" nell'esempio precedente, un utente può fornire "assetFiles" nel manifesto di pubblicazione come indicato di seguito:

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

Procedura dettagliata per la pubblicazione

Prerequisites

Per seguire questa procedura dettagliata, è necessario installare Visual Studio SDK. Per altre informazioni, vedere Installazione di Visual Studio SDK.

Creare un'estensione di Visual Studio

In questo caso si userà un'estensione VSPackage predefinita, ma gli stessi passaggi sono validi per ogni tipo di estensione.

1. Creare un VSPackage in C# denominato "TestPublish" con un comando di menu. Per altre informazioni, vedere Creazione della prima estensione: Hello World.

Confeziona la tua estensione

1. Aggiornare l'estensione vsixmanifest con le informazioni corrette sul nome del prodotto, sull'autore e sulla versione.

   

2. Compilare l'estensione in modalità rilascio . L'estensione verrà ora creata come pacchetto VSIX nella cartella \bin\Release.

3. È possibile fare doppio clic su VSIX per verificare l'installazione.

Testare l'estensione

Prima di distribuire l'estensione, compilare e testarla per assicurarsi che sia installata correttamente nell'istanza sperimentale di Visual Studio.

1. In Visual Studio, avvia il debug. per aprire un'istanza sperimentale di Visual Studio.

2. Nell'istanza sperimentale passare al menu Strumenti e selezionare Estensioni e aggiornamenti. L'estensione TestPublish dovrebbe essere visualizzata nel riquadro centrale e abilitata.

3. Nel menu Strumenti assicurarsi di visualizzare il comando di test.

Pubblicare l'estensione nel Marketplace tramite la riga di comando

1. Assicurarsi di aver compilato la versione release dell'estensione e che sia up-to-date.

2. Assicurarsi di aver creato publishmanifest.json e overview.md file.

3. Aprire la riga di comando e passare alla directory ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\.

4. Per pubblicare una nuova estensione, selezionare il metodo di autenticazione per l'ambiente in uso.

   • Per eseguire l'autenticazione con un token di accesso personale, usare:

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

   • Omettere -personalAccessToken se in precedenza sono state salvate le credenziali per l'editore usando il comando login.

   • Per eseguire l'autenticazione da un flusso di lavoro GitHub Actions configurato per la pubblicazione attendibile, usare:

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

5. Al termine della pubblicazione dell'estensione, verrà visualizzato il seguente messaggio della riga di comando:

   Uploaded 'MyVsixExtension' to the Marketplace.
   

6. È possibile verificare la nuova estensione pubblicata passando a Visual Studio Marketplace

Installare l'estensione da Visual Studio Marketplace

Dopo aver pubblicato l'estensione, installarla in Visual Studio e testarla.

1. In Visual Studio scegliere Strumenti dal menu, quindi selezionare Estensioni e aggiornamenti.

2. Selezionare Online e quindi cercare TestPublish.

3. Seleziona Scarica. L'estensione verrà quindi pianificata per l'installazione.

4. Per completare l'installazione, chiudere tutte le istanze di Visual Studio.

Rimuovere l'estensione

È possibile rimuovere l'estensione dal marketplace di Visual Studio e dal computer.

Per rimuovere l'estensione dal Marketplace tramite la riga di comando

1. Per rimuovere un'estensione, usare il comando seguente:

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

2. Al termine dell'eliminazione dell'estensione, verrà visualizzato il seguente messaggio della riga di comando:

   Removed 'MyVsixExtension' from the Marketplace.
   

Per rimuovere l'estensione dal computer

1. Nel menu Visual Studio Tools selezionare Extensions and Updates.

2. Selezionare "MyVsixExtension" e quindi selezionare Disinstalla. L'estensione verrà quindi pianificata per la disinstallazione.

3. Per completare la disinstallazione, chiudere tutte le istanze di Visual Studio.

Vedere anche

• Installazione dell'SDK Visual Studio
• Crea la tua prima estensione: Hello World