Overview

Left: VB6; Right: C#

FileExplorer is a desktop application that implements a simple Windows file explorer using common ActiveX controls. This demo will demonstrate how to implement more advanced migration rules needed to replace ActiveX controls with .NET control classes.

The FileExplorer is organized into one VB6 project

   FileExplorer.vbp -- an EXE that provides a user interface

The FileExplorer source is comprised of about 600 lines of code (LOC).

   FileExplorer.vbp
   frmExploreLite.frm
   frmExploreLite.frx (contains the ImageLists' Images)

FileExplorer uses a set of controls from mscomctl.ocx (aka "Microsoft Windows Common Controls 6.0). The techniques used to migrate this library can be applied to other third-party (and in-house) OCXs as well.

The ActiveX control classes and their .NET replacements are listed below:

Note that the table above is just the "top-level" controls that are used in FileExplorer. Every one of these controls contains a collection of sub-controls. These collections and sub-controls must also be migrated. A sample of these sub-controls and their .NET replacements are listed below:

In some cases there are even sub-sub-controls; for example, a toolbar contains a collection of Buttons, and a ToolBar button can contain a collection of ButtonMenus. This three-levels-deep migration is also handled in this sample.

A pivot table of data produced by the Source GUI Scan report for FileExplorer is displayed below.

COM Dependencies

FileExplorer depends on the following external COM components that must be installed on your workstation to perform the migration successfully:

Directing COM Replacement 

A RefactorLibrary is a set of translation rules that tell gmStudio how to rewrite specific aspects of your code. For example, the RefactorLibrary file GM.mscomctl.ocx.xml tells the translator how to migrate VB6 code that uses the classes, enums, methods, properties and events of mscomctl.ocx into .NET code that uses winforms controls.

GM.mscomctl.ocx.xml is a hand-modified Interface Description File (IDF) that was initially generated by gmStudio from the COM binary file (MSCOMCTL.OCX). The default, automatically generated, version of the file directs the tool to generate and use a stub framework for the MSCOMCTL controls, or to use the RCW interop assembly. The modified version used for this sample directs the tool to upgrade MSCOMCTL controls to System.Windows.Forms replacements. The top part of the modified IDF contains contains rules describing how to rewrite logic that uses the COM API. The bottom part of the modified IDF provides additional declarations and also references a migration DLL and two gmsl scripts:

<Refactor id="[GM.mscomctl.ocx]" dllName="MscomctlMigration.dll" event="mscomctl">

... delcarative rules directing transformation of VB6 forms/control property bag declarations to .NET designer code ...

<!--
********************************************************** 
* Procedural Transformation Rules
********************************************************** 
-->
<gmSL NameSpace="mscomctl" class="MigCode" Source="gm.mscomctl.gmsl" />
<gmSL NameSpace="mscomctl" class="Transform" Source="" />
</Refactor>

• The migration DLL, MscomctlMigration.dll, includes parsing logic to deal with the complex hierarchical declarations used by the MSCOMCTL controls in VB6
• The first gmslScript, gm.mscomctl.gmsl, implements simple gmsl routines to assist with authoring StatusBar panels in designer files.
• The second gmsl Script, gm.mscomctltransform.gmsl, includes advanced gmsl routines that perform low level analysis and transformation of designer and logic for references to MSCOMCTL API

The custom IDF and the gmSL files are located in proj\usr. The migration DLL is in the gmStudio installation directory.

Note that the managed migration of FileExplorer also loads two other RefactorLibraries: one to upgrade Scripting to System.IO and one to upgrade RichTextLib.RichTextBox to Winforms.RichTextBox.  The commands used to load these custom migrations are shown below:

   <Registry type="libname" source="richtx32.ocx" target="GM.richtx32.ocx" />
   <Registry type="libname" source="scrrun.dll"   target="GM.scrrun.dll" />
   <Registry type="libname" source="mscomctl.ocx" target="GM.mscomctl.ocx" />

For additional details on custom COM replacements see this article.

Deployment

There are two versions of the FileExplorer upgrade sample:  

The FileExplorer migrations all work on the FileExplorer source and save outputs in the FileExplorer workspace. 

All the FileExplorer migration projects have the following deployment settings:

      ProjectFolder = FileExplorer\proj_[lang] (where lang is csh or vbn for C# or VB.NET respectively)
      DeployFolder  = %ProjFolder%\deploy

Log files showing all migration steps are created in the workspace\log folders.

%ProjFolder%\log

The .NET project files are deployed to the following folders:

%ProjFolder%\deploy\FileExplorer.