Deployment

This section describes the rational for gmStudio's approach to deployment . 

Why Bundle?

One of the unique features of gmStudio is that is allows you to separate code generation from code deployment. This best practice resulted from our work in helping teams perform migrations of very large systems. It works like this: rather than publishing the translated code as separate files and folders immediately as they are produced, gmStudio creates a consolidated text archive that contain all the files. This text archive, or bundle file as we call it, must be explicitly processed, or "deployed", to create the separate files and folders. By default, this feature works behind the scenes and it is extremely fast so you barely notice it. This approach provides additional control and visibility to the migration effort, and having all the generated code in a single file facilitates several useful operations:

• Report an inventory of all code generated for a translation 
• Search, or search and replace, all code generated for a translation 
• Create a snapshot all code generated for a translation  
• Compare two snapshots of all code generated for a translation  
• Compare all generated code for two different translations  
• Inspect code before deploying it

Furthermore, migrating a large system produces a new codebase, and this can mean thousands of new source files and millions of new lines of code. It is critical that the migration team plan for this tsunami of new code and has tools to help them manage it efficiently. gmStudio's bundle file deployment feature is useful in this regard.

A contemporary codebase consists of a very large number of files, some of which are text files and some of which have binary formats. It is the mandate of this system that it be able to process an existing codebase and to then transform it into a new codebase with different files, different structure, and even with different internal file format. The term "Deployment" is used to refer to the various operations required to gather large numbers of files into an archive and then to redistribute the contents of the archive in a new location.

Though there are many binary compaction formats that could be used to gather files into a single archive, this system uses a simple text-based format that is compatible with all contemporary operating systems. The details of this format will be discussed later. The advantages of using a text-based format are two-fold:

• First, different operating systems use different internal file formats for text files, which form the bulk of the files in the site. This system knows these formats and can both recognize and produce them as it performs the various deployment operations. Binary zip formats cannot change the formats as they gather and then distribute files; thus, the user is required to use a separate process to do the text-line format conversions. 
   
• Second, the authoring facilities of this system produce outputs which contain many files. It makes this operation easier to manage if the authors can produce single files using this text-based format that can then deployed once they have been produced and accepted.

What is a Bundle File?

Bundle files are the self-extracting text archives produced by the translation process.

Here is a sample bundle file

Notice that the bundle file contains commands and content. The commands are directory management commands such as rmdir and mkdir. The content is in the venerable unix "here-file" format

The translator always writes your translation to a bundle file that you specify in the Translation Script and a separate step, running the deployment tool -- is used to run the bundle file. By default, gmStudio handles all of this behind the scenes. 

Viewing and Reporting your Bundles

You can view the deployment logs for a given migration unit by selecting the [Deploy Log] option on the [Task Details] tab. Checking the [Grid] option here will display the internal contents of the bundle file.

You can generate a report of the internal contents of the bundle files for selected migration units in your project by clicking [Reports/Code Bundles].

How Deployment Works

Deployment is a specific step in the migration process that can be turned on of off from the [Batch Control] Form. By default deployment is always on and runs after the Translation step and before the Build step.

Behind the scenes by gmStudio performs deployments by running an external deployment tool, deploy.exe. The command string for deployment is defined in the application config file by the following settings:

ShellToolExe     = "%SystemFolder%\deploy.exe"

' the 'deploy' sub-command passed to the Shelltool will run shell commands such as rmdir/mkdir/execute otherwise only the cat commands run.
DeployCmd        = "cmd.exe /C pushd '%LogFolder%' && '%ShellToolExe%' '%BndPath%' verbose replace > '%LogPath%' 2>&1 %UserCmd% && popd"

   %LogFolder%     is the workspace\log folder where gmStudio does almost all
                   of its batch operations

   %ShellToolExe%  is the path to deploy.exe

   %BndPath%       is the path to the code bundle to be processed

   verbose         is a command line flag that tells deploy.exe to report progress

   replace         is a command line flag that tells deploy.exe to replace files
                   with the ones in the bundle.

   %Logpath%       is a file that will capture the deployment log

   %UserCmd%       is a place-holder for a user batch command script

The deploy tool is actually a command processor that can remove and create folders, and execute external programs. For example, the deploy.exe utility is used to deploy and build to binary (by running MSBuild) all the prototype assemblies generated in a prototype translation. 

Performing a Deployment with gmStudio

Deployment is a standard operation in the batch upgrade process, however if you want to deploy your migration files on demand, perform the following steps:

1. Select [Open .NET Project Folder] on the migration unit context menu open the deployment folder for that unit.
2. Select [View\Deploy Folder] to open the deploy folder for your migration project.

Default VB6 Deployment

Translating a VB6 migration unit produces a set of files that correspond to the ones referenced by the source VBP:
 

• A .NET project file corresponding to the VBP. The name of this file is the same as the VBP file except with a .csproj or .vbproj extension  
• A collection of .cs or .vb files corresponding to the frm, bas, cls, and ctl files. By default the names of files match their "internal" names that they had in VB6, not their external filenames.  
• A collection of .designer.cs files corresponding to frm and ctl files.  
• A collection of .resx files corresponding to frm and ctl files.

By default, all files generated for a given migration unit are placed in a single folder called the unit deployment folder. The unit deployment folders for VB6 translations use the following naming conventions:

   [WorkspaceRoot]\[MigName]\deploy\[TaskName]_[TaskTag]_[Lang]

where:

   [WorkspaceRoot] is the workspace root folder

   [MigName] is the migration project name

   [TaskName] is the original VBP file

   [TaskTag] is the task tag assigned to the task when it was added

   [Lang] is 'csh' or 'vbn' if the target language is C# or VB.Net respectively.

