Partilhar via

Referência do manifesto de extensão

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

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 melhorar a experiência. Este artigo mostra como criar um manifesto para sua extensão para o Azure DevOps.

Gorjeta

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

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

Veja o seguinte exemplo 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 obrigatórios

Estas propriedades são necessárias:

Property Description Notas
manifestVersion Um número correspondente à versão do formato de manifesto. deverá ser 1.
ID O identificador da extensão. Th ID é uma cadeia de caracteres que deve ser exclusiva entre extensões do mesmo editor. 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.
Versão Uma cadeia de caracteres especificando a versão de uma extensão. Deve estar 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
Designação Um nome curto e legível por humanos da extensão. Limitado a 200 caracteres. Exemplo: "Fabrikam Agile Board Extension".
editora O identificador do editor. Este 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 Plans, e Azure Artifacts.

Notas:
    - 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 do Azure DevOps para publicar, verifique se sua versão é >= 1.2.8. Talvez seja necessário aprovar a atualização da 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) em contexto conectado, use as categorias declaradas anteriormente.
      - Se você vai compartilhar a extensão diretamente (ou seja, não por meio do Visual Studio Marketplace) com um cliente usando TFS <= 2018, use as seguintes categorias: Código, Planejar e rastrear, Compilar e liberar, Testar, Colaborar e Integrar. Se você precisar compartilhar ambos via Visual Studio Marketplace e diretamente com um cliente TFS <= 2018, precisará ter 2 pacotes de extensão.
Objetivos 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 que indica 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)

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

Property Description Notas
Âmbitos de aplicação Uma matriz de escopos de autorização (strings) listando as permissões exigidas pela sua extensão. Por exemplo, vso.work e vs.code_write 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 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.
exigências Uma matriz de demandas (strings) listando os recursos exigidos pela sua extensão. Por exemplo, api-version/3.0 indica que sua extensão usa APIs da versão 3.0 e, portanto, não pode ser executada em produtos mais antigos que não suportam essa versão. Para obter mais informações, consulte a lista completa de demandas.
baseUri URL base (opcional) para todos os URLs relativos especificados pelas contribuições da extensão. Por exemplo: https://myapp.com/{{account.name}}/. Esta 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.
contributionTypes Uma matriz de tipos de contribuição definidos 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:

Property Description Notas
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 a 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
etiquetas Matriz de tags de cadeia de caracteres para ajudar os usuários a encontrar sua extensão. Exemplos: agile, project management, task timer, e assim por diante.
Imagens Matriz de imagens que não puderam ser incluídas no seu conteúdo. As capturas de tela são mais valiosas quando apresentadas em seu conteúdo e devem ser usadas 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 no seu conteúdo. Cada imagem deve ter 1366x768 pixels. O path de cada item é o caminho para o arquivo na extensão.
Conteúdo 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 sua 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.
ligações 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 utilizador 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 descrevem 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.
crachás Matriz de links para emblemas de metadados externos, como TravisCI, Appveyor e assim por diante, dos sites de selos aprovados Chaves válidas: href - Link ao qual o usuário navega ao selecionar o selo. uri - O URL absoluto da imagem do selo a ser exibido. description - Descrição do crachá, a ser exibido no pairar.
Criação de Marcas Dicionário de propriedades relacionadas com a marca. Chaves válidas: color - cor primária da extensão ou editor; pode ser um 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 Package/Publish/Install.

Marcar uma extensão para estar em pré-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 pré-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 a Paid tag (começa com dois sublinhados):

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

Tanto a Paid bandeira quanto __BYOLENFORCED a 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 não é fornecido 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 em seu manifesto de extensão para substituir o licenciamento pago. No futuro, removemos a verificação de licenciamento pago 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 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"
    } 
}

Nota

Se você quiser direcionar o Azure DevOps, mas não quiser exibir uma opção Download para sua extensão, adicione a __DoNotDownload tag (começa com dois sublinhados) ao manifesto da extensão. Se você estiver movendo uma extensão do licenciamento de faturamento oferecido 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
  • 7 - Branding

