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