Walkthrough: A Basic Isolated Shell Application

Article
12/07/2007

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 "https://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.

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.