Share via

Empacotar e publicar uma integração no Marketplace

  • Artigo

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

Você tem uma ferramenta, serviço ou produto que se integra ao Azure DevOps ou ao Team Foundation Server (TFS)? Em caso afirmativo, ajude os usuários a encontrá-lo publicando-o no Visual Studio Marketplace. O Marketplace é um balcão único para indivíduos e equipes encontrarem ferramentas que ampliam e aprimoram a experiência.

Navegue pelo Marketplace para ver exemplos de outras integrações e extensões.

Observação

Se você estiver procurando informações de empacotamento e publicação para extensões, confira Extensões de Publicação de Pacote e Pacote.

Publicação de requisitos

A lista de requisitos a seguir deve ser atendida antes de publicar no Marketplace.

  • Instale a ferramenta de empacotamento de extensão (TFX). Executar npm install -g tfx-cli a partir de um prompt de comando.
  • Certifique-se de que as permissões adequadas sejam concedidas para usar quaisquer imagens, por exemplo, ícones, logotipos, capturas de tela e assim por diante.
  • Inclua um arquivo completo overview.md para descrever sua listagem no Marketplace.
  • Inclua um ícone para sua extensão, que tenha pelo menos 128x128 pixels de tamanho.
  • Quando você se referir a produtos da Microsoft, use nomes completos no lugar de abreviações, por exemplo, Azure DevOps vs. AzDO ou - qualquer outra abreviação.
  • Abster-se de usar nomes de marca no nome da sua extensão.

O que você precisa

  1. Logotipo de 128x128 pixels (formato PNG ou JPEG) representando sua integração, você mesmo ou sua empresa/organização
  2. Mínimo de uma captura de tela mostrando sua integração
  3. URL de chamada para ação / introdução (onde os usuários devem ir para começar a usar sua integração)

Etapas

A publicação no Marketplace é um processo iterativo que começa com a criação de um arquivo de manifesto que define sua integração e as principais características de descoberta (como capturas de tela, logotipos e conteúdo de visão geral). Essas informações são usadas para apresentar sua integração aos usuários no Marketplace, por exemplo:

example

Jenkins for Azure DevOps

Nota: O termo, extension, é usado nas documentações referenciadas abaixo. As extensões são outro tipo de item do Marketplace e compartilham muitas semelhanças do ponto de vista da descoberta como integrações.

Precisa de ajuda para obter sua integração no Marketplace? Entre em contato conosco. E, sim, esse endereço de e-mail é monitorado por pessoas reais.

Criar um editor

Todas as extensões e integrações, incluindo extensões da Microsoft, têm um editor. Qualquer pessoa pode criar um editor e publicar extensões sob ele. Você também pode dar a outras pessoas acesso ao seu editor se uma equipe estiver desenvolvendo a extensão.

Um usuário é o proprietário do editor, normalmente o usuário que o criou. Você também pode compartilhar o editor com outros usuários.

  1. Entre no Portal de Publicação do Visual Studio Marketplace.

  2. Se você ainda não é membro de um editor existente, + Criar um editor. Insira um nome no campo Nome do editor. O campo ID deve ser definido automaticamente com base no nome inserido.

    Captura de tela mostrando o botão realçado, Criar editor.

    Observação

    Anote o ID, pois você precisa defini-lo no arquivo de manifesto de sua extensão.

    Se você não for solicitado a criar um editor, role para baixo até a parte inferior da página e selecione Publicar extensões abaixo de Sites relacionados.

    • Especifique um identificador para seu editor, por exemplo: mycompany-myteam. Esse identificador é usado como o valor para o atributo no arquivo de manifesto publisher de extensão.
    • Especifique um nome de exibição para o editor, por exemplo: My Team

  3. Revise o Contrato de Editor do Marketplace e selecione Criar.

    Criar editor para extensão

Depois que o editor é criado, você é direcionado para gerenciar itens, mas não há itens.

