Skip to content
Great Migrations
Blog

Migration Project Configuration Files

Overview

Section titled “Overview”

A Migration Project File contains the settings and a list of migration units that you wish to process as a coherent set.

Migration Project Files

Section titled “Migration Project Files”

A Migration Project document is an XML file with *.gmproj extension.

A Migration Project is created using the Migration Project Setup form as described in the Preparation section of this guide.

A Migration Project file contains two types of information:

  • migration settings
  • a list of migration tasks.

Here is an example of a project file for one of the migrations discussed in the samples section — FileExplorer_csh.gmProj:

Sample gmProj File
Section titled “Sample gmProj File”
<gmStudio>
  <Name>FileExplorer_csh</Name>
  <MigType>VBP</MigType>
  <DevEnv>VS2019</DevEnv>
  <ProjFolder>C:\gmTestBed\FileExplorer\proj_csh</ProjFolder>
  <DeployFolder>%ProjFolder%\deploy</DeployFolder>
  <VirtualRootFolder>C:\gmTestBed\FileExplorer\src</VirtualRootFolder>
  <ProjectLicense></ProjectLicense>
  <NetProjPattern>%IntName%</NetProjPattern>
  <NetFolderPattern>%IntName%</NetFolderPattern>
  <TlbSearchPath>C:\windows\sysWOW64;C:\windows\system32</TlbSearchPath>
  <GMExecPaths></GMExecPaths>
  <TaskFilter>*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*\|*</TaskFilter>
  <BatchCommands>Apply Task Filter,Reset Task Status,Validate Source,Set Build Order,Author Interface Descriptions,Author Resx Files,Run Translation,Deploy Translation,Build Translation,Generate Visual Studio Solution,</BatchCommands>
  <TaskList><![CDATA[... Task List Data ...]]></TaskList>
  <Signature>R+Flzrxz5XI=</Signature>
</gmStudio>

The settings stored with the Migration Project are initially set when you create the project file as discussed the Preparation section. The settings in a Migration Project file include the following:

Element

Description

MigName
 

Migration Name: User-defined string used to identify the migration

MigType
 

Migration Type: VBP or WEB.

DevEnv
 

Target IDE: e.g. VS2010

ProjFolder

Workspace Root Folder: this folder will contain Migration Project-specific folders to contain files such as logs, Configuration Files, and reports.

DeployFolder

Deployment Root Folder: this folder will receive deployments of migrated code. The deployment folder can be defined in terms of application variables. For example, to make the deployment folder a child of the workspace set DeployFolder to something like this

  • %ProjFolder%\deploy (this is the default)

To make the deploy folder relative to the location of the migration unit, set DeployFolder to something like this

    • %SrcFolder%.. (this will create target project folders next to the source folders)

  •  

See the discussion of Deployment for more information on target project folder naming conventions.
 

NetFolderPattern

Pattern used to set .NET project folder from the information in the VBP 

NetProjPattern

Pattern used to set .NET project name from the information in the VBP 

TlbSearchPath

TypeLib Search Path. This is a semicolon delimited list of folders to use to find COM components that are not registered.
 

GMExecPaths

Alternate Translation Tools Path(s).   GMExecPaths is a semicolon delimited list of zero or more key=value pairs separated by semicolons:

GMEXECkey=path;
where
GMEXECkey is a string corresponding to the value specified in the TScript field of tasks that will use the alternate tool
path is the location of the alternate Translation Tool location.  

For example: 

<GMExecPaths>GMEXEC=%AppExeFolder%\gmWpfSubsystem.exe</GMExecPaths>

directs gmStudio to run the gmWpfSubsystem.exe instead of gmBasic.exe when processing any task having Tscript=GMEXEC:script.xml

A special form GMEXEC*=path may be used to automatically override the default TranTool for all tasks.

GMExecPaths must be set to a valid key=value pair if you are using the GMEXEC: notation in the TScript field of a translation task as discussed below.

VirtualRootFolder

Virtual Root Folder: this folder is used as the “VirtualRoot” when resolving #includes in ASP Site migrations. Not used by VBP migrations.
 

TaskFilter

Task Filter: a sequence of pipe-delimited wild-card patterns that define which migration tasks to display in the gmStudio UI.
This element is maintained by the [Filter Dialog] in gmStudio.
 

