Referência de manifesto de extensão

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019 | TFS 2018

Cada extensão tem um arquivo de manifesto JSON que define informações básicas sobre a extensão. O arquivo também define como ele pode estender e aprimorar a experiência. Este artigo mostra como criar um manifesto para sua extensão para o Azure DevOps.

Dica

Confira nossa documentação mais recente sobre o desenvolvimento de extensão usando o SDK da Extensão do Azure DevOps.

Crie um arquivo nomeado vss-extension.json na raiz da pasta de extensão. Esse arquivo contém atributos necessários, como a ID da extensão e seus destinos de instalação, onde ele pode ser executado. Ele também define as contribuições que estão sendo feitas por sua extensão.

Consulte o exemplo a seguir de um manifesto típico:

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "categories": [
        "Azure Boards"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "content": {
        "details": {
            "path": "readme.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ],
    "files": [
        {
            "path": "launch.html",
            "addressable": true
        },        
        {
            "path": "node_modules/vss-web-extension-sdk/lib",
            "addressable": true,
            "packagePath": "lib"
        }
    ]
}

Atributos necessários

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.
categories 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 Test PlansAzure BoardsAzure Pipelinese .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 campo indicando um id dos seguintes:
    - Microsoft.VisualStudio.Services(extensões que funcionam com o Azure DevOps ou TFS), (extensão que funciona com o TFS), (integrações que funcionam com o Azure DevOps ou TFS),
    - -
    Microsoft.TeamFoundation.Server.IntegrationMicrosoft.TeamFoundation.ServerMicrosoft.VisualStudio.Services.Integration
    - (integrações que funcionam com o TFS)

Exemplos de atributos necessários

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Atributos opcionais

Atributos de tempo de execução

Propriedade Descrição Observações
scopes Uma matriz de escopos de autorização (cadeias de caracteres) listando permissões exigidas pela sua extensão. Por exemplo, vso.work e indica que sua extensão precisa de acesso somente leitura a itens de trabalho e acesso de leitura/gravação ao código-fonte (e vs.code_write recurso relacionado). Os escopos são apresentados ao usuário ao instalar sua extensão. Para obter mais informações, consulte a lista completa de escopos.
Demandas Uma matriz de demandas (strings) listando os recursos exigidos pela sua extensão. Por exemplo, indica que sua extensão usa APIs da versão 3.0 e, portanto, api-version/3.0 não pode ser executada em produtos mais antigos que não oferecem suporte a essa versão. Para obter mais informações, consulte a lista completa de demandas.
baseUri URL base (opcional) para todas as URLs relativas especificadas pelas contribuições da extensão. Por exemplo: https://myapp.com/{{account.name}}/. Essa propriedade deve ser deixada vazia se o conteúdo da extensão for empacotado com a extensão.
Contribuições Uma série de contribuições para o sistema.
tipos de contribuição Uma matriz de tipos de contribuição definida pela extensão
{
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "demands": [
        "api-version/3.0"
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}

Atributos de descoberta

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, , task timer, project managemente 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.

Marcar uma extensão pública

Por padrão, todas as extensões no Azure DevOps Marketplace são privadas. Eles só são visíveis para o editor e contas compartilhadas pelo editor. Se o editor for verificado, você poderá tornar sua extensão pública definindo o sinalizador no manifesto da Public extensão:

{
    "galleryFlags": [
        "Public"
    ]
}            

Ou:

{
    "public": true
}            

Para obter mais informações, consulte Pacote/Publicação/Instalação.

Marcar uma extensão para estar na visualização

Se sua extensão estiver pronta para os usuários no Marketplace experimentarem, mas você ainda estiver trabalhando em alguns bugs ou adicionando função, você pode marcá-la como preview:

{
    "galleryFlags": [
        "Preview"
    ]
}            

Marcar uma extensão como visualização paga

Se você pretende vender sua extensão no Marketplace, marque-a como visualização paga. Uma extensão marcada como gratuita não pode ser alterada para paga.

{
    "galleryFlags": [
        "Paid",
        "Preview"
    ]
}            

Marcar uma extensão como paga

Se você quiser vender sua extensão no Marketplace, você pode marcá-la com a bandeira e __BYOLENFORCED tag Paid (começa com dois sublinhados):

{
    "galleryFlags": [
        "Paid"        
    ],
     "tags": [        
        "__BYOLENFORCED"
    ]
}            

Tanto a bandeira quanto __BYOLENFORCED a Paid tag precisam estar presentes para marcar uma extensão como paga no Marketplace. Bring-Your-Own-License (BYOL) significa que o editor da extensão fornece o mecanismo de cobrança e licenciamento para a extensão, pois ela não é fornecida pela Microsoft para extensões de DevOps do Azure. Todas as extensões pagas são necessárias para definir a política de privacidade, a política de suporte e um contrato de licença de usuário final. Além disso, os editores devem fornecer conteúdo para a guia de preços no Marketplace da seguinte maneira:

{
    "content": {
        "details": {
            "path": "overview.md"
        }, 
        "pricing": {
            "path": "pricing.md"
        }
    }
}          

Você também precisa adicionar uma nova seção no manifesto da extensão para substituir o licenciamento pago. No futuro, removemos a verificação de licenciamento paga e não exigimos mais a substituição. Por enquanto, certifique-se de que sua extensão seja exibida conforme o esperado. Cada substituição consiste em um "ID" e um "comportamento". O "ID" deve corresponder ao ID das contribuições definidas no manifesto.

"licensing": {

      "overrides": [

        { "id": "my-hub", "behavior": " AlwaysInclude" }
      ]
    }

Se a sua extensão BYOL paga oferecer um período de avaliação (recomendamos isso), você pode especificar a duração da avaliação em dias:

{
    "galleryproperties": {
        "trialDays": "30"
    } 
}          

Observação

Se você quiser direcionar o Azure DevOps, mas não quiser exibir uma opção de Download para sua extensão, adicione a __DoNotDownload marca (começa com dois sublinhados) ao manifesto da extensão. Se você estiver movendo uma extensão do licenciamento de faturamento e licenciamento oferecidos anteriormente da Microsoft para o modelo BYOL, entre em contato conosco para obter as etapas adequadas.

Exemplo de mais propriedades

{
    "description": "Awesome tools to help you and your team do great things everyday.",
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "license-terms.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/tools"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ]
}

Exemplo de página de detalhes

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

card

Marketplace Q & A - Propriedade CustomerQnASupport

Todas as extensões no Visual Studio Marketplace têm uma seção de perguntas e respostas para permitir conversas públicas individuais entre usuários de extensão e editores. Os editores podem escolher entre perguntas e respostas do Marketplace, problemas do GitHub ou uma URL de perguntas e respostas personalizada. Você pode desabilitar as Perguntas e Respostas no Marketplace usando a propriedade CustomerQnASupport no manifesto.

Experiência padrão (nenhuma alteração no manifesto é necessária)

  • Para extensões com um repositório do GitHub, o Marketplace redireciona os usuários na seção de perguntas e respostas para os problemas associados do GitHub.
  • Para extensões sem um repositório do GitHub, as Perguntas e Respostas do Marketplace estão habilitadas.

Para uma experiência diferente de uma das opções padrão, use a propriedade CustomerQnASupport no manifesto.

{
    "CustomerQnASupport": {
        "enablemarketplaceqna": true,
        "url": "http://uservoice.visualstudio.com"
    } 
}

Propriedades

Propriedades da seção Customer Q & A Support:

  • enablemarketplaceqna - campo booleano, definido como true para marketplace ou Q&A personalizado; false para desabilitar Q&A
  • url - string, URL para perguntas e respostas personalizadas

Exemplos mostrando o uso do suporte a Q & A

Exemplo: Extensão usando Q & A personalizado

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true",
        "url": "http://uservoice.visualstudio.com"
    } 
}

