Process Overview

A Standard Upgrade solution development proceeds through a series of three stages each producing specific results:

1. Clean Translation Results
   
   By "Clean" we mean no errors reported during the translation process.  Translation errors occur due to missing or mis-referenced code, missing COM descriptions or other environmental issues, or by unexpected code.  If any errors are reported, they should be addressed before proceeding.
    

2. Local (Stand-Alone) Build-Complete Results 
   
   The Local Build is a simplified build model where the resulting projects are stand-alone.  They are independent of each other even if they were cross referential in the legacy codebase.   Legacy references to COM components are replaced by references to COM files within the projects as a project-specific local "Stub Framework" .
     

   

3. Global (Integrated) Build-Complete Results
   
   The Global Build is an integrated build model where the resulting projects reference  each another.  Generally speaking, external references in the legacy projects are reproduced as external references in the new projects.  Legacy references to COM components are replaced by references to a set of generated "COM Stub Framework" assemblies.  The Stub Framework is all .NET code, but it exposes the interfaces needed to allow building the upgraded legacy projects.
   
   

   

   
   
   

The scripts for first two steps are setup more or less automatically and can normally be handled with various translation tuning techniques in a single upgrade script template. The third step requires a special type of script called a Global Stubs script.   This document describes the concepts and activities required to setup and run a GlobalStubs script and then use its output in your upgraded system to produce your Global Build.

As mentioned above, after reaching local build-complete results with stand-alone .NET projects, the next step is to reach global build-complete results with cross-referential .NET projects. In this Global Build step, the stub files that were generated for and referenced by each upgraded project become consolidated into stub projects.  The stub projects build into stub assemblies that may be linked with the upgrade projects. The collection of stub projects/assemblies is referred to as the Global Stub Framework.

The process of generating the stub framework is referred to as the GlobalStubs operation and it is done using a GlobalStubs.xml script that takes as input the VBI files and IDFs from the local build work. The upgrade rules used in the GlobalStubs script must be consistent with those used for the local build work -- although it is expected to need a few additions and changes to produce a complete, clean, and internally consistent stub framework. Clicking Report\Utility\GlobalStubs on the main menu will generate a starter GlobalStubs.xml script template for a selection of VBPs.

In addition to authoring and deploying the stub framework code, the migration team must compile the projects to assemblies that will be linked to the application projects. The GlobalStubs.bnd file contains MSBUILD commands do do this.   These commands may be placed in a GlobalStubs.cmd script that can be integrated with the gmStudio GlobalStubs task.  Presently setting up the GlobalStubs.cmd with the MSBUILD commands is a manual task.

Example of Integrated Solution in gmStudio GUI

Here is an screen shot of gmStudio holding a solution that generates and integrated upgrade solution for a enterprise application comprised of 17 inter-related VBPs.  

Notice that the translations for the "Standalone" translations are larger because they contain the generated stub framework as embedded files rather than referencing the consolidated stub framework as external assemblies.

Going to the Next Level

The main purpose of the Standard Upgrade to generate initial translations and the COM Stub Framework projects and assemblies that set the a solid foundation for adding Custom Upgrade features such as  Custom COM Replacement , dead code cleanup, integrating new code, etc.  There are many types of potential Custom Upgrade requirements and many different ways to implement them with the help of gmStudio.  See this article for a discussion of Scoping and Planning a Custom Upgrade and See our Upgrade Samples for examples of how custom upgrades may be implemented using gmStudio.  Please feel free to contact us to discuss your specific requirements.

Step-by-Step Global Stubs Process

The following text describes the process to produce a GlobalStubs framework and the integrated upgraded application code for a set of VBPs. .

1) Verify that your BuildFile=local translation scripts produce build-complete results.

This step produces BuildFile=local VBI and IDF files for the VBPs.  These VBI and IDF files describe the dependencies of the VBP code and will be used to generate a stub framework for those dependencies later in this process.

2) Prepare a GlobalStubs script that references all COM IDFs that will become part of the stub framework and the VBIs for the VBPs generated from step 1. The IDF references must be placed in build order.

Select the VBPs that you used in Step 1.  Click Reports\Utilities\GlobalStubs Script on the main menu to generate a starter GlobalStubs script template for the selected VBPs.  The tool will generate the script and add it to your project as a GlobalStubs task.  In addition, this task will have an associated GlobalStubs.cmd batch file that will be used to build the Stub Framework projects.  

