Creare un pacchetto e pubblicare un'integrazione nel Marketplace

  • Articolo

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

Si dispone di uno strumento, un servizio o un prodotto che si integra con Azure DevOps o Team Foundation Server (TFS)? In tal caso, aiutare gli utenti a trovarlo pubblicandolo in Visual Studio Marketplace. Marketplace è un punto di riferimento unico per utenti singoli e team per trovare strumenti che estendono e migliorano l'esperienza.

Esplorare il Marketplace per visualizzare esempi di altre integrazioni ed estensioni.

Nota

Per la creazione di pacchetti e la pubblicazione di informazioni sulle estensioni, vedere Package & Publish Extensions (Pacchetti e pubblicazione di estensioni).

Requisiti per la pubblicazione

Prima di pubblicare nel Marketplace, è necessario soddisfare l'elenco seguente dei requisiti.

  • Installare lo strumento di creazione pacchetti di estensioni (TFX). Eseguire npm install -g tfx-cli da un prompt dei comandi.
  • Assicurarsi che le autorizzazioni appropriate siano concesse per usare qualsiasi immagine, ad esempio icone, logo, screenshot e così via.
  • Includere un file completo overview.md per descrivere l'inserzione nel Marketplace.
  • Includere un'icona per l'estensione, con dimensioni di almeno 128x128 pixel.
  • Quando si fa riferimento ai prodotti Microsoft, usare nomi completi al posto delle abbreviazioni, ad esempio Azure DevOps e AzDO o qualsiasi altra abbreviazione.
  • Evitare di usare nomi di marchio nel nome dell'estensione.

Elementi necessari

  1. Logo 128x128 pixel (formato PNG o JPEG) che rappresenta l'integrazione, se stessi o la società/organizzazione
  2. Almeno uno screenshot che mostra l'integrazione
  3. Invito all'azione/URL introduttivo (in cui gli utenti devono iniziare a usare l'integrazione)

Passaggi

La pubblicazione nel Marketplace è un processo iterativo che inizia con la creazione di un file manifesto che definisce le caratteristiche di integrazione e individuazione chiave (ad esempio screenshot, logo e contenuto di panoramica). Queste informazioni vengono usate per presentare l'integrazione agli utenti nel Marketplace, ad esempio:

Esempio

Jenkins per Azure DevOps

Nota: il termine , extension, viene usato nelle documentazioni a cui si fa riferimento di seguito. Le estensioni sono un altro tipo di elemento del Marketplace e condividono molte analogie dal punto di vista dell'individuazione come integrazioni.

Serve aiuto per ottenere l'integrazione in Marketplace? Contattaci. E, sì, questo indirizzo di posta elettronica è monitorato da persone reali.

Creare un autore

Tutte le estensioni e le integrazioni, incluse le estensioni di Microsoft, hanno un editore. Chiunque può creare un editore e pubblicare le estensioni al suo interno. È anche possibile concedere ad altri utenti l'accesso all'editore se un team sta sviluppando l'estensione.

Un utente è proprietario dell'editore, in genere l'utente che lo ha creato. È anche possibile condividere l'editore con altri utenti.

  1. Accedere al portale di pubblicazione di Visual Studio Marketplace.

  2. Se non si è già membri di un server di pubblicazione esistente, + Crea un server di pubblicazione. Immettere un nome nel campo nome editore. Il campo ID dovrebbe essere impostato automaticamente in base al nome immesso.

    Screenshot che mostra il pulsante evidenziato Crea autore.

    Nota

    Prendere nota dell'ID, perché è necessario impostarlo nel file manifesto dell'estensione.

    Se non viene richiesto di creare un server di pubblicazione, scorrere verso il basso fino alla fine della pagina e selezionare Pubblica estensioni sotto Siti correlati.

    • Specificare un identificatore per il server di pubblicazione, ad esempio : mycompany-myteam. Questo identificatore viene usato come valore per l'attributo nel file manifesto dell'estensione publisher .
    • Specificare un nome visualizzato per il server di pubblicazione, ad esempio: My Team

  3. Esaminare il Contratto di pubblicazione del Marketplace e quindi selezionare Crea.

    Creare un server di pubblicazione per l'estensione

Dopo aver creato l'editore, si viene indirizzati alla gestione degli elementi, ma non sono presenti elementi.

Creare una cartella per contenere il manifesto dell'elemento e altri asset

