VB Migration Partner

MANUAL

Previous | Index | Next 

2. Using VB Migration Partner



2. Using VB Migration Partner

VB Migration Partner requires that Microsoft Visual Studio 2005, Visual Studio 2008 or Visual Studio 2010 be installed on the local computer. We recommend that you run the migration process on the same computer where you developed and tested the original VB6 application, therefore also Visual Basic 6 must be installed on the local computer.

Using the program is quite simple and revolves around a few simple actions that can be reached from the toolbar.


Load VB6 project or group Reload the solution Save VB6 or VB.NET files Insert Migration Pragma Convert to VB.NET Generate the assessment report Tasks Compile project or solution Load the generated VB.NET code in Microsoft Visual Studio Modify options Help About VB Migration Partner
VB Migration Partner Toolbar


2.1 Loading the VB6 project


Open toolbar button
Select the File-Open menu command or click the Open toolbar button to load a VB6 project (.vbp) or project group (.vbg). If the project was written with a version of VB6 prior to VB6 you must convert it to VB6 before attempting the conversion. If the loaded file isn’t recognized as a VB6 project or project group a message error is displayed.

If the EXE or DLL file created by compiling the VB6 project is present, VB Migration Partner compares its datetime stamp with the datetime stamp of all the files in the project. If the executable file is older than any of the corresponding source files, VB Migration Partner displays a warning.

Warning: We strongly recommend that you always recompile the original VB6 project before attempting the conversion to .NET and ensure that the VB6 code doesn’t contain syntax errors. While VB Migration Partner is able to spot such errors and solve them in most cases, in some cases these errors might cause invalid .NET code to be emitted and even crash VB Migration Partner.

Note: you can suppress the display of this message box by selecting the corresponding option in the General tab of the Tools-Options window.



2.2 Converting to .NET


Convert toolbar button
Select the Build-Convert to .NET menu command or click the Convert toolbar button to start the conversion process. Each source file undergoes three distinct migration stages: the parsing stage, the processing stage, and the conversion stage. During the process an activity log is created, so that you can watch which files are being converted.

When the migration process is over, a few new tabs appear in the rightmost pane of VB Migration Partner’s main window:

  • the VB.NET or C# Code tab shows how the code in the currently selected file has been migrated
  • the Warnings tab shows all the warnings and issues for the entire project or file that is currently selected
  • the Metrics tab shows code statistics for the entire project or file that is currently selected

The Migration Result pane displays the list of all the issues, warnings, info, and to-do messages that have been emitted as special remarks in the VB.NET or C# code. You can filter these messages by clicking on one of the four tabs at the top of this pane and you can double-click a message to quickly jump to the code portion where the message has been emitted.



2.3 Compiling the .NET solution


Compile toolbar button
Select the Build-Compile Entire Solution menu command or click the Compile toolbar button to compile all the projects in the current solution to VB.NET or C# without leaving VB Migration Partner. You can also compile individual projects, by means of the Build-Compile Selected Project menu command.

Before running the actual compilation, VB Migration Partner has to save .NET source code files to disk. By default, these files are stored in a folder in the same directory as the folder that contains the original VB6 project; the name of the new folder is obtained by appending “_NET” to the name of the original folder. You can modify such default behavior in the Save tab of the Tools-Options dialog.

Before proceeding, VB Migration Partner displays a dialog that allows you to select a different directory:

If the target directory already exists and contains files – presumably created by a previous migration attempt – VB Migration Partner displays a message box that asks you to confirm the selection.

If the default choice is OK, you can tell VB Migration Partner not to display the dialog by enabling the Automatically Select Output Folder For .NET Solutions option, in the Tools-Options window. Likewise, you tell VB Migration Partner not to display the message box by enabling the Automatically Overwrite Existing Output Folder option, in the same window.

Once the compilation process is completed, you can browse all the errors and warnings from the VB.NET or C# compiler in the Compilation Results pane, near the bottom border.

Note: the compilation process is optional, especially when migrating a simple VB6 project or a project that you have already migrated previously and that has been already fixed to avoid compilation errors. In such cases you can directly load the converted code in Microsoft Visual Studio.

Alternatively, you can direct VB Migration Partner to compile the VB.NET or C# code immediately after the migration process, by means of the Automatically Build .NET Solution After Migration option, in the Tools-Option window. You have the option to compile unconditionally or only if the conversion process generated fewer errors, warnings, and issues than a threshold that you specify.




