Tutorial 2-- Creating Your First VSPackage

Article
11/15/2007

Here's a preview of the new Tutorial 2. It's been updated for Visual Studio 2008 and Windows Vista.

The menu event handler section has been rewritten to use the .vsct format.

Submitted by Martin Tracy. This posting is provided "AS IS" with no warranties, and confers no rights.

Tutorial 2: Creating Your First VSPackage

A VSPackage is the unit of extensibility you build when extending to Visual Studio.

At the core, a VSPackage is a co-creatable COM object that implements the IVsPackage interface.

However, by using the Managed Package Framework (MPF) introduced in Visual Studio 2005,

you no longer need to implement the IVsPackage interface yourself because it provides a base class

implementation that you can inherit from. The interface is completely abstracted and you will not even see it.

We will use the MPF throughout this and other tutorials.

The VSPackage wizard creates a VSPackage project in Visual Studio that consists of everything you need
to create your extension. The VSPackage project includes several source and configuration files,
including a file that includes a class that you name when you set up the project.
This class is derived from a class called Package (supplied by MPF) and includes attributes that
define how your VSPackage should operate with Visual Studio. Additionally, this class contains
initialization code and other code such as menu item handlers.
This class is the foundation of your VSPackage.

In this tutorial, you will create a new VSPackage and customize the VsPkg.cs file in various ways.

You will learn how to:

· Create a VSPackage with the project wizard.

· Implement the menu item handler.

· Add a default keyboard shortcut.

· Add custom information to Splash screen and Help/About dialog box.

· Obtain and use a Package Load Key.

Create a VSPackage with the project wizard

1. Open Visual Studio 2008.

2. On the File menu, point to New, and then click Project. In the New Project dialog box,
expand Other Project Types in the left tree view and click Extensibility.
Under Visual Studio installed templates on the right, click Visual Studio Integration Package.
Check Create Directory for Solution, then type in First in the Name field.
Type in a good Location for the solution, such as D:\ExtendVS. Click OK.

3. On the wizard welcome page, click Next. The Select a Programming Language dialog box appears.

4. Click Visual C# (or Visual Basic), then click Generate a new key file to sign the assembly.

5. Click Next. The Basic VSPackage Information dialog box appears.

6. Type FirstPackage in the VSPackage name field, and accept the remaining defaults.
This information is used in a later step to generate the Package Load Key (PLK).

For more information on these fields, and on obtaining and installing PLK’s , see VSPackage Load Keys.

7. Click Next. The Select VSPackage Options dialog box appears.

8. Select Menu Command and click Next. The Command Options dialog box appears.

9. In the Command name field, type First Command (this is the text that will appear on the menu).
Next to Command ID, type cmdidFirstCommand (this is the identifier that will be used
throughout your code to identify the command).

10. Click Next. The Select Test Options dialog appears.

11. Click Finish. After a few moments, the wizard will create a new Visual Studio project for you.

Initially, you'll have a basic project with minimal functionality. You can try it out by clicking Debug
and then clicking Start without debugging.

The first time the project builds, it could take a few minutes, and you could get a warning message
that appears over the Windows tray saying that Visual Studio is busy. After a few more moments,
the experimental build of Visual Studio will open and your extension will be loaded.

12. In the experimental build, open the Tools menu, where you'll see a First Command menu item,
the same name you typed in the wizard.

13. Click First Command. The message box like the following will appear:

The message box you've just seen comes from code in the handler for the menu item.
This handler is in the FirstPackage.cs file.

1. From the Solution Explorer, open the file FirstPackage.cs.

2. Find the FirstPackage class. The FirstPackage class is defined this way:

public sealed class FirstPackage : Package

You can see that the class is derived from the MPF Package class.

3. Find the code for the menu handler, which is implemented by the MenuItemCallback method.
The menu handler function is a standard event handler method like any other event handler
in a .NET Windows Forms program.

private void MenuItemCallback(object sender, EventArgs e)

{

IVsUIShell uiShell = (IVsUIShell)GetService(typeof(SVsUIShell));

Guid clsid = Guid.Empty;

int result;

Microsoft.VisualStudio.ErrorHandler.ThrowOnFailure(

uiShell.ShowMessageBox(

0, ref clsid,

"FirstPackage",

string.Format(CultureInfo.CurrentCulture,

"Inside {0}.MenuItemCallback()", this.ToString()),

string.Empty, 0,

OLEMSGBUTTON.OLEMSGBUTTON_OK,

OLEMSGDEFBUTTON.OLEMSGDEFBUTTON_FIRST,

OLEMSGICON.OLEMSGICON_INFO,

0, out result));

}

Add a default keyboard shortcut

By default, the menu item that was created does not have a keyboard shortcut. Let's add one.

1. Open the file First.vsct for editing. Visual Studio opens this file with the XML editor.

2. Locate the end of the Commands element, indicated by a </Commands> tag.

3. Add these lines between the </Commands> tag and the following <Symbols> tag:

</KeyBindings>

