Preparation

Owned by Mark Juras
Last updated: Apr 01, 2023
5 min read
This section describes how gmStudio can help a migration team assess, plan, prioritize, and prepare for a migration effort.  

Prepare Your Migration Environment: Build a Build Box

Hardware 

One of the first steps in preparing for a migration effort is to provision a reliable, high-performance development workstation that you will use to perform migration work. This is typically one of the workstations you are already using to maintain and build the source codebase.In terms of disk, CPU and memory, this machine should be sized for .NET development using Visual Studio -- the bigger the better.

Software

Once you have a migration workstation, install gmStudio and external tools as outlined on the Overview/Installation page.  

Source Codebase

In addition to hardware and software, your migration environment must contain a complete, internally-consistent and properly configured copy of your source codebase. A codebase has two parts:
  1. Source files that describe the behavior and structure of the system. These must be in the correct locations relative to the referencing files (i.e., VBPs or #including web pages).
     
  2. COM components that contain information about classes and external types that are used by your source codes. These COM components must be properly installed during the preparation phase. Most preparation problems stem from incorrect or incomplete installation of COM components. These can be resolved by installing (e.g., registering) each component that is causing an issue.

VB6 Validation: The Full System Build

A good way to validate your migration environment and source codebase is to perform a "full system build". Specifically, you should be able to successfully build your entire VB6 codebase on the migration workstation.Validation is a bit trickier for ASP sites since there is no way to do an automated build test. Technically speaking, you would have to request and verify every page to even begin to check all of the ASP code.Fortunately, gmStudio includes several facilities to validate source codebases, both VB6 and ASP, as discussed in the Verification section. Also, the gmBasic translator is a strict compiler that can detect problems with your code that VB6 and ASP may not. 

Create a Migration Project

Migration project files specify which legacy components to migrate and how to migrate them. A migration project can be created using the [Migration Project Setup] form. You can access the [Migration Project Setup] form in two ways:
  • Click the [New] button on the Toolbar
  • Select [File/New] from the menu

You may also use the [New Project Wizard] form to create a new project.  This walks you through setting up and running a default translation and reporting scenario.
You may also create a starter VB6 test code and an associated project using the [Create a Specification Code Form ]. This is helpful for creating a "starter project" to do detailed research and development for specific upgrade feature. 

Save and Upgrade

When you are done adding your VBPs (or ASP pages) to a migration project, you can Save it or Save and Upgrade it.  The Save option just takes you back to the Main form to work adhoc.  The Save and Upgrade takes you back to the main form then initiates the default upgrade process.  The default upgrade process includes the following steps:
  • Set Build Order
  • Author Interface Descriptions 
  • Author Resx Files
  • Run Translations
  • Deploy Translations
  • Build Translations
These steps are described below.

Set Build Order

After adding migration units to your migration project, you will use the Build Order tool to sort them in build order (aka dependency-first order)The results of the Build Order tool depend on the type of your migration project:
  • For VB6 migrations, the build order tool assigns every unit a build order number based on how it references other units. The units are arranged in ascending order of dependency on other units in the migration project. 
     
  • For Web migrations, the build order tool assigns every unit an "include" order and a build type (Page, Include, or Pulp) based on how it includes other units.
The [Tools/Set Build Order] option will compute the Build Order and re-arrange the Migration Units of a Migration Project in ascending order of dependency to other units in the project. As a result, units that do not depend on other units in the project will be migrated first and units that do depend on other units will be migrated later.Setting the Build Order is one of the default processing steps for all new migrations. 

Author Interface Descriptions

gmStudio uses information about COM components so it can recognize and interpret them correctly during the translation process. For efficiency, gmStudio stores this information in XML files. These files are called Interface Description Files (IDFs) and they must be created before translating any codes that depend on the components they describe.The [Tools/Author Interface Descriptions] option will create IDFs for your migration project.Creating interface description files is one of the default processing steps for all new migrations. 


Author Interop Assemblies (optional)

If you selected Externals=Interop when you setup your migration project, the system will create Interop assemblies for the external COM components referenced by your codes.The [Tools/Author Interop Assemblies] option will create Interop assemblies for your migration project.Creating interop assemblies is one of the default processing steps for "Interop" migrations.

Default Interop Assembly Location

By Default, interop translations generated by gmStudio reference interop assemblies in the [workspace]\runtime folder. We use this approach to make the location and status of the interop assemblies more transparent and predictable. You can easily alter this default behavior by changing the configuration of the translation process. Ultimately it is a moot point as gmStudio allows you to configure the translator to produce codes that do not use interop.

Author Resx Files

.NET Windows Forms applications use Resx files to store metadata for each form. Resx files contain information used by the forms designer as well as graphics (i.e., bitmaps, icons) and other binary content such as control property settings and binary information needed for Interoped controls (i.e., OCXState).You will need Resx files in order to maintain your user interface components with the .NET designer and to display .NET user interfaces at runtime.The [Tools/Author Resx Files] option will create Resx files for your migration project.Create Resx files is not a default processing steps for new migrations. 

Translate

Read, interpret, and rewrite the application code to the target language.  

Deploy

Place a copy of the generated files in the specified deployment folder.

Build

Run MSBuild on the generated .NET projects and check the results.

Prepare Web Site Script (optional, ASP)

By default, the object of each Translation Script is a single migration unit, a VBP or an ASP page, and processing that script produces a single .NET project as output. This one-legacy-project-to-one-.Net-project model is appropriate for VBPs. However, when migrating a web site, you may want to produce a web application project for the entire site. As described here, gmStudio has procedures for doing this. Prepare Web Site Script Page