Condividi tramite

Informazioni di riferimento sullo schema di estensione VSIX 2.0

  • Articolo

Un file manifesto della distribuzione VSIX descrive il contenuto di un pacchetto VSIX. Il formato di file è regolato da uno schema. La versione 2.0 di questo schema supporta l'aggiunta di tipi e attributi personalizzati. Lo schema del manifesto è estendibile. Il caricatore del manifesto ignora gli elementi XML e gli attributi che non riconosce.

Schema del manifesto del pacchetto

L'elemento radice del file XML manifesto è <PackageManifest>. Ha un singolo attributo Version, ovvero la versione del formato manifesto. Se vengono apportate modifiche importanti al formato, il formato della versione viene modificato. Questo articolo descrive il formato manifesto versione 2.0, specificato nel manifesto impostando l'attributo Version sul valore di Version="2.0".

Elemento PackageManifest

All'interno dell'elemento <PackageManifest> radice è possibile usare gli elementi seguenti:

  • <Metadata> - Metadati e informazioni pubblicitarie sul pacchetto stesso. Nel manifesto è consentito un Metadata solo elemento.

  • <Installation> - Questa sezione definisce il modo in cui è possibile installare questo pacchetto di estensione, inclusi gli SKU dell'applicazione in cui può essere installato. Nel manifesto è consentito un solo Installation elemento. Un manifesto deve avere un Installation elemento o questo pacchetto non verrà installato in alcun SKU.

  • <Dependencies> - Qui è definito un elenco facoltativo di dipendenze per questo pacchetto.

  • <Assets> - Questa sezione contiene tutti gli asset contenuti in questo pacchetto. Senza questa sezione, questo pacchetto non visualizzerà alcun contenuto.

  • <AnyElement>* - Lo schema del manifesto è sufficientemente flessibile per consentire qualsiasi altro elemento. Tutti gli elementi figlio non riconosciuti dal caricatore del manifesto vengono esposti nell'API di Gestione estensioni come oggetti XmlElement aggiuntivi. Usando questi elementi figlio, le estensioni VSIX possono definire dati aggiuntivi nel file manifesto a cui il codice in esecuzione in Visual Studio può accedere in fase di esecuzione. Vedere Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Elemento Metadata

