Upgrade Project Overview
Mark Juras
Project Objectives
The essential objective of a Windows Application upgrade to .NET is to rewrite a legacy system for the .NET platform so that its functionality is preserved and its code can be maintained and further developed on the .NET platform. The resulting system will be a collection of .NET projects, expressed in C# (or VB.NET) and using the .NET Framework. The .NET code will meet the technical and functional requirements developed by an Upgrade Team composed of people from the client and Great Migrations (GM).
Methodology Overview
Agile and Iterative
Our Agile Tool-assisted Rewrite methodology is founded on the following two principles:
- Systematic, Repeatable Transformation
- Continuous, Iterative Improvement
The approach yields meaningful, reproducible results soon after project initiation and continues to deliver results of measurably increasing quality through a process of recurring release cycles – until all the requirements set out by the Upgrade Team are satisfied and the final deliverable is produced. Progress is visible, measurable and verifiable by inspecting, building, and testing the new application.
Figure 1: Upgrading Windows Legacy Applications to .NET using the Tool-Assisted Rewrite Methodology |
Quality Milestones
The Tool-Assisted Rewrite Methodology upgrades a legacy system from a source platform to a target platform through a series of increasing-quality milestones:
Milestone | Phase | Description |
0 | Standard | Source Complete, Ready to Translate |
1 | Translate Complete, Ready to Assess and Prepare Re-engineering and Verification Plans | |
2 | Build Complete, Ready for Re-engineering | |
3 | Custom Upgrade | Re-engineering Complete, Ready for Debugging and Optimization |
4 | Upgrade Complete, Ready for Cut-Over and User Acceptance Testing | |
5 | Verification | Verification Complete, Ready for Transition and Deployment |
6 | Transition | Deploy Verified System to Users |
Upgrade Solution Development
Progress through the six quality levels is measured according to specific technical and functional criteria, as defined by the Upgrade Team, and achieved using a custom Upgrade Solution. Each Upgrade Solution is an original work embodying both the state of the legacy system and the desired end state of the target system.
The Upgrade Solution is a comprehensive framework that integrates new designs, manual work, and automated software transformation. As a framework, the Upgrade Solution supports the continuous improvement of all the artifacts comprising it:
- Improves the clarity, completeness, and quality of the technical and functional requirements
- Improves the legacy source code that is input to the transformation
- Improves the custom metadata and rules that direct gmStudio in reading, interpreting, and rewriting the code
- Improves hand-written code or new .NET components as they are integrated with the result
- Improves the gmStudio tool itself to produce new or better transformations
Two-Phase Approach
Though continuously improving during the course of the project, a typical implementation of the Upgrade Solution has two phases of development:
- Phase 1 – Standard Upgrade, producing a "direct" translation that builds in .NET
- Phase 2 – Custom Upgrade, producing a custom translation having specific technical and functional features
Figure 2: Two-Phase Approach to Software Modernization using gmStudio |
Parallel Testing
Reproducing functionality is the most critical objective of upgrade project work. In a tool-assisted rewrite, meeting this objective requires carefully comparing the behavior of the new system to corresponding behavior of the legacy system. This is referred to as Parallel Testing (aka Side-by-Side Testing).
Figure 3: Parallel Testing |
Parallel Acceptance Test (PAT). |
A critical body of documentation needed to complete the Parallel Testing is the Parallel Acceptance Test (PAT). The PAT consists of a finite number of reproducible test cases (inputs, steps, and outputs) and also the detailed – preferably automatic, if available – procedures for running the application, gathering results, and comparing results to verify functional equivalence between the legacy system and the new system. |
GM has an automated testing tool, called gmTest, which the Upgrade Team may consider using in complementing any manual, script-driven testing procedures – when available.
Release Cycles
The results of our work (project deliverables) will be produced for the Client in a series of regular deliveries (monthly or more frequently, if necessary), subject to a predefined schedule. The upgrade solution evolves in a number of release cycles – each cycle producing a release package that contains the following work products:
- The Source Codebase, as re-written in .NET during the current cycle. The quality of each code delivery will be measured by the number of upgrade features completed during the current cycle.
- Continuous Progress Reporting describing the work done during the current cycle and outlining the work to be done in the next cycle. A web-based Issue Tracking System may be set up to facilitate the day-to-day flow of information among the members of the Upgrade Team and to provide a detailed record of the work:
- Code improvements made during the cycle (in terms of upgrade issues resolved)
- Code upgrade issues to be addressed in the upcoming cycle(s)
- Any design specifications for technical requirements developed during the current cycle
- Any code for new architecture developed during the current cycle
- Any testing procedures developed during the current cycle
- The custom Translation, Re-engineering and Build Scripts and Procedures that were used to direct and automate the tool-assisted rewrite of the Source performed in the current cycle. These refinement procedures provide documentation of all the modernization decisions made during the project.
- A Custom Version of gmStudio, as enhanced to resolve modernization issues encountered during the current cycle.
- The Testing Scripts and Procedures that were developed to test and verify all the modernization issues or defects that were addressed during the current cycle. Over time, these testing artefacts will evolve into a persistent asset, which the Client may use as a re-usable regression-testing resource for the Source application, as it changes over time. Near the end of the project – when the Client will be ready to "cutover" to its then current version of the Source – this asset will be particularly useful.
- Status Meetings that provide periodic (e.g., biweekly) status updates outlining progress, issues and mitigation strategies to achieve completion of activities within each delivery cycle. In turn, GM will provide review and feedback on these status updates. These meetings will be conducted over the web; if necessary, however, GM will make site visits to the Client upon request.
Project Structure
Collaboration
This project will be a collaborative effort between the Client and GM. GM will offer expertise and labor to implement an Upgrade Solution that meets the Client's requirements, but doing this will require input, support, and feedback from the Client to define and verify the results and to facilitate transition and closure of the project.
Team Structure
The Client may achieve the objectives of this project in close collaboration with GM, based on the Client's requirements and preferences. A joint GM/Client Upgrade Team may be formed to conduct all aspects of the planning and execution of the project, as desired by the Client.
GM Staffing
In most cases, GM's role on each project is to assist with configuring and operating gmStudio or to train and support others to use gmStudio themselves. GM team members may also assist with project planning and management, technical design, and implementation of new code to be integrated with the upgraded system.
Client Staffing
The Client staff resources are expected to contribute in the following roles:
- Project Manager – based on knowledge of the overall work plan and external factors that might constrain and impact the modernization effort, this resource will coordinate the work, facilitate approval of deliverables, and ensure successful closure of the project.
- System Architect – based on knowledge of the source application and the desired architecture design, standards, and constraints, this resource will help formulate and approve technical decisions, articulate a clear and consistent vision of the desired system/application architecture, and identify and close gaps between current and desired technical design.
- Application Developer – based on a strong working knowledge of the existing code and of .NET technology, these resources will facilitate problem identification, analysis and resolution and provide technical requirements and other research needed for the upgrade solution.
- Software Configuration Manager – based on knowledge of the legacy source code structure and version control and a detailed understanding of standard builds and deployments across environments, these resources will provide requirements for and support implementation of builds and deployments of the new system.
- Network Engineer – based on knowledge of the access security, networking, workstations, and servers in the project environment these resources will provide infrastructure and network access support for the project.
- Database Administrator – based on knowledge of the databases and database servers used by the legacy and to be used by the new systems these resources will provide database administration support for the project.
- Quality Assurance Team – based on detailed knowledge of the application functionality and the processes to verify it, these resources will provide the detailed test case documentation, and test scripts needed to setup and conduct comprehensive regression testing of the application.
Methodology Details
Phase 1 – Standard Upgrade
The goal of the Standard Upgrade is to rewrite the VB6/COM Source Baseline to a .NET Baseline that builds without errors. The major tasks of this phase are as follows:
- Prepare the Migration Assessment
- Resolve Translation Issues
- Resolve .NET Build Issues
- Prepare an Integrated .NET Solution
Task 1.0: Prepare the Migration Assessment
In this task we extend our understanding of the legacy application, establish a Source Baseline, and develop an Upgrade Plan for the project. For this task, GM will do the following:
- Take inventory of the legacy application and establish a Source Baseline for the project. The Source Baseline will contain all the source artifacts destined for modernization (both the VB6 source code and all the COM libraries and controls referenced by that code). The Client must provide an initial Source Baseline at the start of the project. If the source is changing for maintenance, the Client can make Source Baseline updates corresponding to their production releases. No "code freeze" is required.
- Validate the baseline to ensure all VB6/COM dependencies are present
- Analyze the Source Baseline document the size and complexity metrics in a Migration Assessment Report
- Prepare a Migration Workplan that provides direction for achieving the technical objectives of the project.
Task 1.1: Resolve Translation Issues
In this task, the Source Baseline will be translated in order to produce a complete, first-order .NET translation. For this task, GM will do the following:
- Create a minimal Upgrade Solution that rewrites the Source Baseline as a .NET Code Baseline
- Review and analyze the translation logs to identify translation issues
- Resolve all translation issues identified above by improving the Upgrade Solution
- Repeat the process until all translation issues are resolved
Task 1.2: Resolve Build Issues
In this task, the entire Source Baseline will be translated to C# projects that build without errors on the .NET platform. For this task, GM will do the following:
- Use gmStudio to transform the Source Baseline to self-contained .NET projects
- Use MSBUILD or Visual Studio to compile (build) the .NET projects
- Analyze the build logs for the purpose of identifying build errors and warnings
- Resolve all build issues identified above by improving the Upgrade Solution
- Repeat the translation and compilation process until all build issues are resolved
At this stage, each .NET project corresponds to an application VBP and will be self-contained and independent of the others. Each .NET project will reference two types of files:
- Application Code Files generated from the VB6 code files referenced by the source VBP
- COM/VB6 Stub Framework Files generated from the COM/VB6 components referenced by source VBP
Task 1.3: Prepare an Integrated .NET Solution
The purpose of this task is to generate a .NET Codebase that is integrated in Visual Studio .NET.
- Use gmStudio to transform the Source Baseline to integrated .NET projects
- Use MSBUILD or Visual Studio to compile (build) the .NET projects
- Analyze the build logs for the purpose of identifying build errors and warnings
- Resolve all build issues identified above by the improving Upgrade Solution
- Repeat the translation and compilation process until all build issues are resolved
At this stage there will be two types of projects:
- Application Projects corresponding to the Source application VBPs
- COM/VB6 Stub Framework projects corresponding the COM components used by the Source VBPs
The .NET projects cross-reference each other based on their inter-dependencies. In addition, GM will generate a Visual Studio solution file that integrates the generated projects and allows a full build.
End of Phase 1 Milestone
At the end of Phase 1, the Upgrade Team will have a clean, complete, and internally consistent .NET version of the legacy code and its COM dependencies. The .NET project files will be integrated and organized by a Visual Studio solution (.sln file). The new code will not run because the legacy platform dependencies are only satisfied by stub assemblies. The Team may decide to use the new application code as a resource to be manually "harvested" and reworked to a new design, or they may flow into Phase 2 and continue improving the upgrade solution until it produces results that closer to the required design.
Phase 2 – Custom Upgrade
The goals of the Custom Upgrade are two-fold:
- Technical Goals: Upgrade the Source code so that it has specific technical requirements
- Functional Goals: Upgrade the Source code so that it has specific functional requirements
The major tasks of Phase 2 are as follows:
- Develop Technical Upgrade Plan and Procedures
- Implement the Technical Upgrade
- Develop Functional Verification Plan and Procedures
- Implement the Functional Upgrade
Task 2.1: Develop Technical Upgrade Plan and Procedures
As part of this task, the Client and GM will do the following:
- Develop a Technical Upgrade Plan for the Source. This plan will contain technical requirements for the new .NET code. The requirements are typically design strategies for replacing VB6/COM dependencies with equivalent .NET components, and standards for improving the maintainability of the .NET code base.
- Document design details and procedures describing how to check that the new code meets each technical requirement
Task 2.2: Implement the Technical Upgrade
As part of this task, the Client and GM will implement a Technical Upgrade process using gmStudio to integrate manual and automated code transformation rules to generate the required .NET code. For each technical upgrade requirement, the process includes the following steps:
- Use gmStudio to transform the Source Baseline to upgraded .NET projects that meet the requirement
- Use MSBUILD and Visual Studio to compile (build) the .NET code
- Perform manual and/or automated code inspections to check compliance with the requirement
- Log defects to an issue tracker (optional)
- Analyze the result to identify issues relative to the requirement
- Resolve the issues identified above by improving the Upgrade Solution
- Repeat the upgrade-analyze-improve process until all technical upgrade issues are resolved
Task 2.3: Develop a Functional Verification Plan and Procedures
As part of this task, the Client will do the following:
- Develop a Functional Verification Plan for the Source. This plan will contain a well-defined Parallel Acceptance Test with which to verify the "correctness" of the Source.NET in comparison to its VB6/COM counterpart
- Document detailed procedures describing how to test each functional requirement
Task 2.4: Perform the Functional Verification
As part of this task, the Client will execute the Functional Verification Plan and Procedures. GM will assist the Client in iterating through "upgrade-rebuild-test-fix" cycles improving the Upgrade Solution as needed. Implementing the Functional Upgrade includes the following tasks for each requirement:
- Use gmStudio to transform the Source Baseline to upgraded .NET projects that meet the requirement
- Use MSBUILD and Visual Studio to compile (build) the .NET code
- Install the .NET system in a valid parallel testing environment
- Use Parallel Testing procedures to identify functional issues
- Log defects to an issue tracker (optional)
- Analyze the results to identify issues relative to the requirement
- Resolve the issues identified above by improving the Upgrade Solution
- Repeat the "upgrade-test-improve" process until all functional upgrade issues are resolved
End of Phase 2 Milestone
At the end of Phase 2, the Upgrade Team will have a clean, complete, and internally consistent .NET version of the legacy code and its COM dependencies. The .NET project files will be integrated and organized by a Visual Studio solution (.sln file). The system is verified to meet specific technical and functional requirements.
At this point the new system may be ready for user acceptance testing and transition to production or it may go on to additional manual technical and functional enhancement before release.
The Upgrade Solution developed for this system may be applied on other similar legacy systems in the enterprise, yielding significant economies of scale.
Phase 3: Verification (Acceptance Testing)
At some point during the Custom Upgrade, the new system will be sufficiently upgraded to allow functional testing to begin. Upgrade Project testing is normally done by comparing results gathered by rigorously operating the legacy and new systems side-by-side. Prior to performing the tests and recording results, the project team must define test procedures, prepare test data and environments, and install the old and new software in those test environments. We call this work the Verification Phase of the Upgrade Project. Verification is most efficiently done by an organization that is very familiar with all aspects of operating the application and working with its data. A practical discussion of Verification is beyond the scope of this document, but it will typically involve Side-By-Side Testing as shown below:
Phase 4. Transition to Production
Even after the new system has passed all tests in a carefully controlled test environment, it must still be systematically and carefully distributed to users. Packaging and distribution are the primary tasks in this final phase of the Upgrade Project which we call Transition. Whether the Transition is done all at once, or incrementally over time, it will typically require care planning, execution, monitoring, as well as extra support for users. Transition is most efficiently provided by the organization that is very familiar with the application and its user base. A practical discussion of Transition beyond the scope of this document.