Host Configuration Registry Key Settings
To register the host application, you must create an application-specific subkey with several required entries under the host configuration key. You must also create several additional subkeys if you are including an in-process host or an upgrade helper class with your application. For more information, see Registering the Host Application and How to: Register the Host Application.
If you change any of these subkeys or entries after you register your application on the development computer, you must update the registration. For more information, see How to: Update the Registration for the Host Application.
The entries for the subkeys are described in the following sections:
Entries for the host configuration subkey
Entries for the in-process host subkey
Entries for the upgrade helper class subkey
Entries for the Host Configuration Subkey
The host configuration subkey provides configuration information about the host application to the Visual Studio Tools for Applications integrated development environment (IDE). Visual Studio Tools for Applications uses these values to locate project templates, load default settings, and specify default file locations. The following example demonstrates a host configuration subkey on a 32-bit platform.
HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\ShapeAppCSharp\2.0
For more information about this key, see Registering the Host Application.
The following table lists the entries for the host configuration subkey. All of these entries have the type REG_SZ.
Entry |
Description |
|---|---|
AppName |
Required. Name to appear in the IDE title bar. |
DefaultSettings |
Optional. Location of the Visual Studio Tools for Applications settings file. |
HelpNamespace |
Optional. The Help namespace of a custom .hxs Help file for your host application. |
ItemTemplatesLocation |
Optional. Location of item templates for Visual Studio Tools for Applications. |
NewProjectLocation |
Optional. Location where projects are saved by default. |
ProjectTemplatesLocation |
Required. Location of Visual Studio Tools for Applications project templates. |
UpgradeFrom |
Optional. The host ID of the previous version of an upgraded host application. |
UpgradeHelper |
Optional. The GUID used to register the assembly that contains an upgrade helper class. |
UserFilesFolderName |
Optional. Location where Visual Studio Tools for Applications stores a user's projects and settings. |
VSCSProjectTemplatesLocation |
Optional. Location of custom Visual C# project templates for Visual Studio 2008. |
VSItemTemplatesLocation |
Optional. Location of custom item templates for Visual Studio 2008. |
VSTAVersion |
Required. Version of Visual Studio Tools for Applications that you have integrated with your host application. |
VSVBProjectTemplateLocation |
Optional. Location of custom Visual Basic project templates for Visual Studio 2008. |
AppName
This entry specifies the string that appears in the Visual Studio Tools for Applications IDE title bar. If you do not provide a value for this entry, Visual Studio Tools for Applications displays the host ID. The host ID is the name of the registry key you create when you register the host application. For more information, see How to: Register the Host Application.
DefaultSettings
This entry provides the path of a Visual Studio Tools for Applications settings file. Visual Studio Tools for Applications uses this file for the initial IDE layout. If you do not provide a path for this entry, Visual Studio Tools for Applications uses the default settings file that is located at %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\VSTA\Profiles\VSTA.vssettings.
For information about how to create a custom settings file, see Configuring the IDE.
HelpNamespace
This entry specifies the Help namespace that is used to register a custom .HxS Help file that you are bundling with the Help for the Visual Studio Tools for Applications IDE. Typically, this Help file provides information about the object model of your application and other details that your customers need to know about how to develop and deploy add-ins. For more information, see Integrating Help into the IDE.
When an .HxS file is registered, it is associated with a Help namespace, which functions as a virtual directory to keep track of the physical location of files and enable access through the ms-help protocol. For more information, see Help File Registration in the Visual Studio SDK documentation.
ItemTemplatesLocation
If you create custom item templates for Visual Studio Tools for Applications projects, use this entry to provide a path to those templates. These items will appear in the Add New Item dialog box of the Visual Studio Tools for Applications IDE.
When you install Visual Studio Tools for Applications or run vsta.exe using the /setup switch, Visual Studio Tools for Applications does the following:
Copies the value of ItemTemplatesLocation to the UserFolder entry of the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHost\host ID\9.0\VSTemplate\Item.
Extracts the .zip files from the path that was copied to the UserFolder entry and places the files in %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplatesCache.
NewProjectLocation
Use this entry to provide a path to the location where Visual Studio Tools for Applications saves projects by default.
If you do not provide this entry, Visual Studio Tools for Applications saves projects to the UserFilesFolder\Projects folder, where UserFilesFolder is the path that is specified by the UserFilesFolderName entry.
ProjectTemplatesLocation
This entry provides a path to Visual Studio Tools for Applications project templates. For information about how to create Visual Studio Tools for Applications project templates, see Creating Project Templates (Visual Studio Tools for Applications). Add this entry if you would like project templates to appear in the New Project dialog box. You might not need to add this entry if you plan to programmatically open a project template when the user starts the IDE. For more information, see How to: Start the IDE.
Note
Visual Studio Tools for Applications supports only local paths.
When you install Visual Studio Tools for Applications or run vsta.exe with the /setup switch, Visual Studio Tools for Applications does the following:
Copies the value of ProjectTemplatesLocation to the UserFolder entry in the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSTAHost\host ID\9.0\VSTemplate\Project.
Extracts templates from .zip files that it gets from the location that is specified by the UserFolder entry, and then caches the extracted project templates in a host-specific folder under %AllUsersProfile%\Microsoft\VSTAHost.
UpgradeFrom
This entry specifies the host ID of the previous version of an upgraded host application. Create this entry if you update the host application to support Microsoft Visual Studio Tools for Applications 2.0, and you want to migrate add-in projects that were created for the previous version of the application. For more information, see Migrating Add-in Projects.
UpgradeHelper
This entry specifies the GUID that is used to register an assembly that contains an upgrade helper class. An upgrade helper class is any class that implements the IVstaUpgradeHelper interface. Create this entry if you update the host application to support Microsoft Visual Studio Tools for Applications 2.0, and want to migrate add-in projects that were created for the previous version of the application. For more information, see Migrating Add-in Projects.
This GUID corresponds to another GUID subkey that is under the key VSTAHostConfig\host ID\2.0\VSTA\UpgradeHelper.
UserFilesFolderName
Use this entry to specify where Visual Studio Tools for Applications stores miscellaneous settings files, such as code snippets and temporary settings files that reflect changes that users make to IDE options settings. It is recommended that you set this entry to the path of a folder under %UserProfile%\My Documents (Windows XP) or %UserProfile%\Documents (Windows Vista).
If you do not add the UserFilesFolderName entry, Visual Studio Tools for Applications uses %UserProfile%\My Documents\ApplicationName (Windows XP) or %UserProfile%\Documents\ApplicationName (Windows Vista) by default.
VSCSProjectTemplateLocation and VSVBProjectTemplateLocation
These entries provide paths to custom Visual C# and Visual Basic project templates for Visual Studio 2008. You can use this entry as a convenience to add Visual C# and Visual Basic project templates to Visual Studio 2008. Visual Studio Tools for Applications then adds the templates that are in the specified location to the Visual Studio 2008 template collection.
When you install Visual Studio Tools for Applications or run vsta.exe using the /setup switch, Visual Studio Tools for Applications does the following:
Copies the contents of the directory that is specified by the VSCSProjectTemplateLocation entry to %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ProjectTemplates\CSharp\Host ID.
Copies the contents of the directory that is specified by the VSVBProjectTemplateLocation entry to %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ProjectTemplates\VisualBasic\Host ID.
You must then regenerate the Visual Studio 2008 template cache so it includes the new templates. You can accomplish this by running devenv.exe using the /setup switch. Devenv.exe is usually located at %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE, but it can be installed in another location if the user overrides the default location. If you need to regenerate the template cache programmatically, you can locate devenv.exe by reading the InstallDir registry entry at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0. For more information, see Devenv Command Line Switches.
VSItemTemplatesLocation
If you create custom item templates for Visual Studio 2008 projects, use this entry to provide a path to those templates. These items will appear in the Add New Item dialog box of Visual Studio.
When you install Visual Studio Tools for Applications or run vsta.exe using the /setup switch, Visual Studio Tools for Applications copies the contents of the directory specified by the VSItemTemplatesLocation entry to %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates\Host ID.
You must then regenerate the Visual Studio 2008 template cache so it includes the new templates. You can accomplish this by running devenv.exe using the /setup switch. Devenv.exe is usually located at %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE, but it can be installed in another location if the user overrides the default location. If you need to regenerate the template cache programmatically, you can locate devenv.exe by reading the InstallDir registry entry at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0. For more information, see Devenv Command Line Switches.
VSTAVersion
This entry specifies the version of Visual Studio Tools for Applications that you have integrated with your host application. For host applications that integrate Microsoft Visual Studio Tools for Applications 2.0, this entry must have the value 9.0. The 9.0 value refers to the version of Visual Studio that Microsoft Visual Studio Tools for Applications 2.0 is based on.
Entries for the In-Process Host Subkey
If you include an in-process host for your project templates, you must create a subkey named VSTA\InProcHost\GUID under the host configuration subkey. The GUID key represents the GUID that is used to register the in-process host assembly. The following example demonstrates an in-process host subkey on a 32-bit platform.
HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\ShapeAppCSharp\2.0\VSTA\InProcHost\{21689C71-FDE5-4cd9-8004-4A5A6FAE7206}
For more information, see Creating In-Process Hosts.
The following table describes the entries for the GUID key. All of these entries have the type REG_SZ.
Entry |
Description |
|---|---|
Assembly |
Required. A string that includes the name, version, culture, and public key token of the assembly that contains the in-process host. For example: IPHExample, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b0a84c23d7c3462e |
FullClassName |
Required. The fully qualified name of the class that implements the in-process host. |
Upgrade |
Optional. The GUID that is used to register the assembly that implements the new version of the in-process host for an upgraded host application. This GUID corresponds to another GUID subkey under the key VSTAHostConfig\host ID\2.0\VSTA\InProcHost. For more information, see Updating a Host Application to Support Visual Studio Tools for Applications 2.0. |
Entries for the Upgrade Helper Class Subkey
If you include an upgrade helper class for the new version of a host application, you must create a subkey named VSTA\UpgradeHelper\GUID under the host configuration subkey. The GUID key represents the GUID that is used to register the assembly that contains the upgrade helper class. The following example demonstrates an upgrade helper class subkey on a 32-bit platform.
HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\ShapeAppCSharp\2.0\VSTA\UpgradeHelper\{85baf30d-8ddd-4c3a-a01e-29569fdf5163}
For more information, see Migrating Add-in Projects.
The following table describes the entries for the upgrade helper class subkey. All of these entries have the type REG_SZ.
Entry |
Description |
|---|---|
Assembly |
Required. A string that includes the name, version, culture, and public key token of the assembly that contains the upgrade helper class. For example: UpgradeHelperExample, Version=9.0.0.0, Culture=neutral, PublicKeyToken=b0a84c23d7c3462e |
Class |
Required. The fully qualified name of the upgrade helper class. |
See Also
Tasks
How to: Register the Host Application
How to: Update the Registration for the Host Application