Prima di creare un pacchetto dell'integrazione come estensione, è necessario creare una home cartella per contenere alcuni asset necessari, all'interno di questa cartella:

  1. Creare una cartella denominata images per contenere:
    • Logo per l'integrazione (128x128 pixel)
    • Screenshot (1366x768 pixel)
  2. Creare un file denominato overview.md
  3. Creare un file denominato vss-integration.json
    • Questo file è il file manifesto dell'inserzione nel Marketplace, che contiene molte proprietà per descrivere l'estensione nell'inserzione nel Marketplace. È possibile esplorare il riferimento al manifesto dell'estensione qui

Manifesto dell'estensione

  1. Compilare il vss-integration.json file con il codice JSON seguente:

    {
    "manifestVersion": 1,
    "id": "myservice",
    "version": "1.0.0",
    "name": "My Service",
    "publisher": "mycompany",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ],    
    "icons": {
        "default": "images/service-logo.png"
    },
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "screenshots": [
        {
            "path": "images/screen1.png"
        },
        {
            "path": "images/screen2.png"
        }
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "fabrikam-license-terms.md"
        }
    },
    "links": {
        "getstarted": {
            "uri": "https://www.mycompany.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.mycompany.com/features"
        },
        "support": {
            "uri": "https://www.mycompany.com/support"
        }
    },
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    }
}

  2. Aggiornare il codice JSON usando il riferimento seguente:

Queste proprietà sono obbligatorie:

Proprietà Descrizione Note
manifestVersion Numero corrispondente alla versione del formato manifesto. deve essere 1.
ID Identificatore dell'estensione. L'ID è una stringa che deve essere univoca tra le estensioni dello stesso editore. Deve iniziare con un carattere alfabetico o numerico e contenere 'A' fino a 'Z', 'a' da 'z', '0' a '9' e '-' (trattino). Esempio: sample-extension.
version Stringa che specifica la versione di un'estensione. Deve essere nel formato major.minor.patch, ad esempio 0.1.2 o 1.0.0. È anche possibile aggiungere un quarto numero per il formato seguente: 0.1.2.3
name Nome breve e leggibile dell'estensione. Massimo 200 caratteri. Esempio: "Fabrikam Agile Board Extension".
publisher Identificatore del server di pubblicazione. Questo identificatore deve corrispondere all'identificatore in cui viene pubblicata l'estensione. Vedere Creare e gestire un server di pubblicazione.
Categorie Matrice di stringhe che rappresentano le categorie a cui appartiene l'estensione. È necessario specificare almeno una categoria e non è previsto alcun limite al numero di categorie che è possibile includere. Valori validi: Azure Repos, Azure Boards, Azure PipelinesAzure Test Plans, e Azure Artifacts.

Note:
    - Usare la versione >=0.6.3 di tfx-cli se si pubblica l'estensione a livello di codice.
    - Se si usa l'estensione Azure DevOps Extension Tasks per la pubblicazione, assicurarsi che la versione sia >= 1.2.8. Potrebbe essere necessario approvare l'aggiornamento dell'estensione a causa di modifiche recenti dell'ambito.
    - Le categorie indicate in precedenza sono presenti in modo nativo in Visual Studio Marketplace e Azure DevOps Server 2019 e versioni successive. Per le estensioni destinate a versioni precedenti di TFS:
      - Se i clienti TFS acquisiscono l'estensione tramite Visual Studio Marketplace (non la raccolta locale) nel contesto connesso, usare le categorie indicate in precedenza.
      - Se si intende condividere l'estensione direttamente (ovvero non tramite Visual Studio Marketplace) con un cliente che usa TFS <=2018, usare invece le categorie seguenti: Codice, Piano e traccia, Compilazione e rilascio, Test, Collaborazione e Integrazione. Se è necessario condividere sia tramite Visual Studio Marketplace che direttamente con un cliente TFS <= 2018, è necessario avere 2 pacchetti di estensione.
Obiettivi Prodotti e servizi supportati dall'integrazione o dall'estensione. Per altre informazioni, vedere Destinazioni di installazione. Matrice di oggetti, in cui ogni oggetto ha un id campo che indica uno dei seguenti:
    - Microsoft.VisualStudio.Services(estensioni che funzionano con Azure DevOps o TFS),
    Microsoft.TeamFoundation.Server- (estensione che funziona con TFS),-
    Microsoft.VisualStudio.Services.Integration (integrazioni che funzionano con Azure DevOps o TFS),
    - Microsoft.TeamFoundation.Server.Integration (integrazioni che funzionano con TFS)

