Using Standard Migrations

No migration can expect to use all or even most of the original COM components that were used by VB6, and no serious migration can be considered complete before all COM components have been replaced by native .NET code. Finally, since these migrations must be upgraded as they are performed, no two migration teams are likely to agree on the best upgrade path to be taken. The default migrations performed by gmBasic are generic and designed to be compilable even in situations where the target code is not fully mature. Their intent is not to produce final functionally equivalent .NET code, but rather to provide a structured, well-formed starting point.

The Migration.dll dynamic link library distributed with gmBasic can be used to extensively modify the migrations performed. It is primarily focused on collections, but will soon be expanded to deal with other frequently used COM components. The actual specifications of the modifications are placed in an XML script file which is stored at the specified target location of the migration project. Its full name is %targetLocation%\Migration.%sysId%.xml. The initial record for this file must be <Migration> and it must end with </Migration>. Between those two tags are the various declarative specification commands.

In addition to the presence of the Migration specification file, the following statement

must also be included in the translation script.

Code, such as that in the Migration.dll, to be made available to the gmBasic tool set is executed by the tool when certain events occur. A key event is the FinishAnalyser event that is triggered when the underlying code has been completed, but before it is passed to the author for surface-form formulation.

The Collections Command

The Collections command supplies the specifications needed to transform VBA.Collection and Scripting.Dictionary into strong collection classes. The two classes have separate specification subcommands.

The StrongCollections Subcommand

The goal of the StrongCollections subcommand is to transform references to the weakly typed VB6.Collection class into the strongly typed .NET List<T> or .NET Dictionary<Key,TValue> class. This transformation is implemented within the FinishAnalyser event. It begins with symbol table scan and then requires a series of code scans. Simply stated the command takes original VB6 code like

into target .NET code like

Of course, there are many other environments in which collections are used, such as for-loops and enumerators that have to be dealt with as well.

To keep this discussion simple, the assumption is made that the target classes are List and Dictionary . In fact, the migration team might well select other target classes. As will be seen below the StrongCollections command gives the user full control over this selection.

The first step in the StrongCollections transformation occurs during the initial pass through the symbol table. It simply involves storing the root offsets of all symbols that are instances of the VBA.Collection class in a simple list, so that they can be easily identified via later steps.

Once all of the collections are known, the second step is the determine the type of the collection values and, if relevant, the type of the collection keys. This information can only be obtained from the adds being made to the collection. The second step, then, scans all of the operation code to find calls to the Add methods of the collections. The arguments of these calls are then examined to determine their types. This type information is then included with the initial root offset information saved in the first step.

Once the type information about each collection is known, the third step is to create individual collection classes for the different type combinations and to associate with them the target names and surface patterns needed for the new classes. The actual operation code patterns are known because in the source all are derived from the VB6.Collection class, but the target classes and the target methods are dependent upon the goals of the migration. It is here that the content of the StrongCollections command becomes important. The command itself has no attributes and it has associated with it two subcommands -- ItemOnly and KeyItem. The first describes the migration of collections that have adds without keys and the second with keys. The overall command is as follows then

With each of those subcommands three pattern strings must be specified -- NetName, ForEach and ForVariant. The NetName string is the pattern string to be used to form the name of the class. The ForEach string is the surface-form pattern string to be used when the IFS.ForEach operation is encountered for the collection. The default surface form is

The ForVariant string is the surface-form pattern string to be used when collection type is variant. The ItemOnly entries that can be used with this example are

In these patterns the notation $1d refers to the type of the items in the collection. This string is supplied from the type information gathered for the collection. The %(n)d notations are the actual arguments to the IFS.ForEach operation in the target code. The use of the < and > are toxic to the XML syntax; therefore, these relatively complicated strings require the CDATA notation and must all be written on a single line.

The KeyItem entries are similar except that they require two type strings.

Here $1d is still the item type string; while $2d is the key type string.

Once the new collection classes have been established, the fourth step is to do a final operation code scan to replace references to the VB6.Collection components with the components defined in the previous step.

The StrongDictionaries Subcommand

The goal of the StrongDictionaries subcommand is to transform references to the weakly typed Scripting.Dictionary class into the strongly typed .NET HashSet<T> or .NET Dictionary<Key,TValue> class. This transformation is implemented within the FinishAnalyser event. It begins with symbol table scan and then requires a series of code scans. The Scripting.Dictionary is described in the interface description file scrrun.dll.xml This transformation assumes that the translation script used a simplified version of the this file that removed the unneeded ByRef parameters from the methods. This allowed the tool to generate simpler code patterns. In particular the class interface IDictionary must be described as shown here.

Simply stated this transformation takes original VB6 code like

into target .NET code like

Of course, there are many other environments in which dictionaries are used, such as for-loops and enumerators that have to be dealt with as well.

To keep this discussion simple, the assumption is made that the target classes are HashSet and Dictionary . In fact, the migration team might well select other target classes. As will be seen below the StrongDictionaries command gives the user full control over this selection.

