The Problem and Opportunity of COM Migration

gmStudio is not simply a VB6/ASP migration tool; it is a COM migration tool as well. This page introduces the COM migration capabilities of gmStudio.

One of the major benefits of the .NET platform is the availability of an extensive collections of pre-built, well-integrated frameworks from Microsoft and other software vendors. These frameworks organize classes that provide many of the services that were previously handled in VB6 and ASP by COM type libraries and controls. Most migration teams will require, or at least desire, to re-engineer code that used COM with code that uses .NET classes instead.

Entry-Point APIs

.NET framework classes also can be used to replace calls to entry-point APIs (i.e., functions declared in VB6 code using the Declare statement).
The following discussion is presented in terms of COM replacement but similar techniques can be used to help you migrate calls to entry-point APIs.

COM Information

Real-world VB6/ASP applications make extensive use of external COM libraries and controls (DLLs, OCXs, OleEXEs, TLBs, OLBs, etc.). These COM components contain detailed information about the classes, interfaces, enums, methods, properties and events of external types that may be used by a legacy application. gmBasic stores COM information in Interface Description Files (IDFs): XML documents generated from the COM binaries or from VBPs that build into COM Components. The gmBasic translation engine uses IDFs to resolve ambiguities, such as undeclared, untyped, or weakly typed variables, naming conflicts, and missing optional arguments. The translator will look for and use information about all COM files explicitly referenced from the VBPs, files imported by the explicit references, and also files containing classes instantiated through their ProgIDs (e.g., by CreateObject).

During the preparation process, gmStudio will analyze the source code in a Migration Project and create an inventory of the COM libraries that it references. It then inspects each library and generates an Interface Description File (IDF) that gmBasic can use during the translation process. The details of this process are described in the Preparation section of this guide.

The COM components on which your migration project depends can be classified as being either Local or External:

A Local component is based on a migration unit (VBP) in the migration project and is defined by its source code files.
An External component is based on a binary reference to a COM type library file (TLB, DLL, OCX, etc.) that is not part of the legacy source code

gmStudio attempts to detect your COM dependencies in two different ways:

For VB6 migration units, gmStudio identifies COM dependencies based on the Reference and Object statements in the VBP file.
For ASP codes, gmStudio identifies COM dependencies based on the ProgIds in CreateObject statements and the libraries named in TypeLib directives

In both cases, gmStudio will inspect the referenced type libraries and also identify other type libraries they import.

gmStudio allows you to attach additional metadata to each COM library and it uses this to facilitate replacement of COM components with .NET components. The details of this process are described in the Refactoring section of this guide.

COM Replacement Strategies

The Stub Framework Strategy

A Stub Migration is one in which all code referenced by the migration units is converted to the target language and all COM externals referenced by the migration units are converted to stub files or assemblies. The prototype assemblies declare only those classes, methods, properties, etc., that were explicitly referenced by the source codebase.

The Prototype is informally referred to as the Stub Strategy because external components are replaced with stub classes.

The Interop Strategy

An Interop Migration is one in which all code referenced by the migration units is converted to the target language and all COM externals referenced by the migration units are converted to COM interop assemblies, i.e., .NET assemblies that are imported from existing COM components. These assemblies are "wrappers" to existing COM components and may be produced as follows:

By compiling "reference-only" projects with MSBuild (our preferred method)
By adding a reference to an existing COM component with Visual Studio
By using the tlbimp.exe and aximp.exe utilities. Here, tlbimp (Type Library Importer) converts the type definitions found within a COM type library into equivalent definitions in a common language runtime assembly, while aximp(ActiveX Control Importer) converts type definitions in a COM type library for an ActiveX control into a Windows Forms control wrapper.

Custom Migration Strategy

A Custom Migration is one in which all code referenced by the migration units is converted to the target language and all COM externals referenced by the migration units are converted to .NET assemblies of your choosing -- typically putting in managed components that you buy, build, or borrow (from open source or from the .NET Framework distribution).

A custom migration is implemented using various translation settings in your translation scripts and special configuration files called RefactorLibraries that tell the translator how to replace a COM type with a .NET type. See the Custom COM Replacement section for details. Also review the Samples pages for different examples of how COM replacements can be done.

Browser not supported