Referência do esquema de extensão VSIX 2.0

Um arquivo de manifesto de implantação VSIX descreve o conteúdo de um pacote VSIX. O formato de arquivo é regido por um esquema. A versão 2.0 desse esquema dá suporte à adição de tipos e atributos personalizados. O esquema do manifesto é extensível. O carregador de manifesto ignora elementos XML e atributos que ele não entende.

Esquema de manifesto do pacote

O elemento raiz do arquivo XML de manifesto é <PackageManifest>. Ele tem um único atributo Version, que é a versão do formato de manifesto. Se forem feitas alterações importantes no formato, o formato de versão será alterado. Este artigo descreve o formato de manifesto versão 2.0, que é especificado no manifesto definindo o Version atributo como o valor de Version="2.0".

Elemento PackageManifest

Dentro do <PackageManifest> elemento raiz, você pode usar os seguintes elementos:

• <Metadata> – Dados de metadados e informações de publicidade sobre o próprio pacote. Somente um Metadata elemento é permitido no manifesto.

• <Installation> - Esta seção define a maneira como esse pacote de extensão pode ser instalado, incluindo os SKUs de aplicativo nos quais ele pode ser instalado. Somente um único Installation elemento é permitido no manifesto. Um manifesto deve ter um Installation elemento ou esse pacote não será instalado em nenhum SKU.

• <Dependencies> – Uma lista opcional de dependências para esse pacote é definida aqui.

• <Assets> - Esta seção contém todos os ativos contidos neste pacote. Sem esta seção, este pacote não exibirá nenhum conteúdo.

• <AnyElement>* - O esquema de manifesto é flexível o suficiente para permitir outros elementos. Todos os elementos filho não reconhecidos pelo carregador de manifesto são expostos na API do Gerenciador de Extensões como objetos XmlElement extras. Usando esses elementos filho, as extensões VSIX podem definir dados adicionais no arquivo de manifesto que o código em execução no Visual Studio pode acessar em tempo de execução. Consulte Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Elemento Metadados

Esta seção são os metadados sobre o pacote, sua identidade e informações de publicidade. <Metadata> contém os seguintes elementos:

• <Identity> - Define as informações de identificação deste pacote e inclui os seguintes atributos:

  • Id - Esse atributo deve ser uma ID exclusiva para o pacote escolhido por seu autor. O nome deve ser qualificado da mesma forma que os tipos CLR são espaçados: Company.Product.Feature.Name. O Id atributo é limitado a 100 caracteres.

  • Version – Define a versão deste pacote e seu conteúdo. Esse atributo segue o formato de controle de versão do assembly CLR: Major.Minor.Build.Revision (1.2.40308.00). Um pacote com um número de versão mais alto é considerado atualizações para o pacote e pode ser instalado na versão instalada existente.

  • Language - Esse atributo é o idioma padrão do pacote e corresponde aos dados textuais neste manifesto. Esse atributo segue a convenção de código de localidade CLR para assemblies de recursos, por exemplo: en-us, en, fr-fr. Você pode especificar neutral para declarar uma extensão neutra em idioma que é executada em qualquer versão do Visual Studio. O valor padrão é neutral.

  • Publisher - Esse atributo identifica o editor desse pacote, seja uma empresa ou um nome individual. O Publisher atributo é limitado a 100 caracteres.

• <DisplayName> - Esse elemento especifica o nome do pacote amigável exibido na interface do usuário do Gerenciador de Extensões. O DisplayName conteúdo é limitado a 50 caracteres.

• <Description> - Esse elemento opcional é uma breve descrição do pacote e seu conteúdo exibido na interface do usuário do Gerenciador de Extensões. O Description conteúdo pode conter qualquer texto desejado, mas é limitado a 1000 caracteres.

• <MoreInfo> - Esse elemento opcional é uma URL para uma página online que contém uma descrição completa desse pacote. O protocolo deve ser especificado como http.

• <License> - Esse elemento opcional é um caminho relativo para um arquivo de licença (.txt, .rtf) contido no pacote.

• <ReleaseNotes> - Esse elemento opcional é um caminho relativo para um arquivo de notas de versão contido no pacote (.txt, .rtf) ou então uma URL para um site que exibe as notas de versão.

