The Dec-2019 Release introduces a change in how some of the samples do COM API upgrades.

In prior releases, the deep migration work in the samples was partially done by DLLs developed using our C-based API (gmNI).  gmNI is not available for typical gmStudio users, and we wanted to rework the samples using our scripting language, gmSL. In addition, prior releases of the samples used custom COM Interface Description Files (IDFs). The custom IDFs are a convenient way to map a COM API to its .NET replacement, but they have some disadvantages from a tooling and maintainability perspective. In this release, we are going to use Refactor files to specify mapping COM APIs to their .NET replacement. In some cases, the mappings also include instructions to load gmSL scripts that perform deep migration.  The gmSL scripts that are distributed as text files with the tool and the samples and they may be extended and altered by users to meet their specific upgrade needs.  Note: the COM upgrade techniques demonstrated in the samples are general capabilities that may be applied to any COM API.   Additional examples of COM upgrade rules are published on the gmStudio Extensions page. 

ScanTool Sample Changes

The ScanTool sample includes several COM API replacements. One of these, Scrrun to System.IO, requires a number of deep migrations:

* Replacing FileSystemObject operations with calls to static functions
* Migrating TextStream instances and calls to one of several .NET Streams based on usage

In prior releases of the sample, the Scripting to System.IO migration was done using a custom IDF and an associated gmNI DLL: GM.scrrun.dll.xml and ScrrunMigration.dll. These migration assets were activated using the following commands in the translation script:

<Registry type="libname" source="scrrun.dll" target="GM.scrrun.dll" />
<Registry type="idfstatus" source="GM.scrrun.dll" target="migrate" />

and in the custom IDF:

<Refactor id="[GM.scrrun.dll]" dllName="ScrrunMigration.dll" event="scrrun" >

Starting with the Dec-2019 Release, we are doing the Scripting to System.IO migration with a COM Refactor IDF file and an associated gmSL script: Refactor.Scrrun.dll.xml and Transform.Scrrun.gmsl. These migration assets are activated using the following command in the translation script:

<Registry type="MigFile" source="scrrun.dll" target="Refactor.scrrun.dll" />

and in the custom Refactor IDF File:

<gmSL NameSpace="scrrun" class="Transform" Source="Transform.Scrrun.gmsl" />

This change has several advantages:

• The Refactor IDF file contains just the rules used to map Scripting to System.IO rather than intermingling the full description of the COM API with modifications to drive the migration. We believe this change makes it easier to see and modify the mappings. The Refactor IDF file works hand in hand with the standard generated IDF file making the transition from a standard to custom translation smoother.
• The dynamic migration is done using a gmSL script rather than a pre-compiled DLL. This makes the deep migrations open to extension and modification by gmStudio users. Note: gmSL works very precisely with low-level operations in the compiled model of the VB6/COM code. gmSL can automate very difficult transformations, but the problems and solutions are in the details.
  
  

The following files are used to direct the COM migrations for the ScanTool sample:

• Scrrun.Refactor.xml: COM API elements adjustments for scrrun.dll to System.IO and Specialized Collections.OrderedDictionary
• Scrrun.Transform.xml: Scrrun.Transform Class implementing transformations for various scrrun.dll API references
• Mscomctl.Refactor.xml: COM API mapping for Windows Common Controls to WinForms Controls
• Mscomctl.ServiceMethods.gmsl: MScomCtl.ServiceMethods class implementing service extensions that alter the processing done by the core tool at specific points in the upgrade process
• Mscomctl.MigCode.gmsl: MScomCtl.MigCode class implementing dynamic code generation logic for MScomctl API controls
• Mscomctl.Transform.gmsl: MScomCtl.Transform class implementing transformations for various Mscomctl API references

 Additional examples of these files and other COM upgrade rules are published on the gmStudio Extensions page. 

Other Samples

These changes also impact the FileExplorer, FMStocks, and WPFScanTool samples.

gmBasic: Upgrade Engine

