Bagikan melalui

Referensi skema ekstensi VSIX 2.0

  • Artikel

File manifes penyebaran VSIX menjelaskan konten paket VSIX. Format file diatur oleh skema. Versi 2.0 dari skema ini mendukung penambahan jenis dan atribut kustom. Skema manifes dapat diperluas. Loader manifes mengabaikan elemen dan atribut XML yang tidak dipahaminya.

Skema manifes paket

Elemen akar dari file XML manifes adalah <PackageManifest>. Ini memiliki atribut Versiontunggal , yang merupakan versi format manifes. Jika perubahan besar dilakukan pada format, format versi akan diubah. Artikel ini menjelaskan format manifes versi 2.0, yang ditentukan dalam manifes dengan mengatur Version atribut ke nilai Version="2.0".

Elemen PackageManifest

<PackageManifest> Dalam elemen akar, Anda dapat menggunakan elemen berikut:

  • <Metadata> - Metadata dan informasi iklan tentang paket itu sendiri. Hanya satu Metadata elemen yang diizinkan dalam manifes.

  • <Installation> - Bagian ini mendefinisikan cara paket ekstensi ini dapat diinstal, termasuk SKU aplikasi yang dapat diinstal. Hanya satu Installation elemen yang diizinkan dalam manifes. Manifes harus memiliki Installation elemen, atau paket ini tidak akan diinstal ke SKU apa pun.

  • <Dependencies> - Daftar dependensi opsional untuk paket ini ditentukan di sini.

  • <Assets> - Bagian ini berisi semua aset yang terkandung dalam paket ini. Tanpa bagian ini, paket ini tidak akan menampilkan konten apa pun.

  • <AnyElement>* - Skema manifes cukup fleksibel untuk memungkinkan elemen lain. Setiap elemen turunan yang tidak dikenali oleh pemuat manifes diekspos di API Extension Manager sebagai objek XmlElement tambahan. Dengan menggunakan elemen anak ini, ekstensi VSIX dapat menentukan data tambahan dalam file manifes yang menjalankan kode di Visual Studio dapat diakses pada waktu proses. Lihat Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Elemen metadata