• <Icon> - Esse elemento opcional é um caminho relativo para um arquivo de imagem (png, bmp, jpeg, ico) contido no pacote. A imagem do ícone deve ter 32 x 32 pixels (ou é reduzida para esse tamanho) e aparece na interface do usuário da visão de lista. Se nenhum Icon elemento for especificado, a interface do usuário usará um padrão.

• <PreviewImage> - Esse elemento opcional é um caminho relativo para um arquivo de imagem (png, bmp, jpeg) contido no pacote. A imagem de visualização deve ter 200 x 200 pixels e exibida na interface do usuário de detalhes. Se nenhum PreviewImage elemento for especificado, a interface do usuário usará um padrão.

• <Tags> - Esse elemento opcional lista marcas de texto delimitadas por ponto-e-vírgula adicionais que são usadas para dicas de pesquisa. O Tags elemento é limitado a 100 caracteres.

• <GettingStartedGuide> - Esse elemento opcional é um caminho relativo para um arquivo HTML ou uma URL para um site que contém informações sobre como usar a extensão ou o conteúdo dentro deste pacote. Este guia é iniciado como parte de uma instalação.

• <AnyElement>* - O esquema de manifesto é flexível o suficiente para permitir outros elementos. Todos os elementos filho que não são reconhecidos pelo carregador de manifesto são expostos como uma lista de objetos XmlElement. Usando esses elementos filho, as extensões VSIX podem definir dados adicionais no arquivo de manifesto e enumerá-los em tempo de execução.

Elemento de instalação

Esta seção define a maneira como esse pacote pode ser instalado e os SKUs de aplicativo nos quais ele pode instalar. Esta seção contém os seguintes atributos:

• Experimental - Defina esse atributo como true se você tiver uma extensão instalada no momento para todos os usuários, mas estiver desenvolvendo uma versão atualizada no mesmo computador. Por exemplo, se você instalou o MyExtension 1.0 para todos os usuários, mas deseja depurar MyExtension 2.0 no mesmo computador, defina Experimental="true". Esse atributo está disponível no Visual Studio 2015 Atualização 1 e posterior.

• Scope - Esse atributo pode levar o valor "Global" ou "ProductExtension":

  • "Global" especifica que a instalação não está no escopo de um SKU específico. Por exemplo, esse valor é usado quando um SDK de Extensão é instalado.

  • "ProductExtension" especifica que uma Extensão VSIX tradicional (versão 1.0) com escopo para SKUs individuais do Visual Studio está instalada. Esse é o valor padrão.

