Using the VSIX Manifest Editor
In Visual Studio 2010, we provide a new way of packaging and deploying extensions known as a VSIX. Several project templates in Visual Studio generate VSIX files (from the most basic, VSIX Project, the MEF editor extensions and Visual Studio Packages). The VSIX itself is a simple zip file (using the Open Packaging Convention) containing some content and a manifest (extension.vsixmanifest) that declares what type of extensions are provided by the content in the VSIX. For more information about VSIX files, see Quan To’s post on VSIXs. When building an extension that will be deployed via VSIX, you must specify a source manifest (source.extension.vsixmanifest) that will be transformed into the final manifest included in the VSIX. In any of the templates above, you will find a default source.extension.manifest. We provide an editor (shown below) on top of the source manifest to easily allow you to edit to your needs.
To start, let’s go over the different fields and how they map to different properties of the VSIX and how they are used by the Extension Manager and the standalone Extension Installer (opened when a user double clicks the VSIX).
|ID||The unique identifier of the VSIX. This is used by the Extension Manager to manage the identity of each extension. In particular, when a new version of an extension is deployed, this allows the Extension Manager/Installer to ensure that the old version is replaced. (Maximum length is 100 characters)|
|Product Name||The name of the product. This is the header for the Extension Manager entry for the VSIX. This is also shown in the Extension Installer. (Maximum length is 60 characters)|
|Author||The author of the VSIX. (Maximum length is 50 characters)|
|Version||Specifies the version number of VSIX. Changing this value allows the Extension Manager to know if the VSIX has been updated. The Extension Manager will not permit installing a VSIX if there is already a VSIX with the same ID and same or older version. (Maximum length is 23 characters)|
|Locale||The intended locale of the VSIX extension.|
|Supported Framework Edition (Min/Max)||The minimum and maximum editions of the .NET framework supported by your extension(s). (Maximum length is 10 characters)|
|Description||The description of the VSIX. This is shown in the Extension Manager entry for the VSIX under the product name. (Maximum length is 1024 characters)|
|Supported VS Editions||The versions/editions supported by the extension. The Visual Studio editions are organized into a hierarchy shown below (in the diagram an edition contains its sub-editions). An edition will install an extension with it or any sub-edition supported. Isolated shell products are considered independent of Visual Studio. As such, support for these must be individually specified.
For instance, in the example below, only Visual Studio Professional and an Isolated Shell (Photo Studio) are specified. The Extension Manager/Installer will not install this extension if run from an Express edition or Integrated Shell editions Visual Studio. However, for all higher editions for Professional (Premium and Ultimate in this case), the extension will install.
To specify supported Isolated shell editions:
|Getting Started Guide||An HTTPHTTPS URL to a getting started guide for your extension(s). If specified, a Getting Started link will be provided in the Extension Manager under the detailed view of the extension which will navigate to this website.|
|More Info URL||An HTTPHTTPS URL to a website containing more info for your VSIX. If specified, a More Information link will be provided in the Extension Manager under the detailed view of the extension which will navigate to this website.|
|Icon||This specifies which image will be displayed beside the product name for the VSIX in the Extension Manager’s list of extensions.|
|Preview Image||This specifies which image will be displayed in the details for the VSIX in the Extension Manager’s list of extensions.|
|License Terms||Specifies the licensing terms for the extension. This will be shown when a user attempts to install the extension.|
Here is a screenshot of the fields of the manifest editor filled in with some test data:
In the Extension Manager and Extension Installer this data would appear as below:
The VSIX Manifest Editor goes further than just providing an easy way to edit the VSIX Manifest XML. It also integrates with Visual Studio to simplify the process of adding content to the VSIX. When the Icon, Preview Icon, or License Terms is specified through the Manifest Editor, the corresponding files are added to the project if they are not already present and the “Include In VSIX” property on the files is set to true, so they will be copied into the VSIX generated when the project is built.
The extension content of the VSIX can be viewed at the bottom of the VSIX Manifest Editor in the Content table. The content type specifies the type of extension provided by the content (VS Package, Template Wizard, Toolbox Control, MEF component, Project/Item template, or Custom extension). The path specifies either a project and output group or a relative path (from the project root) to a file. The path will be replaced at build time in the resulting extension.vsixmanifest with the actual location of the file or project output in the built VSIX.
The Content element in the extension.vsixmanifest file for the content specified above would be:
Extension content can easily be added to the VSIX by clicking Add Content above the Content table to open the Add Content dialog. When the source is a file, it is automatically copied to the project and when the source is a project, a project reference is added with the necessary output groups set on the project reference.
The References table specifies dependencies on other VSIX extensions. If an extension specified is not installed in Visual Studio, the Extension Manager/Installer will prevent the VSIX from installing.
The Add Reference dialog can be used to specify a dependency on another extension or add another VSIX as a payload to be deployed with the current VSIX. For specifying dependencies, you may choose between using the information for an installed extension in current instance of Visual Studio or manually specifying the necessary information.
The VSIX Manifest editor provides an easy way to edit a VSIX’s Manifest and adding content to the VSIX. Because it integrates with Visual Studio project system, it ensures that content added through the Add Content dialog is added into the project and is deployed into the VSIX during build. With the Add Reference dialog, you have the option to either deploy your dependencies with your VSIX or declare them so the Extension Installer can verify their presence prior to installation.
|Lance Collins – Developer, Visual Studio Platform Short Bio>: Lance started at Microsoft and Visual Studio six months ago. Since starting, he has worked primarily on Visual Studio SDK with various features around VSIX editing and deployment.|