Referencia del esquema de extensión VSIX 2.0

  • Artículo

Un archivo de manifiesto de implementación VSIX describe el contenido de un paquete VSIX. El formato de archivo se rige por un esquema. La versión 2.0 de este esquema admite la adición de tipos y atributos personalizados. El esquema del manifiesto es extensible. El cargador de manifiestos omite los elementos y atributos XML que no entiende.

Esquema del manifiesto del paquete

El elemento raíz del archivo XML de manifiesto es <PackageManifest>. Tiene un único atributo Version, que es la versión del formato de manifiesto. Si se realizan cambios importantes en el formato, se cambia el formato de versión. En este artículo se describe la versión 2.0 del formato de manifiesto, que se especifica en el manifiesto estableciendo el Version atributo en el valor de Version="2.0".

Elemento PackageManifest

Dentro del <PackageManifest> elemento raíz, puede usar los siguientes elementos:

  • <Metadata> - Metadatos e información de publicidad sobre el propio paquete. Solo se permite un Metadata elemento en el manifiesto.

  • <Installation> - En esta sección se define la forma en que se puede instalar este paquete de extensión, incluidas las SKU de aplicación en las que se puede instalar. Solo se permite un solo Installation elemento en el manifiesto. Un manifiesto debe tener un Installation elemento o este paquete no se instalará en ninguna SKU.

  • <Dependencies> - Aquí se define una lista opcional de dependencias para este paquete.

  • <Assets> - Esta sección contiene todos los recursos contenidos en este paquete. Sin esta sección, este paquete no mostrará ningún contenido.

  • <AnyElement>* - El esquema de manifiesto es lo suficientemente flexible como para permitir cualquier otro elemento. Los elementos secundarios no reconocidos por el cargador de manifiestos se exponen en la API del Administrador de extensiones como objetos XmlElement adicionales. Con estos elementos secundarios, las extensiones VSIX pueden definir datos adicionales en el archivo de manifiesto al que el código que se ejecuta en Visual Studio puede tener acceso en tiempo de ejecución. Consulte Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Elemento Metadata

Esta sección es los metadatos sobre el paquete, su identidad e información de publicidad. <Metadata> contiene los siguientes elementos:

  • <Identity> - Define la información de identificación de este paquete e incluye los siguientes atributos:

    • Id : este atributo debe ser un identificador único para el paquete elegido por su autor. El nombre debe calificarse de la misma manera que los tipos CLR están espacio de nombres: Company.Product.Feature.Name. El Id atributo está limitado a 100 caracteres.

    • Version - Define la versión de este paquete y su contenido. Este atributo sigue el formato de control de versiones del ensamblado CLR: Major.Minor.Build.Revision (1.2.40308.00). Un paquete con un número de versión superior se considera actualizaciones del paquete y se puede instalar a través de la versión instalada existente.

    • Language : este atributo es el idioma predeterminado del paquete y corresponde a los datos textuales de este manifiesto. Este atributo sigue la convención de código de configuración regional clR para los ensamblados de recursos, por ejemplo: en-us, en, fr-fr. Puede especificar neutral para declarar una extensión independiente del lenguaje que se ejecutará en cualquier versión de Visual Studio. El valor predeterminado es neutral.

    • Publisher : este atributo identifica al publicador de este paquete, ya sea una empresa o un nombre individual. El Publisher atributo está limitado a 100 caracteres.

  • <DisplayName> : este elemento especifica el nombre del paquete descriptivo que se muestra en la interfaz de usuario del Administrador de extensiones. El DisplayName contenido está limitado a 50 caracteres.

  • <Description> - Este elemento opcional es una breve descripción del paquete y su contenido que se muestra en la interfaz de usuario del Administrador de extensiones. El Description contenido puede contener cualquier texto que desee, pero está limitado a 1000 caracteres.

  • <MoreInfo> - Este elemento opcional es una dirección URL a una página en línea que contiene una descripción completa de este paquete. El protocolo debe especificarse como http.

  • <License> : este elemento opcional es una ruta de acceso relativa a un archivo de licencia (.txt, .rtf) incluido en el paquete.

  • <ReleaseNotes> : este elemento opcional es una ruta de acceso relativa a un archivo de notas de la versión incluido en el paquete (.txt, .rtf) o, de lo contrario, una dirección URL a un sitio web que muestra las notas de la versión.

  • <Icon> - Este elemento opcional es una ruta de acceso relativa a un archivo de imagen (png, bmp, jpeg, ico) incluido en el paquete. La imagen de icono debe ser de 32 x 32 píxeles (o se reducirá a ese tamaño) y aparecerá en la interfaz de usuario de listview. Si no se especifica ningún Icon elemento, la interfaz de usuario usa un valor predeterminado.

  • <PreviewImage> - Este elemento opcional es una ruta de acceso relativa a un archivo de imagen (png, bmp, jpeg) incluido en el paquete. La imagen de vista previa debe ser de 200 x 200 píxeles y se muestra en la interfaz de usuario de detalles. Si no se especifica ningún PreviewImage elemento, la interfaz de usuario usa un valor predeterminado.

  • <Tags> : este elemento opcional enumera etiquetas de texto delimitadas por punto y coma adicionales que se usan para sugerencias de búsqueda. El Tags elemento está limitado a 100 caracteres.

  • <GettingStartedGuide> : este elemento opcional es una ruta de acceso relativa a un archivo HTML o una dirección URL a un sitio web que contiene información sobre cómo usar la extensión o el contenido dentro de este paquete. Esta guía se inicia como parte de una instalación.

  • <AnyElement>* - El esquema de manifiesto es lo suficientemente flexible como para permitir cualquier otro elemento. Los elementos secundarios que no reconoce el cargador de manifiestos se exponen como una lista de objetos XmlElement. Con estos elementos secundarios, las extensiones VSIX pueden definir datos adicionales en el archivo de manifiesto y enumerarlos en tiempo de ejecución.