Exemplo: Extensão com repositório do GitHub, mas usando o Marketplace Q & A em vez de problemas do GitHub

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true"
    } 
}

Exemplo: Extensão desabilitando a seção Q & A

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"false"
    } 
}

Escopos

Em sua extensão, você pode definir um ou mais escopos. Esses escopos determinam quais recursos sua extensão pode acessar e as operações que ela tem permissão para executar nesses recursos. Os escopos especificados no manifesto de extensão são os escopos definidos em tokens de acesso emitidos para sua extensão. Para obter mais informações, consulte Autenticação e segurança.

Se nenhum escopo for especificado, as extensões receberão acesso apenas aos dados de perfil de usuário e extensão.

Escopos com suporte

Categoria Escopo Nome Descrição
Pools de agentes vso.agentpools Pools de agentes (leitura) Concede a capacidade de exibir tarefas, pools, filas, agentes e trabalhos atualmente em execução ou concluídos recentemente para agentes.
vso.agentpools_manage Pools de agentes (ler, gerenciar) Concede a capacidade de gerenciar pools, filas e agentes.
vso.environment_manage Ambiente (ler, gerenciar) Concede a capacidade de gerenciar pools, filas, agentes e ambientes.
Análise vso.analytics Análise (leitura) Concede a capacidade de consultar dados analíticos.
Auditoria vso.auditlog Log de auditoria (leitura) Concede a capacidade de ler o log de auditoria aos usuários.
vso.auditstreams_manage Fluxos de auditoria (leitura) Concede aos usuários a capacidade de gerenciar fluxos de auditoria.
Compilar vso.build Build (leitura) Concede a capacidade de acessar artefatos de compilação, incluindo resultados de compilação, definições e solicitações, e a capacidade de receber notificações sobre eventos de compilação por meio de ganchos de serviço.
vso.build_execute Construir (ler e executar) Concede a capacidade de acessar artefatos de compilação, incluindo resultados de compilação, definições e solicitações, e a capacidade de enfileirar uma compilação, atualizar propriedades de compilação e a capacidade de receber notificações sobre eventos de compilação por meio de ganchos de serviço.
Código vso.code Código (leitura) Concede a capacidade de ler código-fonte e metadados sobre confirmações, conjuntos de alterações, ramificações e outros artefatos de controle de versão. Também concede a capacidade de pesquisar código e ser notificado sobre eventos de controle de versão por meio de ganchos de serviço.
vso.code_write Código (leitura e gravação) Concede a capacidade de ler, atualizar e excluir código-fonte, acessar metadados sobre confirmações, conjuntos de alterações, ramificações e outros artefatos de controle de versão. Também concede a capacidade de criar e gerenciar solicitações pull e revisões de código e receber notificações sobre eventos de controle de versão por meio de ganchos de serviço.
vso.code_manage Código (leitura, gravação e gerenciamento) Concede a capacidade de ler, atualizar e excluir código-fonte, acessar metadados sobre confirmações, conjuntos de alterações, ramificações e outros artefatos de controle de versão. Também concede a capacidade de criar e gerenciar repositórios de código, criar e gerenciar solicitações pull e revisões de código, e receber notificações sobre eventos de controle de versão por meio de ganchos de serviço.
vso.code_full Código (completo) Concede acesso total ao código-fonte, metadados sobre confirmações, conjuntos de alterações, ramificações e outros artefatos de controle de versão. Também concede a capacidade de criar e gerenciar repositórios de código, criar e gerenciar solicitações pull e revisões de código, e receber notificações sobre eventos de controle de versão por meio de ganchos de serviço. Também inclui suporte limitado para APIs de OM de cliente.
vso.code_status Código (status) Concede a capacidade de ler e gravar o status da solicitação de confirmação e recepção.
Servidor conectado vso.connected_server Servidor conectado Concede a capacidade de acessar pontos de extremidade necessários a partir de um servidor conectado local.
Qualificações vso.entitlements Direitos (Leitura) Fornece acesso somente leitura ao ponto de extremidade de direitos de licenciamento para obter direitos de conta.
vso.memberentitlementmanagement Gerenciamento de Direitos de Membro (leitura) Concede a capacidade de ler usuários, suas licenças, bem como projetos e extensões que eles podem acessar.
vso.memberentitlementmanagement_write Gerenciamento de Direitos de Membro (gravação) Concede a capacidade de gerenciar usuários, suas licenças, bem como projetos e extensões que eles podem acessar.
Extensões vso.extension Extensões (leitura) Concede a capacidade de ler extensões instaladas.
vso.extension_manage Extensões (ler e gerenciar) Concede a capacidade de instalar, desinstalar e executar outras ações administrativas em extensões instaladas.
vso.extension.data Dados de extensão (leitura) Concede a capacidade de ler dados (configurações e documentos) armazenados por extensões instaladas.
vso.extension.data_write Dados de extensão (leitura e gravação) Concede a capacidade de ler e gravar dados (configurações e documentos) armazenados por extensões instaladas.
Gráfico & identidade vso.graph Gráfico (leitura) Concede a capacidade de ler informações de usuário, grupo, escopo e associação de grupo.
vso.graph_manage Gráfico (gerenciar) Concede a capacidade de ler informações de usuário, grupo, escopo e associação de grupo e adicionar usuários, grupos e gerenciar associações de grupo.
vso.identity Identidade (leitura) Concede a capacidade de ler identidades e grupos.
vso.identity_manage Identidade (gerenciar) Concede a capacidade de ler, escrever e gerenciar identidades e grupos.
Grupo de Máquinas vso.machinegroup_manage Grupo de implantação (ler, gerenciar) Fornece a capacidade de gerenciar grupos de implantação e pools de agentes.
Marketplace vso.gallery Marketplace Concede acesso de leitura a itens e editores públicos e privados.
vso.gallery_acquire Marketplace (adquirir) Concede acesso de leitura e a capacidade de adquirir itens.
vso.gallery_publish Marketplace (publicar) Concede acesso de leitura e a capacidade de carregar, atualizar e compartilhar itens.
vso.gallery_manage Marketplace (gerenciar) Concede acesso de leitura e a capacidade de publicar e gerenciar itens e editores.
Notificações vso.notification Notificações (leitura) Fornece acesso de leitura a assinaturas e metadados de eventos, incluindo valores de campo filtráveis.
vso.notification_write Notificações (gravação) Fornece acesso de leitura e gravação a assinaturas e acesso de leitura a metadados de eventos, incluindo valores de campo filtráveis.
vso.notification_manage Notificações (gerenciar) Fornece acesso de leitura, gravação e gerenciamento a assinaturas e acesso de leitura a metadados de eventos, incluindo valores de campo filtráveis.
vso.notification_diagnostics Notificações (diagnóstico) Fornece acesso a logs de diagnóstico relacionados a notificações e fornece a capacidade de habilitar diagnósticos para assinaturas individuais.
Embalagem vso.packaging Embalagem (leia-se) Concede a capacidade de ler feeds e pacotes.
vso.packaging_write Embalagem (leitura e gravação) Concede a capacidade de criar e ler feeds e pacotes.
vso.packaging_manage Empacotamento (leitura, gravação e gerenciamento) Concede a capacidade de criar, ler, atualizar e excluir feeds e pacotes.
Recursos do Pipeline vso.pipelineresources_use Recursos de Pipeline (uso) Concede a capacidade de aprovar a solicitação de um pipeline para usar um recurso protegido: pool de agentes, ambiente, fila, repositório, arquivos seguros, conexão de serviço e grupo de variáveis.
vso.pipelineresources_manage Recursos de pipeline (usar e gerenciar) Concede a capacidade de gerenciar um recurso protegido ou a solicitação de um pipeline para usar um recurso protegido: pool de agentes, ambiente, fila, repositório, arquivos seguros, conexão de serviço e grupo de variáveis.
Projeto e Equipe vso.project Projeto e equipe (leitura) Concede a capacidade de ler projetos e equipes.
vso.project_write Projeto e equipe (leitura e gravação) Concede a capacidade de ler e atualizar projetos e equipes.
vso.project_manage Projeto e equipe (ler, escrever e gerenciar) Concede a capacidade de criar, ler, atualizar e excluir projetos e equipes.
Versão vso.release Lançamento (leitura) Concede a capacidade de ler artefatos de versão, incluindo releases, definições de release e ambiente release.
vso.release_execute Liberar (ler, gravar e executar) Concede a capacidade de ler e atualizar artefatos de versão, incluindo versões, definições de versão e ambiente de versão, e a capacidade de enfileirar uma nova versão.
vso.release_manage Liberar (ler, gravar, executar e gerenciar) Concede a capacidade de ler, atualizar e excluir artefatos de versão, incluindo versões, definições de versão e ambiente de versão, e a capacidade de enfileirar e aprovar uma nova versão.
Arquivos seguros vso.securefiles_read Arquivos seguros (leitura) Concede a capacidade de ler arquivos seguros.
vso.securefiles_write Arquivos seguros (ler, criar) Concede a capacidade de ler e criar arquivos seguros.
vso.securefiles_manage Arquivos seguros (ler, criar e gerenciar) Concede a capacidade de ler, criar e gerenciar arquivos seguros.
Segurança vso.security_manage Segurança (gerenciar) Concede a capacidade de ler, gravar e gerenciar permissões de segurança.
Conexões de Serviço vso.serviceendpoint Pontos de extremidade de serviço (leitura) Concede a capacidade de ler pontos de extremidade de serviço.
vso.serviceendpoint_query Pontos de extremidade de serviço (leitura e consulta) Concede a capacidade de ler e consultar pontos de extremidade de serviço.
vso.serviceendpoint_manage Pontos de extremidade de serviço (leitura, consulta e gerenciamento) Concede a capacidade de ler, consultar e gerenciar pontos de extremidade de serviço.
Configurações vso.settings Configurações (leitura) Concede a capacidade de ler configurações.
vso.settings_write Configurações (leitura e gravação) Concede a capacidade de criar e ler configurações.
Símbolos vso.symbols Símbolos (ler) Concede a capacidade de ler símbolos.
vso.symbols_write Símbolos (leitura e gravação) Concede a capacidade de ler e escrever símbolos.
vso.symbols_manage Símbolos (ler, gravar e gerenciar) Concede a capacidade de ler, escrever e gerenciar símbolos.
Grupos de tarefas vso.taskgroups_read Grupos de tarefas (leitura) Concede a capacidade de ler grupos de tarefas.
vso.taskgroups_write Grupos de tarefas (ler, criar) Concede a capacidade de ler e criar grupos de tarefas.
vso.taskgroups_manage Grupos de tarefas (ler, criar e gerenciar) Concede a capacidade de ler, criar e gerenciar grupos de tarefas.
Painel da equipe vso.dashboards Painéis de equipe (leitura) Concede a capacidade de ler as informações do painel da equipe.
vso.dashboards_manage Painéis de equipe (gerenciar) Concede a capacidade de gerenciar informações do painel da equipe.
Gerenciamento de Testes vso.test Gerenciamento de testes (leitura) Concede a capacidade de ler planos de teste, casos, resultados e outros artefatos relacionados ao gerenciamento de testes.
vso.test_write Gerenciamento de testes (leitura e gravação) Concede a capacidade de ler, criar e atualizar planos de teste, casos, resultados e outros artefatos relacionados ao gerenciamento de teste.
Threads vso.threads_full Tópicos de RP Concede a capacidade de ler e gravar para puxar threads de comentário de solicitação.
Tokens vso.tokens Tokens de autorização delegada Concede a capacidade de gerenciar tokens de autorização delegados aos usuários.
vso.tokenadministration Administração de Token Concede a capacidade de gerenciar (exibir e revogar) tokens existentes aos administradores da organização.
Perfil do Usuário vso.profile Perfil do usuário (leitura) Concede a capacidade de ler seu perfil, contas, coleções, projetos, equipes e outros artefatos organizacionais de nível superior.
vso.profile_write Perfil de usuário (gravação) Concede a capacidade de escrever no seu perfil.
Grupos de Variáveis vso.variablegroups_read Grupos de variáveis (leitura) Concede a capacidade de ler grupos de variáveis.
vso.variablegroups_write Grupos de variáveis (ler, criar) Concede a capacidade de ler e criar grupos de variáveis.
vso.variablegroups_manage Grupos de variáveis (ler, criar e gerenciar) Concede a capacidade de ler, criar e gerenciar grupos de variáveis.
Wiki vso.wiki Wiki (ler) Concede a capacidade de ler wikis, páginas wiki e anexos wiki. Também concede a capacidade de pesquisar páginas wiki.
vso.wiki_write Wiki (ler e escrever) Concede a capacidade de ler, criar e atualizar wikis, páginas wiki e anexos wiki.
Itens de trabalho vso.work Itens de trabalho (leitura) Concede a capacidade de ler itens de trabalho, consultas, quadros, caminhos de área e iterações e outros metadados relacionados ao controle de item de trabalho. Também concede a capacidade de executar consultas, pesquisar itens de trabalho e receber notificações sobre eventos de item de trabalho por meio de ganchos de serviço.
vso.work_write Itens de trabalho (leitura e gravação) Concede a capacidade de ler, criar e atualizar itens de trabalho e consultas, atualizar metadados do quadro, ler caminhos de área e iterações outros metadados relacionados ao controle de item de trabalho, executar consultas e receber notificações sobre eventos de item de trabalho por meio de ganchos de serviço.
vso.work_full Itens de trabalho (completo) Concede acesso total a itens de trabalho, consultas, listas de pendências, planos e metadados de rastreamento de item de trabalho. Também fornece a capacidade de receber notificações sobre eventos de item de trabalho por meio de ganchos de serviço.
Representação de usuário user_impersonation Representação de usuário Tenha acesso total às APIs REST do Visual Studio Team Services. Solicite e/ou autorize este escopo com cautela, pois ele é muito poderoso!