Criar uma pasta para conter o manifesto do item e outros ativos

Antes de empacotar sua integração como uma extensão, você precisará criar uma home pasta para conter alguns ativos necessários, dentro desta pasta:

  1. Crie uma pasta chamada images para conter:
    • Logotipo para sua integração (128x128 pixels)
    • Screenshots (1366x768 pixels)
  2. Criar um arquivo chamado overview.md
  3. Criar um arquivo chamado vss-integration.json
    • Esse arquivo é o arquivo de manifesto da listagem do Marketplace, ele contém muitas propriedades para descrever sua extensão na listagem do Marketplace. Você pode navegar pela referência do manifesto de extensão aqui

Manifesto de extensão

  1. Preencha seu vss-integration.json arquivo com o seguinte JSON:

    {
    "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. Atualize o JSON usando a seguinte referência:

Estas propriedades são necessárias:

Propriedade Descrição Observações
manifestVersion Um número correspondente à versão do formato de manifesto. Deve ser 1.
ID O identificador da extensão. Th ID é uma cadeia de caracteres que deve ser exclusiva entre extensões do mesmo editor. Ele deve começar com um caractere alfabético ou numérico e conter 'A' a 'Z', 'a' a 'z', '0' a '9' e '-' (hífen). Exemplo: sample-extension.
version Uma cadeia de caracteres especificando a versão de uma extensão. Deve ser no formato major.minor.patch, por exemplo 0.1.2 ou 1.0.0. Você também pode adicionar um quarto número para o seguinte formato: 0.1.2.3
name Um nome curto e legível para humanos da extensão. Limitado a 200 caracteres. Exemplo: "Fabrikam Agile Board Extension".
Publicador O identificador do editor. Esse identificador deve corresponder ao identificador sob o qual a extensão é publicada. Consulte Criar e gerenciar um editor.
Categorias Matriz de cadeias de caracteres que representam as categorias às quais sua extensão pertence. Pelo menos uma categoria deve ser fornecida e não há limite para quantas categorias você pode incluir. Valores válidos: Azure Repos, Azure Boards, Azure Pipelines, Azure Test Planse Azure Artifacts.

Observações:
    - Use a versão >=0.6.3 do tfx-cli se você estiver publicando a extensão programaticamente.
    - Se você estiver usando a extensão Tarefas de Extensão de DevOps do Azure para publicar, verifique se sua versão é >= 1.2.8. Talvez seja necessário aprovar a atualização de extensão devido a alterações recentes no escopo.
    - As categorias mencionadas anteriormente estão nativamente presentes no Visual Studio Marketplace e no Azure DevOps Server 2019 & acima. Para extensões direcionadas a versões anteriores do TFS:
      - Se os clientes do TFS adquirirem sua extensão por meio do Visual Studio Marketplace (não da galeria local) no contexto conectado, use as categorias indicadas anteriormente.
      - Se você for compartilhar a extensão diretamente (ou seja, não por meio do Visual Studio Marketplace) com um cliente usando o TFS <=2018, use as seguintes categorias: Código, Planejar e rastrear, Criar e liberar, Testar, Colaborar e Integrar. Se você precisar compartilhar via Visual Studio Marketplace e diretamente com um cliente TFS <= 2018, precisará ter 2 pacotes de extensão.
destinos Os produtos e serviços suportados pela sua integração ou extensão. Para obter mais informações, consulte Destinos de instalação. Uma matriz de objetos, onde cada objeto tem um id campo indicando um dos seguintes:
    - Microsoft.VisualStudio.Services(extensões que funcionam com o Azure DevOps ou TFS),
    Microsoft.TeamFoundation.Server- (extensão que funciona com o TFS),- Microsoft.VisualStudio.Services.Integration
    (integrações que funcionam com o Azure DevOps ou TFS),
    - Microsoft.TeamFoundation.Server.Integration (integrações que funcionam com o TFS)

Estas propriedades opcionais ajudam os usuários a descobrir e aprender sobre sua extensão:

Propriedade Descrição Observações
descrição Algumas frases descrevendo as extensões. Limitado a 200 caracteres. A descrição deve ser o "elevator pitch" da sua extensão - algumas linhas para descrever sua extensão no Marketplace e fazer com que as pessoas queiram instalá-la. Veja o exemplo abaixo
Ícones Dicionário de ícones que representam a extensão. Chaves válidas: default (128x128 pixels) do tipo BMP, GIF, EXIF, JPG, PNG e TIFF). Outras chaves, como large (512x512 pixels) podem ser suportadas no futuro. O valor de cada chave é o caminho para o arquivo de ícone na extensão
marcas Matriz de marcas de cadeia de caracteres para ajudar os usuários a encontrar sua extensão. Exemplos: agile, , project managementtask timer, e assim por diante.
Imagens Matriz de imagens que não puderam ser incluídas em seu conteúdo. As capturas de tela são mais valiosas quando apresentadas em seu conteúdo e devem ser usadas lá para ajudar a criar uma página de detalhes de mercado de qualidade para sua extensão. Use capturas de tela para imagens menos importantes que não aparecem em seu conteúdo. Cada imagem deve ter 1366x768 pixels. O path de cada item é o caminho para o arquivo na extensão.
content Dicionário de arquivos de conteúdo que descrevem sua extensão para os usuários. Toda extensão deve incluir conteúdo sólido. É assim que você mostrará aos usuários o que sua extensão pode fazer. Torne-o rico, consumível e inclua capturas de tela quando necessário. Inclua um overview.md arquivo como parte de conteúdo base. Presume-se que cada arquivo esteja no formato GitHub Flavored Markdown . O path de cada item é o caminho para o arquivo Markdown na extensão. Chaves válidas: details. Outras chaves podem ser suportadas no futuro.
links Dicionário de links que ajudam os usuários a saber mais sobre sua extensão, obter suporte e mover. Chaves válidas: getstarted - primeiros passos, como configurar ou usar. learn - conteúdo mais profundo para ajudar os usuários a entender melhor sua extensão ou serviço. license - contrato de licença de usuário final. privacypolicy - política de privacidade para uma extensão. support - obter ajuda e suporte para uma extensão. O valor de cada chave é um objeto com um uri campo, que é a URL absoluta do link
repositório Dicionário de propriedades que descreve o repositório de código-fonte para a extensão Chaves válidas: type - Tipo de repositório. Exemplo: git. uri - URL absoluta do repositório.
Emblemas Matriz de links para selos de metadados externos, como TravisCI, Appveyor e assim por diante, a partir dos sites de selos aprovados Chaves válidas: href - Link para o qual o usuário navega ao selecionar o selo. uri - A URL absoluta da imagem do emblema a ser exibida. description - Descrição do crachá, a ser exibido ao pairar.
Marca Dicionário de propriedades relacionadas à marca. Chaves válidas: color - cor primária da extensão ou editor; pode ser hexadecimal (#ff00ff), RGB (rgb(100,200,50)) ou nomes de cores HTML suportados (azul). theme - complementa a cor; Use escuro para cores de marca escuras ou claro para cores de marca mais claras.

Página de detalhes

  • 1 - Descrição
  • 2 - ícone
  • 3 - Categorias
  • 4 - Imagens
  • 5 - conteúdo (detalhes)
  • 6 - ligações externas
  • 7 - Identidade visual

cartão

Certifique-se de que o atributo "public" seja definido como "false" (ou não esteja definido) para evitar que sua extensão ou integração se torne prematuramente visível para todos os usuários no Marketplace.

Empacote seu manifesto e ativos

Obter a ferramenta de pacote (tfx-cli)

Você pode instalar ou atualizar a CLI multiplataforma do Azure DevOps (tfx-cli) usando npm, um componente de Node.js, da linha de comando.

npm i -g tfx-cli

Empacote sua integração em um arquivo .vsix

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

Observação

A versão de uma extensão/integração deve ser incrementada em cada atualização.
Se você não incrementou sua extensão/integração no manifesto, você deve passar a opção de linha de --rev-version comando. Isso incrementa o número da versão do patch da extensão e salva a nova versão no manifesto.

Publique sua integração no Marketplace

Depois que sua extensão for empacotada, você poderá carregá-la no Marketplace sob um editor. O publisher identificador especificado no arquivo de manifesto da extensão deve corresponder ao identificador do editor no qual a extensão é carregada.

  1. No portal de gerenciamento, selecione seu editor no menu suspenso na parte superior da página.

  2. Selecione Nova extensão>Azure DevOps.

    Captura de tela mostrando o menu suspenso Nova extensão e a seleção de DevOps do Azure realçada.

  3. Arraste e solte o arquivo ou selecione-o para localizar o arquivo VSIX, que você criou na etapa de empacotamento anterior, e escolha Carregar.

    Captura de tela mostrando Upload de nova extensão para o Azure DevOps.

    Após a validação rápida, sua extensão aparece na lista de extensões publicadas. Não se preocupe, a extensão só é visível para você.

    Captura de tela mostrando a extensão na lista de extensões publicadas.

Neste ponto, sua extensão não está visível para nenhuma conta e não pode ser instalada até que você a compartilhe.

Observação

A Microsoft executa uma verificação de vírus em cada pacote de extensão novo e atualizado publicado. Até que a verificação esteja clara, não publicamos a extensão no Marketplace para uso público. Dessa forma, também evitamos a exibição de conteúdo impróprio ou ofensivo nas páginas do Marketplace.

Compartilhe sua integração

Antes de instalar uma integração em uma organização no Azure DevOps ou no TFS, você deve compartilhá-la com essa organização. O compartilhamento é um requisito durante o desenvolvimento e teste de uma integração, pois é a única maneira de executar uma integração.

Para compartilhar uma integração, execute as seguintes tarefas:

  1. Selecione uma integração na lista de itens exibidos
  2. Selecione o botão Compartilhar
  3. Especifique o nome da organização para tornar essa integração visível.
    • Por exemplo, para tornar uma integração visível para a organização dev.azure.com/fabrikam-fiber-inc , especifique fabrikam-fiber-inc.

Atualizar um item

Para alterar uma extensão já publicada, atualize-a.

Dica

Recomendamos atualizar a extensão em vez de remover e recarregar. Também recomendamos ter duas extensões, por exemplo, publisher.extension e publisher.extension-dev. Publisher.extension é público no Marketplace, onde os clientes podem instalá-lo em suas organizações de DevOps do Azure. Publisher.extension-dev é mantido privado no Marketplace e pode ser compartilhado com uma organização que você possui e controla. Você não precisa manter duas cópias do código-fonte da extensão. Você pode manter dois arquivos de manifesto - um para cada extensão e durante o empacotamento da extensão você pode fornecer o respectivo arquivo de manifesto para a ferramenta tfx-cli. Para obter mais informações sobre os argumentos necessários para a ferramenta, consulte Comandos de extensão TFX.

  1. Selecione uma extensão na lista de itens exibidos.
  2. Clique com o botão direito do mouse e selecione Atualizar para o publisher.extension-dev, por exemplo.
  3. Valide sua extensão.
  4. Faça as mesmas atualizações na versão de produção, publisher.extensionpor exemplo.
  5. Navegue até o .vsix para sua extensão e carregue-a.

A versão atualizada da sua extensão é instalada automaticamente em contas que já a tenham instalada. Novas contas onde a extensão é instalada no futuro também recebem a versão mais recente.

Tornar sua integração pública (visível para todos)

Para obter informações sobre como tornar sua integração pública, visite Tornar seu anúncio público.