Getting Started with gmStudio

Installation

This page describes the gmStudio installation package and the requirements for running gmStudio.

Hardware Requirements

One of the first steps in any migration effort is to provision a development machine that will be used to perform migration work. This is typically one of the workstations already being used in maintaining and building the source codebase.

In terms of disk, CPU, and memory this machine should be sized appropriately for a .NET development workstation using Visual Studio — the bigger the better.

The methodology produces many outputs: logs, model files, reports, .NET codes and assemblies. Plan for about one gigabyte of disk space for these files.

As of December 2023, the gmStudio product package requires a 64bit Windows OS.

If you are maintaining an old 32-bit Windows machine just for VB6, you will have to install gmStudio elsewhere. In that situation, you should plan to track down the code and COM files referenced by your VB6 application and copy them to a more contemporary machine where you will use gmStudio. Ideally, you should install the VB6 IDE and the COM packages (trial editions are fine) needed by your application on the machine with gmStudio. There should be no problem with finding and copying VB6 code files (vbp, bas, cls, frm/frx, ctl/ctx, etc.) but COM files can be more difficult. Assuming you are able find the installers or files, you may still have COM APIs that are no longer compatible with current Windows.

If you cannot install a COM package, you should be able to get by with only a copy of copy of the binary files. It is usually possible to create COM Interface Description Files directly from binary files (dll, ocx, tlb, etc. ) even if the COM packages cannot be installed, but your mileage will vary. See this article and contact us if you need support with this.

BTW: With a little manipulation of INI files and exclusion of a few rarely used features, it is possible to install and use the VB6 IDE (albeit in compatability mode and as administrator) on Windows 10 and Windows 11. Time will tell if VB6 will also work for Windows 12. Here is one such article with additional information on how to install VB6 on new Windows.

Development Workstation Requirements

Required

Windows XP through Windows 10, Windows Server 2003-2016
.NET 4.0 or higher Framework SDK

Recommended

VB6 to validate/build VB6 codes
IIS to validate ASP sites
Visual Studio 2017 or higher (or other application associated with csproj/vbproj files).
Your choice of a programmer’s text editor; we use Notepad++ (default = notepad.exe, not recommended) Note: when running as Visual Studio Plugin, the VS editor will be used
Your choice of a file and directory comparison tool; we use BeyondCompare from Scooter Software
Your choice of tab-delimited file viewer (launched by associated application); we use Excel

Installed Files

gmStudio Product

gmStudio is installed by a Windows Installer setup file (gmStudioSetup.msi).

To install gmStudio, run the gmStudioSetup.msi file.

The following directories are created by the gmStudio installation process:

   [INSTALLDIR]: gmStudio application and default application configuration file
      |
      \---support: default translation config files
          |
          +---help: local redirect to (this documentation)
          +---metalang: default language description and transformation rules<br />          +---rules: Sample rules, templates, and scripts <br />          +---runtime: migration support assembly (use optional)
          +---settings: default gmStudio script templates
          \---tools: gmStudio system tools

gmStudio Samples

The gmStudio samples are available as zip files as described in this Samples section of the manual.

gmStudio Working Configuration

The first time you run gmStudio, it will create your gmStudio workspace and populate it with copies of the default configuration files.

By default the gmStudio workspace will be created in the [AppDataFolder] folder. The default on Windows is:

   C:\Documents and Settings\[current_user]\Application Data\

You may set the AppDataFolder on the User Config form to specify the location of AppDataFolder.

The following directories are created by the workspace setup process:

   [AppDataFolder]
      |
      \---GreatMigrations
          |
          +---workspace: will contain your migration workspaces and migration project files

Verifying the Install

The process described below does a direct, default migration of a small project (comprised of two VBPs); it can also be used to verify your installation.

When you load gmStudio for the first time, you will see the Wizard Form. Normally the application reloads the migration project from your last session, but if this is your very first session, the Main Form will be blank.

You can do a direct migration of a small project in two steps:

Select the VB6 projects to migrate:
- - a) Click [File/New Migration] from the main menu. This will open the [Migration Project Setup] form.
- - b) Enter a name for your migration project; the default is Upgrade1.
- - c) Use the [Select Migration Units] control to find and select VBPs.
- - - d) Click [Add] to add VBPs to the migration project
- - e) Click [Save & Exit] to return to the Main Form.

2. Run the migration process by clicking the [Upgrade] button on the Toolbar.

If you have successfully installed gmStudio, you will get a log file similar to the one shown below. The log shows the default migration steps for a two-VBP sample migration project:

Preparation
Translation
Deployment
Verification (by building the .NET code using MSBuild)

