Keyvan Nayyeri

In the past couple of months I’ve been writing a blog post series about Visual Studio add-in and integration package to compare their structure, applications, and differences, and some related stuff. So far I’ve written five parts:

• An overview and historical perspective
• Technical structure of an add-in and its applications
• Technical structure of a Visual Studio integration package its applications
• Differences between add-ins and VSPackages
• How to choose between add-ins and VSPackages

In this sixth and last part I want to give a short overview of general steps to upgrade an add-in to an integration package and wrap the discussion up.

How to Upgrade an Add-In to an Integration Package

You’re not always going to build an extension from the scratch. You may have some older add-ins in hand that you’d like to upgrade to VSPackages in order to have a better integration and provide better features.

Generally, there isn’t a documented constant progress to upgrade an add-in to an integration package. You might expect to see a classic wizard like Visual Studio solution upgrade wizard or a multi-step process that can simply guide you to upgrade an add-in to a VSPackage, but there aren’t such options available. This upgrade process varies based on your existing add-in and its features as well as the VSPackage that you want to build and its features.

However, with a simple example and some theoretical discussions I just want to give you an idea on how to perform this upgrade task easier. There are some general guidelines that you need to consider when performing the upgrade.

Add-ins are associated with one or more commands in the IDE and in a similar mechanism VSPackages register some commands, too. For a VSPackage, each element is associated with one or more commands. When upgrading an add-in to a VSPackage, you need to move your logic to the appropriate events. This depends on your project. For instance, you may have an add-in that displays something as a Tool window. In this case you need to move the code logic to the command associated with the Tool window in your VSPackage. This is a common step in your upgrade process but in details it varies based on your project.

There are some visual user interface elements in the IDE that you may use for your add-ins. In this case, you need to find the appropriate element in the VSPackage and then move your Windows Forms and user controls to the VSPackage and apply them in the element.

Of course, VSPackages provide much more functionality, features, and elements than add-ins so you always are moving from a smaller space to a larger one and will not require all features of the VSPackages to get it to work.

In the below example I suppose that there is an add-in with some basic features that I’d like to upgrade to a VSPackage. This add-in simply shows a text message in the MessageBox when user triggers the command for the add-in. This may be via a manual call of the command or clicking on the Tools menu option. The main part of the source code of this add-in is presented below.

public void Exec(string commandName, vsCommandExecOption executeOption, ref object varIn, ref object varOut, ref bool handled)
{
    handled = false;
    if (executeOption == vsCommandExecOption.vsCommandExecOptionDoDefault)
    {
        if (commandName == "SampleAddin.Connect.SampleAddin")
        {
            ShowMessage(); 

            handled = true;
            return;
        }
    }
} 

private void ShowMessage()
{
    MessageBox.Show("Visual Studio Extensibility");
}

Now suppose that I want to upgrade this add-in to a VSPackage. All I need to do is simply moving my code logic to VSPackage and bind it to the appropriate command. Of course, this is the most common scenario because many of the add-ins are built on topic of the commands.

When you’re creating a new VSPackage, Visual Studio opens a wizard and asks you to enter information for some commands that are associated with your command window or Tools menu option. You can use these commands to upgrade your add-in to an integration package.

Here I just add my logic to the MenuItemCallback method of the package. This method is called whenever you run the command for the menu item of your VSPackage whether manually or by clicking on the menu item. So in in the code below the MenuItemCallback simply implements the same logic for the VSPackage.

private void MenuItemCallback(object sender, EventArgs e) 
{ 
    IVsUIShell uiShell = (IVsUIShell)GetService(typeof(SVsUIShell)); 
    Guid clsid = Guid.Empty; 
    int result; 

    MessageBox.Show("Visual Studio Extensibility"); 
}

Summary

This post series walked through something that heavily relies on developer’s experience and knowledge, and just tried to give some theoretical points and guidelines to help you understand the key characteristics, similarities, and differences between add-ins and VSPackages as well as when to use each, and how to upgrade an existing add-in to a VS integration package.

Although I gave some guidelines, your experience is a very important parameter to achieve everything covered in this series and it was just an attempt to give a better understanding of concepts and put you on the right way.