Questa sezione contiene i metadati relativi al pacchetto, alla relativa identità e alle informazioni pubblicitarie. <Metadata> contiene gli elementi seguenti:

  • <Identity> - Definisce le informazioni di identificazione per questo pacchetto e include gli attributi seguenti:

    • Id - Questo attributo deve essere un ID univoco per il pacchetto scelto dall'autore. Il nome deve essere qualificato allo stesso modo in cui i tipi CLR sono spazi dei nomi: Company.Product.Feature.Name. L'attributo Id è limitato a 100 caratteri.

    • Version - Definisce la versione di questo pacchetto e il relativo contenuto. Questo attributo segue il formato di controllo delle versioni dell'assembly CLR: Major.Minor.Build.Revision (1.2.40308.00). Un pacchetto con un numero di versione superiore viene considerato aggiornato al pacchetto e può essere installato tramite la versione installata esistente.

    • Language - Questo attributo è la lingua predefinita per il pacchetto e corrisponde ai dati testuali in questo manifesto. Questo attributo segue la convenzione di codice delle impostazioni locali CLR per gli assembly di risorse, ad esempio en-us, en, fr-fr. È possibile specificare di dichiarare neutral un'estensione indipendente dal linguaggio che verrà eseguita in qualsiasi versione di Visual Studio. Il valore predefinito è neutral.

    • Publisher - Questo attributo identifica l'autore di questo pacchetto, ovvero una società o un nome individuale. L'attributo Publisher è limitato a 100 caratteri.

  • <DisplayName> - Questo elemento specifica il nome del pacchetto descrittivo visualizzato nell'interfaccia utente di Gestione estensioni. Il DisplayName contenuto è limitato a 50 caratteri.

  • <Description> - Questo elemento facoltativo è una breve descrizione del pacchetto e il relativo contenuto visualizzato nell'interfaccia utente di Gestione estensioni. Il Description contenuto può contenere qualsiasi testo desiderato, ma è limitato a 1000 caratteri.

  • <MoreInfo> - Questo elemento facoltativo è un URL di una pagina online che contiene una descrizione completa del pacchetto. Il protocollo deve essere specificato come http.

  • <License> - Questo elemento facoltativo è un percorso relativo a un file di licenza (.txt, .rtf) contenuto nel pacchetto.

  • <ReleaseNotes> - Questo elemento facoltativo è un percorso relativo a un file delle note sulla versione contenuto nel pacchetto (.txt, .rtf) oppure un URL di un sito Web che visualizza le note sulla versione.

  • <Icon> - Questo elemento facoltativo è un percorso relativo a un file di immagine (png, bmp, jpeg, ico) contenuto nel pacchetto. L'immagine dell'icona deve essere di 32x32 pixel (o sarà compattata a tale dimensione) e viene visualizzata nell'interfaccia utente di listview. Se non viene specificato alcun Icon elemento, l'interfaccia utente usa un valore predefinito.

  • <PreviewImage> - Questo elemento facoltativo è un percorso relativo a un file di immagine (png, bmp, jpeg) contenuto nel pacchetto. L'immagine di anteprima deve essere di 200x200 pixel e visualizzata nell'interfaccia utente dei dettagli. Se non viene specificato alcun PreviewImage elemento, l'interfaccia utente usa un valore predefinito.

  • <Tags> - Questo elemento facoltativo elenca altri tag di testo delimitati da punto e virgola usati per gli hint di ricerca. L'elemento Tags è limitato a 100 caratteri.

  • <GettingStartedGuide> - Questo elemento facoltativo è un percorso relativo di un file HTML o un URL di un sito Web che contiene informazioni su come usare l'estensione o il contenuto all'interno di questo pacchetto. Questa guida viene avviata come parte di un'installazione.

  • <AnyElement>* - Lo schema del manifesto è sufficientemente flessibile per consentire qualsiasi altro elemento. Tutti gli elementi figlio non riconosciuti dal caricatore del manifesto vengono esposti come elenco di oggetti XmlElement. Usando questi elementi figlio, le estensioni VSIX possono definire dati aggiuntivi nel file manifesto ed enumerarli in fase di esecuzione.

Elemento Installation

