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:
COM Library.Class | .NET Namespace.Class |
MSComctlLib.ToolBar | System.Windows.Forms.Toolstrip |
MSComctlLib.TreeView | System.Windows.Forms.Treeview |
MSComctlLib.ListView | System.Windows.Forms.Listview |
MSComctlLib.StatusBar | System.Windows.Forms.StatusStrip |
MSComctlLib.ImageList | System.Windows.Forms.ImageList |
Scripting | System.IO |
RichTextLib | System.Windows.Forms.RichTextBox |
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:
COM Library.Class | .NET Namespace.Class |
MSComctlLib.Button (on a ToolBar) | ToolstripItem|ToolStripButton|ToolStripSeparator |
MSComctlLib.Node (in a TreeView) | TreeNode |
MSComctlLib.ListItem (in a ListView) | ListViewItem |
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.
FileExplorer depends on the following external COM components that must be installed on your workstation to perform the migration successfully:
File | Description |
MSCOMCTL.OCX | Microsoft Windows Common Controls 6.0 (Statusbar, ToolBar, Treeview, ListView, ImageList) |
scrrun.dll | Microsoft Scripting Runtime |
richtx32.ocx | Microsoft Rich Textbox Control 6.0 |
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 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.
There are two versions of the FileExplorer upgrade sample:
Task | Description |
FileExplorer_csh.gmproj | FileExplorer migrated to C#.NET, all externals migrated to .NET |
FileExplorer_vbn.gmproj | FileExplorer migrated to VB.NET, all externals migrated to .NET |
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.