FAQ for Visual Studio 2017 extensibility
These are some frequently asked questions about extensibility for Visual Studio 2017.
What is the backwards compatibility story for extensions?
The new VSIX v3 format is backward compatible with VSIX v2, so you'll still be able to have a single VSIX with a single VSIX ID that supports Visual Studio 2012 and later. The new VSIX v3 format does not support Visual 2010 and earlier. To support Visual Studio 2010 onward, you will need to create a separate extension (with a separate VSIX ID). As Visual Studio 2010 is now a small percentage of the user base, we recommend that you use the existing VSIX ID for the extension that supports Visual Studio 2012 or later, and assign a new VSIX ID to the Visual Studio 2010 version.
Why do I need to declare prerequisites with Visual Studio 2017?
Visual Studio 2017 enables a faster and lighter-impact installation of Visual Studio that offers users increased control over the workloads and components that are installed. To ensure that the components required by your extension are installed, with VSIX v3 and Visual Studio 2017, you must declare the components your extension depends upon as prerequisites. If any of the required prerequisites are not available on the user's machine, the user will not be able to run the extension. However, if Visual Studio detects that a user is attempting to install an extension that requires missing components, it will prompt the user to install the required components. If you have optional components, there is no need to list them as prerequisites, provided you perform appropriate feature detection at run-time. All extensions must specify the core editor component as a dependency, Microsoft.VisualStudio.Component.CoreEditor.
When you say prerequisite, what level of granularity do you mean?
You declare prerequisites at the component level, that is, individual options that can be selected in the UI. You do not declare prerequisites on workloads or individual DLLs.
Where do I find a list of Component IDs so I can declare dependencies?
To find the list of Component IDs, look at Visual Studio 2017 Workload and Component IDs. If you are unsure which Component contains a specific binary, you can download the Component -> Binary mapping spreadsheet. For more details on using the spreadsheet, see the Finding Component IDs section in How to: Migrating Extensibility Projects to Visual Studio 2017.
My extension requires Visual Studio 15.3, how do I enforce that requirement?
If your extension requires a specific version of Visual Studio 2017, for example, it depends on a feature released in 15.3, you can specify the build number in your VSIX InstallationTarget. For example, release 15.3 has a build number of '15.0.26730.3'. You can see the mapping of releases to build numbers here. Note that using the release number '15.3' will not work correctly.
If your extension requires 15.3 or higher, you would declare the InstallationTarget Version as [15.0.26730.3, 16.0):
<Installation> <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[15.0.26730.3, 16.0)" /> </Installation>
The VSIXInstaller will detect earlier versions of Visual Studio and inform the user that a later update is required.
I keep getting an error when I try to upload my extension.
It's possible you are using the old version of the VSIX manifest. If your extension is marked as supporting Visual Studio 2017 but doesn't use the new VSIX v3 manifest format, you won't be able to upload it.
I use my own installer. Can I continue to do that?
With Visual Studio 2017, the minimal install of Visual Studio will be significantly smaller than previous versions.
We enhanced the VSIX manifest format to support the changes necessary for light-weight installation. As much as possible, we recommend you provide your extension in a VSIX v3 format. You may need to maintain your existing installer for certain scenarios, such as if you install components outside of Visual Studio.
For example, if you need MSBuild, you would specify that as a prerequisite in the VSIX manifest. When you install the VSIX, the installer will ensure that MSBuild is available.
Your installer then invokes the VSIXInstaller to install a VSIX with your Visual Studio 2017 components.
Can you give me more migration guidance?
You can read more in How to: Migrating Extensibility Projects to Visual Studio 2017. In addition, there is a great blog post, Changes to Visual Studio Setup.
How do I do package registration?
You do package registration the same way it was in the past with registry entries. The only change is that the registry is now being detoured and you must declare your registry entries from a .pkgdef file.
If you use the
PackageRegistrationAttribute, this should happen automatically.
Will I need a new gallery entry for the Visual Studio 2017 version of my extension?
No, you won't need a new entry on the Visual Studio Gallery for the updated VSIX, provided your changes are fully backward compatible with all your supported versions. If your extension is not backwards compatible, we recommend you split your extension into multiple VSIXs (even if temporarily), each with their own VSIX ID and entry on the Gallery.
What should I do with my extension that currently supports Visual Studio 2010 and later?
Add support for Visual Studio 2017 to the current VSIX and maintain support for Visual Studio 2012 and later. In addition, create a new VSIX (with new GUID and Gallery entry) with support for Visual Studio 2010.
Can I build a VSIX v3 with Visual Studio 2015?
Yes. There is a NuGet package which has the necessary tools and tasks to build VSIX v3 format manifests in Visual Studio 2015. Add a reference to NuGet package
Microsoft.VisualStudio.Sdk.BuildTasks.14.0 to your extensibility project. You will also need to add the
VsixType element specifying
v3 to your project file:
Can I run the VSIXInstaller in quiet mode?
You will need to pass additional parameters to the VSIXInstaller now that there are potentially multiple instances of Visual Studio 2017 installed.
vsixinstaller.exe /q /appidinstallpath:"c:\program files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\devenv.exe" /appidname:"Visual Studio" /logFile:<path to log file> /skuName:Enterprise /skuVersion:15.0.25810.0 "KendoUI.Mvc.VSPackage.vsix"
Why does the VSIXInstaller now wait for processes to exit before installing the VSIX?
The VSIXInstaller now uses the Visual Studio setup engine to install any prerequisites defined by the VSIX. The setup engine requires all VS related processes to exit before it can update the Visual Studio installation.
Can I now install my extension assets to any location with VSIX v3?
No, the VSIX v3
InstallRoot property does not allow you to install anything outside the Visual Studio install folder structure. See the Installing outside the extensions folder topic for supported locations.
Extension components that aren't part of Visual Studio are likely to be singletons on the computer and they get installed once for all Visual Studio 2017 instances.
The recommendation for that scenario would be to author an MSI for the non-Visual Studio components and have the MSI invoke the VSIXInstaller to install the Visual Studio specific components.