Visual Studio Extensibility User Education

Microsoft.com Home

Site Map

Blogs Home

Visual Studio Extensibility User Education

Tutorial: A Simple Managed Project System

Here's a preview of the new managed project system tutorial. It's written for Visual Studio 2008, Visual Studio SDK 1.0, and Windows Vista.

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

------------------------

Tutorial: A Simple Managed Project System

In Visual Studio, projects are the containers that developers use to organize source-code files and other assets that appear in Solution Explorer. Projects let you organize, build, debug, and deploy your code, and create references to Web services, databases, and other resources.

Typically, projects are specified by the contents of a project file, for example, a .csproj file for a Visual C# project. You can create your own project type that has your own project file name extension. For more information about project types, see Project Types.

This walkthrough shows how to create a project type that has the project file name extension .myproj. You do not have to create a language to complete this walkthrough; instead, the walkthrough borrows from the existing Visual C# project system.

In particular, this walkthrough shows how to do these tasks:

· Create a simple project type.

· Create a simple project prototype template.

· Register the project template in Visual Studio.

· Create a new project instance by using the template together with the New Project wizard.

· Create a project factory for the project system.

· Create a project node for the project system.

· Add custom icons for the project system.

· Implement basic template parameter substitution.

Note: For an end-to-end sample of a complete language project system, see the IronPython sample.

Creating a Simple project Type

Project types, like most Visual Studio extensions, are implemented by VSPackages. For more information about VSPackages, see Tutorial 1: Creating a VSPackage. To create a project type, you must first create a VSPackage.

1. In Visual Studio, on the File menu, point to New and then click Project.

2. In the New Project dialog box, expand Other Project Types and then click Extensibility.
Under Visual Studio installed templates, click Visual Studio Integration Package.
Select Create Directory for Solution, and then type SimpleProject[MO2] in the Name box.
Type a Location for the solution, for example, D:\.
Click OK.

3. On the wizard welcome page, click Next.

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

5. On the Basic VSPackage Information page, click Next.

6. On the Select VSPackage Options page, click Next.

7. On the Command Options page, click Next.

8. On the Select Test Options page, clear both options and then click Finish.
The wizard creates a VSPackage project that has the settings that you specified.

Creating a Simple project Template

You will modify this basic VSPackage to implement the new .myproj project type. To create a project that is based on the .myproj project type, the Visual Studio New Project wizard has to know which files, resources, and references to add to the new project. You provide this information by putting project files in a project template folder. When a project is created by using the .myproj project type in the New Project wizard, the project files are copied to the new project. Some of these project files may contain template parameters that can be updated when the file is copied to a new project.

1. In Solution Explorer, right-click the SimpleProject project node, point to Add, and then click New Folder. Name the folder Templates.

2. In the Templates folder, add a folder named Projects.

3. In the Projects folder, add a folder named SimpleProject.

4. Right-click the SimpleProject folder, point to Add, and then click New Item. Add an Icon File named SimpleProject.ico. Click Add to open the icon editor.

5. Make the icon distinctive. This icon will appear in the New Project wizard later in the walkthrough.

6. Save the icon and close the icon editor.

7. In the SimpleProject folder, add a Class item named Program.cs. Click Add to open the code editor.

8. Replace the existing code by using the following lines.

using System;

using System.Collections.Generic;

using System.Text;

namespace $nameSpace$