Questa sezione definisce il modo in cui è possibile installare questo pacchetto e gli SKU dell'applicazione in cui può essere installato. Questa sezione contiene gli attributi seguenti:

  • Experimental - Impostare questo attributo su true se si dispone di un'estensione attualmente installata per tutti gli utenti, ma si sta sviluppando una versione aggiornata nello stesso computer. Ad esempio, se è stato installato MyExtension 1.0 per tutti gli utenti, ma si vuole eseguire il debug di MyExtension 2.0 nello stesso computer, impostare Experimental="true". Questo attributo è disponibile in Visual Studio 2015 Update 1 e versioni successive.

  • Scope - Questo attributo può accettare il valore "Global" o "ProductExtension":

    • "Global" specifica che l'installazione non ha come ambito uno SKU specifico. Ad esempio, questo valore viene usato quando viene installato un SDK di estensione.

    • "ProductExtension" specifica che è installato un'estensione VSIX tradizionale (versione 1.0) con ambito per singoli SKU di Visual Studio. Questo è il valore predefinito.

  • AllUsers - Questo attributo facoltativo specifica se questo pacchetto verrà installato per tutti gli utenti. Per impostazione predefinita, questo attributo è false, che specifica che il pacchetto è per utente. Quando si imposta questo valore su true, l'utente che installa deve elevare al livello di privilegi amministrativi per installare il VSIX risultante.

  • InstalledByMsi - Questo attributo facoltativo specifica se questo pacchetto è installato da un'identità del servizio gestito. I pacchetti installati da un'identità del servizio gestito vengono installati e gestiti da MSI (Programmi e funzionalità) e non da Gestione estensioni di Visual Studio. Per impostazione predefinita, questo attributo è false, che specifica che il pacchetto non è installato da un'identità del servizio gestito.

  • SystemComponent - Questo attributo facoltativo specifica se questo pacchetto deve essere considerato un componente di sistema. I componenti di sistema non vengono visualizzati nell'interfaccia utente di Gestione estensioni e non possono essere aggiornati. Per impostazione predefinita, questo attributo è false, che specifica che il pacchetto non è un componente di sistema.

  • AnyAttribute* - L'elemento Installation accetta un set di attributi aperto che verrà esposto in fase di esecuzione come dizionario coppie nome-valore.

  • <InstallationTarget> -Questo elemento controlla il percorso in cui il programma di installazione VSIX installa il pacchetto. Se il valore dell'attributo Scope è "ProductExtension", il pacchetto deve avere come destinazione uno SKU, che ha installato un file manifesto come parte del relativo contenuto per annunciarne la disponibilità alle estensioni. L'elemento <InstallationTarget> ha gli attributi seguenti quando l'attributo Scope ha il valore esplicito o predefinito "ProductExtension":

    • Id - Questo attributo identifica il pacchetto. L'attributo segue la convenzione dello spazio dei nomi: Company.Product.Feature.Name. L'attributo Id può contenere solo caratteri alfanumerici ed è limitato a 100 caratteri. Valori previsti:

      • 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 - Questo attributo specifica un intervallo di versioni con le versioni minime e massime supportate di questo SKU. Un pacchetto può descrivere in dettaglio le versioni degli SKU supportati. La notazione dell'intervallo di versioni è [10.0 - 11.0], dove

      • [ - versione minima inclusiva.

      • ] - Versione massima inclusiva.

      • ( - versione minima esclusiva.

      • ) - versione massima esclusiva.

      • Versione singola # : solo la versione specificata.

      Importante

      La versione 2.0 dello schema VSIX è stata introdotta in Visual Studio 2012. Per usare questo schema, è necessario che Nel computer sia installato Visual Studio 2012 o versione successiva e usare VSIXInstaller.exe che fa parte di tale prodotto. È possibile usare le versioni precedenti di Visual Studio con Visual Studio 2012 o versioni successive di VSIXInstaller, ma solo usando le versioni successive del programma di installazione.

      I numeri di versione di Visual Studio 2017 sono disponibili in Numeri di build e date di rilascio di Visual Studio.

      Quando si esprime la versione per Le versioni di Visual Studio 2017, la versione secondaria deve essere sempre 0. Ad esempio, Visual Studio 2017 versione 15.3.26730.0 deve essere espresso come [15.0.26730.0,16.0). Questa operazione è necessaria solo per i numeri di versione di Visual Studio 2017 e versioni successive.

    • AnyAttribute* - L'elemento <InstallationTarget> consente un set aperto di attributi esposti in fase di esecuzione come dizionario coppie nome-valore.

Elemento Dependencies

Questo elemento contiene un elenco di dipendenze dichiarate da questo pacchetto. Se vengono specificate dipendenze, tali pacchetti (identificati dalla relativa Id) devono essere stati installati in precedenza.

  • <Dependency> element : questo elemento figlio ha gli attributi seguenti:

    • Id - Questo attributo deve essere un ID univoco per il pacchetto dipendente. Questo valore Identity deve corrispondere all'attributo <Metadata><Identity>Id di un pacchetto da cui dipende questo pacchetto. L'attributo Id segue la convenzione dello spazio dei nomi: Company.Product.Feature.Name. L'attributo può contenere solo caratteri alfanumerici ed è limitato a 100 caratteri.

    • Version - Questo attributo specifica un intervallo di versioni con le versioni minime e massime supportate di questo SKU. Un pacchetto può descrivere in dettaglio le versioni degli SKU supportati. La notazione dell'intervallo di versioni è [12.0, 13.0], dove:

      • [ - versione minima inclusiva.

      • ] - Versione massima inclusiva.

      • ( - versione minima esclusiva.

      • ) - versione massima esclusiva.

      • Versione singola # : solo la versione specificata.

    • DisplayName - Questo attributo è il nome visualizzato del pacchetto dipendente, che viene usato negli elementi dell'interfaccia utente, ad esempio finestre di dialogo e messaggi di errore. L'attributo è facoltativo a meno che il pacchetto dipendente non sia installato dall'identità del servizio gestito.

    • Location - Questo attributo facoltativo specifica il percorso relativo all'interno di questo VSIX in un pacchetto VSIX annidato o un URL per il percorso di download per la dipendenza. Questo attributo viene usato per aiutare l'utente a individuare il pacchetto dei prerequisiti.

    • AnyAttribute* - L'elemento Dependency accetta un set di attributi aperto che verrà esposto in fase di esecuzione come dizionario coppie nome-valore.

