How to: Migrate extensibility projects to Visual Studio 2017

Applies to: Visual Studio Visual Studio for Mac

This document explains how to upgrade extensibility projects to Visual Studio 2017. In addition to describing how to update the project files, it also describes how to upgrade from extension manifest version 2 (VSIX v2) to the new version 3 VSIX manifest format (VSIX v3).

Install Visual Studio 2017 with required workloads

Make sure your installation includes the following workloads:

• .NET desktop development
• Visual Studio extension development

Open VSIX Solution in Visual Studio 2017

All VSIX projects will require a major version one-way upgrade to Visual Studio 2017.

The project file (for example *.csproj) will be updated:

• MinimumVisualStudioVersion - now set to 15.0
• OldToolsVersion (if previously exists) - now set to 14.0

Update the Microsoft.VSSDK.BuildTools NuGet package

In order to build your extension in the new VSIX v3 (version 3) format, your solution will need to be built with the new VSSDK Build Tools. This will be installed with Visual Studio 2017, but your VSIX v2 extension might be holding a reference to an older version via NuGet. If so, you will need to manually install an update of the Microsoft.VSSDK.BuildTools NuGet package for your solution.

To update the NuGet references to Microsoft.VSSDK.BuildTools:

• Right-click on the solution and choose Manage NuGet Packages for Solution.
• Navigate to the Updates tab.
• Select Microsoft.VSSDK.BuildTools (latest version).
• Press Update.

Make changes to the VSIX extension manifest

To ensure that the user's installation of Visual Studio has all the assemblies required to run the extension, specify all the prerequisite components or packages in the extension manifest file. When a user attempts to install the extension, the VSIXInstaller will check to see if all the prerequisites are installed. If some are missing, the user will be prompted to install the missing components as part of the extension installation process.

• Edit the extension manifest file (usually called source.extension.vsixmanifest).
• Ensure InstallationTarget includes 15.0.
• Add required installation prerequisites (as shown in the example below).
  • We recommend you specify only Component IDs for installation prerequisites.
  • See the section at the end of this document for instructions on identifying Component IDs.

Example:

<PackageManifest>
 ...
    <Prerequisites>
        <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[15.0,16.0)" />
        <Prerequisite Id="Microsoft.VisualStudio.Component.DiagnosticTools" Version="[15.0.25814.0,16.0)" />
        <Prerequisite Id="Microsoft.VisualStudio.Shell.12.0" Version="[12.0]" />
    </Prerequisites>
 ...
</PackageManifest>

Option: Use the designer to make changes to the VSIX extension manifest

Instead of directly editing the manifest XML, you can use the new Prerequisites tab in the Manifest Designer to select the prerequisites and the XML will be updated for you.

• Open source.extension.vsixmanifest [Design] file.

• Select Prerequisites tab and press New button.

  

• The Add New Prerequisite window will open.

  

• Click on the dropdown for Name and select the desired prerequisite.

• Update the version if necessary.

  Note

  The version field will be pre-populated with the version of the currently installed component, with a range spanning up to (but not including) the next major version of the component.

  

• Press OK.

Update Debug settings for the project

If you wish to debug your extension in an experimental instance of Visual Studio, make sure that the project settings for Debug > Start action has the Start external program: value set to the devenv.exe file of your Visual Studio 2017 installation.

It might look like: C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\devenv.exe

Check that the extension builds correctly (as a VSIX v3)

• Build the VSIX project.
• Unzip the generated VSIX.
  • By default, the VSIX file lives inside bin/Debug or bin/Release as [YourCustomExtension].vsix.
  • Rename .vsix to .zip to easily view the contents.
• Check for the existence of three files:
  • extension.vsixmanifest
  • manifest.json
  • catalog.json

Check when all required prerequisites are installed

Test that the VSIX installs successfully on a machine with all required prerequisites installed.

Attempt to install the extension:

• On Visual Studio 2017

• Optional: Check on previous versions of Visual Studio.
  • Proves backward compatibility.
  • Should work for Visual Studio 2012, Visual Studio 2013, Visual Studio 2015.
• Optional: Check that VSIX Installer Version Checker offers a choice of versions.
  • Includes previous versions of Visual Studio (if installed).
  • Includes Visual Studio 2017.

If Visual Studio was recently opened, you might see a dialog box like this:

Wait for the processes to shut down, or manually end the tasks. You can find the processes by the listed name, or with the PID listed in parenthesis.

Check when missing the required prerequisites

• Attempt to install the extension on a machine with Visual Studio 2017 that DOES NOT CONTAIN all the components defined in the Prerequisites (above).
• Check that the installation identifies the missing component/s and lists them as a prerequisite in the VSIXInstaller.
• Note: Elevation will be required if any prerequisites need to be installed with the extension.

Decide on components

When looking up your dependencies, you will find that one dependency could map to multiple components. To determine which dependencies you should specify as your prerequisite, we suggest that you choose a component that has a functionality similar to your extension and to also consider your users and what type of components would they most likely have installed or wouldn't mind installing. We also suggest building your extensions in a way where the required prerequisites satisfy only the minimum that will allow your extension to run and for additional features have them be dormant if certain components are not detected.

To provide further guidance, we have identified a few common extension types and their suggested prerequisites:

Find component IDs

The list of components sorted by Visual Studio product is at Visual Studio 2017 workload and component IDs. Use these component IDs for your prerequisite IDs in your manifest.

If you are unsure which component contains a specific binary, download the Component -> Binary mapping spreadsheet.

vs2017-ComponentBinaryMapping.xlsx

There are four columns in the Excel sheet: Component Name, ComponentId, Version, and Binary / File Names. You can use the filters to search and find specific components and binaries.

For all your references, first determine which ones are in the core editor (Microsoft.VisualStudio.Component.CoreEditor) component. At minimum, we require the core editor component to be specified as a prerequisite for all extensions. Of the references that are left that are not in core editor, add filters in the Binaries / Files Names section to find components that have any of the subsets of those references.

Examples:

• If you have a debugger extension and know that your project has a reference to VSDebugEng.dll and VSDebug.dll, click on the filter button in the Binaries / Files Names header. Search for "VSDebugEng.dll" and select OK. Next click on the filter button in the Binaries / Files Names header again and search for "VSDebug.dll". Select the checkbox Add current selection to filter and select OK. Now look through the Component Name to find a component that is most related to your extension type. In this example, you would chose the Just-In-Time debugger and add it to your vsixmanifest.
• If you know that your project deals with debugger elements, you can search on "debugger" in the filter search box to see what components contain debugger in its name.

Specify a Visual Studio 2017 release

If your extension requires a specific version of Visual Studio 2017, for example, it depends on a feature released in 15.3, you must 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. 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>