cartão

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 P&R 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 (Não são necessárias alterações no manifesto)

  • Para extensões com um repositório GitHub, o Marketplace redireciona os usuários na seção Perguntas e Respostas para os problemas associados do GitHub.
  • Para extensões sem um repositório 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 para a seção Suporte do Cliente Q & A:

  • enablemarketplaceqna - campo booleano, definido como true para marketplace ou P&R personalizadas; false para desativar Perguntas e Respostas
  • url - string, URL para P&R 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 GitHub, mas usando Marketplace Q & A em vez de problemas do GitHub

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

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

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

Âmbitos

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 em seu 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 terão acesso apenas ao perfil do usuário e aos dados da extensão.

Escopos suportados

Categoria Âmbito Nome Descrição
Pools de agentes vso.agentpools Pools de agentes (ler) 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 (ler) Concede a capacidade de consultar dados de análise.
Auditoria vso.auditlog Log de auditoria (ler) Concede a capacidade de ler o log de auditoria aos usuários.
vso.auditstreams_manage Fluxos de auditoria (ler) Concede aos usuários a capacidade de gerenciar fluxos de auditoria.
Compilação vso.build Construir (ler) 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 (lido) 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 (ler, escrever e gerir) 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 OM de cliente.
vso.code_status Código (status) Concede a capacidade de ler e escrever o status da solicitação commit e pull.
Servidor conectado vso.connected_server Servidor conectado Concede a capacidade de acessar os pontos de extremidade necessários a partir de um servidor conectado localmente.
Elegibilidades vso.entitlements Direitos (Ler) Fornece acesso somente leitura ao ponto de extremidade de direitos de licenciamento para obter direitos de conta.
vso.memberentitlementmanagement MemberEntitlement Management (ler) Concede a capacidade de ler usuários, suas licenças, bem como projetos e extensões que eles podem acessar.
vso.memberentitlementmanagement_write MemberEntitlement Management (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 (ler) 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 (ler) Concede a capacidade de ler dados (configurações e documentos) armazenados pelas 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 pelas extensões instaladas.
Gráfico & identidade vso.graph Gráfico (ler) 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, além de adicionar usuários, grupos e gerenciar associações de grupo.
vso.identity Identidade (ler) 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 (aquisição) 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 (ler) 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.
Empacotamento vso.packaging Embalagem (ler) Concede a capacidade de ler feeds e pacotes.
vso.packaging_write Embalagem (leitura e escrita) 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 de 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 Equipa vso.project Projeto e equipa (ler) Concede a capacidade de ler projetos e equipes.
vso.project_write Projeto e equipa (ler e escrever) Concede a capacidade de ler e atualizar projetos e equipes.
vso.project_manage Projeto e equipa (ler, escrever e gerir) Concede a capacidade de criar, ler, atualizar e excluir projetos e equipes.
Lançamento vso.release Lançamento (ler) Concede a capacidade de ler artefatos de versão, incluindo versões, definições de liberação e ambiente de versão.
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 Release (ler, escrever, 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.
Ficheiros Seguros vso.securefiles_read Arquivos seguros (ler) 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, escrever e gerenciar permissões de segurança.
Ligações de Serviço vso.serviceendpoint Pontos de extremidade de serviço (ler) 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 (ler, consultar e gerenciar) Concede a capacidade de ler, consultar e gerenciar pontos de extremidade de serviço.
Definições vso.settings Configurações (ler) 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 escrita) Concede a capacidade de ler e escrever símbolos.
vso.symbols_manage Símbolos (ler, escrever e gerir) Concede a capacidade de ler, escrever e gerenciar símbolos.
Grupos de Tarefas vso.taskgroups_read Grupos de Tarefas (ler) 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 gerir) Concede a capacidade de ler, criar e gerenciar grupos de tarefas.
Painel de Equipa vso.dashboards Painéis da equipe (ler) Concede a capacidade de ler 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.
Gestão de Testes vso.test Gestão de testes (ler) Concede a capacidade de ler planos de teste, casos, resultados e outros artefatos relacionados ao gerenciamento de testes.
vso.test_write Gestão de testes (leitura e escrita) Concede a capacidade de ler, criar e atualizar planos de teste, casos, resultados e outros artefatos relacionados ao gerenciamento de testes.
Tópicos vso.threads_full Tópicos de RP Concede a capacidade de ler e gravar para extrair threads de comentários 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 Tokens Concede a capacidade de gerenciar (exibir e revogar) tokens existentes aos administradores da organização.
Perfil de Utilizador vso.profile Perfil de utilizador (ler) 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 para o seu perfil.
Grupos de variáveis vso.variablegroups_read Grupos de variáveis (ler) 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 gerir) 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 (ler) Concede a capacidade de ler itens de trabalho, consultas, quadros, caminhos de área e iterações e outros metadados relacionados ao rastreamento 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, área de leitura e caminhos de iterações outros metadados relacionados ao rastreamento 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 (completos) Concede acesso total a itens de trabalho, consultas, listas de pendências, planos e metadados de controle 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 do usuário user_impersonation Representação do usuário Tenha acesso total às APIs REST do Visual Studio Team Services. Solicite e/ou consinta este escopo com cautela, pois ele é muito poderoso!