This KeyBinding element has several attributes. The guid and id attributes determine the command
that will receive the key binding. The guid is the GUID of the VSPackage, and id is the command identifier
you typed in when you ran the wizard. Both symbols are defined in the Symbols section:

</GuidSymbol>

The editor attribute is a GUID representing the context where this keyboard shortcut will be available.
Different parts of Visual Studio can have different keyboard handlers. For example,
when you are inside a text editor, the keyboard shortcut CTRL+I runs the Incremental Search command.
But when the Solution Explorer is active, CTRL+I has no key binding. Thus, CTRL+I is only available to the text editor.

We want our keyboard shortcut to be available everywhere in Visual Studio; thus, it will be global.
For global keyboard shortcuts, we use the GUID defined by guidVSStd97.

The key1 and mod1 attributes indicate the keyboard shortcut. The key1 attribute selects the key.
All keyboard keys are available in symbolic form, such as “M” for the letter M and “VK_F5” for the function key F5.
The mod1 attribute specifies some combination of “Alt”, “Control”, or “Shift”, separated by spaces.

In this example, key1 is “M” and mod1 is “Control Shift”. The keyboard shortcut is therefore CTRL+SHIFT+M.

4. Run the build with Debug/Start without debugging.

This time, when the experimental build starts and you open the Tools menu, you will see
a keyboard shortcut of CTRL+SHIFT+M on the right side of the menu.

5. Press CTRL+SHIFT+M, and you'll see the same message box that appeared earlier.

For more information on the .vsct file, see the VSCT XML Schema Reference.

Add custom information to the Splash screen and Help/About dialog box

In order to add a touch of professionalism to your extension, you can include an icon and information
in the Help/About dialog box. You will need to make these changes to the solution:

· Modify the InstalledProductRegistration attribute arguments for the VSPackage class.

· Implement the IVsInstalledProduct interface for the VSPackage class.

· Add a bitmap and icon to the Resources folder.

· Reference the bitmap and icon in the Resources.resx file.

Your main VSPackage class (in this example, FirstPackage, found in FirstPackage.cs) uses the
InstalledProductRegistration attribute to specify where to find information for the About dialog box.

The new project wizard generates this InstalledProductRegistration attribute:

[InstalledProductRegistration(
false, "#110", "#112", "1.0", IconResourceID = 400)]

The resource IDs “#110” and “112” refer to these string resources declared in the VSPackage.resx file:

· 110 – FirstPackage

· 112 – Information about my VSPackage

The IconResourceID 400 refers to the Package.ico file in the Resources folder, as declared in the text of
the VSPackage.resx file:

<value>Resources\Package.ico;System.Drawing.Icon, System.Drawing,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a</value>

To customize the About dialog box, you change the first argument of the InstalledProductRegistration attribute to true,
which means your VSPackage will provide About dialog box resources through the IVsInstalledProduct interface.

1. Open the file FirstPackage.cs, find the InstalledProductRegistration attribute, and change its arguments as follows:

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

2. Derive the FirstPackage class from both Package and IVsInstalledProduct:

public sealed class FirstPackage : Package, IVsInstalledProduct

3. Implicitly implement the IVsInstalledProduct interface by hovering the mouse over the word IVsInstalledProduct.
When the SmartTag menu appears, click the first menu item:

This adds the following stub methods to the FirstPackage class. You will fill these methods in shortly:

public int IdBmpSplash(out uint pIdBmp)

{

throw new NotImplementedException();

}

public int IdIcoLogoForAboutbox(out uint pIdIco)

{

throw new NotImplementedException();

}

public int OfficialName(out string pbstrName)

{

throw new NotImplementedException();

}

public int ProductDetails(out string pbstrProductDetails)

{

throw new NotImplementedException();

}

public int ProductID(out string pbstrPID)

{

throw new NotImplementedException();

}

4. Copy the files GenericPackage.bmp and GenericPackage.ico from
<Visual Studio SDK Install Path>\VisualStudioIntegration\Samples\IDE\CSharp\Reference.Package to
your Resources directory.

5. In the Solution Explorer, right-click the Resources directory, and in the pop-up menu click Add and then
click Existing Item. Set your file type filter to "All Files (*.*)" and add the GenericPackage.bmp file.
Then repeat the procedure and add the GenericPackage.ico file.

6. Right-click the file C:\ExtendVS\FirstPackage\FirstPackage\VSPackage.resx, then click Open With.
Select the XML Editor in the dialog box to open the file in the XML Editor.

7. Add the following lines immediately before the final </root> tag:

<value>Resources\GenericPackage.bmp;
System.Drawing.Bitmap, System.Drawing, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
</value>

</data>

<value>Resources\GenericPackage.ico;
System.Drawing.Icon, System.Drawing, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a

</value>

</data>

This declares the GenericPackage.bmp as resource ID 500, and GenericPackage.iso as resource ID 600.

8. Replace the implementation of the IVsInstalledProduct interface with the following code.

public int IdBmpSplash(out uint pIdBmp)

{

pIdBmp = 500;