Alterando o escopo da extensão publicada

Você pode alterar o escopo de uma extensão publicada. Se você instalou anteriormente sua extensão (e autorizou o conjunto anterior de escopos), deverá autorizar os novos escopos antes de atualizar para a versão mais recente.

A seção Ação necessária do hub de configurações de extensão mostra a um usuário que, se houver, as extensões instaladas exigem autorização:

scope-change

Um administrador pode então revisar e autorizar o novo conjunto de escopos:

scope-change-dialog

Destinos de instalação

Como o nome indica, os destinos de instalação definem os produtos e serviços onde você pode instalar sua extensão. Microsoft.VisualStudio.Services é o destino de instalação mais comum e indica que a extensão pode ser instalada no Azure DevOps.

Os destinos de instalação para uma extensão ou integração são especificados por meio do targets campo no manifesto.

Identificadores suportados para extensões:

  • Microsoft.VisualStudio.Services.Cloud: instala nos Serviços de DevOps do Azure
  • Microsoft.TeamFoundation.Server: instala no Azure DevOps Server
  • Microsoft.VisualStudio.Services: instala em ambos. Atalho para Microsoft.VisualStudio.Services.Cloud e Microsoft.TeamFoundation.Server versão [14.2,)

Identificadores suportados para integrações:

  • Microsoft.VisualStudio.Services.Cloud.Integration: integra-se com os Serviços de DevOps do Azure
  • Microsoft.TeamFoundation.Server.Integration: integra-se com o Azure DevOps Server
  • Microsoft.VisualStudio.Services.Integration: integra-se com ambos. Atalho para Microsoft.VisualStudio.Services.Cloud.Integration e Microsoft.TeamFoundation.Server.Integration

