Isolated Shell Extension Points

Article
05/28/2009

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

A Visual Studio isolated shell application has full access to Visual Studio services and supports special customization and branding. There are several ways you can customize an isolated shell application:

You can use VSPackages to extend an isolated shell application just as you would use them in any other Visual Studio extension.
To make Visual Studio features and menu command groups available or unavailable, update the .vsct file in the user interface (UI) project of the application.
To remove Options pages or other Visual Studio shell components from the application, update the .pkgundef file of the application.
To modify other aspects of the appearance or behavior of the shell, update the .pkgdef file of the application.
Some aspects of the shell can also be specified when the application is started. To do this, update the parameters in the call to the Start entry point of the appenvstub.dll.

Several of these customizations are highlighted in Walkthrough: A Basic Isolated Shell Application.

Registry Settings

Both the .pkgdef and the .pkgundef files modify the registry settings for the application.

After the application has been installed, the devenv program runs with the /setup switch the first time it is invoked. The /setup switch adds registry settings for the application. The registry settings are defined in the following sequence:

The registry key for the application is created.
The registry is updated from the .pkgdef file of the application by defining specified keys and entries.
For every package that is part of your application, the registry is updated from the .pkgdef file of that package. Each package is defined in the .pkgdef file of the application by the $RootKey$\Packages\{vsPackageGuid} key for the package.
The registry is updated from the AppEnvConfig.pkgdef and BaseConfig.pkgdef in the Visual Studio SDK installation path\Common7\IDE\ShellExtensions\Platform directory. These files are part of Visual Studio and also part of the Visual Studio Shell (isolated mode) redistributable package.
The registry is updated from the .pkgundef file of the application by removing specified keys and entries.

The Setup program should be able to uninstall the application by using the /remove switch. The /remove switch removes the registry settings for the application.

Run-Time Settings

When a user starts the isolated shell application, it calls the Start entry point of the Visual Studio shell. Application settings are defined when your application starts, as follows:

The Visual Studio shell checks the application registry for specific keys. If the setting for a key is specified in the call to the Start entry point, then that value overrides the value in the registry.
If neither the registry nor the entry point parameter specifies the value of a setting, then the default value for the setting is used.

When a user starts your application from the command line, all command line switches (except for /remove) are passed to the Visual Studio shell, which treats them in the same way that Devenv does. For more information about Devenv switches, see Devenv Command Line Switches and Devenv Command-Line Switches for VSPackage Development. For more information about how a package registers for command line switches, see Adding Command-Line Switches.

The .Vsct File

The .vsct file lets you specify which standard Visual Studio UI elements are available in the application. For more information, see Modifying the Isolated Shell By Using the .Vsct File.

The .Pkgundef File

When the application is installed on a computer on which Visual Studio is already installed, a copy of the Visual Studio registry entries is made for the application. By default, the application uses VSPackages that are already installed on the computer.

The .pkgundef file lets you exclude registry entries. In this manner, you can ensure that specific elements of the Visual Studio shell or extensions are removed from the application. For more information, see Modifying the Isolated Shell By Using the .Pkgundef File.

The .Pkgdef File

The .pkgdef file lets you define registry entries for the application that are set when the application is installed. For a description of the .pkgdef file and a list of registry entries that the Visual Studio shell uses, see Modifying the Isolated Shell By Using the .Pkgdef File.

The Start Entry Point

The Appenvstub.dll file contains entry points for accessing the isolated shell. When the application starts, it calls the Start entry point of Appenvstub.dll.

You can change the behavior of the application by changing the value of the last parameter that is passed to the Start entry point. For more information, see Isolated Shell Entry Point Parameters (C++).

Substitution Strings

The following substitution strings are used in the .pkgdef and .pkgundef files,

String	Description
$=RegistryEntry$	The value of the RegistryEntry entry. If the registry entry string ends in a backslash (\), then the default value of the registry subkey is used. For example, the substitution string, $=HKEY_CURRENT_USER\Environment\TEMP$, is expanded to the temporary folder of the current user. The $RootKey$ string can be used to retrieve a registry value under the application subkey. For example, the string "$=$RootKey$\AppIcon$" will return the value of the AppIcon entry under the application root subkey. Note The parser processes the .pkgdef file sequentially, and can access a registry entry under the application subkey only if the entry has been previously defined.
$AppName$	The qualified name of the application that is passed to the AppEnv.dll entry points. The qualified name consists of the application name, an underscore, and the class identifier (CLSID) of the application automation object, which is also recorded as the value of the ThisVersionDTECLSID setting in the project .pkgdef file.
$AppDataLocalFolder	The subfolder under %LOCALAPPDATA% for this application.
$BaseInstallDir$	The full path of the location where Visual Studio was installed.
$CommonFiles$	The value of the %CommonProgramFIles% environment variable.
$HivelessRootKey$	The Software\Microsoft\VisualStudio key.
$MyDocuments$	The full path of the My Documents folder of the current user.
$PackageFolder$	The full path of the directory that contains the package assembly files for the application.
$ProgramFiles$	The value of the %ProgramFiles% environment variable.
$RootFolder$	The full path of the root directory of the application.
$RootKey$	The root registry subkey for the application, for example, \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AppEnv\9.0\Apps\MyVsShellStub_D387CBEE-B704-4312-8636-5A359DCF8277. Visual Studio qualifies the name of the application to ensure that this subkey is unique.
$ShellFolder$	The full path of the location where Visual Studio was installed.
$System$	The Windows\system32 folder.
$WINDIR$	The Windows folder.

If the parser does not recognize the substitution string or it cannot determine the value of a registry entry or an environment variable, then it does not perform substitution on that part of the string.