Quick and Easy Customizing Visual Studio Tool Window Integration Package for Beginner Developers

Introduction

If you are interested in Visual Studio Extensibility technology, this article will help you to customize some of your integrated product's shell properties like:

Changing default icon of tool window integration package
Setting window's icon when it is docked
Adding global shortcut key for your package
Adding information for your package into Visual Studio splash screen and the About dialog box
Integrating with Tools->Options menu.
Adding and removing basic package to IDE using XCopy Deployment

Note: To test the article example, you must have installed Visual Studio SDK 2008. It's downloadable from here.

Changing Default Icons

Before the coming of Visual Studio 2005, if you wanted to change your addin default icon, you could place the resource into a separated satellite assembly and next associate it with an assembly as in this article. It means to edit some registry entries, but into actual Microsoft IDE releases, this isn't needed.

In order to see how the resources integration is working, let's create a sample Visual Studio shell integrated tool window called SomeToolWindow. Follow the wizard and check Tool Window option on page 3. In the Resources folder, just add a bitmap with size 16X16 (larger will be ignored from the shell). Mine is called test.bmp.

Open VsPackage.resx resource file, press CTRL+2 and drag and drop your bitmap into the designer. Rename it to 300. (The bitmap's name must be a unique integer number for the VSPackage.resx file.) Then open the file where your tool window is declared and modify it like:

this.Caption = Resources.ToolWindowTitle;

//This associates your image unique id with your package icon when it is docked.
this.BitmapResourceID = 300;
this.BitmapIndex = 0;

When your tool window is docked, the result is similar to:

To change the default icon of your tool window into View->Other Windows menu, open your project *.vsct file and do the steps:

Add this code to the < Symbols > section:

< Symbols >
   < GuidSymbol name="somesymbol" 
	  value="{9AA1659B-F821-4f24-A398-5D9A4A2BE797}" >
   < IDSymbol name="defaulticon" value="1" />
   < /GuidSymbol >
</Symbols>

Add default icon declaration into the < Bitmaps > section:

< Bitmaps >
 < Bitmap guid="somesymbol" 
     href="Resources\test.bmp" usedList="defaulticon"/ >
 < /Bitmaps >

At least change the attributes of < Icon > tag into < Buttons > section.

< Button guid="guidSomeToolWindowCmdSet" 
	id="cmdidCoolToolWindow" priority="
	0x0100" type="Button">
   < Parent guid="guidSHLMainMenu" id="IDG_VS_WNDO_OTRWNDWS1"/>
   < Icon guid="somesymbol" id="defaulticon" />
   < Strings>
     < CommandName>cmdidCoolToolWindow </CommandName >
     < ButtonText>Cool Tool Window </ButtonText >
   < /Strings>
 < /Button>

Adding Global Shortcut Key

To add a global shortcut key, just add < KeyBindings > child element outside of < Commands > element:

 < KeyBindings >
  < KeyBinding guid="guidSomeToolWindowCmdSet" 
	id="cmdidCoolToolWindow" editor="guidVSStd97"  key1="M" mod1="Control"/>
< /KeyBindings >

Notice that the added shortcut key must be unique for your IDE. If it isn't, the error will be ignored! Items guidSomeToolWindowCmdSet and cmdidCoolToolWindow are part of the guid used to group the menu commands together. It can be found at the bottom of *.vsct of your package or in the body of GuidList class. The value guidVSStd97 of editor attribute indicates that the tool window shortcut is globally available. Now we have a global shortcut key CTRL+M for our tool window.

Adding Information to the Splash Screen and the About Dialog Box

To do this, you must modify the default InstalledProductRegistrationAttribute declaration to:

  [InstalledProductRegistration(true, null, null, null)]

Next add your project icon to Resources folder. Drag and drop it into VsPackage.resx file and rename it to 500. Derive from IVsInstalledProduct interface to provide for your package branding:

public sealed class SomeToolWindowPackage : Package,IVsInstalledProduct
{
    ......................................................

    /// < summary >
    /// provides for splash bitmap resource index
    /// < /summary >
    public int IdBmpSplash(out uint pIdBmp)
    {
        pIdBmp = 300;
        return Microsoft.VisualStudio.VSConstants.S_OK;
    }

    /// < summary >
    /// provides for package icon into Visual Studio startup splash
    /// < /summary >
    public int IdIcoLogoForAboutbox(out uint pIdIco)
    {
        pIdIco = 500;
        return Microsoft.VisualStudio.VSConstants.S_OK;
    }

    /// < summary >
    /// official package name like Microsoft Visual C# 2008 for example.
    /// < /summary >
    public int OfficialName(out string pbstrName)
    {
        pbstrName = "My Cool package";
        return Microsoft.VisualStudio.VSConstants.S_OK;
    }

    /// < summary >
    /// Some details for the product
    /// < /summary >
    public int ProductDetails(out string pbstrProductDetails)
    {
        pbstrProductDetails = "This is cool package I think";
        return Microsoft.VisualStudio.VSConstants.S_OK;
    }

    /// < summary >
    /// ID of the product like C# 2008 ID :91899-270-7631713-60451
    /// < /summary >
    public int ProductID(out string pbstrPID)
    {
        pbstrPID = "Some ID";
        return Microsoft.VisualStudio.VSConstants.S_OK;
    }
 }

Now Visual Studio About box looks like this:

Integrating Your Package Options into Visual Studio Options

To create a customized page for your package settings into Tools->Options menu, add a class that derives from Microsoft.VisualStudio.Shell.DialogPage and put the options you like as properties of this class.

Here is the sample class:

using System;
using System.Diagnostics;
using System.ComponentModel;
using System.Collections.Generic;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Interop;

namespace SomeCompany.SomeToolWindow
{
  public sealed class CoolToolWindowOptions:DialogPage
  {
      private string _SomeSetting = "Some Setting";

      /// < summary >
      /// Just setting description string.
      /// It will be available when you click on the setting into IDE options page
      /// < /summary >
      [Description("This is description of 'some setting' setting")]
      [Category("Misc")]
      [LocDisplayName("'Some setting' display name")]
      public string SomeSetting
      {
          get { return _SomeSetting; }
          set
          {
              if (!string.IsNullOrEmpty(value))
                  _SomeSetting = value;
          }
      }

      /// < summary >
      /// Provides for settings reading
      /// < /summary >
      public  static CoolToolWindowOptions GetCurrent(Package package)
      {
          IVsPackage pack = package as IVsPackage;
          if (pack != null)
          {
              object obj;
              pack.GetAutomationObject("Cool Tool Window.General", out obj);

              Debug.Assert(obj != null, "Error reading settings");
              return obj as CoolToolWindowOptions;
          }
          return null;
      }

      /// < summary >
      /// Initializes the setting to their default values 
      /// (for example when you reset your IDE settings)
      /// < /summary >
      public override void ResetSettings()
      {
          _SomeSetting = "Initial setting value";
          base.ResetSettings();
      }
  }
}

After associating the options class with your package, add ProvideOptionsPageAttribute to your package class declaration.

  [ProvideOptionPage(typeof(CoolToolWindowOptions), 
	"Cool Tool Window", "General", 200, 106, true)]

The result now is similar to:

To save settings after you modify them, just call the DialogPage.SaveSettingsToStorage() method and to reload them, call DialogPage.LoadSettingsFromStorage() method. It's recommended also to override the DialogPage.ResetSettings() method. This will initialize settings with their default values when you reset the IDE ones for example with using Import and Export settings wizard.

To test the example, just copy the assembly file to < Visual Studio installation path >
\Common7\IDE\PrivateAssemblies\ folder, then run the command...

regpkg /regfile:< Exiting path you desire to place .reg file >
   	DeployPackage.reg /assembly: "< Visual Studio installation path >
   	\Common7\IDE\PrivateAssemblies\SomeToolWindow.dll"

... and open DeployPackage.reg file (for example) and restart your IDE. The reg file generated of this command may looks like this:

   REGEDIT4

   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\
   InstalledProducts\SomeToolWindowPackage]
   "Package"="{557960f3-1505-4515-82da-94d7b54efac1}"
   "UseInterface"=dword:00000001
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\Packages\
   {557960f3-1505-4515-82da-94d7b54efac1}]
   @="SomeCompany.SomeToolWindow.SomeToolWindowPackage, 
   SomeToolWindow, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
   "InprocServer32"="D:\\WINDOWS\\system32\\mscoree.dll"
   "Class"="SomeCompany.SomeToolWindow.SomeToolWindowPackage"
   "Assembly"="SomeToolWindow, Version=1.0.0.0, 
   Culture=neutral, PublicKeyToken=null"
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\
   Packages\{557960f3-1505-4515-82da-94d7b54efac1}]
   "ID"=dword:00000001
   "MinEdition"="Standard"
   "ProductVersion"="1.0"
   "ProductName"="Customized Package"
   "CompanyName"="Some Company"
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\Menus]
   "{557960f3-1505-4515-82da-94d7b54efac1}"=", 1000, 1"
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\
    ToolsOptionsPages\Cool Tool Window]
   @="#200"
   "Package"="{557960f3-1505-4515-82da-94d7b54efac1}"
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\
    ToolsOptionsPages\Cool Tool Window\General]
   @="#106"
   "Package"="{557960f3-1505-4515-82da-94d7b54efac1}"
   "Page"="{3b39d0cb-26d4-368d-915c-69257e7ee441}"
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\
    AutomationProperties\Cool Tool Window\General]
   "Name"="Cool Tool Window.General"
   "Package"="{557960f3-1505-4515-82da-94d7b54efac1}"
   [HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\9.0\
    ToolWindows\{5db32bac-74f8-4fbc-b150-56c703984f56}]
   @="{557960f3-1505-4515-82da-94d7b54efac1}"
   "Name"="SomeCompany.SomeToolWindow.MyToolWindow"

Notice that the InprocServer32 key must be a correct path to mscoree.dll.

To remove the package, just run the command:

  regpkg.exe /unregister "< Visual Studio installation path >
  	\Common7\IDE\PrivateAssemblies\SomeToolWindow.dll"

If you have an intention to create *.msi or setup.exe for your package, change target installation directory into generated reg file to [TARGETDIR]Yourpackage.dll. The path to mscoree.dll changes as follows [SYSTEMROOT]mscoree.dll.

Thank you for reading this article.