• AllUsers - Esse atributo opcional especifica se esse pacote será instalado para todos os usuários. Por padrão, esse atributo é falso, o que especifica que o pacote é por usuário. (Quando você define esse valor como true, o usuário instalador deve elevar para o nível de privilégio administrativo para instalar o VSIX resultante.

• InstalledByMsi - Esse atributo opcional especifica se esse pacote é instalado por uma MSI. Os pacotes instalados por uma MSI são instalados e gerenciados por MSI (Programas e Recursos) e não pelo Gerenciador de Extensões do Visual Studio. Por padrão, esse atributo é falso, o que especifica que o pacote não está instalado por uma MSI.

• SystemComponent - Esse atributo opcional especifica se esse pacote deve ser considerado um componente do sistema. Os componentes do sistema não são exibidos na interface do usuário do Gerenciador de Extensões e não podem ser atualizados. Por padrão, esse atributo é falso, o que especifica que o pacote não é um componente do sistema.

• AnyAttribute* - O Installation elemento aceita um conjunto aberto de atributos que serão expostos em tempo de execução como um dicionário de par nome-valor.

• <InstallationTarget> -This elemento controla o local onde o instalador VSIX instala o pacote. Se o valor do Scope atributo for "ProductExtension", o pacote deverá ter como destino um SKU, que instalou um arquivo de manifesto como parte de seu conteúdo para anunciar sua disponibilidade para extensões. O <InstallationTarget> elemento tem os seguintes atributos quando o Scope atributo tem o valor explícito ou padrão "ProductExtension":

  • Id - Esse atributo identifica o pacote. O atributo segue a convenção de namespace: Company.Product.Feature.Name. O Id atributo pode conter apenas caracteres alfanuméricos e é limitado a 100 caracteres. Valores esperados:

    • Microsoft.VisualStudio.Community

    • Microsoft.VisualStudio.Pro

    • Microsoft.VisualStudio.Enterprise

    As extensões direcionadas a SKUs inferiores funcionam com todas as SKUs mais altas. Por exemplo, as extensões direcionadas à Comunidade funcionam com todas as SKUs do Visual Studio e as extensões direcionadas ao Pro também funcionam com o Enterprise.

  • Version - Esse atributo especifica um intervalo de versão com as versões mínimas e máximas com suporte dessa SKU. Um pacote pode detalhar as versões dos SKUs compatíveis. A notação do intervalo de versão é [10.0 - 11.0], em que

    • [ - versão mínima inclusiva.

    • ] – versão máxima inclusiva.

    • ( – versão mínima exclusiva.

    • ) – versão máxima exclusiva.

    • Versão única # – somente a versão especificada.

    Importante

    A versão 2.0 do esquema VSIX foi introduzida no Visual Studio 2012. Para usar esse esquema, você deve ter o Visual Studio 2012 ou posterior instalado no computador e usar o VSIXInstaller.exe que faz parte desse produto. Você pode direcionar versões anteriores do Visual Studio com um VSIXInstaller do Visual Studio 2012 ou posterior, mas apenas usando as versões posteriores do instalador.

    Os números de versão do Visual Studio podem ser encontrados em números de build e datas de lançamento do Visual Studio.

    Ao expressar a versão para versões do Visual Studio, a versão secundária sempre deve ser 0. Por exemplo, o Visual Studio 2017 versão 15.3.26730.0 deve ser expresso como [15.0.26730.0,16.0). Isso só é necessário para os números de versão do Visual Studio 2017 e posteriores.

  • AnyAttribute* - O <InstallationTarget> elemento permite um conjunto aberto de atributos que é exposto em tempo de execução como um dicionário de par nome-valor.

<Installation AllUsers="true">
   <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0,)">
      <ProductArchitecture>amd64</ProductArchitecture>
    </InstallationTarget>
   <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0,)">
     <ProductArchitecture>arm64</ProductArchitecture>
   </InstallationTarget>
</Installation>

Elemento Dependencies

Esse elemento contém uma lista de dependências declaradas por esse pacote. Se alguma dependência for especificada, esses pacotes (identificados por seus Id) deverão ter sido instalados antes.

• <Dependency> elemento – Esse elemento filho tem os seguintes atributos:

  • Id - Esse atributo deve ser uma ID exclusiva para o pacote dependente. Esse valor de identidade deve corresponder ao <Metadata><Identity>Id atributo de um pacote do qual esse pacote depende. O Id atributo segue a convenção de namespace: Company.Product.Feature.Name. O atributo pode conter apenas caracteres alfanuméricos e é limitado a 100 caracteres.

  • Version - Esse atributo especifica um intervalo de versão com as versões mínimas e máximas com suporte dessa SKU. Um pacote pode detalhar as versões dos SKUs compatíveis. A notação do intervalo de versão é [12.0, 13.0], em que:

    • [ - versão mínima inclusiva.

    • ] – versão máxima inclusiva.

    • ( – versão mínima exclusiva.

    • ) – versão máxima exclusiva.

    • Versão única # – somente a versão especificada.

  • DisplayName - Esse atributo é o nome de exibição do pacote dependente, que é usado em elementos da interface do usuário, como caixas de diálogo e mensagens de erro. O atributo é opcional, a menos que o pacote dependente seja instalado pelo MSI.

  • Location - Esse atributo opcional especifica o caminho relativo dentro desse VSIX para um pacote VSIX aninhado ou uma URL para o local de download da dependência. Esse atributo é usado para ajudar o usuário a localizar o pacote de pré-requisitos.

  • AnyAttribute* - O Dependency elemento aceita um conjunto aberto de atributos que serão expostos em tempo de execução como um dicionário de par nome-valor.

Elemento Assets

Esse elemento contém uma lista de <Asset> marcas para cada elemento de extensão ou conteúdo exibido por esse pacote.

