Referência de manifesto de extensão

Azure DevOps Services | 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 aprimorar a experiência. Este artigo mostra como criar um manifesto para sua extensão para 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 ela pode ser executada. Ele também define as contribuições feitas por sua extensão.

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

Para obter informações sobre entradas, consulte ...

Atributos necessários

Essas propriedades são necessárias:

Propriedade	Descrição	Observações
manifestVersion	Um número correspondente à versão do formato do 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 que especifica 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
name	Um nome curto e legível da extensão. Limitado a 200 caracteres.	Exemplo: "Fabrikam Agile Board Extension".
Publicador	O identificador do editor.	Esse identificador deve corresponder ao identificador sob o qual a extensão é publicada. Consulte Criar e gerenciar um editor.
Categorias	Matriz de cadeias de caracteres que representam as categorias às quais sua extensão pertence. Pelo menos uma categoria deve ser fornecida e não há limite para quantas categorias você pode incluir.	Valores válidos: Azure Repos, Azure Boards, Azure Pipelines, Azure Test Planse Azure Artifacts. Observações: - Use a versão >=0.6.3 do tfx-cli se você estiver publicando a extensão programaticamente. - Se você estiver usando a extensão Azure DevOps Extension Tasks 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 Azure DevOps Server 2019 e superior. 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 acompanhar, Compilar e liberar, Testar, Colaborar e Integrar. Se você precisar compartilhar por meio do Visual Studio Marketplace e diretamente com um cliente do TFS <= 2018, precisará ter 2 pacotes de extensão.
destinos	Os produtos e serviços suportados por sua integração ou extensão. Para obter mais informações, consulte destinos de instalação.	Uma matriz de objetos, em que cada objeto tem um id campo indicando um dos seguintes: - Microsoft.VisualStudio.Services (extensões que funcionam com o Azure DevOps ou o TFS), - Microsoft.TeamFoundation.Server (extensão que funciona com o TFS), - Microsoft.VisualStudio.Services.Integration (integrações que funcionam com o Azure DevOps ou o 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

Propriedade	Descrição	Observações
scopes	Uma matriz de escopos de autorização (cadeias de caracteres) listando as permissões exigidas por 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.
Demandas	Uma matriz de demandas (cadeias de caracteres) listando os recursos exigidos por 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 dão suporte a essa versão. Para obter mais informações, consulte a lista completa de demandas.
baseUri	(Opcional) para todos os URLs relativos especificados 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 sua extensão.
Contribuições	Uma série de contribuições para o sistema.
tipos de contribuição	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

Essas 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 "discurso de elevador" da sua extensão - algumas linhas para descrever sua extensão no Marketplace e fazer as pessoas quererem 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 tags de string para ajudar os usuários a encontrar sua extensão.	Exemplos: agile, project management, task timere assim por diante.
Capturas de tela	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 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 não apresentadas 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.	Cada 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. Supõe-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 - Obtenha 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.
Emblemas	Matriz de links para selos de metadados externos, como TravisCI, Appveyor e assim por diante, dos sites de selos aprovados	Chaves válidas: href - Vincule o usuário navega ao selecionar o selo. uri - O URL absoluto da imagem do selo a ser exibida. description - Descrição do emblema, a ser exibido ao passar o mouse.
Marca	Dicionário de propriedades relacionadas à 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 escuras ou claro para cores mais claras.

Marcar uma extensão como 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 as contas compartilhadas pelo editor. Se o editor for verificado, você poderá tornar sua extensão pública definindo o sinalizador no manifesto Public da extensão:

{
    "galleryFlags": [
        "Public"
    ]
}            

Ou:

{
    "public": true
}            

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

Marcar uma extensão para estar em versão prévia

Se sua extensão estiver pronta para os usuários do Marketplace experimentarem, mas você ainda estiver resolvendo alguns bugs ou adicionando funções, marque-a 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, poderá marcá-la com o sinalizador e __BYOLENFORCED a Paid tag (começa com dois sublinhados):

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

Tanto o sinalizador quanto __BYOLENFORCED a Paid tag precisam estar presentes para marcar uma extensão como paga no Marketplace. BYOL (Bring-Your-Own-License) 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 do Azure DevOps. 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. 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 ao manifesto da extensão para substituir o licenciamento pago. No futuro, removeremos a verificação de licenciamento pago e não exigiremos mais a substituição. Por enquanto, certifique-se de que sua extensão seja exibida conforme o esperado. Cada substituição consiste em uma "ID" e um "comportamento". Faça com que a "ID" corresponda à 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ê poderá especificar a duração da avaliação em dias:

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

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 - Capturas de tela
• 5 - Conteúdo (detalhes)
• 6 - Links
• 7 - Branding

Perguntas e respostas do Marketplace - Propriedade CustomerQnASupport

Todas as extensões no Visual Studio Marketplace têm uma seção de Perguntas e Respostas (P e R) 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 P e R 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 GitHub, o Marketplace redireciona os usuários na seção P e R para os problemas associados do GitHub.
• Para extensões sem um repositório GitHub, as Perguntas e Respostas do Marketplace estão habilitadas.

Para obter 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 Suporte de perguntas e respostas do cliente:

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

Exemplos que mostram o uso do suporte de perguntas e respostas

Exemplo: extensão usando perguntas e respostas personalizadas

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

Exemplo: extensão com repositório GitHub, mas usando P e R do Marketplace em vez de problemas do GitHub

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

Exemplo: extensão desativando a seção de perguntas e respostas

{
     "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 permitidas para executar nesses recursos. Os escopos especificados no manifesto da extensão são os escopos definidos nos tokens de acesso emitidos para a extensão. Para obter mais informações, consulte Autenticação e segurança.

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

Escopos com suporte

Categoria	Escopo	Nome	Descrição	Herda de
Segurança avançada	vso.advsec	AdvancedSecurity (leitura)	Concede a capacidade de ler alertas, instâncias de resultado, instâncias de resultado de análise.
	vso.advsec_write	AdvancedSecurity (leitura e gravação)	Concede a capacidade de fazer upload de análises em sarif	vso.advsec
	vso.advsec_manage	AdvancedSecurity (leitura, gravação e gerenciamento)	Concede a capacidade de fazer upload de análises em sarif	vso.advsec_write
Pools de agentes	vso.agentpools	Pools de agentes (leitura)	Concede a capacidade de exibir tarefas, pools, filas, agentes e trabalhos 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.agentpools
	vso.environment_manage	Ambiente (ler, gerenciar)	Concede a capacidade de gerenciar pools, filas, agentes e ambientes.	vso.agentpools_manage
Análise	vso.analytics	Análise (leitura)	Concede a capacidade de consultar dados de análise.
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 a capacidade de gerenciar fluxos de auditoria aos usuários.	vso.auditlog
Compilar	vso.build	Build (leitura)	Concede a capacidade de acessar artefatos de build, incluindo resultados de build, definições e solicitações, e a capacidade de receber notificações sobre eventos de build por meio de ganchos de serviço.	vso.hooks_write
	vso.build_execute	Build (leitura e execução)	Concede a capacidade de acessar artefatos de build, incluindo resultados de build, definições e solicitações, e a capacidade de enfileirar um build, atualizar propriedades de build e a capacidade de receber notificações sobre eventos de build por meio de ganchos de serviço.	vso.build
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.hooks_write
	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 de 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
	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 de 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_write
	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 de 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 do cliente.	vso.code_manage
	vso.code_status	Código (status)	Concede a capacidade de ler e gravar o status de confirmação e solicitação de pull.
Servidor conectado	vso.connected_server	Servidor conectado	Concede a capacidade de acessar os pontos de extremidade necessários de um servidor conectado local.
Qualificações	vso.entitlements	Direitos (Ler)	Fornece acesso somente leitura ao ponto de extremidade de direitos de licenciamento para obter direitos de conta.
	vso.memberentitlementmanagement	Gerenciamento de MemberEntitlement (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 MemberEntitlement (gravação)	Concede a capacidade de gerenciar usuários, suas licenças, bem como projetos e extensões que eles podem acessar.	vso.memberentitlementmanagement
Extensões	vso.extension	Extensões (leitura)	Concede a capacidade de ler extensões instaladas.	vso.profile
	vso.extension_manage	Extensões (leitura e gerenciamento)	Concede a capacidade de instalar, desinstalar e executar outras ações administrativas em extensões instaladas.	vso.extension
	vso.extension.data	Dados de extensão (leitura)	Concede a capacidade de ler dados (configurações e documentos) armazenados por extensões instaladas.	vso.profile
	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.	vso.extension.data
Conexões do Github	vso.githubconnections	GitHub Connections (leitura)	Concede a capacidade de ler conexões do GitHub e dados de repositórios do GitHub.
	vso.githubconnections_manage	GitHub Connections (ler e gerenciar)	Concede a capacidade de ler e gerenciar conexões do GitHub e dados de repositórios do GitHub	vso.githubconnections
Gráfico e 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.graph
	vso.identity	Identidade (leitura)	Concede a capacidade de ler identidades e grupos.
	vso.identity_manage	Identidade (gerenciar)	Concede a capacidade de ler, gravar e gerenciar identidades e grupos.	vso.identity
Grupo de máquinas	vso.machinegroup_manage	Grupo de implantação (leitura, gerenciamento)	Fornece a capacidade de gerenciar grupos de implantação e pools de agentes.	vso.agentpools_manage
Marketplace	vso.gallery	Marketplace	Concede acesso de leitura a itens e editores públicos e privados.	vso.profile
	vso.gallery_acquire	Marketplace (adquirir)	Concede acesso de leitura e a capacidade de adquirir itens.	vso.gallery
	vso.gallery_publish	Marketplace (publicar)	Concede acesso de leitura e a capacidade de carregar, atualizar e compartilhar itens.	vso.gallery
	vso.gallery_manage	Marketplace (gerenciar)	Concede acesso de leitura e a capacidade de publicar e gerenciar itens e editores.	vso.gallery_publish
Notificações	vso.notification	Notificações (leitura)	Fornece acesso de leitura a assinaturas e metadados de eventos, incluindo valores de campo filtráveis.	vso.profile
	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
	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_write
	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.	vso.notification
Embalagem	vso.packaging	Embalagem (leitura)	Concede a capacidade de ler feeds e pacotes.	vso.profile
	vso.packaging_write	Empacotamento (leitura e gravação)	Concede a capacidade de criar e ler feeds e pacotes.	vso.packaging
	vso.packaging_manage	Empacotamento (leitura, gravação e gerenciamento)	Concede a capacidade de criar, ler, atualizar e excluir feeds e pacotes.	vso.packaging_write
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.	vso.pipelineresources_manage
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
	vso.project_manage	Projeto e equipe (leitura, gravação e gerenciamento)	Concede a capacidade de criar, ler, atualizar e excluir projetos e equipes.	vso.project_write
Versão	vso.release	Liberação (leitura)	Concede a capacidade de ler artefatos de versão, incluindo versões, definições de versão e ambiente de versão.	vso.profile
	vso.release_execute	Liberação (leitura, gravação e execução)	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
	vso.release_manage	Liberar (leitura, gravação, execução e gerenciamento)	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.	vso.release_manage
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_read
	vso.securefiles_manage	Arquivos seguros (ler, criar e gerenciar)	Concede a capacidade de ler, criar e gerenciar arquivos seguros.	vso.securefiles_write
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.profile
	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
	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.	vso.serviceendpoint_query
Ganchos de serviço	vso.hooks	Ganchos de serviço (leitura)	Concede a capacidade de ler assinaturas e metadados de gancho de serviço, incluindo eventos, consumidores e ações com suporte. (Não é mais público.)	vso.profile
	vso.hooks_write	Ganchos de serviço (leitura e gravação)	Concede a capacidade de criar e atualizar assinaturas de gancho de serviço e ler metadados, incluindo eventos, consumidores e ações com suporte. (Não é mais público.)	vso.hooks
	vso.hooks_interact	Ganchos de serviço (interagir)	Concede a capacidade de interagir e executar ações em eventos recebidos por meio de ganchos de serviço. (Não é mais público.)	vso.profile
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 (leia-se)	Concede a capacidade de ler símbolos.	vso.profile
	vso.symbols_write	Símbolos (leitura e gravação)	Concede a capacidade de ler e escrever símbolos.	vso.symbols
	vso.symbols_manage	Símbolos (leitura, gravação e gerenciamento)	Concede a capacidade de ler, escrever e gerenciar símbolos.	vso.symbols_write
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_read
	vso.taskgroups_manage	Grupos de tarefas (ler, criar e gerenciar)	Concede a capacidade de ler, criar e gerenciar grupos de tarefas.	vso.taskgroups_write
Painel da equipe	vso.dashboards	Painéis de equipe (leia)	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.	vso.dashboards
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.profile
	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 testes.	vso.test
Threads	vso.threads_full	Tópicos de PR	Concede a capacidade de ler e gravar em threads de comentários de solicitação de pull.
Tokens	vso.tokens	Tokens de autorização delegada	Concede a capacidade de gerenciar tokens de autorização delegada aos usuários.
	vso.tokenadministration	Administração de Tokens	Concede a capacidade de gerenciar (visualizar 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 do usuário (gravação)	Concede a capacidade de escrever em seu perfil.	vso.profile
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_read
	vso.variablegroups_manage	Grupos de variáveis (ler, criar e gerenciar)	Concede a capacidade de ler, criar e gerenciar grupos de variáveis.	vso.variablegroups_write
Wiki	vso.wiki	Wiki (leitura)	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.	vso.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 rastreamento de itens 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.hooks_write
	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 de placa, ler caminhos de área e iterações, outros metadados relacionados ao rastreamento de itens de trabalho, executar consultas e receber notificações sobre eventos de item de trabalho por meio de ganchos de serviço.	vso.work
	vso.work_full	Itens de trabalho (completos)	Concede acesso total a itens de trabalho, consultas, listas de pendências, planos e metadados de acompanhamento de itens de trabalho. Também fornece a capacidade de receber notificações sobre eventos de item de trabalho por meio de ganchos de serviço.	vso.work_write
Representação do usuário	user_impersonation	Representação do usuário	Ter acesso total às APIs REST do Visual Studio Team Services. Solicite e/ou autorize este escopo com cautela, pois é 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), autorize 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:

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

Destinos de instalação

Como o nome indica, os destinos de instalação definem os produtos e serviços em que 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 compatíveis com extensões:

• Microsoft.VisualStudio.Services.Cloud: é instalado em Azure DevOps Services
• Microsoft.TeamFoundation.Server: é instalado em 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 compatíveis com integrações:

• Microsoft.VisualStudio.Services.Cloud.Integration: integra-se com Azure DevOps Services
• Microsoft.TeamFoundation.Server.Integration: integra-se com 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 Azure DevOps Services

{
    "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 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ão opcional. Esse intervalo de versões opcional esclarece ainda mais as versões com suporte nas quais a extensão ou integração é suportada.

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

• Uma versão específica, por exemplo: 15.0 (somente RTM 2017)
• Uma variedade de versões com suporte, por exemplo: [14.0) (2015 RTM e posterior), [14.3,15.1] (Atualização 3 de 2015 a Atualização 1 de 2017). Os valores de 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 para Azure DevOps Server:

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 destinos e demandas de instalação

Os destinos e demandas de instalação são usados juntos 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 Microsoft.VisualStudio.Services instalação com uma demanda de api-version/3.0 significa que a extensão funciona com o Azure DevOps.

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

Demandas suportadas

Tipo	Descrição	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/habilitada	Não	Sim
contribution/{id}	Requer uma contribuição específica disponível	Não	Sim
contributionType/{id}	Requer que um tipo de contribuição específico esteja disponível	Não	Sim

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 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 é uma melhor estimativa 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 ativo no manifesto VSIX. Também pode ser uma matriz de strings, caso em que várias entradas de ativos são adicionadas a 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). As versões localizadas do mesmo arquivo devem ter o mesmo assetType.

Contribuições

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

• id - Uma ID de referência (cadeia de caracteres) para a contribuição. Torne cada ID de contribuição exclusiva em uma extensão. Consulte referenciando contribuições e tipos.
• type - A ID da contribuiçãoTipo dessa contribuição.
• description - (Opcional) Uma string 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 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 - Uma ID de referência (cadeia de caracteres) para o tipo de contribuição. Torne cada ID de tipo de contribuição exclusiva em uma extensão. Consulte referenciando contribuições e tipos.
• 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.
• properties - (Opcional) Um dicionário que mapeia nomes de propriedade para descrições de propriedade. Essas propriedades descrevem as propriedades obrigatórias e opcionais que as contribuições desse tipo podem usar.

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

• description - (Opcional) Uma cadeia de caracteres que descreve para que a propriedade é usada.
• required - (Opcional) Um valor booliano, que, se verdadeiro, 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 cadeia de caracteres, uri, guid, booleano, inteiro, double, dateTime, matriz ou objeto.

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. Faça referência a tipos com a type propriedade e faça referência a outras contribuições com a targets propriedade.

• Uma referência de contribuição completa inclui o identificador do editor, o identificador da 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 o identificador de "hub" na extensão "vss-web" publicada pelo editor "ms" (Microsoft).
• As referências de contribuição relativa podem ser usadas em 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 na extensão "vss-web" mencionada anteriormente como um atalho para "ms.vss-web.hub".

Direcionamento de contribuições

Algumas contribuições atuam como contêineres direcionados por outras contribuições.

• As contribuições do hub podem ter como destino grupos de hub. Quando uma página é renderizada, a interface do usuário da Web mostra todas as contribuições do Hub direcionadas ao grupo de hub selecionado. Os grupos de hubs têm como alvo 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 ter como alvo menus: ação, ação de hiperlink e provedor de ação. 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 as diretrizes do ícone do hub.

Serviços de selos compatíveis

O Marketplace só dá 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/

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