Partilhar via

Referência do esquema de extensão VSIX 2.0

  • Artigo

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 deste esquema oferece 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 da versão será alterado. Este artigo descreve o formato de manifesto versão 2.0, que é especificado no manifesto definindo o atributo para o Version valor de Version="2.0".

Elemento PackageManifest

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

  • <Metadata> - Metadados e informações publicitárias sobre o próprio pacote. Apenas 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 do aplicativo nos quais ele pode ser instalado. Apenas um único Installation elemento é permitido no manifesto. Um manifesto deve ter um Installation elemento ou este pacote não será instalado em nenhum SKU.

  • <Dependencies> - Uma lista opcional de dependências para este 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 quaisquer outros elementos. Todos os elementos filho não reconhecidos pelo carregador de manifesto são expostos na API do Extension Manager 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 de 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 informações de identificação para este pacote e inclui os seguintes atributos:

    • Id - Este atributo deve ser um ID exclusivo para o pacote escolhido por seu autor. O nome deve ser qualificado da mesma forma que os tipos CLR são namespace: 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 sobre a versão instalada existente.

    • Language - Esse atributo é o idioma padrão para o 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 de idioma neutro que será executada em qualquer versão do Visual Studio. O valor padrão é neutral.

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

  • <DisplayName> - Esse elemento especifica o nome do pacote amigável que é exibido na interface do usuário do Extension Manager. O DisplayName conteúdo é limitado a 50 caracteres.

  • <Description> - Este elemento opcional é uma breve descrição do pacote e seu conteúdo que é exibido na interface do usuário do Extension Manager. O Description conteúdo pode conter qualquer texto desejado, mas é limitado a 1000 caracteres.

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

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

  • <ReleaseNotes> - Este 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> - Este elemento opcional é um caminho relativo para um arquivo de imagem (png, bmp, jpeg, ico) contido no pacote. A imagem do ícone deve ter 32x32 pixels (ou será reduzida para esse tamanho) e aparece na interface do usuário listview. Se nenhum Icon elemento for especificado, a interface do usuário usará um padrão.

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

  • <Tags> - Este elemento opcional lista tags 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> - Este 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 quaisquer 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 do aplicativo nos quais ele pode ser instalado. Esta seção contém os seguintes atributos:

  • Experimental - Defina esse atributo como true se você tiver uma extensão instalada atualmente para todos os usuários, mas estiver desenvolvendo uma versão atualizada no mesmo computador. Por exemplo, se você instalou 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 - Este atributo pode assumir o valor "Global" ou "ProductExtension":

    • "Global" especifica que a instalação não tem escopo para uma SKU específica. 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. Este é o valor padrão.

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

  • InstalledByMsi - Este atributo opcional especifica se este pacote é instalado por um MSI. Pacotes instalados por um MSI são instalados e gerenciados por MSI (programas e recursos) e não pelo Visual Studio Extension Manager. Por padrão, esse atributo é false, que especifica que o pacote não é instalado por um MSI.

  • SystemComponent - Este atributo opcional especifica se este pacote deve ser considerado um componente do sistema. Os componentes do sistema não são exibidos na interface do usuário do Extension Manager e não podem ser atualizados. Por padrão, esse atributo é false, 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> -Este elemento controla o local onde o instalador do VSIX instala o pacote. Se o valor do atributo for "ProductExtension", o pacote deverá ter como destino um SKU, que instalou um arquivo de manifesto Scope como parte de seu conteúdo para anunciar sua disponibilidade para extensões. O <InstallationTarget> elemento tem os seguintes atributos quando o atributo tem o Scope valor explícito ou padrão "ProductExtension":

    • Id - Este 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.IntegratedShell

      • Microsoft.VisualStudio.Pro

      • Microsoft.VisualStudio.Premium

      • Microsoft.VisualStudio.Ultimate

      • Microsoft.VisualStudio.VWDExpress

      • Microsoft.VisualStudio.VPDExpress

      • Microsoft.VisualStudio.VSWinExpress

      • Microsoft.VisualStudio.VSLS

      • My.Shell.App

    • Version - Este atributo especifica um intervalo de versões com as versões mínima e máxima suportadas desta SKU. Um pacote pode detalhar as versões das SKUs suportadas. A notação do intervalo de versões é [10.0 - 11.0], onde

      • [ - versão mínima inclusive.

      • ] - versão máxima inclusive.

      • ( - versão mínima exclusiva.

      • ) - versão máxima exclusiva.

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

      Importante

      Versão 2.0 do esquema VSIX foi introduzido 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 Visual Studio 2012 ou posterior VSIXInstaller, mas somente usando as versões posteriores do instalador.

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

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

