Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


This is an example of a COM upgrade.  In this case we want to upgrade SysInfoLib.SysInfo.ScrollBarSize to System.Windows.Forms.SystemInformation.VerticalScrollBarWidth.


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:


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.


Code Block
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.


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:


Code Block
<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