Chapter 23

Building and Distributing OLE Objects

Other applications use object libraries, so you must take special care when installing them. Objects must be registered with the system and you must distribute subsequent versions of your objects in a way that does not break existing, dependent applications.

In this chapter, you learn how to do the following:

• Identify the files that you need to distribute with your application
• Manage versions and editions of your application during installation
• Install and register objects based on the version and edition
• Create registration (.REG) files for your objects
• Deinstall your objects

Required Files

You cannot safely assume that anyone using objects that you create in Visual Basic already has a current version of the OLE 2.0 DLLs. Applications that use earlier versions of OLE 2.0 can create and use objects that you create in Visual Basic 4.0 (VB4). These applications include the following:

• Visual Basic 3.0
• Microsoft Excel 5.0
• Microsoft Project 3.0

These three applications permit programmatic access to objects through the CreateObject and GetObject functions. However, for CreateObject and GetObject to use VB4 objects, you must distribute the newest versions of the OLE 2.0 DLLs along with your objects. The earlier versions of the OLE 2.0 DLLs are not compatible with VB4 objects.

Unfortunately, this requirement adds a lot of extra stuff that you must distribute every time that you send out an application. Your .EXE file might be as small as 18K, but you'll need at least two high-density disks for every copy that you distribute. Table 23.1 lists the files required for applications that provide objects.

Table 23.1 Files Required by Applications That Provide Objects

The OLE 2.0 files that table 23.1 lists are 16-bit versions. Windows 95 ships with current versions of the OLE 2.0 DLLs, so you should not have to worry about distributing 32-bit OLE 2.0 DLLs unless either of the following conditions exist:

• Your target platform is Windows NT 3.51, and Visual Basic breaks compatibility between the Windows NT release DLLS and the Visual Basic final release.
• Problems arise with the OLE 2.0 DLLs released in Windows 95, and Visual Basic must issue updated DLLs.

Either of these conditions is impossible to foresee at this point. Check the Visual Basic README.TXT if you have concerns, or call Microsoft's Product Support Services to verify compatibility.

Versioning Objects

Applications that provide objects have two levels of versioning:

• File version
• File edition

The file version differentiates between files with the same name. For instance, you might distribute an updated version of an object library that contains bug fixes. In this case, the new file would have a later file version and simply replace the earlier file when installed.

The file name itself includes the file edition. You must issue a new edition of an application if it breaks compatibility with the previous edition. New editions of an application must not overwrite prior editions.

Creating New Versions

If you are distributing an application that replaces a previous version, the new version must be code-compatible with the previous version. That is, other programs written using objects in the previous version should not break when the users install the new version. There are many ways that you can break compatibility with previous versions of an application, but the ones that OLE defines as critical are all related to the syntax of the objects, properties, and methods that your application provides. Any of the following changes breaks compatibility with previous versions:

• Changing the name of a Public project, class, method, or property
• Changing the declaration of a Public class, method, or property to Private
• Changing the Creatable property of a class
• Changing Public property access from read/write to read-only or write-only
• Removing arguments or order of arguments in a Public method
• Changing data types of arguments or values returned by Public methods or properties
• Changing an optional argument to a required one in a Public method

To have Visual Basic check for compatibility, you can enter the name of the previous version of your released application in the Compatible OLE Server text box on the Project page of the Options property pages.

If you do not make any of the changes in the preceding list, you can safely overwrite the previous version of your application according to the OLE 2.0 rules. The Setup program created by the Setup Wizard automatically determines whether a file should be overwritten, by checking the file's version information. To add version information to a Visual Basic application, follow these steps:

1. Choose File, Make EXE File or File, Make OLE DLL File. Visual Basic displays a dialog box (see fig. 23.1).

Fig. 23.1

Choose the Options button on the Make EXE File or Make OLE DLL dialog box to add version information to an executable file.

2. Choose the Options button. Visual Basic displays the executable options dialog box (see fig. 23.2).

Fig. 23.2

The EXE Options and DLL Options dialog boxes enable you to write version information into the executable file that the functions in VER.DLL can read.

3. Enter new version numbers in the Version Number frame. Then click OK.
4. Click OK to build the executable file.

In the EXE and DLL Options dialog boxes, you can choose from three version number fields:

Each time that you update a field, you should reset the less-significant fields to 00. The accepted convention for prerelease software is to keep Major revision set to 00 until the initial release; this limits you to only 99,999,999 iterations before you have to ship it.

Creating New Editions

If an application that provides objects is not compatible with the previous version, you must release it as a new edition. Application editions have unique file names, such as OUT0100.DLL. The new edition must not overwrite the previous edition, or you risk breaking other, dependent applications on the user's system.

Applications that use editions must include edition information in the system registration database. You must create registration entries that append the edition number to the programmatic ID for each creatable object, as shown in figure 23.3.

Fig. 23.3

The programmatic ID for a new edition includes the edition number.