Para obter mais informações, consulte Pontos de extensibilidade.

Exemplos de destinos de instalação

Exemplo: extensão que funciona com o Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Exemplo: Extensão que funciona apenas com os Serviços de DevOps do Azure

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        }
    ]
}

Os destinos de instalação também podem ser usados no manifesto de integrações. Por exemplo, produtos, aplicativos ou ferramentas que funcionam com, mas não são instalados no Azure DevOps.

Exemplo: Integração que funciona com o Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ]
}

Exemplo: Integração que só funciona com o Azure DevOps Server

{
    "targets": [
        {
            "id": "Microsoft.TeamFoundation.Server.Integration"
        }
    ]
}

Versões de destino de instalação

Alguns identificadores de destino de instalação, como Microsoft.TeamFoundation.Server e Microsoft.TeamFoundation.Server.Integration, oferecem suporte a um intervalo de versões opcional. Este intervalo de versões opcionais esclarece ainda mais as versões suportadas nas quais a extensão ou integração é suportada.

A versão ou intervalo de versões é especificado através do campo no objeto de version destino de instalação. Esse valor pode ser:

  • Uma versão específica, por exemplo: 15.0 (somente RTM 2017)
  • Uma variedade de versões suportadas, por exemplo: [14.0) (2015 RTM e posterior), [14.3,15.1] (2015 Atualização 3 a 2017 Atualização 1). Os valores do intervalo são refinados usando:
    • [: versão mínima inclusive
    • ]: versão máxima inclusive
    • (: versão mínima exclusiva
    • ): versão máxima exclusiva

