Migration Project Configuration Files
Mark Juras
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
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:
<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
 |
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: 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
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) |
SrcBlds | VB6 Build Status (SUCCESS|FAIL) |
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 |
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] 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 <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 :
|
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) |