This is an example of a COM upgrade. In this case we want to upgrade SysInfoLib.SysInfo.ScrollBarSize to System.Windows.Forms.SystemInformation.VerticalScrollBarWidth.
Suppose your VB6 has this:
And suppose the desired translation should use System.Windows.Forms.SystemInformation.VerticalScrollBarWidth instead.
We wish to change a control instance property declared in a COM interface description file (IDF) to a static readonly property declared in a .NET framework class.
We want the migration to simplify how the application gets ScrollBarSize information. This will require several steps:
1) Remove the SysInfo library reference form the csproj file.
2) Remove all references to control class instances.
3) Replace ScrollBarSize property references with System.Windows.Forms.SystemInformation.VerticalScrollBarWidth
4) Avoid unnecessary casts and numeric conversions.
The following sections describe the step by step process to implement the migration.
The recommended way to migrate a COM API is to use a RefactorLibrary file. A RefactorLibrary is a set of migration rules that direct how the translator interprets and rewrites code relating to a COM API. Here is the stub RefactorLibrary file to get us started:
The translator can load RefactorLibraries automatically based on their name (mig.SysInfo.ocx.xml) or explicitly using a registry-migfile command. I prefer the explicit approach as it provides more more control and better documentation. The recommended convention for a RefactorLibrary file name is libfile.description.Refactor.xml. In this case, the file name will be named SysInfo.ocx.WinForms.Refactor.xml and its location will be in the proj\usr folder.
The following command tells the translator to load the RefactorLibrary whenever it detects a translation using SysInfo.ocx.
This registry command must be in effect before the SysInfo.ocx reference is detected by the translation process. Typically this will be done by placing it in your translation script before the <Compile> command.
References to SysInfo.ocx cause gmStudio to load the SysInfo.ocx.xml interface description. If there is a MigFile registered, then gmStudio will also load the RefactorLibrary and modify the SysInfo API description information. Here is an excerpt from the translation log:
The migration details are specified by adding rules to the RefactorLibrary.
Rule 1) The location="DoNotDeclace" and libType="Internal" rules suppress the COM API reference in the .NET project file. The migName may be modified to simplify removing the Control from the designer code later.
Rule 2) The role="define" with a migName tells the tool to treat instances of SysInfo declared in the form property bag as simple declarations. This suppresses adding the instances to the form's Control collection in Designer code.
Rule 3) This tells the tool to migrate references to property ScrollBarSize as System.Windows.Forms.SystemInformation.VerticalScrollBarWidth:
There are three parts to this Rule 3 and all of the attributes of the migrate command are needed to make this transformation precisely.
1) change "ScrollBarSize" to "System.Windows.Forms.SystemInformation.VerticalScrollBarWidth" (migPattern = "...")
2) remove "SysInfo1." (nPram='1' and refType='method')
3) change the type from Single to Integer (type="Integer")
Rule 4) A netControl migClass is used to specify the properties to author fro initializing each control instance in Designer code. An empty migClass suppresses this authoring process.
With the above rules, the translation is nearly complete. However there is still a problem:
Recall, we removed the library reference so this namespace is no longer available. These declarations are no longer needed and they must be removed. This can be done using and Author/Fix:
A migName (e.g. migName="Remove.SysInfoLib") can make this edit more precise by giving SysInfoLib a unique name in the translations
The SysInfoLib.SysInfo.ScrollBarSize migration has several moving parts, and the recommended approach is to organize them with a ScriptRules file:
These two files can be applied to your translation with a ScriptRule command in the translation script:
The example above is know as COM replacement and it involves reworking the application code. An alternative COM upgrade strategy is Stub Implementation. In this approach, the upgrade team implements the interface defined by the COM Stub Framework files generated for the COM API based on usage in the application. For example, the stub file generated for this discussion looks like this:
Notice that the default stub file is generated to allow a build in the early stages of a project before you have settled the upgrade details for your COM APIs. Notices that the default stubs will throw a NotImplemented exception – unless you are just looking at the code in the forms VS Designer.
With the stub implementation strategy, the upgrade team can can simply implement the body of the stub with code providing the expected service. In this case, a reasonable implementation is very simple:
The edit can may be done with a Fix@FileFilter command at the end of the GlobalStubs script:
In this example, the stub implementation is much easier than the COM replacement. In many cases, stub implementation will provide time savings during the project, but it may have a higher cost of ownership if the resulting application code does not follow accepted coding standards. The decision for choosing a COM upgrade strategy should be handled on a case by case basis.