Bagian ini adalah metadata tentang paket, identitasnya, dan informasi iklan. <Metadata> berisi elemen-elemen berikut:

  • <Identity> - Menentukan informasi identifikasi untuk paket ini dan mencakup atribut berikut:

    • Id - Atribut ini harus berupa ID unik untuk paket yang dipilih oleh penulisnya. Nama harus memenuhi syarat dengan cara yang sama seperti jenis CLR diberi namespace: Company.Product.Feature.Name. Atribut Id dibatasi hingga 100 karakter.

    • Version - Mendefinisikan versi paket ini dan isinya. Atribut ini mengikuti format penerapan versi rakitan CLR: Major.Minor.Build.Revision (1.2.40308.00). Paket dengan nomor versi yang lebih tinggi dianggap sebagai pembaruan untuk paket, dan dapat diinstal melalui versi yang diinstal yang ada.

    • Language - Atribut ini adalah bahasa default untuk paket dan sesuai dengan data tekstual dalam manifes ini. Atribut ini mengikuti konvensi kode lokal CLR untuk rakitan sumber daya, misalnya: en-us, en, fr-fr. Anda dapat menentukan neutral untuk mendeklarasikan ekstensi netral bahasa yang akan berjalan pada versi Visual Studio apa pun. Nilai defaultnya adalah neutral.

    • Publisher - Atribut ini mengidentifikasi penerbit paket ini, baik nama perusahaan atau individu. Atribut Publisher dibatasi hingga 100 karakter.

  • <DisplayName> - Elemen ini menentukan nama paket yang mudah digunakan yang ditampilkan di UI Pengelola Ekstensi. Konten DisplayName dibatasi hingga 50 karakter.

  • <Description> - Elemen opsional ini adalah deskripsi singkat tentang paket dan kontennya yang ditampilkan di UI Extension Manager. Konten Description dapat berisi teks apa pun yang Anda inginkan, tetapi dibatasi hingga 1000 karakter.

  • <MoreInfo> - Elemen opsional ini adalah URL ke halaman online yang berisi deskripsi lengkap paket ini. Protokol harus ditentukan sebagai http.

  • <License> - Elemen opsional ini adalah jalur relatif ke file lisensi (.txt, .rtf) yang terkandung dalam paket.

  • <ReleaseNotes> - Elemen opsional ini adalah jalur relatif ke file catatan rilis yang terkandung dalam paket (.txt, .rtf) atau URL ke situs web yang menampilkan catatan rilis.

  • <Icon> - Elemen opsional ini adalah jalur relatif ke file gambar (png, bmp, jpeg, ico) yang terkandung dalam paket. Gambar ikon harus 32x32 piksel (atau akan diciutkan ke ukuran tersebut) dan muncul di UI listview. Jika tidak ada Icon elemen yang ditentukan, UI menggunakan default.

  • <PreviewImage> - Elemen opsional ini adalah jalur relatif ke file gambar (png, bmp, jpeg) yang terkandung dalam paket. Gambar pratinjau harus 200x200 piksel, dan ditampilkan di antarmuka pengguna detail. Jika tidak ada PreviewImage elemen yang ditentukan, UI menggunakan default.

  • <Tags> - Elemen opsional ini mencantumkan tag teks tambahan yang dibatasi titik koma yang digunakan untuk petunjuk pencarian. Elemen Tags dibatasi hingga 100 karakter.

  • <GettingStartedGuide> - Elemen opsional ini adalah jalur relatif ke file HTML atau URL ke situs web yang berisi informasi tentang cara menggunakan ekstensi atau konten dalam paket ini. Panduan ini diluncurkan sebagai bagian dari penginstalan.

  • <AnyElement>* - Skema manifes cukup fleksibel untuk memungkinkan elemen lain. Setiap elemen anak yang tidak dikenali oleh pemuat manifes diekspos sebagai daftar objek XmlElement. Dengan menggunakan elemen turunan ini, ekstensi VSIX dapat menentukan data tambahan dalam file manifes dan menghitungnya pada waktu proses.

Elemen penginstalan