2.4 Fixing the VB6 code


Insert pragma toolbar button
Except for trivial applications, you never come up with a working .NET application at the first attempt. Migrating VB6 code to the .NET Framework platform is better described as an iterative process: you are expected to go back to the original application, edit it to fix all the migration and compilation errors and issues, and convert the code once again. This is the so-called convert-test-fix cycle.

If the converted application has one or more compilation errors you should probably insert one or more pragmas in the original VB6 code. You can do so by selecting the VB6 Code tab and the Edit-Insert Pragma menu command or by clicking on the Insert Pragma toolbar button. This action displays the Insert Pragmas dialog, which assists you in picking up the right pragma and assigning the right arguments. When you click the OK button, the dialog is closed and the actual pragma is inserted at the current position in the VB6 code.



Save toolbar button
If you have added one or more pragmas, or have modified the original VB6 code in any way from inside VB Migration Partner, you should now save the new files to disk, by selecting the File-Save-Save VB6 Files menu command or by clicking on the Save toolbar button.


Reload toolbar button
Alternatively, if you have modified the original VB6 code from outside VB Migration Partner – for example, from inside Microsoft Visual Basic 6 IDE or from an external editor – you can reload the project or project group by selecting the File-Reload menu command or by clicking on the Reload toolbar button.




2.5 Launching Visual Studio


Launch toolbar button
When you are satisfied of the results from the migration process you can load the converted .NET solution inside Microsoft Visual Studio, by selecting the Tools-Run Microsoft Visual Studio menu command or by clicking the Load the generated VB.NET code in Microsoft Visual Studio toolbar button.
VB Migration Partner displays the dialog box that allows you to select the target folder – as for the Compile to .NET command – then it launches Microsoft Visual Studio and loads the converted VB.NET in it.

The first thing to do at this point is checking all the errors and warnings in Visual Studio’s Error List window, and then all the items in the Task List window.

VB Migration Partner can generate for different type of comments in the converted application:

  • UPGRADE_ISSUE: serious migration issues that you should solve immediately
  • UPGRADE_WARNING: migration warnings that might or might not affect the converted application
  • UPGRADE_TODO: suggestions about how to manually edit the migrated code to avoid a potential problem
  • UPGRADE_INFO: information about the generated .NET code, including information about unused constant and methods and recommendations about the .NET type or methods that can replace a Declare statement.

By default, only warnings and to-do comments appear in Visual Studio’s Task List pane. We suggest that you use the Tools-Options command to add the UPGRADE_ISSUE comment to the list of comments that the Task List recognizes and set its importance to High.

If there are no compilation errors you can run the .NET application and see how it behaves. It’s unlikely that a complex application runs smoothly at the first attempt, therefore be prepared for runtime exceptions. We recommend that you enable the option Break When An Exception Is Thrown in the Debug-Exceptions dialog box, so that you immediately catch unexpected runtime errors that would go unnoticed because of an On Error statement.



2.6 Using code analysis features

At the end of the conversion process VB Migration Partner displays a detailed report in the Metrics tab in the right portion of the main window.

  1. Select an item in the tree on the left, to display code metrics at the solution, project, or file level.
  2. Select an item from the combobox to further restrict the report to just forms, classes, public or private members, methods or properties, and so forth.
  3. Select an item in the grid to see a more detailed report in the lower area of the Metrics tab.
  4. Sort the items in the grid in either ascending or descending order, by clicking on a column header.

The sorting feature is especially useful when focusing on the most problematic portions of the VB6 solution to be converted. For example, you can sort all methods on their cyclomatic index in descending order to immediately find the most complex methods in the application.

The Metrics tab of the Tools-Options dialog allows you to configure which code metrics appear in the grid and in the area underneath the grid.

The name of most code metrics values is self-explanatory, but a few might require an explanation. 

Total Lines is the sum of all code lines in the file, project, or solution. It includes the lines in the hidden portion of .frm and .ctl files.

Code Lines is the number of lines that contain actual executable code; it doesn’t include empty and remark lines (which are counted by separate code metrics).

Remark to Code Lines Ratio provides a broad measure of how well the original VB6 project is documented; the higher this value, the better.

Implicit Local Variables is the number of local variables that aren’t explicitly declared; they are typically converted as Object variables, therefore you might need to add the original VB6 code to use a more efficient type.

