Walkthrough: Creating a Basic Isolated Shell Application

This walkthrough shows how to create an isolated shell solution, customize the Help About tool window, and create a setup program for installing the isolated shell.

Prerequisites

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

Creating an Isolated Shell Solution

This section shows how to use the Visual Studio Shell Isolated project template to create an isolated shell solution. The solution contains the following projects:

• The SolutionName.AboutBoxPackage project, which allows you to customize the appearance of the Help/About box.

• The ShellExtensionsVSIX project, which contains the source.extension.vsixmanifest file that defines the different components of the isolated shell applicaton.

• The SolutionName project, which produces the executable file that invokes the isolated shell application. This project contains the Shell Customization folder, which allows you to customize the appearance and behavior of the isolated shell application.

• The SolutionNameUI project, which produces a satellite assembly that defines active menu commands and localizable strings.

To create a basic isolated shell solution

1. Open Visual Studio.

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

3. In the New Project window, under Installed Templates, 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 new solution appears in Solution Explorer.

5. Press F5 to compile the solution and start debugging the isolated shell application.

   The Visual Studio isolated shell appears. The title bar reads "MyVSShellStub". The title bar icon is generated from the file \MyVSShellStub\Resource Files\ApplicationIcon.ico.

6. Stop debugging the application.

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 procedure shows how to change the name and icon that are displayed in the custom application title bar by changing the package definition file, MyVSShellStub.Application.pkgdef.

To customize the custom application name and icon

1. In the MyVSShellStub project, open the Shell Customization\MyVSShellStub.Application.pkgdef for editing.

2. Change the AppName element value:

   "AppName"="Fabrikam Music Editor"
   

3. To change the application icon, copy a different icon to the …\VSShellStub\VSShellStub\VSShellStub directory. Add the icon to the Resource Files folder. Then open the VSShellStub.rc file and replace the value of IDI_STUBPROGRAM with the name of the new icon.

4. Press F5 to compile the solution and start debugging the isolated shell application.

   The isolated shell IDE appears. The title bar has your new icon next to the words Fabrikam Music Editor.

5. Stop debugging the application.

Customizing the Default Web Browser Home Page

This section shows how to change the default home page of the Web Browser window by changing the package definition file.

To customize the default Web Browser home page

1. In the MyVSShellStub.Application.pkgdef file, change the DefaultHomePage element value to "https://www.microsoft.com".

2. Rebuild the MyVSShellStub project.

3. Press F5 to compile the solution and start debugging the isolated shell.

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

5. Stop debugging the application.

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 menus and commands.

The declarations are interpreted by the isolated shell as follows:

• If a declaration is uncommented, that menu or command will be excluded from the isolated shell.

• If a declaration is commented, the menu or command will be included in the isolated shell.

In the following procedure, you uncomment the set of printing commands in your .vsct file.

To remove the printer menu commands

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

2. Close the isolated shell application.

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

4. Locate the following line.

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

5. Uncomment 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 debugging the isolated shell application.

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

8. Stop debugging the application.

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 $RootKey$\Packages registry key.

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 in the Shell Customization folder of the MyVSShellStub project.

2. Add the following line to the file. The GUID is the GUID of the XML Editor package.

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

3. Rebuild the solution and start debugging the isolated shell.

4. On the File menu, point to Open and then click File. Select XML File. Open the MyVSShellStubUI.vsct file (in the MyVSShellStub\MyVSShellStub\MyVSShellStubUI folder) and verify that the XML keywords in the file are not colorized and that typing "<" on a line does not bring up XML tooltips.

5. Stop debugging the application.

Customizing the Help/About box

You can customize the Help/About box, which is created as part of the isolated shell project template.

To customize the Help/About box

1. In the VSShellStub.AboutBoxPackage project, open the AboutBox.xaml file.

2. To change the company name, replace the company content with a string:

   <Label x:Name="company" x:Uid="company" Content="Fabrikam" />
   

3. To add a description of the product, replace the description content with a string:

   <TextBox x:Name="description" x:Uid="description" Text="The description of Fabrikam Music editor."
                        Style="{StaticResource ReadOnlyDescStyle}" />
   

4. To change the title of the description text box, replace the info content with a string:

   <Label x:Name="info" x:Uid="info" Style="{StaticResource ParagraphSeparator}" 
                      Content="Fabrikam Music Editor Details:" />
   

5. To change the color of the Help/About box, go to the block that starts with the following line:

   <Style x:Key="BackgroundStyle" TargetType="{x:Type StackPanel}">
   

   Replace "LightBlue" with "Green" and "White" with "LightGreen".

6. Rebuild the solution and start debugging the isolated shell.

7. On the Help menu, click About VSShellStub.

   The About Box Package window appears. You should see the changed strings in the window, which should be green.

8. Stop debugging the application.

Before You Deploy the Isolated Shell Application

Your isolated shell application can be installed on any computer that has the Visual Studio Shell (isolated mode) Redistributable Package. For more information about the redistributable package, see the Visual Studio Extensibility Downloads Web site.

Deploying the Isolated Shell Application

You deploy your 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 the 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. Select the Setup Project template. Name the new project MySetup and then click OK.

   The template 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.

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 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 Application Folder, point to Add, click Folder, and name the new folder Extensions.

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

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

    • MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.Application.pkgdef

    • MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.pkgdef

    • MyVSShellStub\Release\PackagesToLoad\MyVSShellStub.pkgundef

    • MyVSShellStub\Release\PackagesToLoad\MyHelpAbout.pkgdef

11. Right-click the Application Folder 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. Right-click the MySetup project, point to View, and then click Launch Conditions.

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\10.0\Setup\IsoShell\1033\ProductDir
   Root	vsdrrHKLM
   Value	InstallDir

   Note

   If the InstallDir key is present, you can assume that the Visual Studio 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)	CheckForIsoShell
   Condition	VSINSTALLDIR<>
   InstallUrl
   Message	Install VS Shell Isolated

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.

See Also

Concepts

Shell (Integrated or Isolated)

Visual Studio Shell (Isolated)