RGSEdit

COM servers written using ATL employ an ATL-supplied component called the Registrar. The Registrar components take a registry script as input and apply changes to the registry. Unfortunately, editing the registry script is a tedious process that is error-prone.

OT/ATL provides a visual editor for managing registry scripts. The OT/ATL Registry Script Editor (RGSEdit) reads a registry script (a .RGS file) and then displays the registry hierarchy using a tree control. Once the registry is displayed as a tree, you can edit the registry script by adding, editing, and deleting keys and values like you would in the Windows registry using the RegEdit utility. The following code is an example of a registry script from an ATL-based COM class.

Before the advent of our RGSEdit utility, ATL/COM developers used the 101-key TextWizard. They also needed to understand the registry script syntax to change or add to the default entries for a COM class. By using RGSEdit, you can avoid bungling the registry script syntax and adding spurious registry entries to a client machine's registry. Our RGSEdit utility lets COM developers view and edit a .RGS file in the same way a system administrator can view the registry on a particular workstation.

RGSEdit is a straightforward application whose document type is an ATL registry script file. To start editing a script, open a .RGS file from the file menu. After you open the registry script, you can add, change, and delete keys and values and then save the edited script.

RGSEdit is a splitter window with three panes. The far-left pane includes a tree control specifying the hierarchical arrangement of the registry script. The nodes on the tree expand to reveal sub keys. The middle pane shows the values related to the key selected in the left pane. The far right pane shows the current state of the registry script. If you saved the file, the selections in this pane would be applied.

To add a key to the registry script, select the parent key in the left pane and click the right mouse button. A local menu appears. Select Add New Key from the menu. A new key appears in the far-left pane.

If you want to change the default name provided by RGSEdit or you want to change the name of the key for some other reason, select the new key and then open the local menu. Click Edit to enable editing of the key.

ATL's registrar component also allows you to apply various attributes to the key that direct the registrar towards various actions. You can force the removal and re-creation of a particular key to prevent removal of a particular key or to delete a key. These options are directed by keywords that appear before each key in the script. To apply these keywords to any key, select a key, right click the key, and select Properties from the menu.

Select the local menu on the far-left pane and choose Delete to delete the selected key and all of its subkeys.

To add a value to any of the keys, select the key on the far-left pane and then click the right mouse button to open the local menu. RGSEdit lets you add either a string value or a DWORD value.

To edit a value, double-click the value name in the middle pane.

• If the value represents Miscellaneous Status Bits, RGSEdit displays a dialog box that lets you turn each bit on or off.

• If the value represents the COM class's threading model, you can double click to open a dialog box that lets you select from one of the COM threading models.

NOTE >> Editing values also lets you change the name of the registry value as well as the value itself. If you don't supply a name for the value, the value becomes the default value for the key.

When developing new COM classes, it's useful to categorize them. For example, the formal definition of a COM control is any COM class that implements IUnknown. However, classes that only implement IUnknown are not very useful in a real application—useful COM classes implement several interfaces. In addition, sets of functionality have been subdivided into smaller categories such as scriptable controls, Internet Explorer controls, and more. In the past, there was no way to determine if an object was a control or a scriptable control other than querying for a certain set of interfaces.

Component Categories allow developers to divide components into various categories—scriptable controls and Internet Explorer controls, for example. You can advertise that some classes implement certain features by amending their registry entries:

COM clients can also indicate that they require components to implement various interfaces in the same fashion by amending:

You can insert this information into the registry script by hand or use a facility in the RGSEditor that allows you to add component category entries to your registry script. To amend a component's registry entry and apply implemented and required categories to them, select the class's CLSID key in the far left pane of REGEdit and right-click to open the local menu. Then select, "Manage categories" to open the "Manage Categories" dialog box.

The list box on the far-left side of the dialog box displays all the categories in the registry and the categories implemented by the component. When you select a category from the list of available categories, the dialog box indicates which registered components already implement/require the selected category. The two check boxes on the bottom of the dialog box let you apply the category to the class.

You can operate RGSEdit as a stand-alone application or as a Visual Studio Addin. To use RGSEdit as an add-in, select Tools|Customize in Visual Studio and then select the Add-Ins and Macro Files tab. Check the box next to RGSEditorAddIn.DSAddIn.1 to make it an add-in. After you select RGSEditorAddIn, you can open RGSEdit by clicking the newly installed toolbar button. Now, Visual Studio will load the add-in every time you start Visual Studio.