BatchCommands

Command List: a comma-delimited list of operations to be performed when the user clicks the Batch Button. This element is maintained by the [Batch Control] Dialog in gmStudio.
 

TaskList

Task List: The list of Migration tasks associated with the migration project.

ProjectLicense

Used for project-specific licensing


The task lists stored with each Migration Project describes a collection of Migration Units (e.g., VBPs or ASP pages). Each item in the task list contains about 20 pieces of data that describe the nature and status of a migration unit.

Migration Tasks are added on the Migration Project setup form. Tasks may be removed using the Migration Task Context Menu. Individual tasks may be edited on the [Edit] display of the [Information] Panel. gmStudio can also help you edit and load a task list as a tab-delimited file.

Task Record Format

Section titled “Task Record Format”

Task records are stored as a block of tab-delimited text in the Migration Project files.

Each task record contains the following fields:

Field

Description

BldPath

Path of build product

BldType

Type of build product (VBP:Exe|OleDll|OleExe|Control or WEB:PULP|INCLUDE|PAGE).  The special value “SKIP” may be used to skip build operations for a task

LastMsg

Last status message

LibRegd

Referenced COM components are registered (READY|NOTFOUND)

MigName

Name of parent migration project

NetBlds

.NET Build Status (SUCCESS|FAIL)

NetLang

Target .NET Language (csh|vbn)

NetSize

Source LOC for .NET (includes RESX, CODE, PROJ)

RefStat

Interface description file status (see LibStat Flags)

IntName

Internal Name of VBP (by default this name is used as the folder name, project name, and the namespace in the translated code)

SrcFile

Name of migration unit source file

SrcFldr

Location of migration unit source file (Vbp or Web content)

SrcName

Unique identifier of the task within the migration project.  When creating a new project, gmStudio may alter this name to ensure it is unique.

SrcOrdr

Task build order based on VBP references or ASP #includes

SrcSize

Source LOC for VBP/ASP (may be negative if files are missing)

SrcType

Type of migration unit (VBP|WEB|XML)

TScript

Translation script template name or executable program.

The Tscript value may be of the form

filpath[/options] or blank

where

filepath is most commonly the name or path of an Xml document.  Xml documents are gmPL script files processed by gmBasic.exe or a custom translation tool.

filepath may also specify the name or path of a gmSL script.

filepath may also have a prefix specifying a custom translation engine or tool.

GMTOOL:executable.exe specifies a custom tool that will get the actual template script as its command line argument.

GMAPI:executable.exe specifies a gmAPI executable that gets a TaskInfo.xml file as its command line argument.

GMEXEC<key>;Tscript.xml specifies the task should be translated with an alternate translation tool, typically a gmAPI executable. The path to this tool must be  specified in specified in the GMExecPaths element in the gmProj file.  Note <key> is an optional letter that may be used to indicated one of several alternative translations tools.  For example

TScript=GMEXECD:migration.tran.xml


gmProj:
<GMExecPaths>GMEXECD=..\gmUpgrade\bin\Debug\gmUpgrade.exe;GMEXECR=..\gmUpgrade\bin\Release\gmUpgrade.exe</GMExecPaths>

options are command line arguments to pass to the translation engine (gmbasic) or a special processing options. For example, if you want to use a custom startup file use options = startup=‘..usr/customStartup.xml’.   The special processing options are :

  • MakeMetalang: rebuilds the metalang file before running the translation.
    The tool will rebuild the metalang file from a project-specific vb7lang,xml script in the usr folder.

  • StartDefault: use the default metalang file even if the tool is configured to use a project-specific metalang file.

If TScript is blank, then the translation step will be skipped for the task. This is useful for batch-only processing such as copying files or setting up other assets for the batch upgrade. (see UserCmds below.)

TaskTag

A short string used to differentiate different types of migration tasks; for example for different migration configurations

TrnStat

Translation Status (SUCCESS|WARN|ERROR|ABEND)

UsrCmds

User command script to run after key processing steps translation, deployment, or build (optional). See User Batch Command Script in this section.

UsrCmnt

User-Defined Comment for filtering and tracking (optional)

UsrDesc

User-Defined Description of Task (optional)