When working on an updated version of a COM component, you should always enforce Binary Compatibility in the Component tab of the Project Properties dialog box. When enforcing binary compatibility there are a number of common mistakes that you should stay clear of:
- Always use the last EXE or DLL that was distributed with the application as the reference file. Using as the reference file an executable that was created after the last public build of the component typically causes the new executable to contain many interfaces that were the result of ad-interim compilation commands, that are then automatically inserted in the Registry when the component is registered on the customer’s machine, but that are never actually used because no client is aware of them.
- Never compile to the same executable file used as the reference file in the Binary Compatibility dialog box. In same cases Visual Basic will prevent you from doing that anyway, because of a bug in the IDE that leaves that file open between subsequent compilations. You can achieve this by making a first compilation and then renaming the EXE, or by moving it to another directory, e.g. Release or Reference.
- Whenever you distribute a new version of the component, have the Binary Compatibility dialog box point to this new file as the reference file. This is especially important, even if the new version of the component is binary compatible with the old versione. To explain why this is important, imagine this scenario:
(a) You define a first version of your component with 4 methods, and use the resulting EXE file as the reference file in the Binary Compatibility dialog box
(b) You then create a new version 2 of the component, which now uses 5 methods but doesn’t alter the first four methods. This new component is considered to be compatible with the first one, and old client will work against the new version.
(c) you create a new version 3 of the component, without making version 2 of the component the reference file in the Binary Compatibility dialog box. This newer version changes the signature of the 5th method: since VB is still using the component’s version 1 as its reference for binary compatibility, it accepts the signature change without raising any warning, but the neat result is that clients compiled against version 2 will crash when they execute against version 3.
A VB2TheMax visitor asked some extra advice about when and how the file used as a reference should be replaced by a newer version. Ideally, you should never overwrite the file used for binary compatibilty, because it’s the copy of the EXE or DLL file that has been deployed to your customers. In practice, there are a few cases when you need to replace the referenced file with a newer version. You can do the replacement from Windows Explorer, if possible after closing the VB environment. These are the most common cases when this is necessary:
- You have broken the binary compatibility: in this case you should create another EXE file with all the new classes, methods, interfaces, etc., compile it once and use it as the new reference. In this case, however, the new file should have a different executable name, so you don’t really overwrite the old one.
- You have delivered a new version of the component to your customers. In this case you copy the newest EXE or DLL over the file used for binary compatibility reference, and continue to develop the component.
- You decide that you don’t want or need to support older clients any longer. In this case you manually set binary compatibility to None (so that VB generates a new set of CLSIDs and discard all the IDs from previous, intermediate versions), compile to an executable file, and then reinforce binary compatibility using this latest file as the reference executable.