Walkthrough: Creating a VSPackage (Part 1 of 4)

  • Article

You can add functionality to Visual Studio by creating a VSPackage, which can be distributed to other users as a Visual Studio extension..

The Visual Studio Package template has the source files and configuration files that are required to create a Visual Studio extension. The main class in an extension is a subclass of Package. It includes attributes that determine how the VSPackage should work in Visual Studio, as well as initialization code and other code such as menu command handlers.

This walkthrough shows how to create a VSPackage and customize it, as follows:

  • Create a VSPackage by using the package template.

  • Implement a menu command handler.

  • Add a keyboard shortcut.

This walkthrough is part of a series that show how to extend the Visual Studio integrated development environment (IDE). For more information, see Walkthroughs for Customizing Visual Studio By Using VSPackages.

Prerequisites

To follow this walkthrough, you must install the Visual Studio 2012 SDK. For more information, see Visual Studio Software Development Kit (SDK).

Template Locations for the Visual Studio Package Template

The Visual Studio Package Template can be found in these locations in the New Project dialog box:

  1. Under Visual Basic Extensibility. The default language of the project is Visual Basic.

  2. Under C# Extensibility. The default language of the project is C#.

  3. Under Other Project Types Extensibility. The default language of the project is C++.

Creating a VSPackage By Using the Package Template

This section shows how to create a VSPackage solution in Visual Studio.

To create a basic VSPackage solution

  1. Create a VSPackage using the Visual Studio Package project template.

  2. On the welcome page, click Next.

  3. On the Select a Programming Language page, select Visual C# or Visual Basic, select Generate a new key file to sign the assembly, and then click Next.

  4. On the Basic VSPackage Information page, in the VSPackage name box, type FirstPackage, and accept the remaining defaults. The namespace used for this solution is the company name plus the project name. Click Next.

  5. On the Select VSPackage Options page, select Menu Command, and then click Next.

  6. On the Command Options page, in the Command name box, type My First Command. The command name is what appears on the menu in Visual Studio. In the Command ID box, type cmdidFirstCommand. Click Next.

  7. On the Select Test Options page, click Finish.

    The template creates a Visual Studio project that has basic functionality. You can try it by pressing F5, which builds the project and then starts debugging it. This opens another instance of Visual Studio known as the experimental instance.

  8. In the experimental instance, you should see a command named My First Command on the Tools menu. Notice that My First Command is the name that you typed on the Command Options page of the template.

  9. Click My First Command. A message box should appear.

Changing the Menu Command Handler

The message that is displayed when you click First Command comes from code in the handler for the menu command. This handler is in the FirstPackagePackage.cs or FirstPackagePackage.vb file.

To change the menu command handler

  1. In Solution Explorer, open FirstPackagePackage.cs or FirstPackagePackage.vb.

  2. Find the FirstPackagePackage class. (The name of this class is the name of the project plus “Package”.) This class is derived from the Package class.

  3. Find the code for the menu handler in the MenuItemCallback method. It displays the message box you saw when you selected My First Command.

  4. Change the action performed by this command. In this case we’ll just start Notepad.

    Remove the existing code in the MenuItemCallback, and add the following code:

    private void MenuItemCallback(object sender, EventArgs e)
{
    Process proc = new Process();
    proc.StartInfo.FileName = "notepad.exe";
    proc.Start();
}

    Private Sub MenuItemCallback(ByVal sender As Object, ByVal e As EventArgs)
    Dim proc As New Process
    proc.StartInfo.FileName = "notepad.exe"
    proc.Start()
End Sub

Adding a Keyboard Shortcut

By default, menu commands that are created by the package template do not have a keyboard shortcut. You can add one to First Command.

To add a default keyboard shortcut

  1. In Solution Explorer, open FirstPackage.vsct.

  2. Add the following lines after the end of the <Commands> section (after the </Commands> tag) and before the <Symbols> section (before the <Symbols> tag).

    <KeyBindings>
  <KeyBinding guid="guidFirstPackageCmdSet" id="cmdidFirstCommand"    editor="guidVSStd97" key1="1" mod1="CONTROL"/>
</KeyBindings>

    This KeyBinding element has several attributes. The guid is the GUID of the command set, and id is the command ID. These attributes specify the command that should receive the keyboard shortcut. Both symbols are defined in the <Symbols> section.

    The value of the editor attribute is a GUID that represents the context in which the keyboard shortcut will be available. In Visual Studio, the binding of a keyboard shortcut to a command can be scoped to particular windows or made global (that is, available everywhere in Visual Studio). For example, in a text editor CTRL+I may run the Incremental Search command, but in Solution Explorer CTRL+I has no key binding. In this walkthrough, the keyboard shortcut is designed to be global, so the value of the editor attribute is guidVSStd97.

    The key1 and mod1 attributes set the keys that must be pressed to activate the keyboard shortcut. For the value of key1, all keyboard characters are available, for example, "M" for the letter M and "VK_F5" for the function key F5. The value of mod1 can be ALT, CONTROL, or SHIFT.

    In this walkthrough we are using CTRL+1 for the keyboard shortcut, so the value of key1 is 1 and the value of mod1 is (CONTROL.

  3. Start debugging the application.

    In the experimental instance of Visual Studio, you should see CTRL+1 on the Tools menu next to My First Command.

  4. Press CTRL+1. You should see the same message that appears when you click My First Command on the Tools menu.

What's Next

In Walkthrough: Creating a Tool Window (Part 2 of 4), you learn how to create a tool window that docks in Visual Studio and lets you play music files.

See Also

Concepts

Visual Studio Extensibility Samples

Other Resources

VSPackages

VSPackage Branding

VSPackage Load Keys

Reference.Package sample