Share via

Visual Basic Concepts

  • Article

When Should I Use Version Compatibility?

Visual Basic provides two mechanisms for maintaining backward compatibility while enhancing software components — the Version Compatibility feature and the Implements feature.

Version Compatibility

Visual Basic’s Version Compatibility feature is a way of enhancing your components while maintaining backward compatibility with programs that were compiled using earlier versions. The Version Compatibility box, located on the Component tab of the Project Properties dialog box, contains three options:

  • No Compatibility: Each time you compile the component, new type library information is generated, including new class IDs and new interface IDs. There is no relation between versions of a component, and programs compiled to use one version cannot use subsequent versions.

  • Project Compatibility: Each time you compile the component the type library identifier is kept, so that your test projects can maintain their references to the component project. All class IDs from the previous version are maintained; interface IDs are changed only for classes that are no longer binary-compatible with their earlier counterparts.

    Note   This is a change in Project Compatibility from Visual Basic 5.0, where all class IDs and interface IDs in the project changed if any one class was no longer binary-compatible.

    Important   For the purpose of releasing compatible versions of a component, Project Compatibility is the same as No Compatibility.

  • Binary Compatibility: When you compile the project, if any binary-incompatible changes are detected you will be presented with a warning dialog. If you choose to accept the warning, the component will retain the type library identifier and the class IDs. Interface IDs are changed only for classes that are no longer binary-compatible. This is the same behavior as Project Compatibility.

    If, however, you choose to ignore the warning, the component will also maintain the interface IDs. This option is only available when the compiler determines that the change was in the procedure ID or signature of a method.

    Caution   You should only choose the Ignore button if you are absolutely sure that the changes you have made won't break compatibility. If you aren't absolutely sure, take the safe alternative and choose the Accept button to allow the interface ID's to be changed.

    Important   The option to override the compiler's warning represents a change in behavior from Visual Basic 5.0. It is important that you fully understand the implications of incompatible changes before proceeding with this option.

    Note   When people talk about Version Compatibility, they’re usually referring to Binary Compatibility.

The appropriate use of these options is described below.

Using the Implements Statement for Compatibility

The Implements statement allows you to add multiple interfaces to class modules, as described in "Polymorphism, Interfaces, Type Libraries, and GUIDs" and "Providing Polymorphism by Implementing Interfaces" in "General Principles of Component Design," and in "Polymorphism" in "Programming with Objects," in the Visual Basic Programmer’s Guide.

Multiple interfaces allow your systems to evolve over time, without breaking existing components or requiring massive re-compiles, because a released interface is never changed. Instead, new functionality is added to a system by creating new interfaces.

This approach is much more in keeping with the design philosophy of the Component Object Model (COM), on which the ActiveX specification is based.

Note   The Binary Compatibility option of Version Compatibility is useful in conjunction with Implements and multiple interfaces, to prevent changes to the default interfaces of your classes.

When to Use Version Compatibility Options

If you decide to use the Version Compatibility feature, you may find the following rules helpful in determining when to use the different options:

Use No Compatibility to Make a Clean Break

When you begin working on a new version of an existing component, you may decide that the only way to make necessary enhancements is to break backward compatibility. In this case, set No Compatibility the first time you compile your project. This guarantees that you’ll start with a clean slate of identifiers, and that existing programs won’t mistakenly try to use the incompatible version.

Before compiling an existing project with No Compatibility, you must also:

  • Change the file name of your component, so that the incompatible version won’t over-write earlier versions on your users’ hard disks.

  • Change the Project Name on the General tab of the Project Properties dialog box, so that the incompatible component will have a different type library name. This ensures that the objects the component provides will have unique programmatic IDs.

These items are discussed in more detail in "Levels of Binary Version Compatibility."

After compiling once with No Compatibility, switch to Project Compatibility to simplify your development tasks.

Use Project Compatibility for New Development

Use the Project Compatibility setting when you’re developing the first version of a component. Project Compatibility preserves the type library identifier, so that you’re not continually setting references from your test projects to your component projects.

Using Project Compatibility also makes it easier to switch between the component project and the compiled component when you’re testing.

Project Compatibility is discussed in "Project Compatibility: Avoiding MISSING References."

Use Binary Compatibility for New Versions of Existing Components

Switch to Binary Compatibility mode when you begin work on the second version of any component, if you want applications compiled using the earlier version to continue to work using the new version.

Switching to Binary Compatibility is discussed in the related topic "Providing a Reference Point for Compatibility."

Don’t Mix Binary Compatibility and Multiple Interfaces

If you use multiple interfaces and the Implements statement to provide backward compatibility, don’t use Binary Compatibility to modify the abstract interfaces you’ve defined for use with Implements.

If you enhance any of the interfaces in a component, Visual Basic will change their interface IDs. The technique of evolving component software by adding interfaces depends on interface invariance. That is, an interface once defined is never changed — including the interface ID.

For More Information   See "Providing Polymorphism by Implementing Interfaces" in "General Principles of Component Design" for information about component software design using multiple interfaces. "Maintaining Binary Compatibility" describes the versioning system Visual Basic uses to prevent compatibility problems.