The first step in the StrongDictionaries transformation occurs during the initial pass through the symbol table. It simply involves storing the root offsets of all symbols that are instances or the Scripting.Dictionary class in a simple list, so that they can be easily identified via later steps.

Once all of the dictionary collections are known, the second step is the determine the type of the dictionary values and, if relevant, the type of the dictionary keys. In addition, it is fairly common for dictionaries to be used to store collections. If this is the case for any of the dictionaries, then the reference to the collection class is needed as well. This information can only be obtained from the adds being made to the dictionary. The second step, then, scans all of the operation code to find calls to the Add methods of the dictionaries. The arguments of these calls are then examined to determine their types. This type information is then included with the initial root offset information saved in the first step.

Once the type information about each dictionary is known, the third step is to create individual dictionary classes for the different type combinations and to associate with them the target names and surface patterns needed for the new classes. The actual operation code patterns are known because in the source all are derived from the Scripting.Dictionary class, but the target classes and the target methods are dependent upon the goals of the migration. It is here that the content of the StrongDictionaries command becomes important. The command itself has no attributes and it has associated with it two subcommands -- ItemOnly and KeyItem. The first describes the migration of dictionaries that have adds without keys and the second with keys. The overall command is as follows then

With each of those subcommands nine pattern strings must be specified -- NetName, ForEach, ForDecl, ForVariant, VarDecl, Exists, RemoveAll, Keys, and CompareMode. The NetName string is the pattern string to be used to form the name of the class. It is here that the specification of the target class is actually made. The ItemOnly entries that can be used with this example are

In these patterns the notation $1d refers to the type of the items in the dictionary. This string is supplied from the type information gathered for the dictionary. The %(n)d notations are the actual arguments to the various operations in the target code. The use of the < and > are toxic to the XML syntax; therefore, these relatively complicated strings require the CDATA notation and must all be written on a single line.

The KeyItem entries are similar except that they require two type strings.

Here $1d is still the item type string; while $2d is the key type string.

There are four different patterns that have to be associated with For Loops -- ForEach, ForDecl, ForVariant, and VarDecl. There are two typically different operation patterns associated with these loops and the migration of dictionaries that still have variant types is different from those with know types. The two operation patterns -- simple and complex are as follows.

The Keys string is used to replace references the dictionary Keys method. There are two operation contexts

The Exists string is used to replace references to the dictionary Exists method. The operation context is simply

The RemoveAll string is used to replace references to the dictionary RemoveAll method. The operation context is simply

The CompareMode string is used to replace assignments to the dictionary CompareMode property. The operation context is this

Once the new dictionary classes have been established, the fourth step is to do a final operation code scan to replace references to the Scripting.Dictionary components with the components defined in the previous step.

The NotUpgraded Subcommand

Both the StrongCollections and StrongDictionaries migrations depend upon the presence of Add method calls to determine the item and key types for the individual collections. If such method calls can not be found for a given collection or dictionary then it is not upgraded. The NotUpgraded subcommand supplies the format of a message to be displayed and triggers a search for components that have not been upgraded. When there are such present in a given code project, messages are sent to the log file. The command itself is a singleton content only command. It might be as follows.

The $1d substring is the type name of the component that was not upgraded and the $2d substring is the fully qualified identifier of that component. A sample output would be

Note that there are scripting commands CollectionAdd and MigrationAdd available to supply the missing information for particular code projects.

Scripting Commands

The migrations of particular components within particular source code projects do not always succeed, because the information needed to perform them is either not available of not in the expected form. The tool supports an ExecuteCommand event which is triggered whenever the tool encounters a script command at the primary level of a command script that it does not recognize. This event can be used to supply additional information to the migrations of particular code projects within the translation scripts for those projects.

The DictionaryAdd Scripting Command

The DictionaryAdd scripting command supports the Collections.StrongDictionaries migration. That migration depends upon finding calls to this method in the code.

The key type is derived from the actual type of the Key argument and if the Item argument is specified then the item type is derived from it; else it is unspecified. It is these two types that define the type of the host dictionary.

The DictionaryAdd script command has three attributes as follows:

If the identifier cannot be located, then the command is simply ignored. As an example assume that a translation script whose Collections specification contained a NotUpgraded subcommand, sent this message to the log

then the following command added to the translation script

would allow that component to be upgraded and would then cause changes like the following

Note that the actual DictionaryAdd commands must follow the Compile and precede the Analyse statements.

The CollectionAdd Scripting Command

The CollectionAdd scripting command supports the Collections.StrongCollections migration. That migration depends upon finding calls to this method in the code.

The item type is derived from the actual type of the Item argument and if the Key argument is specified then the key type is derived from it; else it is unspecified. It is these two types that define the type of the host collection.

The CollectionAdd script command has three attributes as follows:

If the identifier cannot be located, then the command is simply ignored. Note that the actual CollectionAdd commands must follow the Compile and precede the Analyse statements.