Create A Migration Project

Owned by Mark Juras
Last updated: Apr 27, 2023

The first file created by gmStudio for your project is the Migration Project file.  This is an xml document, the gmproj file, that is easy to modify and managed by gmStudio to store the very highest-level information about the upgrade process. Initially you will add the files (e.g. VBPs and ASPs) that define your legacy system.  During the course of your project you may also add files for special gmStudio processing operations or integration with other tools and content.  This article describes the how to setup your initial gmproj file. 


Using the New Project Wizard

If desired, you may setup a new project using the New Project Wizard.  You may open the wizard by selecting [File|Upgrade Project Wizard] from the main menu.  The wizard will take your through the process of selecting source code, setting options, and running a translation.  See this article for more information on the New Project Wizard.

Using the Create Migration Project Form

The [Migration Project Setup] form is where you will define settings and add migration units to your project. The inputs captured on this form are described below:

  • a) Enter a migration project name
    Optional, Default = Migration1.
    This will become part of various log and other supporting file names and also be stored in reports produced for the migration.
     
  • b) Select target language (C#|VB.NET).
    Optional, Default = C#
    In addition to setting the target language, this setting specifies a three character code ('csh' or 'vbn') that will become part of various log and other supporting file names and part of the deployment folder name associated with each migration task.
     
  • c) Select an Extern Handling Strategy (Interop|Prototype).
    Optional, Default = Interop
    This setting controls how COM externals will be handled by the translator. The Interop option will handle externals as COM Interop assemblies; the Prototype option will handle externals as prototype assemblies.
     
  • d) Enter a task tag
    Optional, Default = "std" for Externals=Interop; "pro" for Externals=Prototype;
    This is an arbitrary string of (usually 3) characters that becomes part of the names of various logs and other supporting files and part of the deployment folder name associated with each migration task. Task Tags enable you to separate, identify, and compare the artifacts from different migrations of the same migration unit. If you do not intend to experiment with different migrations of the same source unit, just take the default value.
     
  • e) Select a target .NET IDE (e.g., VS2005|VS2008|VS2010).
    Optional, Default = VS2010
     
  • f) Select a migration type (VBP|WEB).
    Optional, Default = VBP
     
  • g) Select a source type (VBPs|VBPs&VBGs|Web Site).
    Optional, Default = VBPs
    This setting controls the file types that will be included when scanning for migration units. The set of file types included when source type=Web Site is specified by the WebFileFilter setting in the application config file.
     
  • h) Select migration units.
    Required, Default=none This is the specific set of VBPs or ASP file(s) that you wish to migrate.
     
  • i) Select the location of a third-party COM component cache.
    Optional, Default = none
    This setting is used to help the system find COM components that are not registered. This variable is rarely used since the recommended approach is to make sure the COM components used by your codebase are registered in the migration environment.
     
  • j) Select the location of the VirtualRoot.
    Optional, Default = none
    This setting is used to help gmStudio resolve #include statements for web migrations. It is typically the root of the directory where your web site files are stored.
    VirtualRoot has no effect for VBP migrations.
     
  • k) Select the location of the workspace root folder.
    Optional, Default = %WorkspaceRoot%\[name]\

    where
    %WorkspaceRoot% is the migration workspace root folder (as set in the application config file)
    [name] is the migration name
    This setting is the root of the directory tree where you want to store your migration artifacts such as Configuration Files, logs, Interop assemblies, etc.
     

  • l) Select location of deployment root folder.
    Optional, Default = %ProjectFolder%\deploy

    where
    [%ProjectFolder%] is the workspace root folder
    This folder is the root of the directory tree where you want to deploy generated projects.


Adding Migration Units

A critical activity in creating a migration project is identifying precisely which legacy code you will migrate.

In gmStudio, the set of legacy codes is explicitly captured in a Migration Project file that is used to drive all tool-assisted migration steps. Each legacy component being migrated is referred to as a Migration Unit. Typically there will be one Migration Task record for each Migration Unit, but you can have multiple tasks for the same unit if you wish to experiment with and compare different ways of migrating that unit.