• <Asset> - Esse elemento contém os seguintes atributos e elementos:

  • Type - Tipo de extensão ou conteúdo representado por esse elemento. Cada <Asset> elemento deve ter um único Type, mas vários <Asset> elementos podem ter o mesmo Type. Esse atributo deve ser representado como um nome totalmente qualificado, de acordo com convenções de namespace. Os tipos conhecidos são:

    1. Microsoft.VisualStudio.VsPackage

    2. Microsoft.VisualStudio.MefComponent

    3. Microsoft.VisualStudio.ToolboxControl

    4. Microsoft.VisualStudio.Samples

    5. Microsoft.VisualStudio.ProjectTemplate

    6. Microsoft.VisualStudio.ItemTemplate

    7. Microsoft.VisualStudio.Assembly

       Você pode criar seus próprios tipos e dar-lhes nomes exclusivos. Em tempo de execução dentro do Visual Studio, seu código pode enumerar e acessar esses tipos personalizados por meio da API do Gerenciador de Extensões.

  • Path - o caminho relativo para o arquivo ou pasta dentro do pacote que contém o ativo.

  • TargetVersion - o intervalo de versão ao qual o ativo fornecido se aplica. Usado para enviar várias versões de ativos para versões diferentes do Visual Studio. Requer que o Visual Studio 2017.3 ou mais recente tenha efeito.

  • AnyAttribute* - Um conjunto aberto de atributos que é exposto em tempo de execução como um dicionário de pares nome-valor.

    <AnyElement>* - Qualquer conteúdo estruturado é permitido entre uma <Asset> marca de início e de término. Todos os elementos são expostos como uma lista de objetos XmlElement. As extensões VSIX podem definir metadados estruturados específicos do tipo no arquivo de manifesto e enumerá-los em tempo de execução.

Sintaxe de espaço reservado para manifestos de extensão

O .vsixmanifest arquivo define o build para o pacote VSIX. Quando um build é solicitado, o Visual Studio analisa o manifesto para produzir um script de build, que é criado usando o MSBuild. Você pode definir determinados valores no tempo de build usando espaços reservados que são avaliados antes que o pacote VSIX seja criado. Espaços reservados são usados para se referir a projetos referenciados no projeto VSIX, propriedades do MSBuild e destinos do MSBuild, geralmente os destinos que representam grupos de saída do projeto. Os grupos de saída do projeto representam coleções de arquivos associados a um projeto e alguns deles podem ser incluídos em um pacote VSIX. Por exemplo, PkgDefProjectOutputGroup, BuiltProjectOutputGroup ou SatelliteDllsProjectOutputGroup.

Para fazer referência a uma propriedade definida no projeto VSIX, use a mesma sintaxe que faria no próprio arquivo de projeto. $(PropertyName)

O token %CurrentProject% especial faz referência ao projeto VSIX. Você pode referenciar outros projetos referenciados em seu projeto VSIX usando Name o ProjectReference elemento em um arquivo de projeto VSIX, cercado por símbolos de pipe (|). Por exemplo, |ProjectTemplate1|.

Você pode referenciar um destino msbuild pelo nome do projeto (a Name propriedade da referência do projeto no projeto VSIX) e, em seguida, o nome de destino. Por exemplo, para fazer referência ao Version destino em um dos projetos referenciados em um pacote VSIX, use a sintaxe |ProjectName;Version|. O destino deve ter um Outputs valor que corresponda ao contexto no qual é usado; o manifesto VSIX contém locais em que a substituição de valores de cadeia de caracteres e coleções de itens é apropriada. Por exemplo, a cadeia de caracteres Version no manifesto pode ser substituída da seguinte maneira:

<Identity Id="0000000-0000-0000-0000-000000000000" Version="|%CurrentProject%;GetVsixVersion|" Language="en-US" Publisher="Company" />

Nesse caso, deve haver um GetVsixVersion destino no projeto VSIX que deve retornar uma cadeia de caracteres simples. Por exemplo

<Target Name="GetVsixVersion" Outputs="$(_VsixVersion)">
  <PropertyGroup>
     <_VsixVersion>1.2.3.4</_VsixVersion>
  </PropertyGroup>
</Target>

Os espaços reservados são usados para criar o arquivo de manifesto VSIX correto com o projeto VSIX no estilo SDK. Suponha que você especifique a versão de destino do Visual Studio com a propriedade 'TargetFramework':

• <TargetFramework>vs17.0</TargetFramework> // Target Visual Studio 2022 version 17.0
• <TargetFramework>vs16.10</TargetFramework> // Target Visual Studio 2019 version 16.10

