VS 2017, VS Extensibility

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

18 Comments

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):

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

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):
<Prerequisites>
   <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[15.0.25904.2,16.0)" DisplayName="Visual Studio core editor" />
</Prerequisites>

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 two .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.

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

  2. 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.

  3. 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=15.0.0.0, 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=15.0.0.0, 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:

    https://social.msdn.microsoft.com/Forums/vstudio/en-US/e3109928-68b4-4edb-ad7f-d78af58cbc92/after-upgrading-to-vs-2015-update-2-my-vsix-project-does-not-build?forum=vsx

    https://gitter.im/Microsoft/extendvs/archives/2016/11/19

    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?

    Thanks,
    Warren

    1. After getting some help on https://gitter.im/Microsoft/extendvs 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. 🙂

      2. @Warren
        We too have many problems while updating our VSIX.
        One solution was to delete the entry under
        C:\Users\\AppData\Local\Microsoft\VisualStudio\15.xxxExp

        What has been your solution?
        Thanks
        Hannes

  4. “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?

  6. I installed 2017, upgraded the project, and added the prerequisites section, but it still doesn’t create the 2 json files.
    I even tried adding the SDK build tools GIT package – even though I had installed the VS2017 SDK component so that it shouldn’t be required. Same result.
    Is there something else that might be making it think it is a V2 package … or causing it to use the 14.0 build tools?

    1. I’d suggest to start a dummy VSIX project and package from start and then compare with the migrated project.

  7. Thanks. I had already tried that … but I had missed the fact that a path [symbolic] had changed in 2 Imports at the bottom of the project file. When I changed it to the new symbolic it started to generate the missing files.

    1. It now successfully builds the package and says it has installed correctly in both 2017 and 2015 … but the extension does not work. (no new menus or windows are available)
      There are no error messages and the ‘Extensions and Updates’ page seems to indicate that all is well.

      I tried using the /log parameter when launching VS but the log produced simply says that the extension was loaded correctly. Is there something I can switch on to make it display the actual load process and whatever error is causing it not to actually load even though it seems to think it has?

      Thanks

        1. Thanks.
          I finally realized that the pkgdef file was not getting generated – hence no menus etc.
          I had updated the project file by copying lines from an empty 2017 VS extension template project … and for some reason that project had GeneratePkgDef=false.
          When I changed that to ‘true’ everything started to work.

Comments are closed.