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.
Software Requirements
The system has been tested on:
- Windows XP SP3, Windows Server 2003, Windows 7
- .NET 2.0 or higher Framework SDK
- VB6 to validate/build VB6 codes
- IIS to validate ASP sites
- VB Migration Assessment tool (optional)
- Visual Studio 2017 or higher (or other application associated with csproj/vbproj files). This guide assumes you have associated a version of Visual Studio with csproj/vbproj files.
- Your choice of a programmer's text editor; we use Notepad++ (default = notepad.exe, not recommended) Note: when running in Visual Studio, 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
+---rules: Sample rules, templates, and scripts
+---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 Main 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.
- 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.