Números de versão do Servidor de DevOps do Azure:

Versão Versões Versão
2010 Todos as versões 10.0
2012 Todos as versões 11.0
2013 RTM e atualizações 12.0, 12.1, 12.2, 12.3, 12.4
2015 RTM e atualizações 14.0, 14.1, 14.2, 14.3
2017 RTM e atualizações 15.0, 15.1
2018 RTM e atualizações 16,0
2019 RTM e atualizações 17.0
2020 RTM e atualizações 18.0

Exemplos mostrando versões

Exemplo: extensão que funciona com o Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[15.0,)"
        }
    ]
}

Atalhos

Microsoft.VisualStudio.Services é um atalho para o Azure DevOps.

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

é equivalente a:

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[14.2,)"
        }
    ]
}

Usando metas e demandas de instalação

As metas e demandas de instalação são usadas em conjunto para apresentar aos usuários uma visão correta dos produtos/serviços com os quais sua extensão ou integração é compatível. Por exemplo, especificar um destino de instalação de com uma demanda de Microsoft.VisualStudio.Servicesapi-version/3.0 significa que a extensão funciona com o Azure DevOps.

Dica

Para obter mais informações sobre APIs REST, consulte a Referência da API REST.

Exemplo: Extensão que usa APIs da versão 3.0

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ]
}

