How does Custom Maps work?
Custom Maps is a feature of the VBUC that allows end users to describe simple transformation rules to be applied over the VB6.0 source code during all the stages of the automated software migration. These transformations complement the VBUC core functionality to achieve very specific requirements. This document shows how to upgrade Third Party Controls into their .NET counter parts.
Note: The complete Custom Maps technical specification is the following url: https://www.mobilize.net/vbtonet/customization-and-extensibility/extensibility
Custom Maps extensibility can be used to upgrade types (classes, forms, modules, controls, enumerations, etc) and members (properties, subs, functions, fields, etc) of binary controls into their .NET replacements. Declarations and references are upgraded both to assure the desired functionality.
The most common uses of this feature are:
- Deleting a Type in the resulting code: For instance, if a module is no longer needed, the Custom Maps functionality can be used to delete all the references to this type and its declaration.
- Changing an existing type and its references to a different type: This can be used to transform a type definition like a class or a module to different definition. For example, the user can define a transformation for Class1 to become Class2.
- Changing type members and their references to custom equivalents: change member invocations and their definitions to particular .NET counterparts including user defined and/or built-in components.
Upgrading unsupported Third Party Controls to their .NET equivalents require extensive use of the second option.
When the legacy and .NET types expose the same members, the work required to perform the transformation is minimal since all the references to the new type will be the same as they were in the original source code. In other words, if a given legacy control exposes properties, subs and functions with the same names as the .NET version, it is only necessary to define a transformation for the type and most members will be automatically supported.
On the other hand, if the source and target control use different names for their members, the manual effort required after the migration may be significant. This is a scenario when using Custom Maps, along with Helper Classes, can reduce the effort required by automating most of the translation.
It is necessary to keep in mind that the transformations defined in the Custom Maps editor are interpreted prior to the automated migration stage; however the resulting structures will be printed directly as .NET code. This means, that the original names used in the transformation are valid VB6 type/member names and the new reference names may be complex, fully qualified .NET names (including namespaces).
The next section shows, using an example, how to add Custom Maps to the VBUC for specific Third Party Controls, and how to get functional equivalence on the resulting source code with minimal manual effort after the migration.