Com base na estrutura de destino, o build do VSIX transforma os valores definidos no arquivo de manifesto de extensão da seguinte maneira. Para a seguinte sintaxe no arquivo de manifesto:

<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="|%CurrentProject%;GetInstallationTargetVersion|" />

A saída usada no código MSBuild do projeto VSIX é:

    <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 18.0)">
      <ProductArchitecture>amd64</ProductArchitecture>
    </InstallationTarget>

E, para o seguinte código em um manifesto de extensão:

 <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="|%CurrentProject%;GetPrerequisiteTargetVersion|" DisplayName="Visual Studio core editor" />

O código de build do projeto é:

<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[17.0, 18.0)" DisplayName="Visual Studio core editor" />

Essa funcionalidade também é usada nos arquivos de manifesto VSIX gerados pelo Visual Studio para referenciar grupos de saída do projeto pelo nome da referência do projeto e, em seguida, pelo nome do destino do MSBuild, separado por um ponto-e-vírgula. Por exemplo, a cadeia de caracteres |%CurrentProject%;PkgDefProjectOutputGroup| significa o grupo de saída PkgDef, que faz referência aos arquivos associados .pkgdef ao projeto VSIX atual. Alguns dos ProjectOutputGroup destinos definidos no arquivo de build do sistema Microsoft.Common.CurrentVersion.targets são usados nos manifestos VSIX gerados pelo Visual Studio. Destinos adicionais do grupo de saída de projeto disponíveis no projeto VSIX são definidos em Microsoft.VsSDK.targets. A tabela a seguir mostra os grupos de saída do projeto definidos:

O sistema de build popula esses grupos de saída com os arquivos apropriados de acordo com a lógica de build padrão. Em um build personalizado, você pode adicionar itens aos grupos de saída do projeto definindo o BeforeTargets atributo em seu destino como um dos destinos anteriores e, no destino, siga o código para os destinos listados anteriormente como exemplos de como usar a BuiltProjectOutputGroupKeyOutput tarefa para definir as saídas.

Em cenários avançados, você pode referenciar um destino de build ou definir um destino personalizado que deseja ser invocado e usar a sintaxe descrita aqui para inserir valores para qualquer elemento no manifesto VSIX. Um destino deve ter o parâmetro de saída apropriado que corresponda à expectativa do contexto no qual ele é usado. Se uma coleção de arquivos como a saída compilada de um projeto for esperada, um destino que gera os itens necessários do MSBuild será necessário. Os destinos criados do grupo de saída do projeto mencionados anteriormente podem ser usados como exemplos ao criar seus próprios destinos.

Manifesto de exemplo

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest Version="2.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011" xmlns:d="http://schemas.microsoft.com/developer/vsx-schema-design/2011">
  <Metadata>
    <Identity Id="0000000-0000-0000-0000-000000000000" Version="1.0" Language="en-US" Publisher="Company" />
    <DisplayName>Test Package</DisplayName>
    <Description>Information about my package</Description>
    <MoreInfo>http://www.fabrikam.com/Extension1/</MoreInfo>
    <License>eula.rtf</License>
    <ReleaseNotes>notes.txt</ReleaseNotes>
    <Icon>Images\icon.png</Icon>
    <PreviewImage>Images\preview.png</PreviewImage>
  </Metadata>
  <Installation InstalledByMsi="false" AllUsers="false" SystemComponent="false" Scope="ProductExtension">
    <InstallationTarget Id="Microsoft.VisualStudio.Pro" Version="[11.0, 12.0]" />
  </Installation>
  <Dependencies>
    <Dependency Id="Microsoft.Framework.NDP" DisplayName="Microsoft .NET Framework" d:Source="Manual" Version="[4.5,)" />
    <Dependency Id="Microsoft.VisualStudio.MPF.12.0" DisplayName="Visual Studio MPF 12.0" d:Source="Installed" Version="[12.0]" />
  </Dependencies>
  <Assets>
    <Asset Type="Microsoft.VisualStudio.VsPackage" d:Source="Project" d:ProjectName="%CurrentProject%" Path="|%CurrentProject%;PkgdefProjectOutputGroup|" />
  </Assets>
</PackageManifest>

Consulte também

• Fornecer extensões do Visual Studio