Resolve para os seguintes destinos de instalação:

  1. Microsoft.VisualStudio.Services.Cloud
  2. Microsoft.TeamFoundation.ServerVersão: [15.0,)

Exemplo: Integração que usa APIs da versão 2.0

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ],
    "demands": [
        "api-version/2.0"
    ]
}

Resolve para os seguintes destinos de instalação:

  1. Microsoft.VisualStudio.Services.Cloud.Integration
  2. Microsoft.TeamFoundation.Server.IntegrationVersão: [14.0,)

Demandas

As demandas permitem que você especifique recursos e outros recursos exigidos por sua extensão. Você pode usar essas demandas para limitar onde sua extensão pode ser publicada ou instalada.

As demandas são usadas pelo Visual Studio Marketplace para listar os produtos e ambientes com os quais sua extensão é compatível, o que ajuda os clientes a entender se sua extensão funciona com sua versão do Azure DevOps, por exemplo.

Consulte o exemplo a seguir de como as demandas são especificadas no manifesto de extensão.

{
    "demands": [
        "api-version/3.0",
        "contribution/ms.vss-dashboards-web.widget-catalog"
    ]
}

Neste exemplo, a extensão exige a versão 3.0 das APIs, o que significa que ela só pode ser instalada no Azure DevOps. Ele também requer que a ms.vss-dashboards-web extensão (e sua contribuição) seja instalada (e habilitada) na coleção antes que sua widget-catalog extensão possa ser instalada.