gmBasic is a code transformation tool that reads, interprets, and rewrites VB6/ASP/COM systems to one of the .NET languages (C# or VB.NET). Based on feedback from our clients and migration projects in the field, we are continuously improving gmBasic so as to help users more easily produce cleaner and more correct results. Most recently this work included the general improvements needed to produce build-complete C# code for a 173K LOC statistical-process-control-reporting application and major improvements to migration rules conventions. This distribution, Version 31.00, includes several enhancements:

• Corrects fixed-size array declarations in VB.NET.
• Improves support for implementing COM API replacements using Migrate command files and gmSL Scripts
• Improves migration of Property.Let statements
• Improves migration of DisplayStyleConstants and DrawModeConstants
• Improves migration of local references to default properties

gmStudio: Upgrade Solution Development Environment

Powered by gmBasic, gmStudio is a development environment for analyzing code and developing custom VB6/ASP/COM to .NET upgrade solutions. We are continuously adding functionality to gmStudio and making it easier to use. This distribution includes several enhancements:

• Updates gmStudio with gmBasic V31.00
• Adds support for creating generic VB6 starter codes and gmStudio projects for testing specific translation scenarios
• Adds File/New menu as context menu to New toolbar button
• Adds option to display Upgrade Task fields with red/yellow/green color for ERROR/WARNING/SUCCESS status
• Adds COM IDL files as a Search Source
• Modifies Alternate Field Layout
• Improves highlighting Task List items
• Improves Search Results to allow sorting of numeric columns in natural numeric order
• Improves Visual Studio Solution File Project list to allow %UserFolder% variable in project path
• Improves performance of pre-processing large translation scripts
• Improves adding new tasks to a project
• Improves Translation Log Reports
• Improves organization of File and Help Menus
• Improves appearance of Fonts in high DPI environments

gmslAPI: a .NET API for Developing Advanced Upgrade Solutions

Powered by gmBasic, gmslAPI is a .NET API for automating our upgrade engine and accessing the semantic models produced by our unique linguistic compilation technology. gmslAPI also includes classes for managing complex upgrade rules and integrating with gmStudio. This API was updated to reflect the latest product improvements and conventions.

Sample Upgrade Rules

gmStudio ships with a collection of sample upgrade rules that can be used to add custom features to your upgrade solution. These XML documents and gmSL scripts are distributed as source that you may modify to fit your unique requirements. The sample rules were updated to reflect the latest product improvements and conventions. See also additions and changes in gmStudio Extensions Repository.  This distribution includes several script enhancements:

• Scrrun.Refactor.xml – Adds COM API mapping for scrrun.dll to System.IO and Specialized Collections.OrderedDictionry
• Scrrun.Transform.xml – Adds Scrrun.Transform Class implementing transformations for various scrrun.dll API references
• Mscomctl.Refactor.xml – Adds COM API mapping for Windows Common Controls to WinForms Controls
• Mscomctl.Transform.gmsl – Adds MScomCtl.Transform class implementing transformations for various Mscomctl API references
• Mscomctl.MigCode.gmsl -- Adds MScomCtl.MigCode class implementing dynamic code generation logic for MScomctl API controls
• Mscomctl.ServiceMethods.gmsl – Adds MScomCtl.ServiceMethods class implementing service extensions that alter the processing done by the core tool at specific points in the upgrade process
• UserCmd.std.cmd – Improves Testing logic

Sample Upgrade Solutions

Great Migrations publishes a number of sample VB6/ASP upgrade solutions to illustrate the capabilities of gmStudio. The sample upgrade solutions were updated to reflect the latest product improvements and conventions.

• FileExplorer – Adds ListView Columns Sorting example to this sample
• FileExplorer – Adds ListView Item Selection example to this sample
• Batch Script – Adds logic to run Analytics Definitions Reports to the sample batch script
• Changes to using Refactor IDF files rather than Custom IDF files for deep migrations
• Changes to using gmSL scripts rather than gmNI DLLs for deep migrations
  Learn more on this Blog Post.