{

public class $className$

{

static void Main(string[] args)

{

Console.WriteLine("Hello VSX!!!");

Console.ReadKey();

}

Note: Later in the walkthrough, you can learn how to programmatically change the template parameters $nameSpace$ and $className$ during new project generation.

9. Save the file and close the code editor.

10. In the Properties folder, copy AssemblyInfo.cs and then paste it in the Projects\SimpleProject folder.

11. Open the Projects\SimpleProject folder. In the Properties window, set the Build Action of both AssemblyInfo.cs and Program.cs to None.

12. In Solution Explorer, right-click the SimpleProject folder, point to Add, and then click New Item. Add a XML File item named SimpleProject.myproj. Click Add to open the XML editor.
Note: myproj is the file name extension for all projects of this type. If you want to change it, you must change it everywhere it is mentioned in the walkthrough.

13. Replace the existing content by using the following lines.

<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

<RootNamespace>MyRootNamespace</RootNamespace>

<AssemblyName>MyAssemblyName</AssemblyName>

<EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>

</PropertyGroup>

<OutputPath>bin\Debug\</OutputPath>

</PropertyGroup>

<DebugSymbols>false</DebugSymbols>

<OutputPath>bin\Release\</OutputPath>

</PropertyGroup>

</ItemGroup>

</Compile>

</Compile>

</ItemGroup>

</Project>

This project template describes a basic Visual C# project that has both a Debug configuration and a Release configuration. The project includes two source files, AssemblyInfo.cs and Program.cs, and several assembly references. When a project is created from the template, the ProjectGuid value is automatically replaced by a new GUID.

14. Save the file and close the XML editor.

In Solution Explorer, the expanded Templates folder should appear as follows:

· Templates

o Projects

§ SimpleProject

· AssemblyInfo.cs

· Program.cs

· SimpleProject.ico

· SimpleProject.myproj

Creating a Skeletal Project Factory

You must tell Visual Studio the location of your project template folder. To do this, add an attribute to the VSPackage class that implements the project factory so that the template location is written to the system registry when the VSPackage is built. Start by creating a simple project factory that is identified by a project factory GUID. Use the ProvideProjectFactory attribute to connect the project factory to the SimpleProjectPackage class.

1. Open Guids.cs in the code editor.

2. On the Tools menu, click Create GUID.

3. Create a GUID for your project factory, or use the one in the following example. Add the GUID to the GuidList. The GUID must be in both Guid form and string form. The resulting code should resemble the following example.

static class GuidList

{

public const string guidSimpleProjectPkgString =

"96bf4c26-d94e-43bf-a56a-f8500b52bfad";

public const string guidSimpleProjectCmdSetString =

"72c23e1d-f389-410a-b5f1-c938303f1391";

public const string guidSimpleProjectFactoryString =

"471EC4BB-E47E-4229-A789-D1F5F83B52D4";

public static readonly Guid guidSimpleProjectCmdSet =

new Guid(guidSimpleProjectCmdSetString);

public static readonly Guid guidSimpleProjectFactory =

new Guid(guidSimpleProjectFactoryString);

};

4. Save the file and close the editor.

5. In Solution Explorer, right-click the SimpleProject project node, point to Add, and then click New Item. Add a Class named SimpleProjectFactory.cs. Click Add to open the code editor.

6. Add the following using statement after the other using statements.

using System.Runtime.InteropServices;

7. Add a Guid attribute to the SimpleProjectFactory class. The value of the attribute is the new project factory GUID.

[Guid(GuidList.guidSimpleProjectFactoryString)]

class SimpleProjectFactory

8. Rebuild the solution and verify that it builds without errors.

Registering the Project Template

Now you can register your project template.

1. Open SimpleProjectPackage.cs in the code editor.

2. Add a ProvideProjectFactory attribute to the SimpleProjectPackage class, as follows.

[ProvideProjectFactory(

typeof(SimpleProjectFactory),

"Simple Project",

"Simple Project Files (*.myproj);*.myproj",

"myproj", "myproj",

@"..\..\Templates\Projects\SimpleProject",

LanguageVsTemplate = "SimpleProject",

NewProjectRequireNewFolderVsTemplate = false)]

[Guid(GuidList.guidSimpleProjectPkgString)]

public sealed class SimpleProjectPackage : Package

3. Rebuild the solution and verify that it builds without errors. Rebuilding registers the project template.

The ProvideProjectFactory attribute has the following syntax.

public ProvideProjectFactoryAttribute(
    Type factoryType,
    string name,
    string displayProjectFileExtensionsResourceID,
    string defaultProjectExtension,
    string possibleProjectExtensions,
    string projectTemplatesDirectory
)

The parameters defaultProjectExtension and possibleProjectExtensions are set to the project file name extension (.myproj). The projectTemplatesDirectory parameter is set to the relative path of the Templates folder. RegPkg.exe converts this to a full path to register it in the system registry.

Examining the Template Registration

Run regedit.exe and examine the system registry key.

HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0Exp\Configuration\Projects\{471EC4BB-E47E-4229-A789-D1F5F83B52D4}

Note: The GUID in the \Projects\ key should match the value of GuidList.guidSimpleProjectFactoryString in the earlier example.

Value Name	Type	Value Data
(Default)	REG_SZ	SimpleProjectFactory
DefaultProjectExtension	REG_SZ	myproj
DisplayName	REG_SZ	Simple Project
DisplayProjectFileExtensions	REG_SZ	Simple Project Files (.myproj);.myproj
Language(VsTemplate)	REG_SZ	SimpleProject
Package	REG_SZ	{96bf4c26-d94e-43bf-a56a-f8500b52bfad}
PossibleProjectExtensions	REG_SZ	myproj
ProjectTemplatesDir	REG_SZ	D:\SimpleProject\...\Templates\Projects\SimpleProject

The value data is obtained by reflecting over the VSPackage assembly, especially the ProvideProjectFactory attribute. The Package value data is obtained by reflecting the SimpleProjectPackage class Guid attribute, whose value is given by GuidList.guidSimpleProjectPkgString. The value of your Package may differ.

The ProjectTemplatesDir value is the full path of the \Templates\Projects\SimpleProject\ folder that you created for the project. This folder holds the project template files that are copied and expanded when a project of type .myproj is created. Visual Studio uses this path to display the new project icon and additional information in the New Project dialog box.

Testing the Template Registration

1. In Visual Studio, press F5 to start a new instance of Visual Studio in the experimental hive.

2. On the File menu, point to New, and then click Project.
In the New Project dialog box, select the SimpleProject project type.
The SimpleProject icon appears under Visual Studio installed templates.

3. Close the instance of Visual Studio that is running in the experimental hive.

Now you have a project factory that can demonstrate registration, but it cannot yet create a project. The project package and project factory work together to create and initialize a project.

Initializing the Project Factory

To implement the connection between the project package and project factory, complete these tasks:

· To the solution, add links to the source-code files for the Microsoft.VisualStudio.Package Project framework. This framework is an extension of the Managed Package Framework (MPF). The Project framework is provided only as source code.

· Derive SimpleProjectPackage from Microsoft.VisualStudio.Package.ProjectPackage.

· Create a SimpleProjectFactory and register it with Visual Studio by using the Microsoft.VisualStudio.Package.RegisterProjectFactory method.

· Derive SimpleProjectPackage from Microsoft.VisualStudio.Package.ProjectPackage.

· Pass to the SimpleProjectFactory constructor a reference to the SimpleProjectPackage. This reference is cached for later use in setting a service provider site. For more information about services, see Services.

1. Open Visual Studio.

2. In Solution Explorer, right-click the SimpleProject node and then click Unload Project.

3. Right-click the SimpleProject node and then click Edit SimpleProject.csproj.

4. In the XML editor, add the following ProjectBasePath element after the RegisterWithCodebase element. Do not break the line that contains the ProjectBasePath element.

<ProjectBasePath>$(VSSDK90Install)VisualStudioIntegration\Common\Source\CSharp\Project</ProjectBasePath>

5. Add the following Import element after the existing Import elements.

<Import Project="$(ProjectBasePath)\ProjectBase.Files" />

6. Save the project file and close the editor.

7. Right-click the SimpleProject node, and then click Reload Project.
Solution Explorer should now display a ProjectBase folder.

8. In the Solution Explorer, right-click the References node, and add the following .NET references.

· EnvDTE (<Visual Studio installation path>\Common7\IDE\PublicAssemblies\EnvDTE.dll)

· Microsoft.VisualStudio.Designer.Interfaces

9. In the SimpleProjectPackage.cs file, add the following using statement after the existing using statements.

using Microsoft.VisualStudio.Package;

10. Derive the SimpleProjectPackage class from Microsoft.VisualStudio.Package.ProjectPackage.

public sealed class SimpleProjectPackage : ProjectPackage

11. Add the following line to the SimpleProjectPackage.Initialize method, just after base.Initialize.

base.Initialize();

this.RegisterProjectFactory(new SimpleProjectFactory(this));

12. In SimpleProjectFactory.cs, add the following using statement after the existing using statements.

using Microsoft.VisualStudio.Package;

13. Derive the SimpleProjectFactory class from ProjectFactory.

class SimpleProjectFactory : ProjectFactory

14. Add the following dummy method to the SimpleProjectFactory class. You will implement this method in a later section.

protected override ProjectNode CreateProject()

{

return null;

}

15. Add the following constructor to the SimpleProjectFactory class. This SimpleProjectPackage reference is cached in a private field so that it can be used in setting a service provider site.

private SimpleProjectPackage package;

public SimpleProjectFactory(SimpleProjectPackage package)

: base(package)

{

this.package = package;

}

16. Rebuild the solution and verify that it builds without errors.

Testing the Project Factory Implementation

1. In the SimpleProjectFactory.cs file, set a breakpoint on the following line in the SimpleProjectFactory constructor.

this.package = package;

2. Press F5 to start a new instance of Visual Studio in the experimental hive.

3. On the File menu, point to New, and then click Project.

4. In the New Project dialog box, select the SimpleProject project type and then click OK.
Execution stops at the breakpoint.

5. Press SHIFT+F5 to stop debugging.

Extending the Project Node Class

Now you can implement the SimpleProjectNode class, which derives from the ProjectNode class. The ProjectNode base class handles the following tasks of project creation:

· Copies the project template file, SimpleProject.myproj, to the destination folder. The copy is renamed according to the name entered in the New Project wizard. The ProjectGuid property value is replaced with a new GUID.

· Traverses the MSBuild elements of the project template file, SimpleProject.myproj, and looks for Compile elements. For each Compile target file, copies the file to the new project destination folder.

The derived SimpleProjectNode class handles these tasks:

· Icons for project and file nodes in Solution Explorer can be created or selected.

· Additional project template parameter substitutions can be specified.

1. Right-click the SimpleProject project node, point to Add, and then click New Item. Add a Class named SimpleProjectNode.cs. Click Add to open the code editor.

2. Replace the existing code with the following code.

using System;

using System.Collections.Generic;

using Microsoft.VisualStudio.Package;

namespace Company.SimpleProject

{

public class SimpleProjectNode : ProjectNode

{

private SimpleProjectPackage package;

public SimpleProjectNode(SimpleProjectPackage package)

{

this.package = package;

}

public override Guid ProjectGuid

{

get { return GuidList.guidSimpleProjectFactory; }

}

public override string ProjectType

{

get { return "SimpleProjectType"; }

}

public override void AddFileFromTemplate(

string source, string target)

{

this.FileTemplateProcessor.UntokenFile(source, target);

this.FileTemplateProcessor.Reset();

}

This SimpleProjectNode class implementation has the following overridden methods:

● ProjectGuid, which returns the project factory GUID.

● ProjectType, which returns the localized name of the project type.

● AddFileFromTemplate, which copies selected files from the template folder to the destination project. This method is explained in a later section.

The SimpleProjectNode constructor, like the SimpleProjectFactory constructor, caches a SimpleProjectPackage reference in a private field for later use.

To connect the SimpleProjectFactory class to the SimpleProjectNode class, you must instantiate a new SimpleProjectNode in the SimpleProjectFactory.CreateProject method and cache it in a private field for later use.

3. In the SimpleProjectFactory.cs file, add the following using statement after the existing using statements.

using IOleServiceProvider =
Microsoft.VisualStudio.OLE.Interop.IServiceProvider;

4. Replace the SimpleProjectFactory.CreateProject method by using the following code.

protected override ProjectNode CreateProject()

{

SimpleProjectNode project = new SimpleProjectNode(this.package);

    project.SetSite((IOleServiceProvider)
        ((IServiceProvider)this.package).GetService(
            typeof(IOleServiceProvider)));

return project;

}

5. Rebuild the solution and verify that it builds without errors.

Testing the Project Node Class

1. Press F5 to start a new instance of Visual Studio in the experimental hive.

2. On the File menu, point to New, and then click Project.

3. In the New Project dialog box, under Visual Studio installed templates, select SimpleProject.

4. Select Create Directory for Solution, and type MyProject in the Name box.

5. Type a location for the solution, for example, D:\.

6. Click OK.

Visual Studio calls your project factory to create a project.

7. Close the instance of Visual Studio that is running in the experimental hive.

Adding a Custom Project Node Icon

The project node icon in the earlier section is a default icon. You can change it to a custom icon.

1. In the Solution Explorer, right-click the Resources folder, point to Add, and then click New Item. Add a Bitmap File named SimpleProjectNode.bmp. Click Add to open the bitmap editor.

2. Reduce the bitmap to 16 by 16 pixels. Make the bitmap distinctive.

3. In the Properties window, change the Build action of the bitmap to Embedded Resource.

4. In SimpleProjectNode.cs, add the following using statements after the existing using statements.

using System.Drawing;

using System.Windows.Forms;

5. Add the following static constructor to the SimpleProjectNode class.

private static ImageList imageList;

static SimpleProjectNode()

{

    imageList =
        Utilities.GetImageList(
            typeof(SimpleProjectNode).Assembly.GetManifestResourceStream(
                "Company.SimpleProject.Resources.SimpleProjectNode.bmp"));

}

During static construction, SimpleProjectNode retrieves the project node bitmap from the assembly manifest resources and caches it in a private field for later use. Notice the syntax of the Assembly.GetManifestResourceStream image path. To see the names of the manifest resources embedded in an assembly, use the Assembly.GetManifestResourceNames method. When this method is applied to the SimpleProject assembly, the results are as follows:

· Company.SimpleProject.Resources.resources

· Microsoft.VisualStudio.Package.Project.resources

· Company.SimpleProject.VSPackage.resources

· Resources.imagelis.bmp

· Microsoft.VisualStudio.Package.DontShowAgainDialog.resources

· Microsoft.VisualStudio.Package.SecurityWarningDialog.resources

· Company.SimpleProject.Resources.SimpleProjectNode.bmp

6. Add the following property to the beginning of the SimpleProjectNode class.

internal static int imageIndex;

public override int ImageIndex

{

get { return imageIndex + 0; }

}

7. Replace the instance constructor by using the following code.

public SimpleProjectNode(SimpleProjectPackage package)

{

this.package = package;

imageIndex = this.ImageHandler.ImageList.Images.Count;

foreach (Image img in imageList.Images)

{

this.ImageHandler.AddImage(img);

}

During instance construction, the ProjectNode base class loads Resources.imagelis.bmp, in which are embedded commonly used 16 x 16 bitmaps from Resources\imagelis.bmp. This bitmap list is made available to SimpleProjectNode as ImageHandler.ImageList. SimpleProjectNode appends the project node bitmap to the list. The offset of the project node bitmap in the image list is cached for later use as the value of the public ImageIndex property. Visual Studio uses this property to determine which bitmap to display as the project node icon.

Testing the Custom Project Node Icon

1. Close Visual Studio.

2. Delete the MyProject solution.

3. Open Visual Studio.

4. Press F5 to start a new instance of Visual Studio in the experimental hive.

5. On the File menu, point to New, and then click Project.

6. In the New Project dialog box, under Visual Studio installed templates, select SimpleProject.

7. Select Create Directory for Solution, and type MyProject in the Name box.

8. Type a location for the solution, for example, D:\.

9. Click OK.
The wizard creates a Visual Studio project. Notice that SimpleProjectNode.bmp is used as the project node icon.

10. Open Program.cs in the code editor. You should see source code that resembles the following code.

using System;

using System.Collections.Generic;

using System.Text;

namespace $nameSpace$

{

public class $className$

{

static void Main(string[] args)

{

Console.WriteLine("Hello VSX!!!");

Console.ReadKey();

}

Notice that the template parameters $nameSpace$ and $className$ do not yet have new values. You can implement template parameter substitution in the next section.

11. Press SHIFT+F5 to stop debugging.

Simple Template Parameter Substitution

In an earlier procedure, you registered the project template with Visual Studio by using the ProvideProjectFactory attribute. Registering the path of a template folder in this manner lets you enable basic template parameter substitution by overriding and expanding the ProjectNode.AddFileFromTemplate class. For more information, see New Project Generation: Under the Hood, Part Two.

To replace the values of template parameters $nameSpace$ and $className$ in the Program.cs file template, you must add code to the AddFileFromTemplate class.

1. In SimpleProjectNode.cs, add this using statement to the end of the using statements:

using System.IO;

2. Replace the AddFileFromTemplate method by using the following code.

public override void AddFileFromTemplate(

string source, string target)

{

string nameSpace =

this.FileTemplateProcessor.GetFileNamespace(target, this);

string className = Path.GetFileNameWithoutExtension(target);

this.FileTemplateProcessor.AddReplace("$nameSpace$", nameSpace);

this.FileTemplateProcessor.AddReplace("$className$", className);

this.FileTemplateProcessor.UntokenFile(source, target);

this.FileTemplateProcessor.Reset();

}

2. Set a breakpoint in the method, just after the nameSpace assignment statement.

The assignment statements determine reasonable values for a namespace and a new class name. The two ProjectNode.FileTemplateProcessor.AddReplace method calls replace the corresponding template parameter values by using these new values.

Testing the Template Parameter Substitution

1. Close Visual Studio.

2. Delete the MyProject solution.

3. Open Visual Studio.

4. Press F5 to start a new instance of Visual Studio in the experimental hive.

5. On the File menu, point to New, and then click Project.

6. In the New Project dialog box, under Visual Studio installed templates, select SimpleProject.

7. Select Create Directory for Solution, and type MyProject in the Name box.

8. Type a location for the solution, for example, D:\.

9. Click OK.

Execution stops at the breakpoint in the AddFileFromTemplate method. Examine the values for the nameSpace and className.

· nameSpace is given the value of the <RootNamespace> element in the \Templates\Projects\SimpleProject\SimpleProject.myproj project template file. In this case, the value is “MyRootNamespace”.

· className is given the value of the class source file name, without the file name extension. In this case, the first file to be copied to the destination folder is AssemblyInfo.cs; therefore, className is “AssemblyInfo”.

10. Remove the breakpoint and press F5 to continue execution.
The wizard creates a Visual Studio project.

11. Open Program.cs in the code editor. You should see source code that resembles the following code.

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

namespace MyRootNamespace

{

public class Program

{

static void Main(string[] args)

{

Console.WriteLine("Hello VSX!!!");

Console.ReadKey();

}

Notice that the namespace is “MyRootNamespace” and the class name is “Program”.

12. In the instance of Visual Studio that is running in the experimental hive, press F5. The new project should compile, run, and display “Hello VSX!!!” in the console window.

Posted Wednesday, March 12, 2008 8:31 PM by martintr | 5 Comments

Walkthrough: A Basic Isolated Shell Application

This preview walkthrough shows how to integrate a custom application into the Microsoft Visual Studio 2008 Shell (isolated mode). In this walkthrough, you create an isolated shell solution, add a custom Help About tool window, and create a Setup program for installing the isolated shell.

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

Creating an Isolated Shell Solution

In this section, you use the the Microsoft Visual Studio 2008 Shell project template to create an isolated Shell solution. The solution contains two projects, as follows:

· The Shell Stub, which produces the executable file that invokes the isolated Shell.

· The Shell Stub UI, which produces a satellite DLL that defines active menu commands and localizable strings.

To create a basic isolated shell solution

1. Open Visual Studio.

Note When you are running on Windows Vista, open Visual Studio with administrative credentials.

2. On the File menu, point to New and then click Project.
The New Project dialog box appears.

3. In the Project types window, click Other Project Types and then Extensibility. Click the Visual Studio Shell Isolated project template.

4. Name the project MyVSShellStub and specify a location for the project. Select Create directory for solution and then click OK.
The wizard creates a new solution, which appears in Solution Explorer.

5. Press F5 to compile the solution and start the isolated Shell.
The isolated Shell integrated development environment (IDE) appears. The title bar reads "MyVSShellStub". The title bar icon is generated from the file \MyVSShellStub\Resource Files\MyVSShellStub.ico.

6. Close the isolated Shell.

Important This process may take some time to finish because MyVSShellStub is generating registry data and menu information. If you modify a .vsct file, a .pkgdef file, or a .pkgundef file, then Setup will run the next time that you build. You can watch the progress of the isolated Shell Setup in Task Manager.

Examining the Shell Stub Registry Key

· When the isolated shell solution is built for the first time (or after a .vsct file, a .pkgdef file, or a .pkgundef file has been modified), it is run once with the /setup switch. This creates a new registry key.

To examine the shell stub registry key

1. In the MyVSShellStubUI project, open the file Source Files\MyVSShellStub.cpp.

2. Find a string literal that begins with "MyVSShellStub_". (There should be more than one.) The end of this string contains the GUID of the application. The string should resemble the following example. (Your GUID will be different.)

MyVSShellStub_e34ac168-999b-4999-91cf-f5f0f700025f

3. Run regedit and navigate to the AppEnv registry key that has the same GUID, for example,

HKCU\SOFTWARE\Microsoft\AppEnv\9.0\Apps\MyVSShellStub_e34ac168-999b-4999-91cf-f5f0f700025f

This is the registry key that the Shell stub uses to keep track of menu items, projects, and so forth. You can add this location to your Favorites for future reference.

Note When you prepare to distribute your isolated Shell application, you should remove the GUID part from the strings in this file. This GUID is in place so that if you run the wizard, delete the project, and then run the wizard again, the old registry location will not be re-used.

Customizing the Custom Application Name and Icon

You may want to brand your custom application by using the name of your company and its logo in the title bar. In this section, you change the name and icon that are displayed in the custom application title bar by changing the package definition file, MyVSShellStub.pkgdef.

To customize the custom application name and icon

1. In the MyVSShellStub project, open MyVSShellStub.pkgdef for editing.

2. Change the AppName element value to "My Company Name".

3. Change the AppIcon element value to the path of another icon. You can use the Visual Studio icon, which is typically located in "C:\Program Files\Microsoft Visual Studio 9.0\Setup\Setup.ico".

"AppName"="My Company Name"

"AppIcon"="C:\Program Files\Microsoft Visual Studio 9.0\Setup\Setup.ico"

4. Press F5 to compile the solution and start the isolated Shell.
The isolated Shell IDE appears. The title bar has a new icon and now reads "My Company Name".

5. Close the isolated Shell.

Customizing the Default Web Browser Home Page

Suppose you want the Web Browser window to show your company's home page when it opens. In this section, you change the default home page of the Web Browser window by changing the package definition file, MyVSShellStub.pkgdef.

To customize the default Web Browser home page

6. In the MyVSShellStub project, open MyVSShellStub.pkgdef for editing.

7. Change the DefaultHomePage element value to "http://www.microsoft.com".

8. Rebuild the MyVSShellStub project.

9. Press F5 to compile the solution and start the isolated Shell.
The isolated Shell IDE appears.

10. On the View menu, point to Other Windows and then click Web Browser.
The Web Browser window opens and displays the MSN home page.

11. Close the isolated Shell.

Removing Printing Commands

The .vsct file in an isolated shell UI project consists of a set of declarations of the form <Define name=No_Element> where Element is one of the set of standard Visual Studio shell UI elements. If a declaration is un-commented, that UI element will be excluded from the isolated shell that you are defining. In the following procedure, you un-comment the set of printing commands in your .vsct file, MyVSShellStubUI.vsct.

To remove the printer menu commands

1. Open the isolated Shell and click the File menu. Verify that the Page Setup and Print commands appear on the menu.

2. Close the isolated Shell.

3. In the MyVSShellStubUI project, open Resource Files\MyVSShellStubUI.vsct for editing.

4. Locate the following line.

5. Un-comment the line. This will remove all the print commands, including Print, Print Preview, and Page Setup.

6. Press F5 to compile the solution and start the isolated Shell.
The isolated Shell IDE appears.

7. Click the File menu. Verify that the Page Setup and Print commands are gone.

8. Close the isolated Shell.

Removing Features from the Isolated Shell

You can remove some of the packages that are loaded with Visual Studio by editing the .pkgundef file if you do not want those features to load in your custom isolated shell application. You specify the package by using one of the subkeys of the registry key, HKLM\SOFTWARE\Microsoft\VisualStudio\9.0\Packages.

The following procedure shows how to remove the XML editor from the isolated shell.

To remove the XML editor

1. Find and open the MyVSShellStub.pkgundef file under the MyVSShellStub project.

2. Add the following line to the file.

[$RootKey$\Packages\{87569308-4813-40a0-9cd0-d7a30838ca3f}]

3. Rebuild the solution and start the isolated Shell.
The isolated Shell IDE appears.

4. On the File menu, point to New and then click File. Select XML File. Open the file and verify that it does not appear in the XML editor, for example, that the XML keywords in the file are not colorized, and that typing "<" on a line does not bring up XML tooltips.

5. Close the isolated Shell.

Adding a VSPackage

You can add a VSPackage to your custom application. In the following procedure, you add a new Tool Window VSPackage as the start of a Help About box.

To add a new VSPackage

1. In Solution Explorer, right-click the VSShellStub solution node, click Add and then click New Project.

The Add New Project dialog box appears.

2. In the Project types window, click Other Project Types, then Extensibility. Select the Visual Studio Integration Package project template.

3. Name the project MyHelpAbout and then click OK.

The Visual Studio Integration Package wizard appears.

4. Click Next and then select Visual C#. Click Next again to accept the defaults.

The Basic VSPackage Information dialog box appears.

5. Click Next, then select Tool Window. Click Next again to accept the defaults.

The Tool Window Options dialog box appears.

6. Set the default window name to My Help About, and the default Command ID to cmdidMyHelpAbout, then click Next.

The Select Test Project Options dialog box appears.

7. Clear the test check boxes, and then click Finish.

The wizard creates a new MyHelpAbout project, which appears in Solution Explorer.

8. In Solution Explorer, right-click the MyVSShellStub project node and then click Shell Dependencies.

The Shell Dependencies dialog box appears.

9. Select MyHelpAbout, and then click OK.

10. Press F5 to compile the solution and start the isolated Shell.
The isolated Shell IDE appears.

11. On the View menu, point to Other Windows and then click My Help About.

The My Help About tool window appears.

12. Close the isolated Shell.

Moving the Help About Box to the Help Menu

You can move the My Help About command, which you created earlier in this walkthrough, to the Help menu. By changing the priority of the command, you can force it to the bottom of the Help menu. This is the typical location for the Help About command.

To move the Help About box to the Help menu

1. In the MyHelpAbout project, open MyHelpAbout.vsct for editing.

2. Locate the following lines.

IDG_VS_WNDO_OTRWNDWS1 parents the My Help About command to the Other Windows menu group.

3. Move the My Help About command to the Help About menu group by making the following changes.

Notice that these lines not only move the command to the Help About group, but they also lower the priority of the command to 0x9999 to force it to the bottom of the Help menu.

4. Press F5 to compile the solution and start the isolated Shell.
The isolated Shell IDE appears.

5. On the Help menu, click My Help About.

The My Help About tool window appears.

6. Close the isolated Shell.

Deploying the Isolated Shell Application

You deploy your custom isolated shell application to a target computer by creating a Setup project. You must specify the following things:

· The layout of the folders and files on the target computer.

· The launch conditions that guarantee that the .NET Framework and Visual Studio Shell runtime are installed on the target computer.

· Custom actions to install and uninstall the custom isolated shell application.

To create the Setup project

1. In Solution Explorer, right-click the solution node and then click Add New Project.
The New Project dialog box appears.

2. In the Project types window, expand Other Project Types and then click Setup and Deployment. Click the Setup Project template. Name the new project MySetup and then click OK.
The wizard creates the Setup project and adds it to the solution.

In the next step, you will lay out the files for the setup program to look like the directory structure of the MyVSShellStub\Release folder.

To lay out the files and folders on the target computer

1. Right-click the MySetup project and then click Add, then Project Output.

The Add Project Output Group dialog box appears.

2. Select MyVSShellStub in the Project drop-down list and (Active) in the Configuration drop-down list.

3. Select Primary Output in the list box and then click OK.

Primary Output from MyVSShellStub (Active) is added to the project.

4. Repeat the preceding three steps for the MyVSShellStubUI and MyHelpAbout projects.

Note You may see a warning that some dependencies cannot be determined automatically. Press OK to accept the suggested dependencies.

5. Exclude all the items (except Microsoft .Net Framework) from the MySetup\DetectedDependencies node.

6. Right-click the MySetup project and then click View, then File System. The File System (MySetup) window appears.

7. In the File System (MySetup) window, right-click Application Folder, then Add, then File. Select the file:

MySShellStub\Release\MyVSShellStub.exe.config.

8. Right-click the MySetup project and then click View, then File System to open the File System on Target Machine window. Right-click Application Folder then Add, then Folder, and name the new folder PackagesToLoad.

9. Select Primary output from MyHelpAbout (Active) under Application Folder and move it under the PackagesToLoad folder.

10. Right-click the PackagesToLoad folder and then click Add,then File. Select the following files:

· MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.pkgdef

· MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.pkgundef

· MyVSShellStub\Release\PackagesToLoad\MyHelpAbout.pkgdef

11. Right-click the PackagesToLoad folder and then click Add, then Folder. Name the folder 1033.

12. Move Primary Output from MyVSShellStubUI (Active) from the Application Folder to the 1033 folder.

To specify the launch conditions

1. Open the MySetup project in the Launch Conditions editor.

2. Right-click the Search Target Machine folder and then click Add Registry Search.

3. Right-click the new search entry to open the Properties Window, and then set the following values for the given properties.

Property	Value
(Name)	Search for Visual Studio Registration.
Property	VSINSTALLDIR
RegKey	Software\Microsoft\VisualStudio\9.0
Root	vsdrrHKLM
Value	InstallDir

Note If the InstallDir key is present, you can assume that the Visual Studio Shell runtime is installed on the target computer.

4. Right-click the Launch Conditions folder and then click Add Launch Condition.

Right-click the new search entry to open the Properties window, and then set the following values for the given properties.

Property	Value
(Name)	CheckForVS
Condition	VSINSTALLDIR<>
InstallUrl
Message	Install VS Shell Isolated

To create the Setup project custom actions

5. Right-click the MySetup project, select View,and then click Custom Actions.

6. Right-click the Install folder and then click Add Custom Action.
The Select Item in Project dialog box appears.

7. Double-click the Application Folder to open it.

8. Double-click Primary Output from MyVSShellStub (Active).
The Custom Actions editor reappears.

9. Select Primary Output from MyVSShellStub (Active).

10. Open the Properties Window and set the following values for the given properties.

Property	Value
(Name)	Primary Output from MyVSShellStub (Active)
Arguments	/setup
Condition
CustomActionData
InstallerClass	False

11. Right-click the Uninstall folder and then click Add Custom Action.
The Select Item in Project dialog box appears.

12. Double-click Application Folder to open it.

13. Double-click Primary Output from MyVSShellStub (Active).
The Custom Actions editor reappears.

14. Select Primary Output from MyVSShellStub (Active).

15. Open the Properties Window and set the following values for the given properties.

Property	Value
(Name)	Primary Output from MyVSShellStub (Active)
Arguments	/remove
Condition
CustomActionData
InstallerClass	False

16. Build the MySetup project. Doing this produces a MySetup.msi file and a setup.exe file in the Debug or Release output directory of the project. If the other projects are out of date, they are rebuilt.

Testing the Installation Program

After you rebuild the Setup project, you should find two files, MySetup.msi and setup.exe, in the Release folder of the MySetup project. To test them, copy them to a different computer and run the Setup executable. The Setup program should install the isolated shell, and you should be able to run it.

You may install your isolated shell application on any computer that has the release version of Visual Studio 2008 or the Visual Studio 2008 Shell (isolated mode) Redistributable Package. Do not try to install the application on computers that have a pre-release version of Visual Studio 2008.

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:

Examine the menu item handler

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;