Walkthru:Managed Package Registration
|Extensibility Guided Tour||Send comments on this topic.|
|Walkthru:Managed Package Registration|
Glossary Item Box
In order for VsPackages to integrate correctly, Visual Studio must be instructed on how to load and interact with them at run time. Visual Studio relies upon the registry to know which packages and supporting resources to load. It also relies upon the registry to locate the COM components exposed as part of a VsPackage's implementation. Normally, allowing COM components to self-register (i.e. ‘notify' the registry of their interfaces and locations) through the Installer is the standard way to deploy COM objects, but with VsPackages self-registration should not be employed. The main problems with self-registration involve degrading the ability for the Installer Package to correctly rollback, uninstall, and access external resources. Because of the ill effects self registration can have on the installation process, Visual Studio Industry Partners are prohibited by their agreement from installing self-registering packages. (Additional details about the problems of using self-registration are covered in the VS SDK.)
Windows Installer Packages generally include directives to modify the registry in a resource known as the registry table. Registry entries found in that table will be merged with the target machine upon deployment. All that is needed, therefore, to correctly register a VsPackage is to put the correct values in the registry table, and let the Installer do the rest. Happily, the VS SDK includes a powerful tool, RegPkg.exe, which will read the registration attributes for a Managed VsPackage and generate the correct registry entries. Registering a Managed VsPackage therefore consists of nothing more than generating the correct registry values using RegPkg.exe and moving the resultant data to the proper location within the Installer or Setup project.
In order for RegPkg.exe to function, it loads the VsPackage Assembly and uses reflection to evaluate several key attributes that must be associated with the VsPackage. Happily, using the Wizard to create a managed VsPackage adds all of the needed attributes for you.
1. In Solution Explorer, open VsPkg.cs in the DevAnnotater Project.
2. Look at some of the attributes above the DevAnnotater class. Attributes such as PackageRegistration and DefaultRegistryRoot provide key information that can be used by RegPkg.exe to generate corresponding registry information on target computers.
3. Modify the value of the DefaultRegistryRootAttribute to point to Experimental Build instead of Visual Studio by adding "Exp" to the end of the existing value – i.e. the entire attribute should now look like:
4. Rebuild the DevAnnotater project by selecting the Build | Rebuild DevAnnotater menu option.
At this point, you are now ready to use RegPkg.exe to generate registry information needed by your setup project. To use RegPkg.exe you'll just need to open a command prompt, and execute the tool – specifying a couple of special switches: one to output the registry information to a file (instead of registering the VsPackage against Visual Studio), and the second to ensure that the output is actually targeted against Experimental Build (instead of against Visual Studio – just to be safe).
5. Open a Command Prompt by selecting Start | Run and then typing "cmd" and pressing Enter.
6. In the command prompt, navigate to the directory where the VS SDK was installed. Once there, you'll need to locate the Tools\Bin directory to locate RegPkg.exe. Typically the path will be:
C:\Program Files\Visual Studio 2005 SDK\<build>\VisualStudioIntegration\Tools\Bin
(Where <build> is the number of the VS SDK build (such as 2005.10 etc.).)
7. Type "RegPkg.exe /?" (and press Enter) to see a list of options, or switches, for the RegPkg tool. Among the available options is the ability to export the registry information (in various formats) to a file instead of to the current machine's registry. There is also an option to explicitly target an experimental version (or registry hive) of Visual Studio by using the optional /root: switch.
8. To direct RegPkg to reflect over your VsPackage and export registry information to a file, type the following at the command prompt:
RegPkg.exe /root:Software\Microsoft\VisualStudio\8.0Exp /regfile:C:\DevAnnotater.reg "<path>"
Where <path> is the path to your actual assembly, such as: "C:\Documents and Settings\YourUserName\My Documents\Visual Studio 2005\Projects\VSIP Walkthroughs\DevAnnotater\DevAnnotater\Debug\DevAnnotater.dll". Successful output from the RegPkg executable looks like the following:
9. Close the command prompt.
10. In Visual Studio, right-click on the DevAnnotaterPackage Project in Solution Explorer and select the View | Registry menu option.
11. In the Registry window, right click the Registry on Target Machine root node and select Import.
12. In the Import Registry File dialog, navigate to the C:\ drive and double click on the DevAnnotater.reg file to open and import it.
13. In the Registry window, navigate to the following path: Registry on Target Machine | HKEY_LOCAL_MACHINE | Software | Microsoft | VisualStudio | 8.0Exp. All of the registry information in the DevAnnotater.reg file has been imported and will be deployed to the configured locations (with the specified values) to the target machine upon installation. Take a few seconds to explore the registry values that will be deployed with your installer – especially the Packages andToolWindows nodes and their contents.
14. Rebuild your current Solution to ensure that all of your changes have been correctly configured before continuing on to the next section which will describe some of the core remaining tasks associated with redistributing VsPackages.