Upgrading
The Upgrade wizard is invoked whenever you open a Visual Basic 6.0 project in Visual Studio .NET. The wizard makes as few changes to your code as possible while attempting to alter your existing code so it will work in Visual Basic .NET.
Upgrading from Earlier Versions than Visual Basic 6.0
Although you might be able to successfully upgrade Visual Basic 5.0 projects using the Upgrade wizard (the file format is similar to that of Visual Basic 6.0), you won't be able to upgrade ActiveX controls in the project. Your best bet with older versions of Visual Basic is to upgrade them to Visual Basic 6.0 first, and then run the Upgrade wizard.
Upgrading Project Groups
Visual Basic 6.0 enables you to create a project group in which multiple projects are compiled and debugged together. The closest thing to a project group in Visual Basic .NET is a solution, which can contain multiple projects. When converting a project group, you will need to convert one project at a time, starting downstream with the most dependent project, and working your way up the dependency hierarchy.
Upgrading WebClass Projects
The Upgrade wizard that is included with Visual Studio 2003 can upgrade Visual Basic 6.0 WebClass projects (also known as IIS Application projects). This is a new feature in this version of the wizard. The process for upgrading WebClass projects is essentially the same as for any other project type. In addition, you must have Internet Information Services (IIS) installed and running on the upgrade computer, and have Administrative privileges.
When a WebClass project is upgraded, by default the project is created with a new project name of projectname.NET (where projectname is the name of the Visual Basic 6.0 project). This name is used when naming a new IIS virtual directory, and the virtual directory is automatically configured as an application in IIS.
If the virtual directory name already exists on the http://localhost server, which is typical in a repeat upgrade scenario, a number is appended to the virtual directory and project names in order to ensure uniqueness.
When a Visual Basic 6.0 WebClass project is upgraded to Visual Basic .NET, the .ASP file for the project is upgraded to an .ASPX file. Any references to the .ASP file within an HTML template file are not automatically changed to .ASPX references. These are not upgraded because a template file might contain references to other .ASP files that were not part of the WebClass project.
In addition, when files are copied to the new project directory during upgrade, only HTML template files are copied. Any other .HTML files or image files are not copied to the new directory.
HTML files are added to a Visual Basic .NET project as content files by default. However, when a WebClass project is upgraded, HTML files are added as embedded resources. If you add HTML files to the project after upgrading, you must set their Build Action property to Embedded Resource in order to make them visible to the application.
Upgrade Wizard Methodology
The wizard works by converting project types to their .NET equivalents and upgrading the code as best it can. For example, Visual Basic 6.0 forms are converted to .NET Windows Forms, and the properties of controls are converted to equivalent properties of the .NET controls.
What the Wizard Doesn't Handle
However, there are certain Visual Basic 6.0 elements that either have no direct .NET equivalents or that have equivalents that the wizard doesn't attempt to handle. For example, the following items are not upgraded:
ActiveX documents
Collection classes
DDE
Designers
Drag and drop
Generic objects (form/screen/control)
Graphics statements and graphical controls
MDI forms
Sub Main (or default forms)
If you have any of these elements in your project, you can expect to see them listed as errors, warnings, or issues.
Errors, Warnings, and Issues
Each time you upgrade a project, the wizard upgrades most of the code and objects to Visual Basic .NET. However, not all items can be upgraded and they require manual modification after the wizard has run. The Upgrade wizard inserts comments in your code for Errors, Warnings, and Issues (EWIs). The Upgrade wizard can insert 50 EWIs, grouped into six categories:
Upgrade Issues are inserted into your code whenever the wizard meets code that will cause a compile error. Upgrade issues mark items that you need to fix before the program will run.
Upgrade ToDos let you know when code has been partially upgraded and needs finishing before it will run. This type of issue commonly arises when you declare a variable of a type that contains a fixed-size array.
Run-Time Warnings alert you to behavioral differences between Visual Basic 6.0 and VB.NET. For example, you might have code that doesn't cause a compile error in .NET, but that might yield unexpected results at runtime.
Design Issues identify differences in the design of a form. Design issues are recorded only in the upgrade report, and do not appear in the task list.
Upgrade Notes are memos that alert you whenever code is substantially changed. Unlike the other types of warnings, these notes don't show up in the Task List or in the upgrade report. You need to manually find them.
Global Warnings are inserted into the upgrade report to alert you to major issues that need attention, such as differences in data binding.
Each comment is associated with a hyperlink (Ctrl-click) that takes you to a Help topic explaining the issue. Bear in mind that the Upgrade wizard isn't infallible. Be prepared to thoroughly review and test your code, even after all errors, warnings, and issues have been addressed. Just because your code compiles in .NET, that doesn't mean that it works the way you intended it to. Allow plenty of time for the upgrade process, and be very careful about deploying upgraded code.
Upgrading with Command-Line Tools
You can also upgrade using a command-line tool, VBUpgrade.exe. The command-line tool uses the same engine as the wizard and produces the same results, except that no report is generated.
Begin by browsing to the folder where VBUpgrade.exe resides; the default location is:
C:Program FilesMicrosoft Visual Studio .NET 2003Vb7VBUpgrade
Type vbupgrade /? at the command prompt to see a list of the available switches and parameters.
The following statement upgrades a Visual Basic 6.0 project named Project1 to .NET:
vbupgrade c:Project1.vbp /Out c:Project1.NET
Upgrading Script Code
If you use Active Server Pages (ASP) or Windows Scripting Host (WSH) and have your Visual Basic code in scripts rather than VB projects, you can't use the Upgrade wizard to convert the script code to Visual Basic .NET. Follow these steps to use Visual Studio .NET 2003's new “Upgrade Visual Basic 6 Code” option to convert your script code.
1. | Open a Visual Basic .NET project and position your cursor in a code window where you want the converted script code to be placed. |
2. | Open your script code in a text editor and copy it to the Clipboard. |
3. | |
4. | |
5. | Click the References tab and click Add Reference to add any needed references to COM objects. |
6. | Click Upgrade to convert your code, which will appear at the cursor location. |
You might find that your upgraded script code is rather heavily laden with upgrade issues that need your attention. You will need to make the decision whether it's worthwhile to upgrade your script code or to rewrite it from scratch in Visual Basic .NET.
Viewing the Upgrade Report
The Upgrade Wizard will place the upgrade report in the new project folder (unless you upgrade from the command prompt, which only creates comments).
In Visual Studio .NET, double-click the _UpgradeReport.htm node in the Solution Explorer to open the upgrade report.
The Visual Basic 6.0 Compatibility Library
When you upgrade a Visual Basic 6.0 application to Visual Basic .NET, you will notice that there is a reference to the Visual Basic 6.0 Compatibility library (Microsoft.VisualBasic.Compatibility) in your project. The Upgrade Wizard cannot convert all code because of syntactical or architectural differences. The Wizard uses functions in the Compatibility library so that your Visual Basic 6.0 code can run in Visual Basic .NET without extensive modifications. These functions mimic Visual Basic 6.0 behavior while remaining compliant with the common language specification. You might prefer to replace as many of these calls as possible with code that works directly with the native .NET libraries, although this won't necessarily improve performance. The IL code created by the compatibility classes is probably no less efficient than the IL that would be created by native .NET classes.
Common Issues to Resolve
The following are some commonly occurring issues that you might need to resolve after you have upgraded your project to Visual Basic .NET.
Default Properties
Default properties are not supported by the common language runtime (other than indexer properties). If the Upgrade wizard can determine a default property, it will modify your code to state the property explicitly in Visual Basic .NET. If the Upgrade wizard cannot determine the property being referenced, it will leave your code as is and insert a warning highlighting the issue for you to resolve.
Opening and Closing Forms Issues
In Visual Basic 6.0, you can unload a form and later reload it by calling the form's Show method—without the form ever being flushed from memory. In Visual Basic .NET, the Close method for a form calls the Dispose method under the covers, so that the form is automatically garbage-collected. This can cause subtle behavioral differences that might be hard to detect, if your Visual Basic 6.0 code relied on variables retaining values between calls to show the form.
If the form is shown modally, Dispose is not called automatically in .NET when the Close method is invoked. You might need to destroy the object explicitly to clean up resources.
Error Number Differences
In some cases, errors returned by Visual Basic .NET might be different from those returned by Visual Basic 6.0. If you have error-handling code in your Visual Basic 6.0 application that relies on values returned by Err.Number, this might cause different behavior in your application.
If you depend on the return values from Err.Number in your code, you should carefully test the results and modify your code as necessary. Or better yet, switch to structured exception handling in your converted procedures.
DataEnvironment Resource Issues
In Visual Basic 6.0, when you close a DataEnvironment object, any open recordsets and connections are automatically closed. When upgraded to Visual Basic .NET, the DataEnvironment becomes a Public member of the DataEnvironment class; recordsets and connections are not automatically closed.
After upgrading, you need to add code that explicitly closes any open recordsets and connections by calling the Dispose method. Or better yet, use native .NET methods for data binding instead of the DataEnvironment.
Issues with Data Access Code
DAO, RDO, and ADO code all upgrades easily. However, only ADO data binding is supported. If your application relies heavily on data binding, it is probably best to redo the data binding using ADO.NET.
ADO.NET also makes it much easier to work with stored procedures to perform updates. If you have code that cycles through the rows in a recordset to make parameterized calls to stored procedures, you should consider rewriting the code to make use of an ADO.NET DataAdapter.