Variant Variables is the number of Variant variables; they are migrated as Object variables, therefore it is recommend that you carefully scrutinize each of them and change them to a more efficient type if possible, or possibly use a SetType pragma to convert them to VB6Variant variables.

Fixed Length Variables is the number of fixed-length strings. By default they are converted to instances of the VB6FixedLength class, but you might want to edit the original VB6 code (or use a UseSystemString pragma) to transform them into regular string.

Auto-Instancing Variables is the number of variables declared with the “As New” keyword. These variables have a different semantics in .NET and might behave differently.

Non-Zero Bound Array Variables is the number of arrays whose lower index is nonzero; such arrays require a pragma to compile correctly under .NET.

Gotos, Gosubs, On Gotos and Gosubs are the total number of GoTo keywords, GoSub keywords, and calculated GoTo/GoSub keywords, respectively. VB.NET and C# supports the GoTo keyword and VB Migration Partner generates code that simulates GoSubs and calculated GoTo/GoSub; nevertheless, it is strongly recommended that you edit the original VB6 application to get rid of them.

On Errors and Resumes are the number of On Error statements and of Resume/Resume Next statements. VB.NET supports them, but you should replace them with more structured and efficient Try…Catch blocks. (When converting to C#, VB Migration Partner always attempts to convert On Error and Resume statements to try-catch clock)

File Operations is the number of Open, Get#, Put#, and other file-related statements. These keywords don’t behave in exactly the same way in VB6 and .NET. VB Migration Partner automatically accounts for most differences, however you should test each occurrence.

Exit Points is the number of Exit Sub, Exit Function, and Exit Property keywords. This value is included in the code metrics report because many developers prefer to have a single exit point for each method.

Cyclomatic Index is the number of all possible code execution paths in a method and is therefore equal to the number of tests that should be performed to prove that the method behaves correctly in all situations. When evaluated at the file, project, or solution level it returns the sum of cyclomatic index of all contained methods and therefore can be assumed as a broad measure of the overall complexity of that file, project, or solution.

Nesting Level is the maximum nesting level of blocks inside a method. For example, a method that contains a For loop that contains an If block has a nesting level equal to 2. When evaluated at the file, project, or solution level it returns the sum of nesting level of all contained methods.

If Directives is the number of #If, #ElseIf, and #Else keywords. VB Migration Partner is capable to evaluate #If conditions and converts only the portion of code that is contained in the “true” portion of the #If block. All other sections must be converted manually, therefore it is a good idea to revise the original VB6 application and ensure that #If and #Const expressions exactly define the code that you want to convert.




2.7 Using assessment features

If the VB6 project has been already converted, VB Migration Partner can generate an assessment report and export it Microsoft Excel. The report contains detailed information about each project in the original application, including code metrics, number of migration issues and warnings, and an estimation of time (and money) required to complete the conversion process.


Generate the assessment report
Run the assessment feature by selecting the Tools-Generate Assessment Report menu command or by clicking on the Assessment toolbar button.

VB Migration Partner lets you select the name of the target Microsoft Excel file and then creates the assessment report. This step can take several seconds, or even minutes, for long and complex VB6 applications. At the end of the process a message box allows you to load the generated report inside Microsoft Excel.

The first worksheet generated Microsoft Excel file provides a summary of estimated costs for the entire application. If the VB6 application contains two or more project, a separate worksheet is generated for each project.

The “Config – Resources” worksheet allows you to define five different developer roles and assign a different hourly cost to each of them. The predefined roles are Project Manager, Architect, Junior Developer, Senior Developer, and Senior Tester, but you can change their name and cost as you see fit. (You can also add more roles, if you are an expert Microsoft Excel user.)

The “Config – Migration Warnings” worksheet is where you configure how many minutes it takes for each developer role to fix a given issue or warning message. Each message is identified by an obscure hexadecimal ID, but you can read its description in the rightmost column.

Finally, in the “Config – Code Tasks” you configure the duration (in minutes) for tasks that aren’t related to specific migration error and warning messages – for example, the time required to check 100 lines of code to ensure that they have been migrated correctly.

After configuring a report according to your preferences, you should save it to a different Microsoft Excel file, so that you can reuse it as a template for subsequent assessments – either for the same or a different VB6 project. You select which template should be used in the Assessment Report tab of the Tools-Options dialog box.



2.8 Customizing the code window

You can customize the colors used by the VB6 and VB.NET/C# code windows from inside the Code Editor tab in the Tool-Options dialog box.


Previous | Index | Next