Applications can also register an entry in the registration database that indicates the most current edition. This entry does not include an edition number. Figure 23.3 shows both edition-specific and general entries for OUT0100.DLL. Both programmatic IDs (Outline.Topic and Outline.Topic.1) share the same class ID number. OLE uses the class ID to locate the executable file, so both programmatic IDs start the same application when used with CreateObject or GetObject. The following two lines have equivalent results:

The only difference between the preceding two lines is compatibility. If a new edition of the OUTLINE.VBP application is released, the first line might cause subsequent code to break. The second line, however, always starts the original edition of the application.

Installing Objects

Visual Basic writes registration information into each application that provides public, creatable objects. During installation, you can write this information to the system registration database by running the application with the /REGSERVER switch. For example, the following line registers the OUTLINE.EXE application:

If your executable is a .DLL, you can't use the Shell function to register the executable's objects, because .DLLs cannot run by themselves. Instead, you must use the DLLSelfRegister API function included in the Setup Toolkit .DLL. The following code shows the declarations and use of the function:

The Setup Wizard automatically registers an application file if you add the $(EXESelfRegister) flag as the sixth argument for the file's entry in the SETUP.LST file. The following line shows the .LST file line that registers OUTLINE.EXE during setup:

To register .DLLs, use the $(DLLSelfRegister) flag, as in the following example:

If your application needs to register a new edition, you must create a separate .REG file that registers both the current version and the edition-specific entries for your application.

Creating an .REG File

To create an .REG file that contains edition information, follow these steps:

1. Build your application on your system.
2. Run the application to register it in your system registration database.
3. Run the Registration Info Editor (see fig. 23.3) by entering REGEDIT /V.
4. Select the registration entry of the application that you just registered and choose File, Save Registration File.
5. Locate the matching entry for the class ID registered for the application that you just registered. You can locate the key by copying the value of the CLSID entry into the Find dialog box, as shown in figure 23.4. To display the dialog box, choose Edit, Find Key.

Fig. 23.4

To locate the class ID entry, copy the value of the CLSID key into the Find dialog box.

6. Select the CLSID entry and choose File, Save Registration File. Figure 23.5 shows a key selected for the CLSID entry before being saved.

Fig. 23.5

The CLSID entry contains the location and name of the executable file for the object.

7. Repeat steps 4 through 6 for each creatable object that your application provides.
8. Merge all the saved files by using a text editor.
9. Add edition information to the programmatic ID for each object.

The following lines show the .REG file entries for OUT0100.EXE. The file contains edition-specific entries and general entries indicating the current edition.

The preceding .REG file includes the file path (\WINDOWS\SYSTEM) where the Setup program installed the application. During Setup, you must modify this information to indicate the actual installed path and file name.

The Registration Info Editor differs in Windows 95 and Windows 3.x. Windows 3.x requires the /V command-line switch to view full listings. The Windows 95 version ignores this switch. Also, some commands and menus differ in the two versions.

Registering an .REG File

To register an .REG file during setup, modify the SETUP.LST file generated by the Setup Wizard to include the application's .REG file name, as follows:

Be sure to include the .REG file in the list of files to be installed. The Setup program generated by the Setup Wizard decompresses all files before registering them, so you need not worry about the order of .REG and executable files in SETUP.LST.

To register an .REG file without using the Setup Wizard, run the Registration Info Editor with the /S switch, as follows:

The /S switch runs the Registration Info Editor silently, without displaying a confirmation message after the application is registered.

Uninstalling Objects

Most Windows 3.x applications do not provide a facility for removing themselves from the system. This capability is a new feature that Windows 95 provides. If you are distributing your applications for Windows 95, you need not worry about uninstalling because the process is built in to the system. However, on earlier versions of Windows, you do need to concern yourself with uninstalling.

The Windows 3.x system registration database (REG.DAT) can fill up. Once the file exceeds 110K, it may be too big to edit in the Registration Database Info Editor. This can also cause problems within Visual Basic when loading and reading entries from REG.DAT. If REG.DAT becomes too big on your system, you get "Not enough memory" errors when you try to load the database in the Registration Info Editor.

When such errors occur, you can only delete the file and run SETUP.REG from your Windows system directory. This reregisters the applications that come with Windows. You must rerun each of your other Windows applications to reregister them.

You can run your application with the /UNREGSERVER switch to remove its registration database entries before you remove the executable file from disk. The following lines show how you might remove the OUTLINE.VBP sample:

The /UNREGSERVER switch removes only the OLE Automation entries for an application. If you created associations among file types and your application in the registry, you must use the Windows registration APIs to delete the keys. The SYSTEM.VBP sample includes a Registration object to provide methods that invoke these functions. The following code shows how to use the Registration object to delete the registration entry for the OUT0100.EXE application:

From Here...

For more information on the following topics, see the indicated chapters:

• Chapter 22, "Debugging Applications That Provide Objects," gives you important insight into solving the many new problem areas that crop up as you program with objects.
• Chapter 24, "Creating Add-Ins," explains how to create add-in applications that you can use to extend the Visual Basic programming system.