Page tree
Skip to end of metadata
Go to start of metadata

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.

The diagrams in this article show a system with two inter-related projects. Large applications may have dozens or even hundreds of inter-related projects; or in some cases a system will have just one VBP.  The same stages and steps apply to these cases as well. 

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.

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%" />

You can insert a conditional rule block (e.g. <if>) for Global stubs translations above the <Compile statement> like the example following. (this sample assumes that the Global Stubs translations have TaskTag='int')

<if id="%MigName%-%SrcName%-int-csh">
  <Select BuildFile="global" />
  <Select Library="%NetProjFolder%" />
<Compile Project="%SrcPath%" >

You may also change the setting in a ScriptRules file:

<ScriptRule id="Standard">
<Option Condition="%TaskTag%=='std'">
      <Select BuildFile="local"/>
<Option Condition="%TaskTag%=~'int|upg'">
      <Select BuildFile="global"/>
      <Select Library="%DeployFolder%" />

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

This will generated, deploy, and build the global build results.

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 related projects so they reference their project files rather than assemblies.

  • No labels