Selecting migration units and adding them to a migration project is done on the [Migration Project Setup] form as follows:

  1. Select the type of migration tasks you want to add.

    • VBP Tasks (VBP files)
    • Web Tasks (ASP files)
    • Multi-Unit Tasks (e.g., a pre-built web site migration script)
       
    At present, VBP tasks and Web tasks cannot be in the same Migration Project. If you are migrating an ASP web site that depends on VB6 codes, you must create two migration projects: one for the VB6 code and one for the ASP code, but assign them the same workspace. This allows them to be migrated in a cohesive and consistent manner. You will initially want to migrate the VB6 units before the ASP units so that .NET versions for the VB6 components are available to use in migrating your ASP codes. See the FMStocks sample for a demonstration of a mixed VB6/ASP migration.
     
  2. Select the type of migration units you want to look for.

    • VBPs (*.VBP)
    • VBPs and VBGs (*.VBP and *.VBG)
    • Web Site Files (See the WebFileFilter in gmStudio.cfg)
    • Translation Scripts (*.XML)
    • Recon (*.*) this actually is a reporting tool used to inventory a directory tree.
     
  3. Use the FolderPicker to choose the directory you want to scan for migration unit(s)
     
  4. Click the [Scan ...] button to populate the [Select Migration Units] list.
     
  5. Select the desired unit(s) from the left-hand list.
    Beware that the file scan can throw a very wide net, and it may include files that you do not intend to migrate. This is particularly true for web sites that contain many files. As you select migration units consider that your migration effort is a golden opportunity to do some housekeeping. Take your time and be sure to select only those files that you intend to migrate and maintain going forward.
     
  6. Click the [Add] button to add the selected units to the list on the right of the panel.
     
  7. Click [Save & Exit] to return to the Main Form.

You may remove selected items from the [Tasks in the Migration Project] list by selecting them and clicking [Remove].

By clicking [Reset], you may restore the task list to its state prior to opening the [Migration Project Setup] form.

You may discard changes and exit the [Migration Project Setup] form by clicking [Cancel].

If you wish to add or remove tasks after the initial project setup, click the [Add] button on the Toolbar. This will return you to the Migration Project Setup form where you can use the procedures described above to add or remove tasks as needed.

Migrating Inter-Related VBPs

Putting migration units in the same migration project folder means they will share migration settings and workspace Configuration Files. You will typically only want to do this for migration units that are inter-dependent and part of a cohesive system that you intend to migrate as a set.

By default, target projects within the same migration project will reference the same Interop assemblies (in the workspace\Interop folder) or the same prototype assemblies (in the workspace\deploy\externs folder). depending on the external handling strategy selected on the [Migration project Setup] form. For example, the FMStocks sample contains several VBPs that all depend on ADODB. By default, all of the FMStocks .NET project files contain a reference to the Interop assembly created during preparation:

lib\FMSStore_Bus_std_csh\FMSStore_Bus.csproj: <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>
lib\FMSStore_DB_std_csh\FMSStore_DB.csproj:   <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>
lib\FMSTest_std_csh\FMSTest.csproj:           <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>
lib\FMStocks_Bus_std_csh\FMStocks_Bus.csproj: <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>
lib\FMStocks_DB_std_csh\FMStocks_DB.csproj:   <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>
lib\FMStocks_Ext_std_csh\FMStocks_Ext.csproj: <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>
web\DemoFMSWeb_csh.csproj:                    <HintPath>C:\gms\samples\workspace\FMStocks_csh\Interop\Interop.ADODB.dll</HintPath>

The location of Interop assemblies can be controlled by the setting of the Library translation option and by RefactorLibrary settings.

COM components implemented by source codes within a migration project are referred to as local components. By default, references to local components become references to the new, managed binaries, not references to the original COM components. Said another way: gmStudio's translations do not use Interop to access migrated local components. For example, the Interop2_csh sample contains two inter-related components: ScanToolLib.dll and ScanToolUI.exe. After translation, ScanToolUI references the managed ScanToolLib binary, not the Interop assembly:

DemoScanTool\deploy\ScanToolUI_iop2_csh\ScanToolUI.csproj: <HintPath>C:\gms\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\bin\ScanToolLib.dll</HintPath>