Queste proprietà facoltative consentono agli utenti di individuare e ottenere informazioni sull'estensione:

Proprietà Descrizione Note
description Alcune frasi che descrivono le estensioni. Massimo 200 caratteri. La descrizione deve essere la "presentazione dell'ascensore" dell'estensione: un paio di righe per descrivere l'estensione nel Marketplace e far sì che gli utenti vogliano installarla. Vedere l'esempio seguente
Icone Dizionario di icone che rappresentano l'estensione. Chiavi valide: default (128x128 pixel) di tipo BMP, GIF, EXIF, JPG, PNG e TIFF. Altre chiavi, large ad esempio (512x512 pixel) potrebbero essere supportate in futuro. Il valore di ogni chiave è il percorso del file icona nell'estensione
tag Matrice di tag stringa per aiutare gli utenti a trovare l'estensione. Esempi: agile, project management, task timere così via.
Screenshot Matrice di immagini che non possono essere incluse nel contenuto. Gli screenshot sono più utili quando sono presenti nel contenuto e devono essere usati per creare una pagina dei dettagli di mercato di qualità per l'estensione. Usare screenshot per immagini meno importanti non presenti nel contenuto. Ogni immagine deve essere di 1366x768 pixel. L'oggetto path di ogni elemento è il percorso del file nell'estensione.
content Dizionario di file di contenuto che descrivono l'estensione per gli utenti. Ogni estensione deve includere contenuto solido. Questo è il modo in cui si mostreranno agli utenti cosa può fare l'estensione. Renderlo ricco, utilizzabile e includere screenshot dove necessario. Includere un overview.md file come parte del contenuto di base. Si presuppone che ogni file sia in formato GitHub Flavored Markdown . L'oggetto path di ogni elemento è il percorso del file Markdown nell'estensione. Chiavi valide: details. Altre chiavi potrebbero essere supportate in futuro.
collegamenti Dizionario di collegamenti che consentono agli utenti di ottenere altre informazioni sull'estensione, ottenere supporto e spostare. Chiavi valide: getstarted - primi passaggi, come configurare o usare. learn - Contenuto più approfondito per aiutare gli utenti a comprendere meglio l'estensione o il servizio. license - Contratto di licenza per l'utente finale. privacypolicy - Informativa sulla privacy per un'estensione. support : ottenere assistenza e supporto per un'estensione. Il valore di ogni chiave è un oggetto con un uri campo, ovvero l'URL assoluto del collegamento
repository Dizionario delle proprietà che descrivono il repository del codice sorgente per l'estensione Chiavi valide: type - Tipo di repository. Esempio: git. uri - URL assoluto del repository.
Distintivi Matrice di collegamenti a badge di metadati esterni come TravisCI, Appveyor e così via, dai siti di badge approvati Chiavi valide: href - Collegare l'utente a quando si seleziona il badge. uri - URL assoluto dell'immagine badge da visualizzare. description - Descrizione del badge da visualizzare al passaggio del mouse.
Branding Dizionario delle proprietà correlate al marchio. Chiavi valide: color - colore principale dell'estensione o del server di pubblicazione; può essere un esadecimale (#ff00ff), RGB (rgb(100,200,50)) o nomi di colori HTML supportati (blu). theme - integra il colore; utilizzare scuro per colori di personalizzazione scuri o chiaro per colori di personalizzazione più chiari.

Pagina dei dettagli

  • 1 - descrizione
  • 2 - Icona
  • 3 - Categorie
  • 4 - Screenshot
  • 5 - Contenuto (dettagli)
  • 6 - Collegamenti
  • 7 - Personalizzazione

scheda

Assicurarsi che l'attributo "public" venga impostato su "false" (o non impostato affatto) per evitare che l'estensione o l'integrazione diventino prematuramente visibili a tutti gli utenti nel Marketplace.

Creare un pacchetto del manifesto e degli asset

Ottenere lo strumento del pacchetto (tfx-cli)

È possibile installare o aggiornare l'interfaccia della riga di comando multipiattaforma per Azure DevOps (tfx-cli) usando npm, un componente di Node.js dalla riga di comando.

