Walkthrough: A Basic Isolated Shell Application

  • Article

This walkthrough shows how to integrate a custom application into Microsoft Visual Studio 2008 Shell (integrated mode) by creating an isolated shell solution, adding a custom Help About tool window, and creating a Setup program for installing the isolated shell.

Prerequisites

To complete this walkthrough, you must install the Visual Studio SDK.

Note

For more information about the Visual Studio SDK, see Visual Studio Integration SDK. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN Web site.

Creating an Isolated Shell Solution

This section shows how to use the Microsoft Visual Studio 2008 Shell (integrated mode) project template to create an isolated Shell solution. The solution contains these two projects:

  • 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 noteImportant Note:

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, 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. This section shows how to 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. This section shows how to 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

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

  2. Change the DefaultHomePage element value to "https://www.microsoft.com".

  3. Rebuild the MyVSShellStub project.

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

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

  6. 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.

    <!-- <Define name="No_PrintingCommands"/> -->

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

    <Define name="No_PrintingCommands"/>

  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. The following procedure shows how to 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. Under Project types, expand Other Project Types, then select Extensibility. Under Tempates, 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 page appears.

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

    The Tool Window Options page appears.

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

    The Select Test Project Options page 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. Rebuild 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.

    <Button guid="guidMyHelpAboutCmdSet" id="cmdidMyHelpAbout"  priority="0x0100" type="Button">
  <Parent guid="guidSHLMainMenu" id="IDG_VS_WNDO_OTRWNDWS1"/>

    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.

    <Button guid="guidMyHelpAboutCmdSet" id="cmdidMyHelpAbout"  priority="0x9999" type="Button">
  <Parent guid="guidSHLMainMenu" id="IDG_VS_HELP_ABOUT"/>

    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.

Before You Deploy the Isolated Shell Application

Your isolated shell application can be installed on any computer that has the Visual Studio 2008 Shell (isolated mode) Redistributable Package. This walkthrough does not show how to chain install your isolated shell application and the redistributable package. For more information about the redistributable package, see Visual Studio 2008 Shell (Isolated) redistributable binaries on the Visual Studio Extensibility Downloads Web site.

Also, your isolated shell application must have a shell load key (SLK) to run on a non-development computer. In addition, the shell UI package and the help package each require a package load key (PLK). For more information about how to obtain and add SLKs and PLKs to your project, see the following topics:

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. Under Project types, expand Other Project Types, and then select Setup and Deployment. Under Templates, select 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.

The next step shows how to lay out the files for the setup program to look like the directory structure of the MyVSShellStub\Release folder.

Note

To generate the directory structure of the Release folder, build the solution by using the Release configuration.

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 list, and (Active) in the Configuration 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 items except the Microsoft .NET Framework from the MySetup\DetectedDependencies node.

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

  7. In the File System (MySetup) window, right-click Application Folder, point to Add, and then click File. In the Add Files dialog box, add MyVSShellStub\Release\MyVSShellStub.exe.config.

  8. In the File System (MySetup) window, right-click the Application Folder, point to Add, click Folder, and name the new folder PackagesToLoad.

  9. Move the Primary output from MyHelpAbout (Active) item from the Application Folder to the PackagesToLoad folder.

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

    • MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.pkgdef

    • MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.pkgundef

    • MyVSShellStub\Release\PackagesToLoad\MyHelpAbout.pkgdef

  11. Right-click the PackagesToLoad folder, point to Add, and then click 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.

  5. 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

  1. Right-click the MySetup project, point to View, and then click Custom Actions.

  2. Right-click the Install folder and then click Add Custom Action.

    The Select Item in Project dialog box appears.

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

  4. Double-click Primary Output from MyVSShellStub (Active).

    The Custom Actions editor reappears.

  5. Select Primary Output from MyVSShellStub (Active).

  6. 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

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

  8. Double-click Application Folder to open it.

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

  10. Select Primary Output from MyVSShellStub (Active).

  11. 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

  12. 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 build the Setup project, 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.

Do not try to install the application on computers that have a pre-release version of Visual Studio 2008.

See Also

Concepts

Visual Studio Shell-Based Applications

Visual Studio Shell (Isolated Mode)

Change History

Date

History

Reason

July 2008

Rewrote and refactored project.

Content bug fix.

January 2010

Added prerequisites.

Content bug fix.