So you now have a license of the Visual Basic Upgrade Companion, you open it up, and you don't know what now to do. Well, here are 5 simple steps you can follow to get the most out of the migration:
-
Read the "Getting Started" Guide: This is of course a no brainer, but well, we are all developers, and as such, we only read the manual when we reach a dead end ;). The Getting Started guide is installed alongside the Visual Basic Upgrade Companion, and you can launch it form the same program group in the start menu:
- Create a New Upgrade Solution: the first step for every migration will be to create a new VBUC Migration Solution. In it, you need to select the directory that holds your sources, select where you want the VBUC to generate the output .NET code, and the location of the binaries generated and use by the application. This last bit of information is very important, since the VBUC extracts information from the binaries in order to resolve the references between projects and create a VS.NET solution complete with references between the projects:
- Select the Target Language: One of the most significant advantages of using the Visual Basic Upgrade Companion is that it allows you to generate Visual Basic.NET or C# code directly. This can be selected using the combo box in the Upgrade Manager's UI:
- Create a Migration Profile: The Visual Basic Upgrade Companion gives a large degree of control to the end users on how the .NET code will be generated. In addition to the option of creating either C# or VB.NET code, there are also a large amount of transformations that can be turned on/off using the profile manager. Starting with version 2.2, the Profile Manager recognizes the components used in the application and adds a green checkmark to the features that apply transformations to those components. This simplifies profile creation and improves the quality of the generated code from the start:
- Select the Code Typing Mechanism: the VBUC is able to determine the data type for variables in the VB6.0 code that are either declared without type or as Variant. To do this, for each project included in the migration solution you can select three levels of typing: Full Typing, Local Typing or No Typing. Full Typing is the most accurate typing mechanism - it infers the type for the variables depending on how they are used throughout the project. This means that it needs to analyze the complete source code in order to make typing decisions, which slows the migration process and has higher memory consumption. Local Typing also infers data types but only within the current scope of the variable. And No Typing leaves the variables with the same data types from the VB6.0 code:
After going through these 5 steps, you will have an Upgrade Solution ready to go that will generate close to optimal code. The next step is just to hit the "Start" button and wait for the migration to finish:
A few days ago we posted some new case studies to our site. These case studies highlight the positive impression that the capabilities of the Visual Basic Upgrade Companion leave on our customers when we do Visual Basic 6.0 to C# migrations.
The first couple of them deal with a UK company called Vertex. We did two migration projects with them, one for a web-based application, and another one for a desktop application. Vertex had a very clear idea of how they wanted the migrated code to look like. We added custom rules to the VBUC in order to meet their highly technical requirements, so the VBUC would do most of the work and speed up the process. Click on the links to read the case studies for their Omiga application or for the Supervisor application.
The other one deals with a Texas-based company called HSI. By going with us they managed to move all their Visual Basic 6.0 code (including their data access and charting components) to native .NET code. They estimate that by using the Visual Basic Upgrade companion they saved about a year in development time and a lot of money. You can read the case study here.
In Visual Basic 6.0 you can specify optional parameters in a function or sub signature. This, however, isn't possible in .NET. In order to migrate code that uses this optional parameters, the Visual Basic Upgrade Companion creates different overload methods with all the possible combinations present in the method's signature. The following example will further explain this.
Take this declaration in VB6:
Public Function OptionSub(Optional ByVal param1 As String, Optional ByVal param2 As Integer, Optional ByVal param3 As String) As String
OptionSub = param1 + param2 + param3
End Function
In the declaration, you see that you can call the function with 0, 1, 2 or 3 parameters. When running the code through the VBUC, you will get four different methods, with the different overload combinations, as shown below:
static public string OptionSub( string param1, int param2, string param3)
{
return (Double.Parse(param1) + param2 + Double.Parse(param3)).ToString();
}
static public string OptionSub( string param1, int param2)
{
return OptionSub(param1, param2, "");
}
static public string OptionSub( string param1)
{
return OptionSub(param1, 0, "");
}
static public string OptionSub()
{
return OptionSub("", 0, "");
}
The C# code above doesn't have any change applied to it after it comes out of the VBUC. There may be other ways around this problem, such as using parameter arrays in C#, but that would be more complex in scenarios like when mixing different data types (as seen above).
Right now we are entering the final stages of testing for the release of the next version of the Visual Basic Upgrade Companion (VBUC). This release is scheduled for sometime within the next month.
One of the most exiting new features of this new release is the addition of Custom Maps. Custom Maps are simple translation rules that can be added to the VBUC so they are applied during the automated migration. This allows end users to fine tune specific mappings so that they better suit a particular application. Or you can actually create mappings for third party COM controls that you use, as long as the APIs for the source and target controls are similar.
The VBUC will include an interface for you to edit these maps:
Also, once you create the map, you can select them using the Profile Editor:
Custom Maps add a great deal of flexibility to the tool. Even though only simple mappings are allowed (simple as in one-to-one mappings, currently it doesn't allow you to add new code before or after the mapped element), this feature allows end users edit, modify or delete any transformation included, and to add your own. By doing this, you can have the VBUC do more work in an automated fashion, freeing up developer's time and speeding up the migration process even more.
While working on a migration project recently, we found a very particular behavior of the TabIndex property when migrating from Visual Basic 6.0 to .NET. It is as follows:
In VB6, we have the following form: (TabIndexes in Red)
Note that TabIndex 0 and 10 correspond to the Frames Frame1 and Frame2. If you stand on the textbox Text1, and start pressing the tab key, it will go through all the controls in the following order (based on the TabIndex): 1->2->3->4->5->6->-7>8->9.
After the migration, we have the same form but in .NET. We still keep the same TabIndex for the components, as shown below:
In this case TabIndex 0 and 10 correspond to the GroupBox Frame1 and Frame2. When going through the control in .NET, however, if you start pressing the tab key, it will use the following order: 1->2->3->7>8->9->4->5->6. As you can see, it first goes through the buttons (7, 8 and 9) instead of going through the textboxes. This requires an incredibly easy fix (just changing the TabIndex on the GroupBox) to replicate the behavior from VB6, but I thought it would be interesting to throw this one out there. This is one of the scenarios where there is not much that the VBUC can do (it is setting the properties correctly on the migration). It is just a difference in behavior between VB6 and .NET for which a manual change IS necessary.
Every once in a while when trying to install the VBUC you may run into error 2869:
This error, as you can see, doesn't really give you any insight on what may be wrong with the installation. Well, thanks to this blog post, here is a quick process you can follow to troubleshoot the installation and get the actual error that is being masked:
- First, you need to have ORCA installed on your system. ORCA is available as part of the Windows SDK.
- Once you have it installed, find the file setup.msi from the VBUC installer package. Right click on it and select "Edit with ORCA" from the popup menu:
- Once in ORCA, in the Table panel, scroll down and highlight the "Error" line. On the right-hand panel right-click and select Add Row:
- In the panel that is displayed, enter "1001" for the Error, and "Error [1]:[2]" on the Message. Press OK and the table should look like the following:
- Once you are done editing, save the file in ORCA, close it, and launch the installer. You will now get a more explanatory error:
As you can see, in this case at least, the error was caused by not having one of the requirements, Visual Studio (2005 or 2008) installed. This only applies to the current version of the VBUC, as the next version will have these issues with the error messages solved. I still wanted to put this out there, as I got some feedback on it last week.
The latest release of the Visual Basic Upgrade Companion improves the support for moving from VB6.0's On Error Statements to C# structured error handling, using try/catch blocks. In this post I will cover a couple of examples on how this transformation is performed.
First of, this is something that you may not need/want in your application, so this is a features managed through the Migration Profile of the application. In order to enable it, in the Profile, make sure the "On Error To Try Catch" feature is enabled.
Now let's get started with the examples.
On Error Resume Next
First of, let's cover one of the most frustrating statements to migrate from VB6.0: the dreaded On Error Resume Next. This statement tells VB6.0 to basically ignore errors and continue execution no matter what. VB6.0 can recover from some errors, so an application can continue without being affected. These same errors, however, can cause an exception in .NET, or may leave the application in an inconsistent state.
Now let's look at a code example in VB6.0:
Private Sub bttnOK_Click()
On Error Resume Next
MsgBox ("Assume this line throws an error")
End Sub
The VBUC would then leave it as follows in C#:
private void bttnOK_Click( Object eventSender, EventArgs eventArgs)
{
//UPGRADE_TODO: (1069) Error handling statement
(On Error Resume Next) was converted to a complex pattern which
might not be equivalent to the original.
try
{
MessageBox.Show("Assume this line throws an error",
Application.ProductName);
}
catch (Exception exc)
{
throw new Exception(
"Migration Exception: The
following exception could be handled in a different
way after the conversion: " + exc.Message);
}
}
Because of this, the decision was made to wrap the code that is in the scope of the On Error Resume Next statement on a try/catch block. This is likely the way it would be implement in a "native" .NET way, as there is no real equivalent functionality to tell C# to ignore errors and continue. Also, the VBUC adds a comment (an UPGRADE_TODO), so the developer can review the scenario and make a judgement call on wether to leave it as it is, or change it in some way. Most of the time, the try/catch block can be limited to just one line of code, but that modification requires some manual intervention. Still, it is easier when there is something already there.
:-)
On Error GoTo <label>
The other common scenario is to have a more structured approach to error handling. This can be illustrated with the following code snippet:
Private Sub bttnCancel_Click()
On Error GoTo errorHandler
MsgBox ("Assume this line throws an error")
exitSub:
Exit Sub
errorHandler:
MsgBox ("An error was caught")
GoTo exitSub
End Sub
Since this code is using a pattern that is very similar to what the try/catch statement would do, the VBUC is able to identify the pattern and move it to the appropriate try/catch block:
private void bttnCancel_Click( Object eventSender, EventArgs eventArgs)
{
try
{
MessageBox.Show("Assume this line throws an error", Application.ProductName);
}
catch
{
MessageBox.Show("An error was caught", Application.ProductName);
}
}
As you can see, the functionality of this type of pattern is replicated completely, maintaining complete functional equivalence with the VB6.0 code.
Overall, the support for converting On Error statements from VB6.0 into the proper structured error handling structures in C# has come a long way. It is now very robust and supports the most commonly used patterns. So, unless you are using some strange spaghetti code or have a very peculiar way of doing things, the VBUC will be able to translate most scenarios without issues. Some of them, as mentioned, may still required human intervention, but let's face it - using On Error Resume Next shouldn't really be allowed in any programming language!! ;-)
Before starting any migration from Visual Basic 6.0 to the .NET Framework (either VB.NET or C#), we always recommend that our clients perform at least a couple of pre-migration tasks that help streamline a potential migration process. Here is a brief summary of some of them:
- Code Cleanup: Sometime we run into applications that have modules that haven't been used in a while, and nobody really knows if they are still in use. Going through a Code Cleanup stage greatly helps reduce the amount of code that needs to be migrated, and avoids wasting effort in deprecated parts
- Code Advisor: It is also recommended that you execute Microsoft's Code Advisor for Visual Basic 6.0. This Visual Studio plug-in analyzes your VB6 code and points out programming patterns that present a challenge for the migration to .NET. Some of these patterns are automatically resolved by the VBUC, but even then, you should always use this rule of thumb: if you use high quality VB6 code as input for the VBUC, you get high-quality .NET code as output. Here is a brief example of the suggestion you'll get from the Code Advisor:
- Arrays that are not based on a zero index: Should be fixed in VB6
- Use of #If: Only the part that evaluates to "true" will be converted. This may cause problems after the conversion
- Use Option Explicit and Late binding, declare X with earlybound types: The VBUC is able to deduce the data types of most variables, but if you have an opportunity to fix this in VB6, you should take advantage of it
- Trim, UCase, Left, Right and Mid String functions: The VBUC is able to detect the data type being used and interpret the function (for example, Trim()), as a correct string function (in the example, Trim$()). It still recommended that you fix it before performing the migration.
There are other tasks that may be necessary depending on the project and client, like developing test cases, training the developers on the .NET Framework, preparing the environment, and countless other specific requirements. But if you are considering a .NET migration, you should at the very least take into consideration performing the tasks mentioned above.
One of the nicest features of the Visual Basic Upgrade Companion version 2.0 is the support for Migration Profiles. These profiles give you control over which translations to use for a particular migration, improving the quality of the generated code and applying only the conversions desired (for example, for specific third party components). Profiles are managed through the Profile Maintenance screen, as shown here:
If look at the screen in some detail, you will see some of the features included with the tool. Here you can select, for example, to convert the MAPI (Mail API) library to the Microsoft.Office.Interop.Outlook component. And it shows that this particular conversion has a coverage of 80%. This particular library shows why Migration Profiles are important. If the application you are migrating is an end-user application that is locally installed in the user's desktop inside your enterprise, and MS Outlook is part of your standard installation on these desktops, then it should save you quite a bit of work to let the VBUC perform this transformation. If, however, it is a server-side application where MS Office is very rarely installed, then having this option selected will only cause you additional work later on, as you will have to go through the code and remove the references.
Other good examples are the ADODB and ADOCOMMON plug-ins. Both of them convert code that uses ADO into ADO.NET. How they do it, however, is completely different. The first plug-in, ADODB, converts ADO into ADO.NET using the SqlClient libraries, so it only works with SQL Server. The ADOCOMMON plug-in, however, generates code that uses the interfaces introduced with version 2.0 of the .NET Framework in the System.Data.Common namespace. This allows the application to connect to any database using an ADO.NET data provider that complies with this interfaces - most major database vendors now have providers that meet that specification. So you can use either transformation depending on your target database!
The previous two examples illustrate the importance of Migration Profiles. As you can see in the screenshot above, the tool currently has a large amount of plug-in with specific transformations. This number is expected to grow over time. I will be covering some of these plug-ins in later posts. Stay tuned!
I was expecting the annoucement near the end of the week, but here it is - The Visual Basic Upgrade Companion version 2.0 was released today! Just in time to attend that other tool's funeral ;)
I am still waiting for the official press release, but at least the press here in Costa Rica is already talking about it (link in spanish). So you know, the VBUC2.0 is a considerable improvement over previous versions of the Companion. Some of the most interesting new features are:
-
Solves over 800 issues reported by our consulting staff, testing team, partners and end-users.
-
Significantly reduces the amount of manual work required to compile the migrated application, so you can start the testing earlier in the migration process
-
Improves the quality of the migrated code
-
Adds the concept of Migration Profiles - you can select from a series of migration features and apply only those that you want to a particular migration. This greatly improves both the quality of the migrated code, and decreases the amount of manual work required after the migration. It also allows greater future expandability of the product.
As you probably know, eye candy sells. And it makes your life easier, too. So the VBUC2.0 includes a new Graphical User Interface called the Upgrade Manager, that incorporates all the features and concepts described above into one easy to use environment:
If you have been thinking about upgrading your VB6 applications to the .NET framework, think no more. With this new version of the VBUC you will be able to have your .NET application up and running in no time!