How VSIX extensions are discovered and loaded in VS 2010
VSIX is the new technology used for deploying extensions in Visual Studio 2010. The primary goal of this new technology is to encourage extension creation and consumption by easing the management (“management” meaning Browsing/Installing/Uninstalling/Enabling/Disabling) of Visual Studio extensions. To take full advantage of the VSIX installer for deploying your extensions, it helps to know a little bit more about how Visual Studio decides which extensions to load.
Dmitry Goncharenko provided a good high-level overview of how these VSIX extensions are discovered and loaded in his post Bootstrapping of VS packages and VSIX extensions in VS2010. Let’s now take a more in-depth look at how this process works.
An extension consists of:
- an extension.vsixmanifest file, which contains metadata about the extension
- any additional files that represent the extension content. This could include MEF assemblies, VS Package assemblies, VS Template ZIP files, PkgDef files, etc..
The simplest vsix extension would contain only the extension.vsixmanifest file, though that would admittedly be a very uninteresting extension.
In accordance with the goal of simplicity, a VSIX extension install consists of only copying the extension files into one of a few well-known locations. These locations are defined in the “Master PkgDef” file, located at <VsInstallRootFolder>Common7IDEdevenv.pkgdef and pictured below.
The relevant values are described below.
|ApplicationExtensionsFolder||The root folder under which machine wide VSIXs are deployed.
(This is set as <VsInstallRootFolder>Common7IDEExtensions)
|UserExtensionsRootFolder||The root folder under which user specific VSIXs are deployed.
(This is set as %LocalAppData%MicrosoftVisualStudio10.0Extensions)
|PkgDefSearchPath||A list of additional folders where extensions will be searched for. The name for this property was originally defined by the PkgDef subsystem. This list is shared with vsix extensions so that any extensions that contain .pkgdef files will be properly loaded. Note that this includes ApplicationExtensionsFolder.|
Upon initialization, the Extension Manager service, SVsExtensionManager, will search the above locations for extension.vsixmanifest files. The PkgDefSearchPath folders are searched first, followed by the UserExtensionsRootFolder.
Extension Loading Rules
At this point, each extension must pass a few trials before being considered installed by the Extension Manager. Before diving into the details, here’s a quick summary of these:
- The extension.vsixmanifest XML conforms to the XSD.
- The extension has not been marked for deletion.
- The extension’s identifier cannot conflict with any other previously discovered extensions.
First, if the extension.vsixmanifest XML does not conform to the VSIX manifest XSD schema, it is ignored. If the manifest XML passes schema validation, then it will be deserialized into an object model in memory. Second, the Extension Manager needs to verify that the extension is not marked for deletion. Before going any further, it would be helpful to discuss what exactly this means.
If you’ve uninstalled an extension through the Extension Manager dialog in Visual Studio, you may have noticed that the uninstall occurs extremely fast. This is because the extension is only marked for deletion at that time. On a subsequent initialization of the Extension Manager (the next time Visual Studio or the VSIX Installer are launched), all of the pending deletions are cleaned up on a background thread *after* all installed extensions have been discovered. Therefore, any extension that is marked for deletion should be discarded and no longer considered installed.
Third, if the extension contains the same ID as another extension that has already been discovered, it will be discarded. This is where the search order becomes important. The UserExtensionsRootFolder is searched last in order to give precedence to machine wide extensions when an ID conflict is encountered.
Once an extension has passed these checks, it is considered “installed” by the Extension Manager service. Figuring out whether an extension is not installed because of one of the above reasons is easy since the Extension Manager logs this information to the Visual Studio activity log. The activity log can be enabled by running the Visual Studio process (<VsInstallRootFolder>Common7IDEdevenv.exe) with the ‘/log’ switch, as follows:
devenv.exe /log <path_to_log_file>
The Mechanics of Enabled/Disabled Extensions
So your extension is successfully “installed”, but how does the Extension Manager determine whether it’s “Enabled”? The answer depends upon where your extension is installed. Extensions installed to any directory in the PkgDefSearchPath list of folders are always enabled. Extensions installed to the UserExtensionsRootFolder path must be individually enabled through a list maintained in the HKEY_CURRENT_USERSoftwareMicrosoftVisualStudio10.0ExtensionManagerEnabledExtensions registry key. The Extension Manager Install API, used by the extension install dialog as well as the VSIX installer, will write the entry in the EnabledExtensions key for any newly installed extension so that extensions installed in this manner are automatically enabled. You’ll notice that if you manually install an extension by copying the extension files to a subfolder in the UserExtensionsRootFolder path, it will be disabled at first because the corresponding entry in EnabledExtensions has not been added. Enabling the extension can also be accomplished through the Extension Manager dialog.
Lastly, extensions in the UserExtensionsRootFolder path will all be disabled when running Visual Studio as an administrator, if the following option is not checked under Tools->Options->Environment->Extension Manager
This option was likely the most common culprit for why users (particularly administrators running WindowsXP) found that their extensions were not enabled in Beta2 and prior builds of Visual Studio, since the default value for the option was ‘False’. Due to the frequency with which customers ran into this problem, we’ve changed the default value for this option to ‘True’. Note that the Extension Manager dialog provides a warning if you’re running Visual Studio elevated, but do not have this option checked.
When in doubt about why an extension does not seem to be loaded or enabled, you should consult the Visual Studio activity log, which will output various diagnostics during the loading process. You may also want to check out the following posts related to extension loading:
- What’s A PkgDef? And Why?
- Bootstrapping of VS packages and VSIX extensions in VS2010
- Pkgdef and the Experimental Instance in VS 2010
Mariano Blanco: Developer, Visual Studio Platform
Mariano started in the Visual Studio Ecosystem team at Microsoft in 2007. He now works on the Visual Studio Platform Extensibility team and is responsible for the Extension Manager API and the VSIX installer tool shipping in Visual Studio 2010.