It’s time to change the VSIX manifest of your extension to v3 for Visual Studio 2017 compatibility

I still see, even as today Jan 10, people asking why you get this error when trying to install your extension on Visual Studio 2017 RC:

“The following extensions are not compatible with Visual Studio 15. Installation may cause Visual Studio to be unstable”:

or this other one when you try to upload the extension to the Visual Studio Gallery:

“This extension targets Visual Studio 2017 but was not build with an up-to-date VSSDK. Please make sure to update your references and try uploading again. Note: you’ll also need to add Prerequisites to your extension.vsixmanifest.”:

In both cases, the answer is the same: you have just updated the extension.vsixmanifest of your Visual Studio 2015 extension to add 15.0 (for Visual Studio 2017):

 <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[14.0, 15.0]" />

But that is not enough to add compatibility for Visual Studio 2017. Even worse, some people wonder if you can live ignoring those warnings.

The short answer to make an extension compatible with Visual Studio 2017 is the following:

  • You need to build it with Visual Studio 2017, you cannot use Visual Studio 2015 (at least at this time). Updated (Feb 7): actually you can build with VS 2015. Updated (Mar 3): as explained in the FAQ entry Can I build a VSIX v3 with Visual Studio 2015?
  • You need an updated pre-release VS SDK (via NuGet). Updated (Feb 7): The Nuget VSSDK 15.0 is no longer prerelease. This VS SDK generates two additional files (catalog.json and manifest.json) inside the output .vsix file (which being a .zip file really, you can rename and unzip to inspect) that were not present in the .vsix generated by the VS 2015 SDK.
  • You need to update the InstallationTarget range in the extension.vsixmanifest (likely this is the only thing that you have done).
  • You need to convert the extension.vsixmanifest to version 3, which is the only version that Visual Studio 2017 accepts (and the Visual Studio Gallery for extensions targeting Visual Studio 2017). Version 3 is backwards compatible with version 2, which means that all fields are the same (including the Version=”2.0.0″!). The only difference is that version 3.0 adds a mandatory section for the prerequisites. At the very least you need to specify the Visual Studio Core Editor (Visual Studio 2017 has an editor to enter values in a friendly way):
   <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[15.0.25904.2,16.0)" DisplayName="Visual Studio core editor" />

The long answer, with links to resources is on my post Visual Studio 2017 RC announced. Extensions need some changes, and for advanced topics read Some implications of the new modular setup of Visual Studio 2017 for VSX developers.

Now, once that you have assumed that you need a v3 VSIX manifest for Visual Studio 2017, you may wonder how to support multiple instances of Visual Studio from VS 2010 to VS 2017 with the same .vsix: you can’t, because VS 2010 only accepts manifest v1, while VS 2012, VS 2013 and VS 2015 accept manifest v1, v2 or v3 (backwards compatible with v2), and VS 2017 only accepts manifest v3. You need to .vsix files. So, you have two choices:

  • Create a VSIX with manifest v1 for VS 2010, VS 2012, VS 2013 and VS 2015, and another VSIX with manifest v3 for VS 2017. This is the most suggested approach, but there is a better one.
  • Create a VSIX with manifest v1 for VS 2010, VS 2012 and VS 2013, and another VSIX with manifest v3 for VS 2015 and VS 2017. Why? Because VS 2015 introduced APIs not available in previous versions that you can use in VS 2015 and VS 2017 to make your extension a better citizen, such as How to: Use AsyncPackage to Load VSPackages in the Background and How to: Use Rule-based UI Context for Visual Studio Extensions.
  • Updated (Feb 7): if you are not targeting VS 2010 but only VS 2012 and higher, you can have a single VSIX using v3 for VS 2012, 2013, 2015 and 2017.

To get support from Microsoft, you can become a Microsoft Visual Studio Industry Partner (VSIP) “Basic” level for free and get access to workshops explaining the migration process, or you can use Gitter (Microsoft/extendvs), where people from Microsoft and other VSX developers answer questions, the MSDN Visual Studio Integrate Forum that I visit daily, or StackOverflow. And if you find bugs or want to provide suggestions to Microsoft, you can also send feedback to Microsoft about Visual Studio Extensibility through several ways.

Email this to someoneTweet about this on TwitterShare on LinkedInShare on FacebookShare on Google+

10 thoughts on “It’s time to change the VSIX manifest of your extension to v3 for Visual Studio 2017 compatibility”

  1. If your extension has an entry in the Visual Studio Marketplace, and that entry has amassed a pile of reviews, ratings, Q&A’s etc., I’d recommend a third choice: use that existing Marketplace entry for a version targeting as many VS versions as possible, meaning VS 2012-2017, and only introduce a new VSIX for your smallest possible audience, meaning VS 2010.

  2. I have to VSIX installers, one for 2015 and the other for 2017. Unfortunaly when I try to install the 2015 version I get an error about the manifest being corrupt. The issue is that since I installed VS 2017 after VS 2015, 2017’s version of vsixinstaller.exe is associated with .vsix files. So when I double click on my 2015 VSIX, it uses the newer installer which doesn’t find catalog.json and manifest.json and fails with the rather unhelpful error message. I can always directly invoke the vsixinstaller.exe from VS 2015, but that’s not very user friendly.

    I read in the above comments that I should be able to simply update my Microsoft.VSSDK.BuildTools NuGet package to v15 so the generated 2015 VSIX will contain the required files. Unfortunately once I did that I get this build error:

    Microsoft.VsSDK.targets(621,5): error MSB4018: The “GetExtensionsPath” task failed unexpectedly.
    Microsoft.VsSDK.targets(621,5): error MSB4018: System.IO.FileNotFoundException: Could not load file or assembly ‘Microsoft.VisualStudio.Settings.15.0, Version=, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a’ or one of its dependencies. The system cannot find the file specified.
    Microsoft.VsSDK.targets(621,5): error MSB4018: File name: ‘Microsoft.VisualStudio.Settings.15.0, Version=, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a’
    Microsoft.VsSDK.targets(621,5): error MSB4018: at Microsoft.VsSDK.Build.Tasks.GetExtensionsPath.Execute()
    Microsoft.VsSDK.targets(621,5): error MSB4018: at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
    Microsoft.VsSDK.targets(621,5): error MSB4018: at Microsoft.Build.BackEnd.TaskBuilder.d__26.MoveNext()

    Searching on that led to a few hints:

    So if I disable VSIX deployment it builds fine and my VSIX has the new files, but now I can no longer debug in 2015. I seem to have the latest Microsoft.VSSDK.BuildTools – 15.0.26201.

    Is that a known issue or am I just missing something?


    1. After getting some help on my problem is resolved. I can build a VSIX from 2015 that installs with 2017’s vsixinstaller.exe. I updated my Microsoft.VSSDK.BuildTools to 14.3.25420, but I’m not sure that’s even relevant. The main issues seems to be the prerequisite I had. It seems to work if I just have

      instead. The error message was very misleading and seems to have led me on a wild goose chase, but at least I’m past it now. 🙂

  3. “Updated (Feb 7): actually you can build with VS 2015.”

    This is a vague update to building the VSIX with VS 2015. Does this mean the resulting VSIX will be compatible with VS 2017? From what I’ve seen, it doesn’t create a VSIX v3 compatible file. Are there extra steps to achieve this build setup?

Leave a Reply

Your email address will not be published. Required fields are marked *