Elemento Assets

Questo elemento contiene un elenco di <Asset> tag per ogni estensione o elemento di contenuto visualizzato da questo pacchetto.

  • <Asset> - Questo elemento contiene gli attributi e gli elementi seguenti:

    • Type - Tipo di estensione o contenuto rappresentato da questo elemento. Ogni <Asset> elemento deve avere un singolo Typeelemento , ma più <Asset> elementi possono avere lo stesso Type. Questo attributo deve essere rappresentato come nome completo, in base alle convenzioni dello spazio dei nomi. I tipi noti sono:

      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

        È possibile creare tipi personalizzati e assegnare loro nomi univoci. In fase di esecuzione all'interno di Visual Studio, il codice può enumerare e accedere a questi tipi personalizzati tramite l'API di Gestione estensioni.

    • Path : percorso relativo del file o della cartella all'interno del pacchetto che contiene l'asset.

    • TargetVersion : intervallo di versioni a cui si applica l'asset specificato. Usato per la spedizione di più versioni di asset a versioni diverse di Visual Studio. Richiede che Visual Studio 2017.3 o versione successiva abbia effetto.

    • AnyAttribute* - Set aperto di attributi esposti in fase di esecuzione come dizionario coppie nome-valore.

      <AnyElement>* - Qualsiasi contenuto strutturato è consentito tra un <Asset> tag di inizio e di fine. Tutti gli elementi vengono esposti come elenco di oggetti XmlElement. Le estensioni VSIX possono definire metadati specifici del tipo strutturato nel file manifesto ed enumerarle in fase di esecuzione.

Sintassi segnaposto per i manifesti dell'estensione

Il .vsixmanifest file definisce la compilazione per il pacchetto VSIX. Quando viene richiesta una compilazione, Visual Studio analizza il manifesto per produrre uno script di compilazione, compilato tramite MSBuild. È possibile impostare determinati valori in fase di compilazione usando segnaposto valutati prima della compilazione del pacchetto VSIX. I segnaposto vengono usati per fare riferimento ai progetti a cui si fa riferimento nel progetto VSIX, nelle proprietà MSBuild e nelle destinazioni MSBuild, in genere le destinazioni che rappresentano i gruppi di output del progetto. I gruppi di output del progetto rappresentano raccolte di file associati a un progetto e alcuni di questi possono essere inclusi in un pacchetto VSIX. Ad esempio, PkgDefProjectOutputGroup, BuiltProjectOutputGroup o SatelliteDllsProjectOutputGroup.

Per fare riferimento a una proprietà definita nel progetto VSIX, usare la stessa sintassi del file di progetto stesso, $(PropertyName).

Il token %CurrentProject% speciale fa riferimento al progetto VSIX. È possibile fare riferimento ad altri progetti a cui si fa riferimento nel progetto VSIX usando Name l'elemento ProjectReference in un file di progetto VSIX, circondato da simboli pipe (|). Ad esempio: |ProjectTemplate1|.

È possibile fare riferimento a una destinazione MSBuild in base al nome del progetto (la Name proprietà del riferimento del progetto nel progetto VSIX) e quindi al nome di destinazione. Ad esempio, per fare riferimento alla Version destinazione in uno dei progetti a cui si fa riferimento in un pacchetto VSIX, usare la sintassi |ProjectName;Version|. La destinazione deve avere un Outputs valore che corrisponde al contesto in cui viene usato. Il manifesto VSIX contiene posizioni in cui è appropriata la sostituzione dei valori stringa e delle raccolte di elementi. Ad esempio, la stringa Version nel manifesto potrebbe essere sostituita come segue:

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