Demandas suportadas

Tipo Descrição Verificado no publish? Verificado na instalação?
environment/cloud Requer execução em um ambiente de nuvem Sim Yes
environment/onprem Requer execução em um ambiente local Sim Yes
api-version/{version} Requer uma versão específica da API (mínimo) Não Sim
extension/{id} Requer que uma extensão específica seja instalada/habilitada Não Sim
contribution/{id} Requer que uma contribuição específica esteja disponível Não Sim
contributionType/{id} Requer que um tipo de contribuição específico esteja disponível Não Sim

Observação

  • Use environment/cloud e environment/onprem somente quando sua extensão tiver requisitos relacionados à topologia que exijam a execução nesse ambiente específico.
  • extension, contributione as demandas são avaliadas no momento da instalação e exigem que a extensão especificada já esteja instalada e contributionType habilitada na organização/coleção.

Arquivos

A files seção é onde você faz referência a todos os arquivos que deseja incluir em sua extensão. Você pode adicionar pastas e arquivos individuais:

{
    "files": [
        {
            "path": "hello-world.html", "addressable": true
        },
        {
            "path": "scripts", "addressable": true
        },
        {
            "path": "images/logo.png", "addressable": true, "packagePath": "/"
        }
    ]
}

Propriedades

Propriedades da seção Arquivos:

  • path - Caminho para o recurso no disco, que pode ser relativo ao diretório raiz.
  • endereçável – (opcional) Defina como true se quiser que seu arquivo seja endereçável por URL. O padrão é false.
  • packagePath – (opcional) Caminho para o recurso dentro do pacote. O padrão é o caminho relativo no disco a partir do diretório raiz.
  • contentType – tipo MIME (opcional) do arquivo. O padrão é uma melhor suposição com base na extensão do arquivo e nas configurações do sistema operacional.
  • assetType – (opcional) Especifique o valor do atributo Type da entrada do ativo no manifesto VSIX. Também pode ser uma matriz de cadeias de caracteres, caso em que várias entradas de ativos são adicionadas para esse arquivo. O padrão é packagePath.
  • lang – (opcional) Idioma deste ativo. Os arquivos localizados são servidos com base no cabeçalho Accept-Language. Deixe em branco para indicar que esse arquivo está no idioma padrão (ou fallback). Versões localizadas do mesmo arquivo devem ter o mesmo assetType.

Contribuições

Cada entrada de contribuição tem as seguintes propriedades:

  • id - Um ID de referência (string) para a contribuição. O ID de cada contribuição deve ser exclusivo dentro de uma extensão. Consulte contribuições e tipos de referência.
  • tipo - O ID da contribuiçãoTipo desta contribuição.
  • description - (Opcional) Uma cadeia de caracteres que descreve o que a contribuição está fornecendo.
  • targets - Uma matriz de IDs de contribuição que a contribuição está direcionando (contribuindo). Consulte Direcionando contribuições.
  • propriedades - (Opcional) Um objeto que inclui propriedades para a contribuição, conforme definido no tipo de contribuição.

