Walkthrough: A Basic Isolated Shell Custom Tool

  • Artikel

This walkthrough presents what you must know to integrate your custom tool into Microsoft Visual Studio 2008 Shell (integrated mode). In this walkthrough, you create a basic custom tool and then brand it.

Creating the Custom Tool

In this section, you use the Microsoft Visual Studio 2008 Shell (integrated mode) 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 custom tool

  • Open Visual Studio.

Hinweis

To circumvent some known issues when running under the Vista operating system, open Visual Studio with elevated privileges.

Hinweis

The Shell Stub and Shell Stub UI projects have no dependencies on each other. If you update an item in the UI project, you must also build the Stub project. To do this, rebuild the entire solution. This is a known issue.

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

  2. In the Project types window, click Visual C++. You may have to select Other Languages first. Click the Visual Studio Shell Isolated project template.

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

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

Hinweis

You can watch the progress of the isolated Shell setup in Task Manager. Look for the process named MyVSShellStub.exe.

  1. Close the isolated Shell.

Examining the Shell Stub Registry Hive

  • When MyVSShellStub.exe is first created, it is run once with the /setup switch. This creates a new registry hive.

To examine the shell stub registry hive

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

  2. Locate any string literal that begins with "MyVSShellStub_". For example (your GUID will vary):

    MyVSShellStub_e34ac168-999b-4999-91cf-f5f0f700025f

  3. Run regedit and navigate to the AppEnv registry hive with the same key, for example:

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

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

Customizing the Custom Tool Name and Icon

Suppose you want to brand your custom tool 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 tool title bar by changing the package definition file, MyVSShellStub.pkgdef.

To customize the custom tool 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. Rebuild the MyVSShellStub project.

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

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

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

  2. Change the DefaultHomePage element value to "https://www.msn.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 MSN home page.

  6. Close the isolated Shell.

Removing the Printer Menu Commands

Suppose your custom tool does not support printing. In this section, you remove printer commands from the File menu by changing the 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 lines.

    <!-- <Define name="No_PrintingCommands"/> -->
<!-- <Define name="No_PageSetupCommand"/> -->
<!-- <Define name="No_PrintPreviewCommand"/> -->
<!-- <Define name="No_PrintCommand"/> -->
<!-- <Define name="No_PrintDefaultCommand"/> -->

  5. Remove the HTML comment delimiters from the lines so that they resemble the following.

    <Define name="No_PrintingCommands"/>
<Define name="No_PageSetupCommand"/>
<Define name="No_PrintPreviewCommand"/>
<Define name="No_PrintCommand"/>
<Define name="No_PrintDefaultCommand"/>

  6. If you are running under the Vista operating system, navigate to the folder

    C:\ProgramData\Microsoft\AppEnv\9.0\Apps\MyVSShellStub_e34ac168-999b-4999-91cf-f5f0f700025f\1033

    (your GUID will vary). Delete the .CTM file or else the Shell will not update your menu changes. This is a known issue.

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

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

  9. Close the isolated Shell.

Adding a VSPackage

You can add a new or existing VSPackage to your custom tool. Let's add a new Tool Window VSPackage. You can use this tool window as the start of a Help About box.