You may edit the generated GlobalStubs.xml script to include special pre-processing commands are added (e.g. selects, registry).  Also remove any spurious references (e.g. stdole2).  
You may edit the generated GlobalStubs.cmd script to include any user commands such as integrating external assemblies, replace stubs with hand written code, or running external tools (e.g. nuget restore).

3) Translate the GlobalStubs script.

Select the GlobalStubs task and run the Translate process from the task context menu.  The tool will produce a bundle containing the GlobalStubs framework codes: one .NET project for each COM IDF referenced in the GlobalStubs and one for the MigrationSupport IDF.

4) Deploy the GlobalStubs bundle

Select the GlobalStubs task and run the Deploy process from the task context menu. This breaks the GlobalStubs bundle file into separate .NET projects and code files that can be built using MSBuild.

5) Build the GlobalStubs projects

Select the GlobalStubs task and run the Build process from the task context menu.  This runs the GlobalStubs.cmd file that was created in Step 2 and creates a full set of stub framework assemblies that may be linked with the upgraded application codes.

6) Prepare a set of BuildFile=global translations tasks for the VBPs

See: usr\tran.ScanTool_int.xml

NOTE: these are very close the buildFile=local scripts with a few changes. Of course the big one is this:

^{<Select BuildFile="local" />
---
<Select BuildFile="global" />}

I also change Library; I set it to deployFolder to simplify project-cross-references and linking to the stub framework.

^{<Select Library="%DeployFolder%" />}

Finally the Select.Local is modified so that FromCode IDF files generated for BuildFile=local translations are separate from the ones generated for BuildFile=global translations. This is a best practice if you are running multiple translations in the same workspace. 

^{<Select Local="%ProjFolder%\idf\%TaskTag%" />}

Create a ScriptRule to conditionally author either local or global stubbing commands:

FILE: usr\StandardUpgrade.Rules.xml
<ScriptRule id="SupportFramework">
<!--
Support Framework Conventions
-->
<Option Condition="'%TaskTag%'=='std'">
   <Select BuildFile="local"/>
   <Select Library="%RuntimeFolder%" />
   <Select Local="%ProjFolder%\idf\%TaskTag%" />
 </Option>
<Option Condition="'%TaskTag%'!='std'">
   <Select BuildFile="global"/>
   <Select Library="%DeployFolder%" />
   <Select Local="%ProjFolder%\idf\%TaskTag%" />
  </Option>
</ScriptRule>
...

Reference the SupportFramework rule in the template translation script. This ScriptRule 
element may replace the BuildFile and Library commands normally placed in the file.

FILE: MigName.std.Tran.xml
<!-- Translation options -->
<Select GlobalSettings="%UserFolder%\GlobalSettings.xml" />
<Select Progress="1" />
<Select DevEnv="%DevEnv%" />
<Select Dialect="%Dialect%" />
<Select OptionalArguments="on" />
<Select DeployLocation="%NetProjFolder%" />
<Registry type="GUID" source="Project" target="{%TaskGuid%}"/>   
<ScriptRule id="SupportFramework" FileName="..\usr\StandardUpgrade.Rules.xml" /> <--- add this

7) Translate, Deploy, and Build the BuildFile=global translation scripts.

This will generated, deploy, and build the application translations.

8) Generate a VisualStudio solution to reference your integrated projects

Click [Report\Utility\Generate Visual Studio Solution] on the main menu to generate a SLN file the .NET projects in your deployment space.  The tool will also generate a GenerateSolution.txt file that you may edit to include only the Global Build COM and ..NET projects. 

NOTE: Generating the VS Solution modifies the projects to use project references rather than assembly references. This enables building the projects in order for a Rebuild in Visual Studio.

Removing Spurious Stub Projects

Searching for "^}" in the generated GlobalStubs code reports the size of each stub file. If some of these files are found to have only a few records, they are empty stubs.  

Empty stubs occur when the VBPs reference a Library, but no references to the library's API elements are found by the GlobalStubs analysis.  These libraries corresponding to the empty stubs should be researched for possible late binding issues.  It f they are in fact referenced but not used, they the libraries should be removed from the reference list in GlobalStubs.  These should also be added to the GlobalStubs script as DoNotDeclare for future runs; for example, insert the following before the GlobalStubs command in the GlobalStubs.xml script: 

   <Migrate id="MSDATASRC" location="DoNotDeclare" />