Para obter mais informações, consulte a visão geral do modelo de contribuição.

Tipos de contribuição

Cada entrada de contribuição tem as seguintes propriedades:

  • id - Um ID de referência (string) para o tipo de contribuição. O ID de cada tipo de contribuição deve ser exclusivo dentro de uma extensão. Consulte contribuições e tipos de referência.
  • name - O nome amigável do tipo de contribuição.
  • description - (Opcional) Uma cadeia de caracteres que descreve com mais detalhes para que serve o tipo de contribuição.
  • propriedades - (Opcional) Um dicionário que mapeia nomes de propriedades para descrições de propriedades . Essas propriedades descrevem as propriedades obrigatórias e opcionais que contribuições desse tipo podem usar.

As descrições de propriedade têm as seguintes propriedades:

  • description - (Opcional) Uma cadeia de caracteres que descreve para que a propriedade é usada.
  • required - (Opcional) Um valor booleano, que se true indica que a propriedade é necessária para todas as contribuições desse tipo.
  • type - O tipo de valor que a propriedade pode ter, que pode ser string, uri, guid, booleano, inteiro, double, dateTime, array ou object.

Para obter mais informações, consulte a visão geral do modelo de contribuição.

Referenciando contribuições e tipos

Use identificadores exclusivos para fazer referência a contribuições e tipos de contribuição. Tipos de referência com a propriedade e referência outras contribuições com a typetargets propriedade.

  • Uma referência de contribuição completa inclui o identificador de editor, o identificador de extensão e o identificador de contribuição/tipo, separados por um ponto (.). Por exemplo, ms.vss-web.hub é o identificador completo para a contribuição com identificador de "hub" na extensão "vss-web" publicada pelo editor "ms" (Microsoft).
  • As referências de contribuição relativa podem ser usadas dentro de um manifesto de extensão para a referência de uma contribuição a outra contribuição ou tipo de contribuição dentro dessa mesma extensão. Nesse caso, os identificadores de editor e extensão NÃO são incluídos, e o identificador é um ponto (.) seguido pelo identificador de contribuição. Por exemplo, ".hub" pode ser usado dentro da extensão "vss-web" mencionada anteriormente como um atalho para "ms.vss-web.hub".

Direcionamento de contribuições

Algumas contribuições funcionam como recipientes visados por outras contribuições.

  • As contribuições de Hub podem ter como alvo Grupos de Hub. Quando uma página é renderizada, a interface do usuário da Web mostra todas as contribuições do Hub destinadas ao grupo de hub selecionado. Os grupos de hub têm como alvo uma coleção de grupos de hubs, que define um conjunto de grupos de hub que aparecem em uma determinada área de navegação, por exemplo, páginas de administração no nível do projeto.
  • Diferentes tipos de contribuições podem segmentar menus: action, hyperlink-action e action-provider. Ações e ações de hiperlink fornecem entradas de item de menu único. Um provedor de ação pode fornecer vários itens de menu dinâmicos. Para um determinado menu, os itens são agregados em todas as contribuições (de qualquer um desses tipos) que visam essa contribuição de menu específica.

Adicionando um ícone de hub

Para obter informações sobre como adicionar um ícone ao hub, confira a orientação do ícone de hub.

Serviços de selo suportados

O Marketplace só oferece suporte a selos dos seguintes serviços confiáveis:

  • api.travis-ci.org/
  • badge.fury.io/
  • badges.frapsoft.com/
  • badges.gitter.im/
  • badges.greenkeeper.io/
  • cdn.travis-ci.org/
  • ci.appveyor.com/
  • codeclimate.com/
  • codecov.io/
  • coveralls.io/
  • david-dm.org/
  • gemnasium.com/
  • img.shields.io/
  • isitmaintained.com/
  • marketplace.visualstudio.com/
  • snyk.io/
  • travis-ci.com/
  • travis-ci.org/
  • vsmarketplacebadges.dev/
  • bithound.io/
  • deepscan.io/
  • githost.io/
  • gitlab.com/
  • opencollective.co/

Observação

Substitua "vsmarketplacebadge.apphb.com" por "vsmarketplacebadges.dev".

Para mostrar um selo de outro serviço, entre em contato com vsmarketplace@microsoft.com.

Exemplo de manifesto

A extensão a seguir contribui com uma ação para o menu de contexto de compilações concluídas e um hub para o grupo de hub de compilação:

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write"
    ],
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}