To add a new VSPackage

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

    The Add New Project wizard appears.

  2. In the Project types window, click Other Project Types. Click 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, then click the Visual C# radio button. Click Next again to accept the defaults.

    The Basic VSPackage Information dialog appears.

  5. Click Next, then click the Tool Window check box. Click Next again to accept the defaults.

    The Tool Window Options dialog appears.

  6. Click Next to accept the default Window name My Help About and the default Command ID cmdidMyHelpAbout.

    The Select Test Project Options dialog appears.

  7. Click the Integration Test Project (C#) check box to clear it. Click Finish

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

  8. In the Solution Explorer, right-click the MyHelpAbout project node and click Properties.

    The application designer appears.

  9. Click the Build Events tab and then click the Edit Post-build button.

    The Post-build Event Command Line dialog appears.

  10. Copy and paste these four lines into the edit box, then click OK:

    copy /y "$(TargetPath)" "$(SolutionDir)$(ConfigurationName)\PackagesToLoad\"

"C:\Program Files\Microsoft Visual Studio 2008 SDK\VisualStudioIntegration\Tools\Bin\RegPkg.exe" /pkgdeffile:"$(TargetDir)$(TargetName).pkgdef"  "$(TargetPath)"

copy /y "$(TargetDir)$(TargetName).pkgdef" "$(SolutionDir)$(ConfigurationName)\PackagesToLoad\" 

$(SolutionDir)$(ConfigurationName)\$(SolutionName).exe /setup

    These post-build steps create a .pkgdef file for the MyHelpAbout VSPackage. The VSPackage dll and .pkgdef files are copied into the PackagesToLoad folder. Finally, the Shell stub is run with the /setup switch.

Hinweis

You need to specify the full path to the RegPkg utility.

Hinweis

The final post-build step exits with a spurious error message. This is a known issue.

  1. Rebuild the MyHelpAbout project.

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

  3. Click the View menu, then click Other Windows. Click My Help About.

    The My Help About tool window appears.

  4. Close the isolated Shell.

Moving the Help About Box to the Help Menu

You can move the My Help About menu command created in the previous step to the Help menu. By changing the priority of the menu 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 menu command to the Other Windows menu group.

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

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

    In addition to moving the command to the Help About group, the priority has been lowered to 0x9999 to force it to the bottom of the menu.

  4. If you are running under the Vista operating system, navigate to the folder

    C:\ProgramData\Microsoft\AppEnv\9.0\Apps\MyVSShellStub_e34ac168-999b-4999-91cf-f5f0f700025f\1033

    (your GUID will vary). Delete the .CTM file or else the Shell will not update your menu changes. This is a known issue.

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

  6. Click the Help menu, then click My Help About.

    The My Help About tool window appears.

  7. Close the isolated Shell.

Deploying the Custom Tool

You deploy your shell custom tool to a target computer by creating a setup project. You must specify the following:

  • 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 shell custom tool.

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.

To lay out the files and folders on the target computer

  1. Open the MySetup project in the File System Editor.

  2. Right-click the Custom tool Folder and then click Add Project Output.The Add Project Output Group dialog box appears.

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

  4. Select Primary Output in the list box and then click OK.Primary Output from MyVSShellStub (Active) is added to the Custom tool Folder.

  5. Repeat the last three steps, and change the selection in the Project drop-down list every time to add the outputs of the MyVSShellStubPkg and MyVSShellStubUI to the Custom tool Folder.

    Hinweis

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

  6. Right-click the Custom tool Folder and then click Add Folder. Name the new folder PackagesToLoad.

  7. Right-click the Custom tool Folder and then click Add Folder. Name the new folder 1033.

  8. Right-click the PackagesToLoad folder and then click Add File. Select the file MyVSShellStub/Debug/PackagesToLoad/MyVSShellStub.pkgdef.

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. Open the Properties Window and set the following values for the given properties.

  • (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.

  • (Name)
    CheckForVS

  • Condition
    VSINSTALLDIR<>

  • InstallUrl

  • Message
    Install VS Shell Isolated

To create the setup project custom actions

  1. Open the MySetup project in the Custom Actions editor.

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

  3. Double-click the Custom tool Folder in the list 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.

  • (Name)
    Primary Output from MyVSShellStub (Active)

  • Arguments
    /setup

  • Condition

  • CustomActionData

  • InstallerClass
    False

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

  2. Double-click the Custom tool Folder in the list box to open it.

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

  4. Select Primary Output from MyVSShellStub (Active).

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

  • (Name)
    Primary Output from MyVSShellStub (Active)

  • Arguments
    /remove

  • Condition

  • CustomActionData

  • InstallerClass
    False

See Also

Concepts

Visual Studio 2008 Shell

Visual Studio 2008 Shell Isolated Mode