Deploying Analyzers and Refactorings to the Visual Studio Gallery

Note: The content of this chapter does not apply to Visual Studio 2015 Express editions.

For years, developers have used the Visual Studio Gallery for downloading third-party extensions for Visual Studio (via the integrated Extensions Manager tool) and publishing custom extensions so they can be consumed by other developers. Now, you can also publish code analyzers and refactorings to the Visual Studio Gallery in the form of Visual Studio extensions and make them available to other developers via the familiar IDE instrumentation.

Understanding VSIX Packages

When you create analyzers and refactorings, both the Analyzer with Code Fix (NuGet + VSIX) and the Code Refactoring (VSIX) templates include a project that automates the generation of a VSIX package, which you can easily see in Solution Explorer because its name ends with .vsix. VSIX packages are compiled, self-installing .vsix files that contain extensions for Visual Studio. If you ever installed an extension for Visual Studio from either the Visual Studio Gallery or the integrated Extensions Manager tool, you might already know that such an extension is deployed with a VSIX package. An extension for Visual Studio is a .dll library tailored to be plugged into the IDE that extends the environment with custom features such as new commands, custom tool windows, and more.

Behind the scenes, VSIX packages are Open XML compressed files that contain:

• The .dll library.
• A package manifest called extension.vsixmanifest that contains information such as the author information, version number, package description, package dependencies, and the list of Visual Studio editions the package is intended for.
• The license agreement that the user must accept in order to install the extension.
• An optional icon and preview image that will be used to present the extension in the Visual Studio Gallery and in the Visual Studio Extension and Updates dialog.

You can easily investigate the content structure of a VSIX package by opening a .vsix file with an archiver tool such as WinZip or WinRAR. Because both code analyzers and refactorings are .dll libraries that can be plugged into the code editor, they can be packaged into VSIX files and recognized as if they were Visual Studio extensions. Fortunately, Visual Studio 2015 automatically generates VSIX packages for you, making the deployment experience easier.

Note: When you press F5 to debug an analyzer or refactoring in the experimental instance of Visual Studio 2015, the IDE first installs the auto-generated VSIX package to the experimental instance. This is necessary to allow you to debug an analyzer or refactoring through the usual debugging instrumentation.

Preparing an Example

In this chapter, you will see how to deploy a code refactoring to the Visual Studio Gallery. This section looks at code refactorings due to the fact that the Visual Studio 2015 project template for code refactorings does not include support for NuGet, but only automates the generation of a VSIX package. On the other hand, the project template for code analyzers automates the generation of both a NuGet package and a VSIX package. As a result, the steps described in this chapter apply to both refactorings and analyzers. With that in mind, in Visual Studio 2015, open the PublicFieldRefactoring project you created back in Chapter 5. This will serve as the base for deployment.

Preparing for Publication

Before you publish a VSIX package, you need to edit some information included in the package manifest, which contains information such as the package description, author name, license agreement, release notes, icon and preview images, and links to documentation. The package manifest is called source.extension.vsixmanifest, and is available in the .vsix project. Editing the manifest is very easy since Visual Studio 2015 offers a convenient designer, which you enable by double-clicking source.extension.vsixmanifest in the Solution Explorer. Figure 43 shows how to edit the package manifest.

Figure 43: Editing the package manifest

The designer is composed of several tabs: Metadata, Install Targets, Assets, and Dependencies. In the Metadata tab, you supply all the information that will be shown to other developers in the Visual Studio Gallery and in the Extensions Manager tool, which is very important to identify and describe the package. One thing you should not change is the Product ID field, which contains a unique identifier containing a GUID for your product. You can edit the author name, the product name, and provide a full description of what the package does. You are also strongly encouraged to choose a license agreement, which must be a .txt file. The other information is optional.

Another important tab is Install Targets, where you specify the Visual Studio editions that can receive your package. When you open this tab, you will see a list of supported editions. At the time of writing, the Express editions are not supported, so select each Express edition, and then click Delete. You might want to include the Visual Studio 2015 Community edition instead, so click New. In the Add New Installation Target dialog box (see Figure 44), select the Microsoft.VisualStudio.Community option from the Product Identifier combo box. The Version Range field will be filled automatically. When you’re done, click OK.

Figure 44: Specifying a supported edition of Visual Studio

At this point, the designer will show the newly added edition, plus the Visual Studio Professional edition supported by default, as demonstrated in Figure 45.

Figure 45: Supported editions of Visual Studio

Note: Pro edition means Professional and higher, so there is no need to specify the Enterprise edition, which is supported implicitly.

The Assets tab allows specifying additional project targets that will be packaged into the VSIX file. The Dependencies tab contains the list of frameworks and libraries that an extension depends on. In the case of analyzers and code refactorings, you do not need to edit the content of these tabs because they are already tailored for these types of libraries. However, it’s worth mentioning that the Dependencies tab is where you can optionally specify any possible analyzer or refactoring dependencies. This is different from the NuGet experience, where dependencies are resolved automatically.

Once you have supplied the necessary information, ensure the build configuration is set to Release and compile the project. The build process produces a stand-alone, self-installing VSIX package that can be shared in a number of ways, or installed on the local machine by double-clicking. In the current scenario, the generated VSIX package will be published to the Visual Studio Gallery.

Tip: Changes you make in the package manifest are also visible in the experimental instance of Visual Studio when you debug a refactoring or an analyzer. To demonstrate this, start debugging with F5, and then open the Extensions Manager tool. If you select the current refactoring or analyzer, you will see the updated product information.

Publishing to the Visual Studio Gallery

Open the Visual Studio Gallery and sign in with your Microsoft Account using the Sign In link in the upper-right corner. When signed in, you will have options to upload new extensions and manage your published extensions (if any). Click Upload (see Figure 46) to start the Upload wizard.