The ScanTool sample has the following settings

   In the project file header:

      ProjFolder = "C:\GMS\samples\workspace\DemoScanTool"
      DeployFolder = "%ProjFolder%\deploy"

   On the task records:

      TaskTag = "mgd"
      Lang = "csh"
      SrcName = "ScanToolUI" or "ScanToolLib"

Thus, the full path to the csproj files produced for each migration unit is: 

• C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolUI_mgd_csh\ScanToolUI.csproj]  
• C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_mgd_csh\ScanToolLib.csproj]

gmStudio communicates the deployment folder to the translation process using a select DeployLocation command in the Translation Script. 

The contents of the file look like this:

deploy V9.77 (BETA.007) System Build(6/18/09 8:40:51)
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\ScanToolLib.csproj
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\AssemblyInfo.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\modScanToolLib.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsVBPRefReporter.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsDirList.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsVBPBinReporter.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsCOMReporter.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsVBPModReporter.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsVBPCntReporter.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsVBPSrcReporter.cs
Unbundling: C:\GMS\samples\workspace\DemoScanTool\deploy\ScanToolLib_iop2_csh\clsScanControl.cs

Default Web Deployment

Translating a web site has a different deployment model because folder structures tend to be much more elaborate and important to the conceptual design, security, and operation of the site. In addition #include paths may be virtual or physical and the concept of a virtual root directory comes into play.

The discussion here refers to a web site migration script that contains commands to compile all the pages in the site, but it would also apply to a script for a single page.

Translating a web site produces a set of files that correspond to the ones referenced by page slices named that script as follows:
 

• A Web Application Project for the entire site. The name of this file is the same as migration project file with a .csproj or .vbproj extension. This project names and relates all the .NET files generated for the site.  
• A default Web.Config file  
• A collection of .aspx files corresponding to the asp pages. These files have the same names and relative locations as the original asp pages. These files contain the "Markup" part of each .NET page class.  
• A collection of .aspx files corresponding to the asp pages. These files have the same names and relative locations as the original asp pages. These files contain the "CodeBehind" part of each .NET page class.  
• A collection of .ascx files corresponding to the include files. These files have the same names and relative locations as the original include files. These files contain the "Markup" part of each .NET control class.  
• A collection of .aspx files corresponding to the include files. These files have the same names and relative locations as the original include files pages. These files contain the "CodeBehind" part of each .NET control class. 
   

By default, all files generated for the site are placed in a folder hierarchy that corresponds to the source folder hierarchy, but under the deployment folder. The deployment folder for a web translation is similar to the one used for a VB6 translation. The default folder for a migrated web site uses the following naming conventions:

   [WorkspaceRoot]\[MigName]\deploy\

where:

   [WorkspaceRoot] is the workspace root folder

   [MigName] is the migration project name

::----------------------------------------------------------------
:PRE-DEPLOY
::----------------------------------------------------------------
echo USER COMMAND: %1 [%JobId%]

::echo setup directory folders for site
robocopy "%VirtualRoot%" "%ProjFolder%\deploy" * /s /xf * /e 

::echo deleting files from deployment %ProjFolder%\deploy
del /s "%ProjFolder%\deploy\*.as*"
del /s "%ProjFolder%\deploy\*.cs*"

These pre-deployment commands create empty folders to receive the generated site and also delete all files from prior translations.  

Example Web Deployment

The DemoFMSWeb_csh.gmproj sample has the following settings:
 

In the project file header:

   <ProjFolder> C:\GMS\samples\workspace\FMStocks_csh</ProjFolder>
   <DeployFolder>%ProjFolder%\deploy\web</DeployFolder>

Note that the subdirectory "web" was added to the default deployment path. This was done do put the FMStocks site in its own folder next to the "lib" folder that is used for all the FMStocks class assemblies.

The full path to the web application project file produced for the site is

   C:\GMS\samples\workspace\deploy\web\DemoFMSweb_csh.csproj]

gmStudio communicates the deployment folder to the translation process using a select DeployLocationcommand in the Translation Script. For example, the tran.DemoFMSweb_csh.xml script template contains the following statements:

   <Select DeployLocation="%NetProjFolder%" />

gmStudio uses information in the Configuration Files to set the parameter %NetProjFolder% when you run the translation.

   <Select DeployLocation ="C:\GMS\samples\workspace\deploy\web" />

This folder ultimately ends up in the bundle file and directs the physical deployment of files to disk. 

Custom VBP deployment

The VBP deployment conventions are controlled by several settings in the gmStudio.cfg file:

   WorkSpaceRootFolder = "user-defined directory"
   DefaultDeployFolder = "%ProjFolder%\deploy"
   VbpDeployPat        = "%DeployFolder%\%SrcName%_%TaskTag%_%Dialect%"

You can modify the settings in the gmStudio.cfg file to change the application defaults.

The migration project file provides two variables that can override deployment folder defaults if desired

   ProjFolder = User-defined directory; default = [WorkspaceRoot]\[MigName]
   DeployFolder = User-defined pattern; default = %ProjFolder%\deploy

You can modify these settings in the gmproj files to change the project defaults.

For example, set

   DeployFolder = %SrcFolder%\..

To put the migration unit folder next to the original source project folder.

The Translation Script has the final say on where deployments will be placed. The default command means use the value computed by gmStudio from the config.

   <Select DeployLocation="%NetProjFolder%" />

You can modify this setting to change the deploy location for the units that use the script. For example

   <Select DeployLocation="C:\project1_net" />