Overview

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:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SysInfo control on a Form
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>1301    Begin SysInfoLib.SysInfo SysInfo1 
 1302       Left            =   13920
 1303       Top             =   0
 1304       _ExtentX        =   1005
 1305       _ExtentY        =   1005
 1306       _Version        =   393216
 1307    End
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Logic to use SysInfo control to get ScrollBarSizwe
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 8014 Private Function XSizePartsUpDown()
...
>8020         .Width = SysInfo1.ScrollBarSize
...
 8024     End With
 8025 End Function

...

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.

Here is the property in the COM IDF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
proj\idf\FromIdl\SYSINFO.OCX.xml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   17    <class id="ISysInfo" parent="IDispatch">
...
>  26       <property id="ScrollBarSize" type="Single" status="Out"/>
...
   32    </class>

And, here is the replacement property in WinForms:

      //
      // Summary:
      //     Gets the default width, in pixels, of the vertical scroll bar.
      //
      // Returns:
      //     The default width, in pixels, of the vertical scroll bar.
      public static int VerticalScrollBarWidth { get; }

...

The following sections describe the step by step process to implement the migration.

Create a COM RefactorLibrary file

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:

   <RefactorLibrary>
   <Refactor id="[SYSINFO.OCX]">
   ... rules will go here ...
   </Refactor>
   </RefactorLibrary>

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.

Activate the RefactorLibrary.

The following command tells the translator to load the RefactorLibrary whenever it detects a translation using SysInfo.ocx.

...

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:

Loading reference:[SYSINFO.OCX] ...\proj\idf\FromIdl\SYSINFO.OCX.xml
Loading reference:[SYSINFO.OCX.WinForms.Refactor] ...\proj\usr\SYSINFO.OCX.WinForms.Refactor.xml

Add migration rules to the RefactorLibrary

The migration details are specified by adding rules to the RefactorLibrary.

proj\usr\SYSINFO.OCX.WinForms.Refactor.xml

<Refactor id="[SYSINFO.OCX]">
   
Rule 1)   <Migrate location="DoNotDeclace" libType="Internal" /> 

Rule 2)   <Migrate id="SysInfo" role="define" migName="SysInfo" />
   
Rule 3)   <Migrate id="ISysInfo.ScrollBarSize" type="Integer" refType="Method" migPattern="System.Windows.Forms.SystemInformation.VerticalScrollBarWidth" nPram="1"/>
      
Rule 4)   <migClass id="NetControl.SysInfo" migName="Remove.SysInfo" parent="SysInfo">
              <!-- Suppress designer code -->
          </migClass>
</Refactor>

...

Rule 3) This tells the tool to migrate references to property ScrollBarSize as System.Windows.Forms.SystemInformation.VerticalScrollBarWidth:

   NOT THAT: .Width = SysInfo1.ScrollBarSize
   BUT THIS: .Width = System.Windows.Forms.SystemInformation.VerticalScrollBarWidth   

...

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.

Clean Up

With the above rules, the translation is nearly complete. However there is still a problem:

...

A migName (e.g. migName="Remove.SysInfoLib") can make this edit more precise by giving SysInfoLib a unique name in the translations

Consolidating the migration rules with a ScriptRules file

The SysInfoLib.SysInfo.ScrollBarSize migration has several moving parts, and the recommended approach is to organize them with a ScriptRules file:

...

<gmBasic>
...
<ScriptRule id="SYSINFO.OCX" FileName="..\usr\SysInfo.ocx.Rules.xml" />

<Compile Project="%SrcPath%" Resx="%ResxFolder%"/>

...

Alternative Approach: Stub Implementation

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:

...

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.  

See also:

Custom COM Replacement