Isolated Shell Extensibility Points

Article
11/16/2012

A Visual Studio isolated shell-based application has full access to Visual Studio services and supports customization and branding. There are several ways you can customize a shell-based application, as follows:

You can use add-ins and VSPackages to extend an isolated shell-based application just as you would use them to extend Visual Studio itself.
To turn 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 it installs the application, the Setup program should call the application by using the /setup switch. 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\AppEnv 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.

Before it uninstalls the application, the Setup program should call 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 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 /setup and /remove, are passed to the Visual Studio shell, which treats them in the same way as 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 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 Visual Studio shell in isolated mode. When the application starts, it calls the Start entry point of Appenvstub.dll. The last parameter of the Start entry point takes a pointer to a UTF-16 Unicode string.

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

In the .pkgdef and .pkgundef files, the following strings are expanded when they are parsed. In general, the parser does not perform recursive substitution. These strings are parsed when a user installs the application.

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 only access a registry entry under the application subkey 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.
$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.
$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.
%EnvVariable%	The value of the EnvVariable environment variable.

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.