Modifying the Isolated Shell By Using the .Pkgdef File
The .pkgdef file supports settings that you can use to customize an isolated shell-based application. The .pkgdef file represents registry values that are created when an application is installed on a computer and that are referenced by the Visual Studio Shell when it starts the application. The settings are organized in the file in a way that resembles how the values appear in the registry.
The .pkgdef file contains sections that are each identified by a key, either [$RootKey$] or [$RootKey$\subkey], where $RootKey$ represents the root key for the application.
Each section contains name/value pairs that have the following format: "ValueName"=Value.
Values are either a string that is enclosed in quotes, or a 32-bit integer that is represented as a dword. Values have the following constraints:
All dword values are in hexidecimal, for example, dword:00000001.
For Boolean values, 1 represents true, and 0 represents false.
All GUID strings are in registry format, for example, "{00000000-0000-0000-0000-000000000000}".
All localizable resource identifiers have the form, "@resourceID" or "#resourceID", where resourceID is the resource identifier in the application UI package, for example, "@102". The application UI package is the same as the package that is referenced in the AppLocalizationPackage setting.
For example,
"HideSolutionConcept"=dword:00000001
"DefaultDebugEngine"="{00000000-0000-0000-0000-000000000000}"
You can add comments to the .pkgdef file. A single-line comment has two slashes as the first two characters.
For a list of the substitution strings, see the Substitution Strings section of Isolated Shell Extensibility Points.
The following sections describe specific registry values that affect the behavior of the Visual Studio shell in isolated mode. You can also define additional registry values for the application in this file.
Note
If a setting is not provided in the .pkgdef file, then no corresponding entry is made in the registry.
Settings
The following table describes the values defined under [$RootKey$].
Name |
Type |
Value |
|---|---|---|
AddinsAllowed |
dword |
True if add-ins can be loaded; otherwise, false. The .pkgdef default value is true. |
AllowsDroppedFilesOnMainWindow |
dword |
True if the main window can accept dropped files; otherwise, false. Files dropped on the main window are opened by using the OpenDocumentViaProject method. This is equivalent to opening a document by using the Open command on the File menu in the application. The .pkgdef default value is true. |
AppIcon |
string |
The full path of the program icon. This icon appears in the title bar to the left of the application name. The .pkgdef default value is "$RootFolder$\solutionName.ico", where solutionName is the name of the application solution file. |
AppLocalizationPackage |
string |
The GUID of the VSPackage that contains the UI satellite DLL for the application. This VSPackage includes a compiled version of the .vsct file and can include other localized strings. Feature sets and menu command groups can be enabled or disabled by changing the settings in the UI project .vsct file. The .pkgdef default value is "{vsUiPackageGuid}", where vsUiPackageGuid is the GUID assigned to the application UI package. |
AppName |
string |
The name of the application. The name appears in the title bar of the application window. If you distribute the application, this name must match the Shell Name value you used to generate the shell load key (SLK). The .pkgdef default value is "solutionName", where solutionName is the name of the application solution file. |
CommandLineLogo |
string |
The banner text when the application is run in a console window. This setting only affects applications that support command-line build operations. The .pkgdef default value is "companyNamesolutionName Version 1.0.", where companyName is the name of the company provided when Windows was installed, and solutionName is the name of the application solution file. |
CompanyName |
string |
The company name associated with this application. If you distribute the application, this name must match the company name that you used to generate the SLK for the application. The .pkgdef default value is set to the name of the company provided when Windows was installed. By default, this entry is commented out. |
DefaultDebugEngine |
string |
The GUID of the default debug engine to use for the application. Note A GUID of all zeroes indicates that the application does not specify a default debug engine. This enables the debugger to select the debug engine to use. The .pkgdef default value is "{00000000-0000-0000-0000-000000000000}". |
DefaultHomePage |
string |
The default home page URL for the internal Web browser window. If the Home page option is available in the application, then this setting also affects the default state of the option. For more information, see Web Browser, Environment, Options Dialog Box. The .pkgdef default value is "http://www.companyName.com", where companyName is the name of the company provided when Windows was installed. |
DefaultProjectsLocation |
string |
The full path of the default projects folder. For example, If the Visual Studio projects location option is available in the application, then this setting also affects the default state of the option. For more information, see General, Projects and Solutions, Options Dialog Box. The .pkgdef default value is "$MyDocuments$\solutionName", where solutionName is the name of the application solution file. |
DefaultSearchPage |
string |
The default search page URL for the internal Web browser window. If the Search page option is available in the application, then this setting also affects the default state of the option. For more information, see Web Browser, Environment, Options Dialog Box. The .pkgdef default value is "http://search.live.com". |
DefaultUserFilesFolderRoot |
string |
The name of the user folder, relative to the current user's My Documents folder. The .pkgdef default value is "solutionName", where solutionName is the name of the application solution file. |
DisableOutputWindow |
dword |
Indicates whether the isolated shell should treat the output window as disabled. If this value is set to true, the Visual Studio Shell does not display the solution build manager output in the Output window and hides the Show Output window when build starts check box in the Projects and Solutions category in the Options dialog box. The .pkgdef default value is false. |
HideMiscellaneousFilesByDefault |
dword |
True to hide the Miscellaneous Files folder by default in Solution Explorer; otherwise, false. If the Show Miscellaneous files in Solution Explorer option is available in the application, then this setting also affects the default state of the option. For more information, see Documents, Environment, Options Dialog Box. The .pkgdef default value is false. |
HideSolutionConcept |
dword |
True to create all projects as stand-alone projects and hide the solution and solution-related commands for stand-alone projects by default; otherwise, false. If the Always show solution option is available in the application, then this setting also affects the default state of the option. For more information, see General, Projects and Solutions, Options Dialog Box. The .pkgdef default value is false. |
ID |
dword |
The resource identifier for the SLK in the application string table. If you distribute the application, this setting is required. The .pkgdef default value is dword:00000069. By default, this entry is commented out. |
NewProjDlgInstalledTemplatesHdr |
string |
The name for the Visual Studio installed templates header in the Templates list in the New Project dialog box. This is either a string or a localizable resource identifier that is loaded from the application UI package. The .pkgdef default value is "solutionName installed templates", where solutionName is the name of the application solution file. |
NewProjDlgSlnTreeNodeTitle |
string |
The name for the Visual Studio Solutions node in the Project types tree in the New Project dialog box. This is either a string or a localizable resource identifier that is loaded from the application UI package. The .pkgdef default value is "solutionName installed templates", where solutionName is the name of the application solution file. |
Productversion |
string |
The version string for the application. If you distribute the application, this name must match the Shell Version value that you used to generate the SLK for the application. The .pkgdef default value is "1.0". By default, this entry is commented out. |
SolutionFileCreatorIdentifier |
string |
The application identifier, which appears as the second line in the solution files that are generated by the application. This line indicates the application that created the file. By convention, this value includes both the name of the application and the application version number. For example, The VSLauncher.exe program, which is the default program for opening a Visual Studio solution file, uses this second line to determine in which version of Visual Studio to open the solution file. The application would require its own launcher to handle its associated solution files. The launcher could also use this second line in the solution file to determine in which version of the application to open the solution. Note The Visual Studio VSLauncher.exe program does not handle .sln files that were created by an isolated shell-based application. The .pkgdef default value is "solutionName Solution File, Format Version 10.00", where solutionName is the name of the application solution file. |
SolutionFileExt |
string |
The solution file name extension for the application. We recommend that you choose a unique file name extension and do not use the .sln file name extension. The .pkgdef default value is "solutionName_sln", where solutionName is the name of the application solution file. |
SplashScreenBitmap |
string |
The full path of the bitmap file for the splash screen for the application. The .pkgdef default value is "$RootFolder$\Splash.bmp". |
ThisVersionDTECLSID |
string |
The class identifier (CLSID) of the automation object for the application. The application automation object is the top-level object for the application in the Visual Studio shell automation model and implements the EnvDTE._DTE interface. If the application automation object is correctly registered under the HKEY_CLASSES_ROOT\CLSID registry key, then you can use the CoCreateInstance function to directly create an instance of the application. The Visual Studio shell uses this CLSID to register the application automation object in the Running Object Table (ROT) by using the ACTIVEOBJECT_WEAK flag. This lets you use the GetActiveObject function to retrieve a pointer to a running instance of the application. In addition, if you define a ProgID for the application automation object, then the Visual Studio shell also registers each instance of the application in the ROT by using an item moniker of the form progID:processID, where progID is the ProgID of the application automation object, and processID is the process identifier for that instance of the application. For example, if you create a moniker as follows, CreateItemMoniker(L"!", instanceString, &itemMoniker), where instanceString is the progID:processID string, then you could use instanceMoniker with the ROT GetObject function to get the instance. If the ThisVersionDTECLSID setting is omitted, then the application is not exposed through the Component Object Model (COM). In this case, an instance of the application cannot be created by calling the CoCreateInstance function and cannot be registered in the ROT. Each version of a VSPackage must have a different CLSID. If you distribute the application, this value must match the Shell GUID value that you used to generate the SLK for the application. The .pkgdef default value is "{vsPackageGuid}", where vsPackageGuid is a GUID that Visual Studio generated for the automation object for the application. |
ThisVersionSolutionCLSID |
string |
The CLSID of the solution object for the application. The solution automation object contains information about the current open solution in an instance of the application and implements the EnvDTE._Solution interface. If the solution automation object is correctly registered under the HKEY_CLASSES_ROOT\CLSID registry key, then you can use the CoCreateInstance function to directly create a solution object for the application. The Visual Studio shell uses this CLSID to register the solution automation object in the ROT by using the ACTIVEOBJECT_WEAK flag. If this setting is omitted, then the solution class is not registered with the Component Object Model (COM). In this case, a solution object cannot be created by calling the CoCreateInstance function and cannot be registered in the ROT. The .pkgdef default value is "{solutionAutomationObjectGuid}", where vsPackageGuid is a GUID that Visual Studio generated for the solution object for the application. |
UserFilesSubFolderName |
string |
Name of the subfolder under the user's My Documents folder in which the application creates user files and subfolders. The .pkgdef default value is "solutionName", where solutionName is the name of the application solution file. |
UserOptsFileExt |
string |
The extension for solution user options files for the application. The .pkgdef default value is "solutionName_suo", where solutionName is the name of the application solution file. |
Binding Path Settings
The [$RootKey$\BindingPaths\{00000000-0000-0000-0000-000000000000}] key contains the list directories that the shell checks for assemblies. These directories are added to the list of directories that the shell probes for private assemblies for the application.
By default, no binding-path entries are added to the .pkgdef file. However, the following subdirectories of the Visual Studio installation directory are automatically added to the application binding-path list in the registry.
Common7\IDE\
Common7\IDE\\PrivateAssemblies
Common7\IDE\\PublicAssemblies
To add a directory to the binding path, add an entry of the form "directoryName"="", where directoryName is an absolute path. For example,
[$RootKey$\BindingPaths\{00000000-0000-0000-0000-000000000000}]
"$RootFolder$\directory1"=""
"%CommonProgramFiles%\directory2"=""
Profile Settings
The following table describes the values that are defined for each associated package under [$RootKey$\Profile].
Name |
Type |
Value |
|---|---|---|
AutoSaveFile |
string |
The directory in which the application stores auto-save files. The .pkgdef default value is "$RootFolder$\Profiles\CurrentSettings.vssettings". |
Package Settings
Each VSPackage that is distributed as a part of the application must have a package load key (PLK). For instructions about how to obtain a PLK, see How to: Obtain a PLK for a VSPackage.
The following table describes the values that are defined for each associated package under [$RootKey$\Packages\{vsPackageGuid}], where vsPackageGuid is the GUID of the associated package. This GUID must match the Package Guid value that you used to generate the PLK.
Name |
Type |
Value |
|---|---|---|
CompanyName |
string |
The company name associated with this package. If you distribute the application, this name must match the company name that you used to generate the PLK for the package. The .pkgdef default value is set to the name of the company provided when Windows was installed. |
ProductName |
string |
The name of the product with which this package is associated. The .pkgdef default value is "solutionName", where solutionName is the name of the application solution file. |
ProductVersion |
string |
The version string for this package. If you distribute the application, this name must match the PLK Version value that you used to generate the PLK for the package. The .pkgdef default value is "1.0". |
ID |
dword |
The resource identifier for the PLK in the package string table. If you distribute the application, this setting is required. The .pkgdef default value is dword:00000065. |
Inprocserver32 |
string |
The .pkgdef default value is "$RootFolder$\PackagesToLoad\1033\uiPackageName.dll", where uiPackageName is the name of the application UI project file. |
MinEdition |
string |
The minimum edition of Visual Studio that can load this package. If you distribute the application, this name must match the Minimum Product Edition value that you used to generate the PLK for the package. The .pkgdef default value is "Standard". |
Package Satellite DLL Settings
The following table describes the values that are defined under [$RootKey$\Packages\{vsPackageGuid}\SatelliteDll] for the satellite DLL of each associated package, where vsPackageGuid is the GUID of the associated package.
Name |
Type |
Value |
|---|---|---|
DllName |
string |
The file name of the DLL. The .pkgdef default value is "solutionNameui.dll", where solutionName is the name of the application solution file. |
Path |
string |
The directory that contains the satellite DLL. The .pkgdef default value is "$PackageFolder$". |
Package Menu Item Settings
The [$RootKey$\Menus] key defines UI resource files for the application.
Menu item values have the form "{vsUiPackageGuid}"=", resourceId, versionNumber", where vsUiPackageGuid is the GUID for the application UI package, resourceId is the resource identifier of the CTMENU resource that contains the UI elements, and versionNumber is a virtual version number for the CTMENU resource. For more information, see Registering Interop Assembly Command Handlers.
By default, a menu item entry is created in the .pkgdef file for the application UI package.
For each package that provides menu items and that is distributed as a part of the application, add a menu item entry for the package.
See Also
Concepts
Isolated Shell Extensibility Points
Modifying the Isolated Shell By Using the .Pkgundef File
Change History
Date |
History |
Reason |
|---|---|---|
July 2008 |
Revised to reflect changes in how SLKs are generated. |
SP1 feature change. |