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.
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.
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.
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.
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.
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.
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.
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.
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.
- Select an item in the tree on the left, to display code metrics at the solution,
project, or file level.
- 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.
- Select an item in the grid to see a more detailed report in the lower area of
the Metrics tab.
- 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.
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.
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.
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.