Starting Batch
Set Build Order
Setup Build Order
Compute Build Order
Apply Build Order
READY: See C:\GMS\samples\workspace\DemoScanTool\report\Interop2_csh-SrcOrder.txt
Author Interop Assemblies
Loading Interface Cache
Scanning References: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
Scanning References: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
Importing: stdole2.tlb
Importing: TLBINF32.DLL
Importing: scrrun.dll
Importing: ScanToolLib.dll
Importing: msxml4.dll
Importing: ComDlg32.OCX
Validating: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
LibRegd = SUCCESS
RefStat = READY
SrcSize = 1518
Validating: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
LibRegd = SUCCESS
RefStat = READY
SrcSize = 727
Syncing Project File
Validation Complete
Author Interface Descriptions
Loading Interface Cache
Scanning References: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
Scanning References: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
Generating Interface Description for: stdole2.tlb
Generating Interface Description for: TLBINF32.DLL
Generating Interface Description for: scrrun.dll
Generating Interface Description for: ScanToolLib.dll
Generating Interface Description for: msxml4.dll
Generating Interface Description for: ComDlg32.OCX
Updating Interface Cache
Validating: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
LibRegd = SUCCESS
RefStat = READY
SrcSize = 1518
Validating: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
LibRegd = SUCCESS
RefStat = READY
SrcSize = 727
Syncing Project File
Validation Complete
Reset Task Status
Reset: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
LastMsg = Reset
NetSize = -1
Run Translation
Translating C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
Basic Processor V9.80 (BETA.002) System Build(8/27/09 15:14:45)
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.bas
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPRefReporter.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsDirList.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPBinReporter.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsCOMReporter.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPModReporter.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPCntReporter.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPSrcReporter.cls
Processing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsScanControl.cls
Loading reference:<stdole2.tlb> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\stdole2.tlb.xml
Loading reference:<Mig.stdole2.tlb> C:\GMS\support\lang\Mig.stdole2.tlb.xml
Loading reference:<TLBINF32.DLL> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\TLBINF32.DLL.xml
Loading reference:<scrrun.dll> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\scrrun.dll.xml
Loading reference:<msxml4.dll> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\msxml4.dll.xml
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.bas
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPRefReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsDirList.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPBinReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsCOMReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPModReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPCntReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPSrcReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsScanControl.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.bas
Loading reference:<vb6control.dcl> C:\GMS\support\lang\vb6control.dcl.xml
Loading reference:<dao350.dll> C:\GMS\support\lang\dao350.dll.xml
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPRefReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsDirList.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPBinReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsCOMReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPModReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPCntReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsVBPSrcReporter.cls
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\clsScanControl.cls
LastMsg = TRANSLATED:2009-09-08 10:39:17
TrnStat = SUCCESS
NetSize = 2196
Deploy Translation
Deploying: C:\GMS\samples\workspace\DemoScanTool\log\Interop2_csh-ScanToolLib-iop2-csh.bnd
LastMsg = DEPLOYED:2009-09-08 10:39:17
Build Translation
Building: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\ScanToolLib.csproj
LastMsg = .NET BUILD COMPLETED: 2009-09-08 10:39:18
NetBlds = SUCCESS
Reset Task Status
Reset: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
LastMsg = Reset
NetSize = -1
Run Translation
Translating C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
Basic Processor V9.80 (BETA.002) System Build(8/27/09 15:14:45)
Processing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
Processing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanTool.frm
Processing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.bas
Loading reference:<stdole2.tlb> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\stdole2.tlb.xml
Loading reference:<Mig.stdole2.tlb> C:\GMS\support\lang\Mig.stdole2.tlb.xml
Loading reference:<scrrun.dll> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\scrrun.dll.xml
Loading reference:<ScanToolLib.dll> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\ScanToolLib.dll.xml
Loading reference:<TLBINF32.DLL> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\TLBINF32.DLL.xml
Loading reference:<msxml4.dll> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\msxml4.dll.xml
Loading reference:<ComDlg32.OCX> C:\GMS\samples\workspace\DemoScanTool\idf\FromIdl\ComDlg32.OCX.xml
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanTool.frm
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.bas
Loading reference:<shell32.dcl> C:\GMS\support\lang\shell32.dcl.xml
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanTool.frm
Loading reference:<vb6control.dcl> C:\GMS\support\lang\vb6control.dcl.xml
Loading reference:<dao350.dll> C:\GMS\support\lang\dao350.dll.xml
Reprocessing file: C:\GMS\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.bas
LastMsg = TRANSLATED:2009-09-08 10:39:18
TrnStat = SUCCESS
NetSize = 1689
Deploy Translation
Deploying: C:\GMS\samples\workspace\DemoScanTool\log\Interop2_csh-ScanToolUI-iop2-csh.bnd
LastMsg = DEPLOYED:2009-09-08 10:39:19
Build Translation
Building: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolUI_iop2_csh\ScanToolUI.csproj
LastMsg = .NET BUILD COMPLETED: 2009-09-08 10:39:20
NetBlds = SUCCESS
Batch Complete. Elapsed Time= 0:0:14.484

The default translation uses Interop for all COM externals and is written in the default .NET language (C#).

The entire process should take less than a minute for “small” codes. Most of the time will be spent in preparation steps — creating interface descriptions and Interop assemblies. The preparation steps typically only need to be redone if you change the external dependencies of your codebase. The translation itself is extremely efficient:

   -- VBPs referencing up to 50K lines of code (LOC) should finish in under 5 seconds.
   -- VBPs referencing   50-100K lines should finish in under 20 seconds.
   -- VBPs referencing  100-200K lines should finish in under 30 seconds.
   -- VBPs referencing  200-400K lines should finish in under 50 seconds.
   -- VBPs referencing  400-600K lines should finish in under 70 seconds.

Note that translation runtime is not directly proportional to the number of lines. The runtime is sensitive to the total number of symbols and atomic operations defined in the codebase being translated. This includes all identifiers declared by the VB6 code as well as all the identifiers declared in referenced COM components and all operations in the code.

Outputs

The .NET project files will be in the default deployment folder

      [INSTALLDIR]\samples\workspace\[name]\deploy\[project]_std_[lang].

The log files from all of the migration steps will be created in the workspace\log folder

      [INSTALLDIR]\samples\workspace\[name]\log

where:

      [name] is the name you entered for your migration project.

      [project] is the name of the VBP file selected above.

      [lang] is "csh" for C# or "vbn" for VB.NET depending on the task settings

Where can you go from here?

You can inspect the generated code (written in the files of the deployment folder) by selecting a migration task and right clicking [Open .NET Project Folder] from the context menu.
You can try to compile the generated code by clicking the [DevEnv] button on the Toolbar (and thus opening the .NET project in Visual Studio).
You can use gmStudio to browse, analyze, and summarize the various migration logs.
You can read the remaining sections of this guide, experiment and explore.
You can contact us for a assistance or a guided tour.