Bagian ini menentukan cara paket ini dapat diinstal dan SKU aplikasi yang dapat diinstal. Bagian ini berisi atribut berikut:

  • Experimental - Atur atribut ini ke true jika Anda memiliki ekstensi yang saat ini diinstal untuk semua pengguna, tetapi Anda mengembangkan versi yang diperbarui pada komputer yang sama. Misalnya, jika Anda telah menginstal MyExtension 1.0 untuk semua pengguna, tetapi Anda ingin men-debug MyExtension 2.0 di komputer yang sama, atur Experimental="true". Atribut ini tersedia di Visual Studio 2015 Update 1 dan yang lebih baru.

  • Scope - Atribut ini dapat mengambil nilai "Global" atau "ProductExtension":

    • "Global" menentukan bahwa penginstalan tidak tercakup ke SKU tertentu. Misalnya, nilai ini digunakan saat Extension SDK diinstal.

    • "ProductExtension" menentukan bahwa Ekstensi VSIX tradisional (versi 1.0) yang dilingkup ke SKU Visual Studio individual diinstal. Ini adalah nilai default.

  • AllUsers - Atribut opsional ini menentukan apakah paket ini akan diinstal untuk semua pengguna. Secara default, atribut ini false, yang menentukan bahwa paket adalah per pengguna. (Ketika Anda mengatur nilai ini ke true, pengguna yang menginstal harus meningkatkan ke tingkat hak istimewa administratif untuk menginstal VSIX yang dihasilkan.

  • InstalledByMsi - Atribut opsional ini menentukan apakah paket ini diinstal oleh MSI. Paket yang diinstal oleh MSI diinstal dan dikelola oleh MSI (Program dan Fitur) dan bukan oleh Visual Studio Extension Manager. Secara default, atribut ini salah, yang menentukan bahwa paket tidak diinstal oleh MSI.

  • SystemComponent - Atribut opsional ini menentukan apakah paket ini harus dianggap sebagai komponen sistem. Komponen sistem tidak ditampilkan di UI Pengelola Ekstensi dan tidak dapat diperbarui. Secara default, atribut ini false, yang menentukan bahwa paket bukan komponen sistem.

  • AnyAttribute* - Elemen Installation menerima sekumpulan atribut terbuka yang akan diekspos pada waktu proses sebagai kamus pasangan nama-nilai.

  • <InstallationTarget> -Elemen ini mengontrol lokasi tempat alat penginstal VSIX menginstal paket. Jika nilai Scope atribut adalah "ProductExtension" paket harus menargetkan SKU, yang telah menginstal file manifes sebagai bagian dari kontennya untuk mengiklankan ketersediaannya ke ekstensi. Elemen <InstallationTarget> ini memiliki atribut berikut ketika Scope atribut memiliki nilai eksplisit atau default "ProductExtension":

    • Id - Atribut ini mengidentifikasi paket. Atribut mengikuti konvensi namespace layanan: Company.Product.Feature.Name. Atribut Id hanya dapat berisi karakter alfanumerik dan dibatasi hingga 100 karakter. Nilai yang diharapkan:

      • 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 - Atribut ini menentukan rentang versi dengan versi minimum dan maksimum yang didukung dari SKU ini. Paket dapat merinci versi SKU yang didukungnya. Notasi rentang versi adalah [10.0 - 11.0], di mana

      • [ - versi minimum inklusif.

      • ] - versi maksimum inklusif.

      • ( - versi minimum eksklusif.

      • ) - versi maksimum eksklusif.

      • Versi tunggal # - hanya versi yang ditentukan.

      Penting

      Skema VSIX versi 2.0 diperkenalkan di Visual Studio 2012. Untuk menggunakan skema ini, Anda harus menginstal Visual Studio 2012 atau yang lebih baru pada komputer dan menggunakan VSIXInstaller.exe yang merupakan bagian dari produk tersebut. Anda dapat menargetkan versi Visual Studio yang lebih lama dengan Visual Studio 2012 atau VSIXInstaller yang lebih baru, tetapi hanya dengan menggunakan versi penginstal yang lebih baru.

      Nomor versi Visual Studio 2017 dapat ditemukan di nomor build Visual Studio dan tanggal rilis.

      Saat mengekspresikan versi untuk rilis Visual Studio 2017, versi minor harus selalu 0. Misalnya, Visual Studio 2017 versi 15.3.26730.0 harus dinyatakan sebagai [15.0.26730.0,16.0). Ini hanya diperlukan untuk Nomor versi Visual Studio 2017 dan yang lebih baru.

    • AnyAttribute* - Elemen <InstallationTarget> ini memungkinkan sekumpulan atribut terbuka yang diekspos pada waktu proses sebagai kamus pasangan nilai nama.

Elemen Dependensi

Elemen ini berisi daftar dependensi yang dideklarasikan paket ini. Jika ada dependensi yang ditentukan, paket tersebut (diidentifikasi oleh mereka Id) harus telah diinstal sebelumnya.

  • <Dependency> elemen - Elemen turunan ini memiliki atribut berikut:

    • Id - Atribut ini harus berupa ID unik untuk paket dependen. Nilai identitas ini harus cocok dengan <Metadata><Identity>Id atribut paket yang bergantung pada paket ini. Atribut Id mengikuti konvensi namespace layanan: Company.Product.Feature.Name. Atribut hanya dapat berisi karakter alfanumerik dan dibatasi hingga 100 karakter.

    • Version - Atribut ini menentukan rentang versi dengan versi minimum dan maksimum yang didukung dari SKU ini. Paket dapat merinci versi SKU yang didukungnya. Notasi rentang versi adalah [12.0, 13.0], di mana:

      • [ - versi minimum inklusif.

      • ] - versi maksimum inklusif.

      • ( - versi minimum eksklusif.

      • ) - versi maksimum eksklusif.

      • Versi tunggal # - hanya versi yang ditentukan.

    • DisplayName - Atribut ini adalah nama tampilan paket dependen, yang digunakan dalam elemen UI seperti kotak dialog dan pesan kesalahan. Atribut bersifat opsional kecuali paket dependen diinstal oleh MSI.

    • Location - Atribut opsional ini menentukan jalur relatif dalam VSIX ini ke paket VSIX berlapis atau URL ke lokasi unduhan untuk dependensi. Atribut ini digunakan untuk membantu pengguna menemukan paket prasyarat.

    • AnyAttribute* - Elemen Dependency menerima sekumpulan atribut terbuka yang akan diekspos pada waktu proses sebagai kamus pasangan nama-nilai.

Elemen aset

Elemen ini berisi daftar <Asset> tag untuk setiap ekstensi atau elemen konten yang muncul oleh paket ini.

  • <Asset> - Elemen ini berisi atribut dan elemen berikut:

    • Type - Jenis ekstensi atau konten yang diwakili oleh elemen ini. Setiap <Asset> elemen harus memiliki satu Type, tetapi beberapa <Asset> elemen mungkin memiliki yang sama Type. Atribut ini harus direpresentasikan sebagai nama yang sepenuhnya memenuhi syarat, sesuai dengan konvensi namespace layanan. Jenis yang diketahui adalah:

      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

        Anda dapat membuat jenis Anda sendiri dan memberinya nama unik. Pada waktu proses di dalam Visual Studio, kode Anda dapat menghitung dan mengakses jenis kustom ini melalui API Extension Manager.

    • Path - jalur relatif ke file atau folder dalam paket yang berisi aset.

    • TargetVersion - rentang versi tempat aset yang diberikan berlaku. Digunakan untuk mengirim beberapa versi aset ke versi Visual Studio yang berbeda. Mengharuskan Visual Studio 2017.3 atau yang lebih baru memiliki efek.

    • AnyAttribute* - Sekumpulan atribut terbuka yang diekspos pada waktu proses sebagai kamus pasangan nama-nilai.

      <AnyElement>* - Konten terstruktur apa pun diizinkan antara <Asset> tag awal dan akhir. Semua elemen diekspos sebagai daftar objek XmlElement. Ekstensi VSIX dapat menentukan metadata khusus jenis terstruktur dalam file manifes dan menghitungnya pada waktu proses.

Sintaks tempat penampung untuk manifes ekstensi

File .vsixmanifest menentukan build untuk paket VSIX. Saat build diminta, Visual Studio mengurai manifes untuk menghasilkan skrip build, yang dibangun dengan menggunakan MSBuild. Anda dapat mengatur nilai tertentu pada waktu build menggunakan tempat penampung yang dievaluasi sebelum paket VSIX dibuat. Tempat penampung digunakan untuk merujuk ke proyek yang dirujuk dalam proyek VSIX, properti MSBuild, dan target MSBuild, paling umum adalah target yang mewakili grup output proyek. Grup output proyek mewakili kumpulan file yang terkait dengan proyek, dan beberapa di antaranya dapat disertakan dalam paket VSIX. Misalnya, PkgDefProjectOutputGroup, BuiltProjectOutputGroup, atau SatelliteDllsProjectOutputGroup.

Untuk mereferensikan properti yang ditentukan dalam proyek VSIX, gunakan sintaks yang sama seperti yang Anda lakukan dalam file proyek itu sendiri, $(PropertyName).

Token %CurrentProject% khusus mereferensikan proyek VSIX. Anda dapat mereferensikan proyek lain yang direferensikan dalam proyek VSIX Anda dengan menggunakan Name ProjectReference elemen dalam file proyek VSIX, yang dikelilingi oleh simbol pipa (|). Contohnya, |ProjectTemplate1|.

Anda dapat mereferensikan target MSBuild dengan nama proyek ( Name properti referensi proyek dalam proyek VSIX) lalu nama target. Misalnya, untuk mereferensikan Version target di salah satu proyek yang dirujuk dalam paket VSIX, gunakan sintaks .|ProjectName;Version| Target harus memiliki Outputs nilai yang cocok dengan konteks yang digunakan; manifes VSIX berisi tempat di mana penggantian nilai string dan koleksi item sesuai. Misalnya, string Versi dalam manifes mungkin diganti sebagai berikut:

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

Dalam hal ini, harus GetVsixVersion ada target dalam proyek VSIX yang harus mengembalikan string sederhana. Contohnya,

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

Tempat penampung digunakan untuk membuat file manifes VSIX yang benar dengan proyek VSIX bergaya SDK. Misalkan Anda menentukan versi target Visual Studio dengan properti 'TargetFramework':

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

Berdasarkan kerangka kerja target, build VSIX mengubah nilai yang ditentukan dalam file manifes ekstensi sebagai berikut. Untuk sintaks berikut dalam file manifes:

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

Output yang digunakan dalam kode MSBuild proyek VSIX adalah:

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

Dan, untuk kode berikut dalam manifes ekstensi:

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

Kode build proyek adalah:

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

Fungsionalitas ini juga digunakan dalam file manifes VSIX yang dihasilkan Visual Studio untuk mereferensikan grup output proyek dengan nama referensi proyek dan kemudian nama target MSBuild, dipisahkan oleh titik koma. Misalnya, string |%CurrentProject%;PkgDefProjectOutputGroup| berarti grup output PkgDef, yang mereferensikan .pkgdef file yang terkait dengan proyek VSIX saat ini. Beberapa target yang ProjectOutputGroup ditentukan dalam file build sistem Microsoft.Common.CurrentVersion.targets digunakan dalam manifes VSIX yang dihasilkan oleh Visual Studio. Target grup output proyek tambahan yang tersedia dalam proyek VSIX ditentukan dalam Microsoft.VsSDK.targets. Tabel berikut ini memperlihatkan grup output proyek yang ditentukan:

ProjectOutputGroup Deskripsi
BuiltProjectOutputGroup File yang mewakili output build.
ContentFilesProjectOutputGroup File non-biner yang terkait dengan proyek, seperti file HTML dan CSS.
DebugSymbolsProjectOutputGroup Simbol file (.pdb) untuk men-debug ekstensi dalam instans eksperimental Visual Studio.
DocumentationFilesProjectOutputGroup File dokumentasi XML.
PkgDefProjectOutputGroup File definisi paket (.pkgdef).
PriFilesOutputGroup File .pri sumber daya yang terkait dengan proyek UWP.
SatelliteDllsProjectOutputGroup Rakitan satelit untuk sumber daya yang dilokalkan.
SDKRedistOutputGroup Folder yang dapat didistribusikan ulang dari SDK yang dirujuk oleh proyek.
SGenFilesOutputGroup File GenerateSerializationAssemblies, yang dihasilkan oleh target dan tugas GenerateSerializationAssemblies.
SourceFilesProjectOutputGroup File kode sumber.
TemplateProjectOutputGroup Templat proyek.

Sistem build mengisi grup output ini dengan file yang sesuai sesuai dengan logika build default. Dalam build kustom, Anda dapat menambahkan item ke grup output proyek baik dengan mengatur BeforeTargets atribut pada target Anda ke salah satu target di atas, dan di target, ikuti kode untuk target yang tercantum di atas sebagai contoh cara menggunakan BuiltProjectOutputGroupKeyOutput tugas untuk mengatur output.

Dalam skenario tingkat lanjut, Anda dapat mereferensikan target build atau menentukan target kustom yang ingin Anda panggil dan menggunakan sintaks yang dijelaskan di sini untuk menyisipkan nilai untuk elemen apa pun dalam manifes VSIX. Target harus memiliki parameter output yang sesuai yang sesuai dengan harapan konteks tempatnya digunakan. Jika kumpulan file seperti output bawaan proyek diharapkan, maka target yang menghasilkan item MSBuild yang diperlukan diperlukan. Target yang dibangun grup output proyek yang disebutkan sebelumnya dapat digunakan sebagai contoh saat membangun target Anda sendiri.

Manifes sampel

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

Baca juga