Figure 46: Visual Studio Gallery home page

The first thing you will do is specify the extension type. Select Tool (see Figure 47) and then click Next.

Figure 47: Specifying Tool as the extension type

In this step, you will specify the VSIX package to upload. Select I would like to upload my tool, and then click Browse (see Figure 48).

Figure 48: Specifying the VSIX package to upload

At this point, locate and select the VSIX package that contains the code refactoring. As a general rule, it is located under the Bin\Release subfolder of the VSIX project. In this case, it is PublicFieldRefactoring_VB.Vsix\Bin\Release for Visual Basic or PublicFieldRefactoring_CS.Vsix\Bin\Release for C#. Click Next when you’re ready. In the next step (see Figure 49), you will see summary information that the Gallery takes from the package manifest, and you will be asked to do the following:

• Select up to three categories to help developers recognize the extension’s purpose.
• Specify a cost category of Free, Trial, or Paid.
• Specify one or more tags that will help developers find your extension on the Gallery.

Categories and tags are totally your choice, but I recommend selecting Coding and Programming Languages as categories, and specifying Roslyn as a tag. In the Cost category drop-down menu, select Free. If you decide to use Trial or Paid, implementing the purchase logic is your own responsibility; the Visual Studio Gallery will basically inform users that an extension is not free.

Figure 49: Categorizing your package

A detailed description of the package content must also be supplied. Scroll down the page and provide a description, as shown in Figure 50. You can take advantage of the built-in editor that also allows formatting text and adding multimedia.

Figure 50: Providing the package description

Ensure your description is at least 280 characters long; otherwise, an error message will appear (see Figure 50). When you’re done, read and accept the contribution agreement, and click Create contribution. At this point, your contribution has been created and you have an option to see a preview of how it will appear to other developers (see Figure 51).

Figure 51: Reviewing your contribution before it’s public

If you are satisfied with the preview and it matches your requirements, click Publish so that it will be immediately available for downloading. If you wish to make any modifications, click Edit instead. With a few simple steps, you have published a code refactoring to the Visual Studio Gallery. Remember that the same steps apply to analyzers, too.

Downloading and Installing Code Analyzers and Refactorings from the Visual Studio Gallery

To understand the developer experience with an analyzer or refactoring available from the Visual Studio Gallery, launch Visual Studio 2015, and then select Tools > Extensions and Updates. Select the Online tab, and in the search box, type Roslyn. As you can see in Figure 52, the code refactoring appears in the list of available extensions, also showing the package description.

Figure 52: Finding a code refactoring in the Visual Studio Gallery

Click Download. When the download completes, you will be asked to accept the included license agreement (see Figure 53).

Figure 53: Accepting the package license agreement

When you click Install, Visual Studio 2015 will complete the install operation in a few seconds. Notice that you will be asked to restart Visual Studio after the installation completes. Once Visual Studio has restarted, create a new console application. Add a new class and a public field declaration in it, as shown in Figure 54.

Figure 54: Testing the code refactoring

Right-click the Public keyword, select Quick Actions, and see how the newly installed code refactoring works perfectly, allowing you to change public field member identifiers to uppercase.

Uninstalling Code Analyzers and Refactorings

Analyzers and refactorings installed from the Visual Studio Gallery can be easily disabled or uninstalled. To accomplish this, select Tools > Extensions and Updates, and in the list of installed extensions, select the one you want to disable or remove. Figure 55 shows the code refactoring described in this chapter.

Figure 55: Disabling or uninstalling a code refactoring

Select Disable or Uninstall, but remember that the selected refactoring (or analyzer) will not be available to any projects until you explicitly re-enable or reinstall.

Differences between NuGet and the Visual Studio Gallery

There are a number of differences between sharing analyzers through NuGet and the Visual Studio Gallery. The following is a list of important differences that you might want to consider when you have to decide where to publish your work:

• NuGet packages are per project. Every time you create a new project, you will need to install the analyzer or refactoring from NuGet.
• VSIX packages are Visual Studio extensions, so they are always available to new and existing projects. You need to disable or uninstall packages explicitly if you do not want your projects to use them.
• NuGet packages automatically resolve any dependencies an analyzer or refactoring might rely on.
• VSIX packages do not automatically resolve any dependencies an analyzer or refactoring might rely on. You are allowed to add dependencies manually in the Dependencies tab of the package manifest.
• VSIX packages are self-installing. This means that you can share a .vsix file not only through the Visual Studio Gallery, but in any way you want. For example, you could share one with a shared network path, email, or a USB flash drive. The recipient will simply double-click the file to install the extension. Installation is powered by the VSIX Installer engine, which integrates with the operating system.
• Updating packages with a new version is pretty similar. For NuGet packages, Visual Studio 2015 automatically updates the version number. For VSIX packages, you update the version number manually in the package manifest editor. For both, you upload the updated package in the respective website.

Of course, you are totally free to publish analyzers and refactorings to both NuGet and the Visual Studio Gallery.

Chapter Summary

Analyzers and code refactorings can be published to the Visual Studio Gallery in the form of VSIX packages. Project templates for both analyzers and refactorings automate the generation of a stand-alone VSIX package that can be shared with other developers in many ways. Visual Studio 2015 includes a convenient designer that you use to edit the package manifest, whose information will be shown to other developers. Concerning publishing, the Visual Studio Gallery allows publishing a VSIX package with a few steps, providing an option to review the package information before it is available to the public. Using analyzers and refactorings deployed in this way is very simple: the Extensions and Updates dialog in Visual Studio 2015 allows searching for and downloading both components in the same way you would search for and download any other Visual Studio extension.