Elemento de dependências

Este elemento contém uma lista de dependências que este pacote declara. Se alguma dependência for especificada, esses pacotes (identificados por eles Id) devem ter sido instalados antes.

  • <Dependency> element - Este elemento filho tem os seguintes atributos:

    • Id - Esse atributo deve ser um ID exclusivo para o pacote dependente. Esse valor de identidade deve corresponder ao <Metadata><Identity>Id atributo de um pacote do qual esse pacote é dependente. 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 - Este atributo especifica um intervalo de versões com as versões mínima e máxima suportadas desta SKU. Um pacote pode detalhar as versões das SKUs suportadas. A notação do intervalo de versões é [12.0, 13.0], onde:

      • [ - versão mínima inclusive.

      • ] - versão máxima inclusive.

      • ( - 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 - Este atributo opcional especifica o caminho relativo dentro deste 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é-requisito.

    • 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 tags para cada extensão ou elemento de <Asset> conteúdo exibido por este pacote.

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

    • Type - Tipo de extensão ou conteúdo representado por este 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 as 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 Extension Manager.

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

    • TargetVersion - o intervalo de versões ao qual o ativo em questão se aplica. Usado para enviar várias versões de ativos para diferentes versões do Visual Studio. Requer o Visual Studio 2017.3 ou mais recente para ter 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> tag de início e fim. 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 a compilação para o pacote VSIX. Quando uma compilação é solicitada, o Visual Studio analisa o manifesto para produzir um script de compilação, que é criado usando o MSBuild. Você pode definir determinados valores em tempo de compilação usando espaços reservados que são avaliados antes que o pacote VSIX seja criado. Os espaços reservados são usados para se referir a projetos referenciados no projeto VSIX, propriedades do MSBuild e destinos do MSBuild, mais comumente os destinos que representam os 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 fazer referência a 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 fazer referência a um destino do MSBuild pelo nome do projeto (a Name propriedade da referência do projeto no projeto VSIX) e, em seguida, o nome do 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 em que é usado, o manifesto VSIX contém locais onde a substituição de valores de cadeia de caracteres e coleções de itens são apropriadas. 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, a compilação 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 compilação 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 que o Visual Studio gera para fazer referência a grupos de saída do projeto pelo nome da referência do projeto e, em seguida, o nome do destino do MSBuild, separados por ponto-e-vírgula. Por exemplo, a cadeia de caracteres significa o grupo de |%CurrentProject%;PkgDefProjectOutputGroup| saída PkgDef, que faz referência ao .pkgdef (s) arquivo(s) associado(s) ao projeto VSIX atual. Alguns dos ProjectOutputGroup destinos definidos no arquivo de compilação do sistema Microsoft.Common.CurrentVersion.targets são usados nos manifestos VSIX gerados pelo Visual Studio. Os destinos adicionais do grupo de saída do 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:

ProjectOutputGroup Descrição
BuiltProjectOutputGroup Os arquivos que representam a saída da compilação.
ContentFilesProjectOutputGroup Arquivos não-binários associados ao projeto, como arquivos HTML e CSS.
DebugSymbolsProjectOutputGroup Arquivos de símbolos (.pdb) para depurar uma extensão na instância experimental do Visual Studio.
DocumentationFilesProjectOutputGroup Arquivos de documentação XML.
PkgDefProjectOutputGroup Arquivo(s) de definição de pacote (.pkgdef).
PriFilesOutputGroup Os .pri arquivos de recurso associados a um projeto UWP.
SatelliteDllsProjectOutputGroup Montagens de satélite para recursos localizados.
SDKRedistOutputGroup As pastas redistribuíveis dos SDKs referenciados por um projeto.
SGenFilesOutputGroup Os arquivos GenerateSerializationAssemblies, que são aqueles gerados pelo destino e tarefa GenerateSerializationAssemblies.
SourceFilesProjectOutputGroup Arquivos de código-fonte.
TemplateProjectOutputGroup Modelos de projeto.

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

Em cenários avançados, você pode fazer referência a um destino de compilação ou definir um destino personalizado que deseja chamar 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 em que é usado. Se uma coleção de arquivos, como a saída criada de um projeto, for esperada, um destino que produza 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.

Exemplo de manifesto

<?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>

Confira também