In tal caso, deve essere presente una GetVsixVersion destinazione nel progetto VSIX che deve restituire una stringa semplice. ad esempio:

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

I segnaposto vengono usati per creare il file manifesto VSIX corretto con il progetto VSIX in stile SDK. Si supponga di specificare la versione di destinazione di Visual Studio con la proprietà 'TargetFramework':

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

In base al framework di destinazione, la compilazione VSIX trasforma i valori definiti nel file manifesto dell'estensione come indicato di seguito. Per la sintassi seguente nel file manifesto:

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

L'output usato nel codice MSBuild del progetto VSIX è:

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

E, per il codice seguente in un manifesto dell'estensione:

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

Il codice di compilazione del progetto è:

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

Questa funzionalità viene usata anche nei file manifesto VSIX generati da Visual Studio per fare riferimento ai gruppi di output del progetto in base al nome del riferimento al progetto e quindi al nome della destinazione MSBuild, separati da un punto e virgola. Ad esempio, la stringa |%CurrentProject%;PkgDefProjectOutputGroup| indica il gruppo di output PkgDef, che fa riferimento ai .pkgdef file associati al progetto VSIX corrente. Alcune delle ProjectOutputGroup destinazioni definite nel file di compilazione di sistema Microsoft.Common.CurrentVersion.targets vengono usate nei manifesti VSIX generati da Visual Studio. Le destinazioni aggiuntive del gruppo di output del progetto disponibili nel progetto VSIX sono definite in Microsoft.VsSDK.targets. La tabella seguente illustra i gruppi di output del progetto definiti:

ProjectOutputGroup Descrizione
BuiltProjectOutputGroup File che rappresentano l'output di compilazione.
ContentFilesProjectOutputGroup File non binari associati al progetto, ad esempio file HTML e CSS.
DebugSymbolsProjectOutputGroup File di simboli (.pdb) per il debug di un'estensione nell'istanza sperimentale di Visual Studio.
DocumentationFilesProjectOutputGroup File di documentazione XML.
PkgDefProjectOutputGroup File di definizione del pacchetto (.pkgdef)
PriFilesOutputGroup File .pri di risorse associati a un progetto UWP.
SatelliteDllsProjectOutputGroup Assembly satellite per le risorse localizzate.
SDKRedistOutputGroup Cartelle ridistribuibili dagli SDK a cui fa riferimento un progetto.
SGenFilesOutputGroup I file GenerateSerializationAssemblies, che sono quelli generati dalla destinazione e dall'attività GenerateSerializationAssemblies.
SourceFilesProjectOutputGroup File di codice sorgente.
TemplateProjectOutputGroup Modelli di progetto.

Il sistema di compilazione popola questi gruppi di output con i file appropriati in base alla logica di compilazione predefinita. In una compilazione personalizzata è possibile aggiungere elementi ai gruppi di output del progetto impostando l'attributo BeforeTargets nella destinazione su una delle destinazioni precedenti e, nella destinazione, seguire il codice per le destinazioni elencate in precedenza come esempi per l'uso dell'attività BuiltProjectOutputGroupKeyOutput per impostare gli output.

Negli scenari avanzati è possibile fare riferimento a una destinazione di compilazione o definire una destinazione personalizzata che si desidera richiamare e usare la sintassi descritta qui per inserire valori per qualsiasi elemento nel manifesto VSIX. Una destinazione deve avere il parametro di output appropriato che corrisponde alle aspettative del contesto in cui viene usato. Se è prevista una raccolta di file, ad esempio l'output compilato di un progetto, è necessaria una destinazione che restituisce gli elementi MSBuild necessari. Il gruppo di output del progetto creato in precedenza può essere usato come esempi durante la compilazione di destinazioni personalizzate.

Manifesto di esempio

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

Vedi anche