Alteração do âmbito 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 poder atualizar para a versão mais recente.

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

Alteração do âmbito

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

diálogo de alteração de escopo-diálogo

Alvos de instalação

Como o nome indica, os alvos 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 através 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-se 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, 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, suportam 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 version campo no objeto de destino da instalação. Este valor pode ser:

  • Uma versão específica, por exemplo: 15.0 (apenas 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 Azure DevOps Server:

Versão Versões Versão
2010 Todos os lançamentos 10,0
2012 Todos os lançamentos 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 Microsoft.VisualStudio.Services com uma demanda de api-version/3.0 significa que a extensão funciona com o Azure DevOps.

Gorjeta

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,)

Exigências

As demandas permitem que você especifique recursos e outros recursos exigidos pela 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.

Veja 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 widget-catalog contribuição) seja instalada (e habilitada) na coleção antes que sua extensão possa ser instalada.

Demandas suportadas

Tipo Description Verificado na publicação? Verificado na instalação?
environment/cloud Requer execução em um ambiente de nuvem Sim Sim
environment/onprem Requer execução em um ambiente local Sim Sim
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/ativada Não Sim
contribution/{id} Requer a disponibilidade de uma contribuição específica Não Sim
contributionType/{id} Requer a disponibilidade de um tipo de contribuição específico Não Sim

Nota

  • 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 contributionType as demandas são avaliadas no momento da instalação e requer que a extensão especificada já esteja instalada e habilitada na organização/coleção.

Ficheiros

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 seu 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 do diretório raiz.
  • contentType – (opcional) tipo MIME do arquivo. O padrão é um palpite com base na extensão do arquivo e nas configurações do sistema operacional.
  • assetType – (opcional) Especifique o valor do atributo Type da entrada de ativos 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 este 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 este arquivo está no idioma padrão (ou fallback). As 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 único dentro de uma extensão. Veja as referências de contribuições e tipos.
  • type - O ID da contribuiçãoTipo desta contribuição.
  • description - (Opcional) Uma string que descreve o que a contribuição está fornecendo.
  • targets - Uma matriz de IDs de contribuição para os quais a contribuição está direcionada (contribuindo). Consulte Direcionamento de contribuições.
  • properties - (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 único dentro de uma extensão. Veja as referências de contribuições e tipos.
  • name - O nome amigável do tipo de contribuição.
  • description - (Opcional) Uma cadeia de caracteres que descreve mais detalhadamente para que serve o tipo de contribuição.
  • properties - (Opcional) Um dicionário que mapeia nomes de propriedades para descrições de propriedades. Essas propriedades descrevem as propriedades necessárias e opcionais que as contribuições desse tipo podem usar.

As descrições das propriedades 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 deste 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.

Referenciação de contribuições e tipos

Use identificadores exclusivos para fazer referência a contribuições e tipos de contribuições. Tipos de referência com o type imóvel, e referenciar outras contribuições com o targets imóvel.

  • Uma referência de contribuição completa inclui o identificador do 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 relativas à contribuição podem ser utilizadas num 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 estã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".

Direcionar as contribuições

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

  • As contribuições do 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 destinam-se a uma coleção de grupos de hubs, que define um conjunto de grupos de hubs 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ções 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 específica do menu.

Adicionar um ícone de hub

Para obter informações sobre como adicionar um ícone ao seu hub, confira as diretrizes do ícone do hub.

Serviços de crachás suportados

O Marketplace só suporta emblemas dos seguintes serviços fidedignos:

  • 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/

Nota

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

Para mostrar um selo de outro serviço, entre em contato com o Suporte ao Cliente na Comunidade de desenvolvedores.

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