npm i -g tfx-cli

Creare un pacchetto dell'integrazione in un file con estensione vsix

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

Nota

La versione di un'estensione/integrazione deve essere incrementata a ogni aggiornamento.
Se l'estensione o l'integrazione non sono state incrementate nel manifesto, è necessario passare l'opzione della --rev-version riga di comando. In questo modo viene incrementato il numero di versione patch dell'estensione e la nuova versione viene salvata nel manifesto.

Pubblicare l'integrazione in Marketplace

Dopo aver creato il pacchetto dell'estensione, è possibile caricarla nel Marketplace in un editore. L'identificatore publisher specificato nel file manifesto dell'estensione deve corrispondere all'identificatore del server di pubblicazione in cui viene caricata l'estensione.

  1. Nel portale di gestione selezionare l'editore dal menu a discesa nella parte superiore della pagina.

  2. Selezionare Nuova estensione >Azure DevOps.

    Screenshot che mostra il menu a discesa Nuova estensione e la selezione di Azure DevOps evidenziata.

  3. Trascinare e rilasciare il file o selezionarlo per trovare il file VSIX creato nel passaggio di creazione del pacchetto precedente e quindi scegliere Carica.

    Screenshot che mostra il caricamento della nuova estensione per Azure DevOps.

    Dopo la convalida rapida, l'estensione viene visualizzata nell'elenco delle estensioni pubblicate. Non preoccuparti, l'estensione è visibile solo per te.

    Screenshot che mostra l'estensione nell'elenco delle estensioni pubblicate.

A questo punto, l'estensione non è visibile ad alcun account e non può essere installata fino a quando non la condividi.

Nota

Microsoft esegue un'analisi di virus su ogni pacchetto di estensione nuovo e aggiornato pubblicato. Finché l'analisi non è chiara, l'estensione non viene pubblicata nel Marketplace per l'utilizzo pubblico. In questo modo si evita anche di evitare di esaminare contenuti inappropriati o offensivi nelle pagine del Marketplace.

Condividere l'integrazione

Prima di poter installare un'integrazione in un'organizzazione in Azure DevOps o TFS, è necessario condividerla con tale organizzazione. La condivisione è un requisito durante lo sviluppo e il test di un'integrazione, perché è l'unico modo per eseguire un'integrazione.

Per condividere un'integrazione, eseguire le attività seguenti:

  1. Selezionare un'integrazione dall'elenco di elementi visualizzati
  2. Selezionare il pulsante Condividi
  3. Specificare il nome dell'organizzazione per rendere visibile questa integrazione.
    • Ad esempio, per rendere visibile un'integrazione all'organizzazione dev.azure.com/fabrikam-fiber-inc , specificare fabrikam-fiber-inc.

Aggiornare un elemento

Per modificare un'estensione già pubblicata, aggiornarla.

Suggerimento

È consigliabile aggiornare l'estensione per rimuovere e ricaricare. È anche consigliabile avere due estensioni, publisher.extension ad esempio e publisher.extension-dev. Publisher.extension è pubblico nel Marketplace, in cui i clienti possono installarlo nelle organizzazioni Azure DevOps. Publisher.extension-dev viene mantenuto privato nel Marketplace e può essere condiviso con un'organizzazione proprietaria e di controllo. Non è necessario mantenere due copie del codice sorgente dell'estensione. È possibile gestire due file manifesto, uno per ogni estensione e durante la creazione di pacchetti dell'estensione, è possibile fornire il rispettivo file manifesto allo strumento tfx-cli. Per altre informazioni sugli argomenti necessari per lo strumento, vedere Comandi di estensione TFX.

  1. Selezionare un'estensione dall'elenco di elementi visualizzati.
  2. Fare clic con il pulsante destro del mouse e selezionare Aggiorna per , publisher.extension-devad esempio.
  3. Convalidare l'estensione.
  4. Eseguire gli stessi aggiornamenti alla versione di produzione, publisher.extensionad esempio .
  5. Passare al file vsix per l'estensione e caricarlo.

La versione aggiornata dell'estensione viene installata automaticamente negli account in cui è già installato. I nuovi account in cui l'estensione è installata in futuro ricevono anche la versione più recente.

Rendere pubblica l'integrazione (visibile a tutti)

Per informazioni su come rendere pubblica l'integrazione, visitare Rendere pubblico l'inserzione.