Visual Basic Concepts

When Should I Use Version Compatibility?

See Also

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:

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:

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.