Elemento Installation

En esta sección se define la forma en que se puede instalar este paquete y las SKU de aplicación en las que se puede instalar. Esta sección contiene los siguientes atributos:

  • Experimental - Establezca este atributo en true si tiene una extensión que está instalada actualmente para todos los usuarios, pero está desarrollando una versión actualizada en el mismo equipo. Por ejemplo, si ha instalado MyExtension 1.0 para todos los usuarios, pero quiere depurar MyExtension 2.0 en el mismo equipo, establezca Experimental="true". Este atributo está disponible en Visual Studio 2015 Update 1 y versiones posteriores.

  • Scope : este atributo puede tomar el valor "Global" o "ProductExtension":

    • "Global" especifica que la instalación no tiene como ámbito una SKU específica. Por ejemplo, este valor se usa cuando se instala un SDK de extensión.

    • "ProductExtension" especifica que se instala una extensión VSIX tradicional (versión 1.0) con ámbito de SKU individuales de Visual Studio. Este es el valor predeterminado.

  • AllUsers : este atributo opcional especifica si este paquete se instalará para todos los usuarios. De forma predeterminada, este atributo es false, que especifica que el paquete es por usuario. (Cuando se establece este valor en true, el usuario de instalación debe elevar al nivel de privilegios administrativos para instalar el VSIX resultante.

  • InstalledByMsi : este atributo opcional especifica si un MSI instala este paquete. Los paquetes instalados por un MSI se instalan y administran mediante MSI (Programas y características) y no mediante el Administrador de extensiones de Visual Studio. De forma predeterminada, este atributo es false, que especifica que un MSI no instala el paquete.

  • SystemComponent : este atributo opcional especifica si este paquete debe considerarse un componente del sistema. Los componentes del sistema no se muestran en la interfaz de usuario del Administrador de extensiones y no se pueden actualizar. De forma predeterminada, este atributo es false, que especifica que el paquete no es un componente del sistema.

  • AnyAttribute* - El Installation elemento acepta un conjunto abierto de atributos que se expondrá en tiempo de ejecución como diccionario de pares nombre-valor.

  • <InstallationTarget> -Este elemento controla la ubicación donde el instalador VSIX instala el paquete. Si el valor del Scope atributo es "ProductExtension", el paquete debe tener como destino una SKU, que ha instalado un archivo de manifiesto como parte de su contenido para anunciar su disponibilidad a las extensiones. El <InstallationTarget> elemento tiene los atributos siguientes cuando el Scope atributo tiene el valor explícito o predeterminado "ProductExtension":

    • Id : este atributo identifica el paquete. El atributo sigue la convención de espacio de nombres: Company.Product.Feature.Name. El Id atributo solo puede contener caracteres alfanuméricos y está 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 un intervalo de versiones con las versiones mínimas y máximas admitidas de esta SKU. Un paquete puede detallar las versiones de las SKU que admite. La notación del intervalo de versiones es [10.0 - 11.0], donde

      • [ - versión mínima inclusiva.

      • ] : versión máxima inclusiva.

      • ( : versión mínima exclusiva.

      • ) : versión máxima exclusiva.

      • Versión única # : solo la versión especificada.

      Importante

      La versión 2.0 del esquema VSIX se introdujo en Visual Studio 2012. Para usar este esquema, debe tener Visual Studio 2012 o posterior instalado en el equipo y usar VSIXInstaller.exe que forma parte de ese producto. Puede tener como destino versiones anteriores de Visual Studio con un VSIXInstaller de Visual Studio 2012 o posterior, pero solo con las versiones posteriores del instalador.

      Los números de versión de Visual Studio 2017 se pueden encontrar en Números de compilación y fechas de lanzamiento de Visual Studio.

      Al expresar la versión de las versiones de Visual Studio 2017, la versión secundaria siempre debe ser 0. Por ejemplo, la versión 15.3.26730.0 de Visual Studio 2017 debe expresarse como [15.0.26730.0,16.0). Esto solo es necesario para los números de versión de Visual Studio 2017 y versiones posteriores.

    • AnyAttribute* : el <InstallationTarget> elemento permite un conjunto abierto de atributos que se expone en tiempo de ejecución como diccionario de pares nombre-valor.

Elemento dependencies

Este elemento contiene una lista de dependencias que declara este paquete. Si se especifican dependencias, esos paquetes (identificados por sus Id) deben haberse instalado antes.

  • <Dependency> element: este elemento secundario tiene los atributos siguientes:

    • Id : este atributo debe ser un identificador único para el paquete dependiente. Este valor de identidad debe coincidir con el <Metadata><Identity>Id atributo de un paquete del que depende este paquete. El Id atributo sigue la convención de espacio de nombres: Company.Product.Feature.Name. El atributo solo puede contener caracteres alfanuméricos y está limitado a 100 caracteres.

    • Version : este atributo especifica un intervalo de versiones con las versiones mínimas y máximas admitidas de esta SKU. Un paquete puede detallar las versiones de las SKU que admite. La notación del intervalo de versiones es [12.0, 13.0], donde:

      • [ - versión mínima inclusiva.

      • ] : versión máxima inclusiva.

      • ( : versión mínima exclusiva.

      • ) : versión máxima exclusiva.

      • Versión única # : solo la versión especificada.

    • DisplayName : este atributo es el nombre para mostrar del paquete dependiente, que se usa en elementos de la interfaz de usuario, como cuadros de diálogo y mensajes de error. El atributo es opcional a menos que MSI instale el paquete dependiente.

    • Location : este atributo opcional especifica la ruta de acceso relativa de este VSIX a un paquete VSIX anidado o una dirección URL a la ubicación de descarga de la dependencia. Este atributo se usa para ayudar al usuario a localizar el paquete de requisitos previos.

    • AnyAttribute* - El Dependency elemento acepta un conjunto abierto de atributos que se expondrá en tiempo de ejecución como diccionario de pares nombre-valor.

Elemento Assets

Este elemento contiene una lista de <Asset> etiquetas para cada extensión o elemento de contenido que expone este paquete.

  • <Asset> : este elemento contiene los siguientes atributos y elementos:

    • Type - Tipo de extensión o contenido representado por este elemento. Cada <Asset> elemento debe tener un solo Type, pero varios <Asset> elementos pueden tener el mismo Type. Este atributo debe representarse como un nombre completo, según las convenciones de espacio de nombres. Los tipos conocidos son:

      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

        Puede crear sus propios tipos y asignarles nombres únicos. En tiempo de ejecución dentro de Visual Studio, el código puede enumerar y acceder a estos tipos personalizados a través de la API del Administrador de extensiones.

    • Path : la ruta de acceso relativa al archivo o carpeta dentro del paquete que contiene el recurso.

    • TargetVersion : el intervalo de versiones al que se aplica el recurso especificado. Se usa para enviar varias versiones de recursos a distintas versiones de Visual Studio. Requiere que Visual Studio 2017.3 o posterior tenga efecto.

    • AnyAttribute* : conjunto abierto de atributos que se expone en tiempo de ejecución como un diccionario de pares nombre-valor.

      <AnyElement>* - Se permite cualquier contenido estructurado entre una <Asset> etiqueta begin y end. Todos los elementos se exponen como una lista de objetos XmlElement. Las extensiones VSIX pueden definir metadatos específicos del tipo estructurado en el archivo de manifiesto y enumerarlos en tiempo de ejecución.

Sintaxis de marcador de posición para manifiestos de extensión

El .vsixmanifest archivo define la compilación para el paquete VSIX. Cuando se solicita una compilación, Visual Studio analiza el manifiesto para generar un script de compilación, que se compila mediante MSBuild. Puede establecer determinados valores en tiempo de compilación mediante marcadores de posición que se evalúan antes de compilar el paquete VSIX. Los marcadores de posición se usan para hacer referencia a proyectos a los que se hace referencia en el proyecto VSIX, las propiedades de MSBuild y los destinos de MSBuild, normalmente los destinos que representan los grupos de salida del proyecto. Los grupos de salida del proyecto representan colecciones de archivos asociados a un proyecto y algunos de ellos se pueden incluir en un paquete VSIX. Por ejemplo, PkgDefProjectOutputGroup, BuiltProjectOutputGroup o SatelliteDllsProjectOutputGroup.

Para hacer referencia a una propiedad definida en el proyecto VSIX, use la misma sintaxis que lo haría en el propio archivo de proyecto, $(PropertyName).

El token %CurrentProject% especial hace referencia al proyecto VSIX. Puede hacer referencia a otros proyectos a los que se hace referencia en el proyecto VSIX mediante el uso Name del ProjectReference elemento en un archivo de proyecto VSIX, rodeado de símbolos de canalización (|). Por ejemplo, |ProjectTemplate1|.

Puede hacer referencia a un destino de MSBuild por el nombre del proyecto (la Name propiedad de la referencia del proyecto en el proyecto VSIX) y, a continuación, el nombre de destino. Por ejemplo, para hacer referencia al Version destino en uno de los proyectos a los que se hace referencia en un paquete VSIX, use la sintaxis |ProjectName;Version|. El destino debe tener un Outputs valor que coincida con el contexto en el que se usa; el manifiesto VSIX contiene lugares donde la sustitución de valores de cadena y colecciones de elementos son adecuadas. Por ejemplo, la cadena Version del manifiesto podría reemplazarse de la siguiente manera:

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

En ese caso, debe haber un GetVsixVersion destino en el proyecto VSIX que debe devolver una cadena simple. Por ejemplo,

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

Los marcadores de posición se usan para crear el archivo de manifiesto VSIX correcto con el proyecto VSIX de estilo SDK. Supongamos que especifica la versión de destino de Visual Studio con la propiedad "TargetFramework":

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

En función de la plataforma de destino, la compilación VSIX transforma los valores definidos en el archivo de manifiesto de extensión como se indica a continuación. Para la sintaxis siguiente en el archivo de manifiesto:

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

La salida usada en el código de MSBuild del proyecto VSIX es:

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

Además, para el código siguiente en un manifiesto de extensión:

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

El código de compilación del proyecto es:

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

Esta funcionalidad también se usa en los archivos de manifiesto VSIX que Visual Studio genera para hacer referencia a los grupos de salida del proyecto por el nombre de la referencia del proyecto y, a continuación, el nombre del destino de MSBuild, separados por punto y coma. Por ejemplo, la cadena |%CurrentProject%;PkgDefProjectOutputGroup| significa el grupo de salida PkgDef, que hace referencia a los .pkgdef archivos asociados al proyecto VSIX actual. Algunos de los ProjectOutputGroup destinos definidos en el archivo de compilación del sistema Microsoft.Common.CurrentVersion.targets se usan en los manifiestos VSIX generados por Visual Studio. Los destinos de grupo de salida de proyecto adicionales disponibles en el proyecto VSIX se definen en Microsoft.VsSDK.targets. En la tabla siguiente se muestran los grupos de salida de proyecto definidos:

ProjectOutputGroup Descripción
BuiltProjectOutputGroup Archivos que representan la salida de la compilación.
ContentFilesProjectOutputGroup Archivos no binarios asociados con el proyecto, como archivos HTML y CSS.
DebugSymbolsProjectOutputGroup Archivos de símbolos (.pdb) para depurar una extensión en la instancia experimental de Visual Studio.
DocumentationFilesProjectOutputGroup Archivos de documentación XML.
PkgDefProjectOutputGroup Archivos de definición de paquete (.pkgdef).
PriFilesOutputGroup Los .pri archivos de recursos asociados a un proyecto de UWP.
SatelliteDllsProjectOutputGroup Ensamblados satélite para recursos localizados.
SDKRedistOutputGroup Las carpetas redistribuibles de los SDK a los que hace referencia un proyecto.
SGenFilesOutputGroup Los archivos GenerateSerializationAssemblies, que son los generados por el destino y la tarea GenerateSerializationAssemblies.
SourceFilesProjectOutputGroup Archivos de código fuente.
TemplateProjectOutputGroup Plantillas de proyecto.

El sistema de compilación rellena estos grupos de salida con los archivos adecuados según la lógica de compilación predeterminada. En una compilación personalizada, puede agregar elementos a los grupos de salida del proyecto estableciendo el atributo en el BeforeTargets destino en uno de los destinos anteriores y, en el destino, siga el código de los destinos enumerados anteriormente como ejemplos de cómo usar la BuiltProjectOutputGroupKeyOutput tarea para establecer las salidas.

En escenarios avanzados, puede hacer referencia a un destino de compilación o definir un destino personalizado que quiera invocar y usar la sintaxis descrita aquí para insertar valores para cualquier elemento del manifiesto VSIX. Un destino debe tener el parámetro de salida adecuado que coincida con la expectativa del contexto en el que se usa. Si se espera una colección de archivos como la salida compilada de un proyecto, se necesita un destino que genera los elementos de MSBuild necesarios. Los destinos creados del grupo de salida del proyecto mencionados anteriormente se pueden usar como ejemplos al compilar sus propios destinos.

Manifiesto de ejemplo

<?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 también