Visual Basic Concepts

Versioning Issues for Controls

When you create a new version of a control, there are several areas of backward compatibility you must address:

• Your controls interface; that is, its properties, methods, and events.

• UserControl properties that affect control behavior.

• Whether property values are saved and retrieved.

• Procedure attribute settings.

Interface Compatibility

You can add new properties, methods, and events without breaking applications compiled using earlier versions of your control component. However, you cannot remove members from the interface, or change the arguments of members.

You can use Visual Basic's Version Compatibility feature to avoid creating incompatible interfaces. On the Component tab of the Project Properties dialog box, click Binary Compatibility in the Version Compatibility box. This enables a text box in which you can enter the path and file name of the previous version of your component.

The default value in this text box is the last location where you built the component. If you are going to continue using that location to build the new version of your control component, it's a good idea to place a copy of your previous version in another location, and then enter that location in the text box.

For More Information   Interface compatibility and the use of the Version Compatible Component box are discussed in "Version Compatibility," in "General Principles of Component Design."

UserControl Properties

Be careful when changing properties of the UserControl object, such as ControlContainer. If a previous version of your control had this property set to True, so that developers could use the control to contain other controls, and you change the property to False in a subsequent version, existing applications may no longer work correctly if the new version is installed on the same computer.

Saving and Retrieving Property Values

You may retain a property for backward compatibility, but stop mentioning it in your Help file, and mark it as Hidden using the Procedure Attributes dialog box.

You can stop saving the value of such obsolete properties in the WriteProperties event, but you should continue to load their values in the ReadProperties event. If you stop loading a property value, you will break any previously compiled application that used the property.

Procedure Attribute Settings

Changing attributes of a procedure may break applications that were compiled using previous versions of your control. For example, it you use the Procedure Attributes dialog to change the default property or method of a control, code that relied on the default will no longer work.

Compiled Applications

In some cases, changing properties in a new version of your control will have no effect on applications that were compiled with an earlier version. This is because some services are provided by the container and are set when the application is compiled. Even though the settings have been changed in the new version of your control, the container won't initialize these properties.

Properties that are provided by the container may include Alignable, CanGetFocus, ControlContainer, DefaultCancel, ForwardFocus, Public, ToolboxBitmap, and Visible. If you change any of these properties in a later version of your control, you will need to recompile any applications that use the control.