Chapter 6: Understanding the Visual Basic Upgrade Wizard

When executing a VB6 to .NET migration project, you should apply tools that automate as much of the conversion as possible. The most accessible of those tools is the Visual Basic Upgrade Wizard, part of the Visual Studio.NET IDE and created by ArtinSoft for Microsoft. To ensure a smooth, efficient migration, it is helpful to understand the upgrade wizard supported features in relation to the Visual Basic 6.0 application. From declarations and properties to modules and interfaces, Chapter 6 describes how the tool manages to upgrade from VB6 to .NET. Also, learn about the characteristics of the resulting code, the VB 6.0 upgrade issues that may occur and the tasks you will need to perform after the upgrade wizard had done its job.

How does the Visual Basic Upgrade Wizard works?

The Visual Basic Upgrade Wizard, created by ArtinSoft for Microsoft, is an automated source code upgrade tool that upgrades a project written in Visual Basic 6.0 to a series of files written in Visual Basic .NET. It takes into account the different aspects of software creation and transformation, including program organization, statements, expressions, symbols, data types, literal values and variables, creating a new project, copying each file from the original project into the new one, and modifying the files as necessary. Finally, it generates a report detailing what was done and what you need to do to finish the upgrade.

How is the Upgrade Wizard available?

The upgrade tool is available in two forms: the upgrade wizard that is integrated into the Visual Studio .NET development environment and a command-line tool that is available with the .NET Framework.

What are the Visual Basic .NET project equivalents or alternatives for VB 6.0 project types?

Visual Basic 6.0 Visual Basic .NET
Standard EXE Windows Application
ActiveX DLL Class Library
ActiveX EXE Class Library
ActiveX Control Windows Control Library
ActiveX Document No direct Equivalent Visual Basic .NET can interoperate with ActiveX Documents
DHTML Application No direct equivalent. Use ASP .NET Web Application
IIS Application (WebClass)  No direct equivalent. Use ASP .NET Web Application

When the Upgrade Wizard converts a project, how is the code modified?

  • Language changes: The upgrade wizard transforms Visual Basic 6.0 code to use the new keywords and language structures introduced in Visual Basic .NET.
  • Core functions: References to Visual Basic 6.0 core functions are upgraded to equivalent classes and methods in the .NET Framework, when possible. When there are no equivalent .NET functions, or the upgrade wizard cannot determine the function to use, the wizard adds a note to the code file so you can fix it manually.
  • Forms: Visual Basic 6.0 forms and controls are upgraded to .NET Windows Form Controls equivalents.
  • Web classes: Visual Basic 6.0 Web classes are upgraded to .NET Web Forms.
  • Data: Data and connection objects are upgraded to Visual Basic .NET runtime callable wrappers (RCW) corresponding to data and connection objects. Upgrading these components to ADO.NET requires additional work.
  • User controls: Visual Basic 6.0 ActiveX user control components are upgraded to .NET user controls.

Does the Upgrade Wizard inspect for reference when it upgrades a project?

Yes, when the upgrade wizard upgrades a project to Visual Basic .NET, it inspects the code for references to other files in the project, and to any external libraries, components, COM objects, and files.

Considering the limitations of the Upgrade Wizard, is there a way to customize or extend its functionality?

No, but there’s an enhanced version (or enterprise edition) of the upgrade wizard called the Visual Basic Upgrade Companion, developed and sold by ArtinSoft, the same company that built the Upgrade Wizard for Microsoft. It can parse database schema definition files to obtain additional information about field data types and produce improved Visual Basic .NET code.

This and other enhancements can help you further shorten your upgrade process by automating more of it. It can even be customized to extend its functionality, according to the characteristics of the application to be migrated.

Does the Upgrade Wizard provide any type of information after the conversion process?

When the upgrade wizard upgrades your project, it generates a report that can be used as a guide for the manual changes that your project requires afterwards. It details the results of the upgrade process, as well as a list of issues uncovered during the upgrade that you need to address before your project can be compiled. It’s in in HTML format and you can view it within the Visual Studio .NET development environment, by double-clicking the _UpgradeReport.htm file in Solution Explorer, or in an external Web browser, by choosing Browse With from the File menu.

The top portion of the report contains a list of global issues followed by a listing for each file that was upgraded. By expanding the section for each file, you can view a detailed list of issues that will need to be addressed, along with the location of the code that must be fixed and a description of the issue. The last portion of the report contains general information about the upgrade, including the settings that were used during the upgrade and the location of the new project files.

In addition to the report, the upgrade wizard inserts comments into your upgraded code alerting you to statements that will need to be changed. These comments are displayed as TO DO tasks in the new Visual Studio .NET Task List window, so you can easily see what changes are required. Double-clicking a task in the task list will immediately take you to the relevant line of code. Each task and item in the upgrade report is associated with an online Help topic that gives further information on why the code needs to be changed, and guidance on what you need to do to resolve the issue.

What elements are supported by the Upgrade Wizard?

  • Visual Basic 6.0 language structures: declarations, routines, properties, event handlers, control structures, modules and classes, interfaces, web classes, late binding, type casts, enumerations, and user-defined types.
  • Native libraries: VB, VBA and VBRUN
  • Visual Basic 6.0 Objects: Forms and visual components
  • ActiveX components and controls

How are Visual Basic 6.0 Declarations upgraded?

The upgrade wizard automatically upgrades variable declarations to their equivalent.NET Framework types, following the Visual Basic .NET structure and

taking into account the Visual Basic 6.0 declaration guidelines. For example, in Visual Basic .NET, variables must be declared explicitly, and there is no Variant data type, so in those cases the upgrade wizard changes the code to declare using the Object data type, which is the .NET Framework’s closest equivalent to Variant.

How are Visual Basic 6.0 Routines upgraded?

Parameters can be passed to a procedure or function in one of two ways: by reference (ByRef) or by value (ByVal). When a parameter is passed to a subprocedure by reference, changes made to the parameter’s value affect the actual variable or object passed by the calling procedure. When a parameter is passed by value, the subprocedure uses a copy of the original variable or object, and any changes the subprocedure makes to it do not affect the original.

By default, Visual Basic 6.0 uses the ByRef method when the parameter’s data type is an intrinsic one such as Integer, Long, Boolean, String, and so on. When a parameter uses a non-intrinsic data type, Visual Basic 6.0 passes it by value by default.

By comparison, Visual Basic .NET passes all parameters by value unless otherwise specified. If a parameter keyword is specified in the signature a Visual Basic 6.0 routine, the upgrade wizard will generate the Visual Basic .NET routine accordingly. If ByVal or ByRef are not specified for a parameter in a Visual Basic 6.0 routine, the upgrade wizard will specify ByRef for the parameter.

How are Visual Basic 6.0 Properties upgraded?

In Visual Basic 6.0, properties are defined using the Property Get, Property Let, and Property Set statements. Visual Basic .NET replaces these statements with a new property declaration syntax that uses Get and Set accessors to provide access to the property.

How are Event Handlers built in Visual Basic .NET?

Events in Visual Basic .NET are built on top of delegates, so they are handled very differently from events in Visual Basic 6.0.

The upgrade wizard automatically handles the details surrounding events by generating signatures for the methods according to the rules of the .NET Framework, and by adding the necessary Visual Basic keywords to comply with the Visual Basic .NET events infrastructure.

How Visual Basic 6.0 control structures upgraded to VB.NET?

Some of the Visual Basic .NET control structures are slightly different from the control structures in Visual Basic 6.0. For example, the Wend keyword, that ends

While loops in Visual Basic 6.0, is replaced by End While in Visual Basic .NET. The upgrade wizard automatically upgrades Visual Basic 6.0 flow statements and preserves their functionality.

Are Visual Basic 6.0 Modules and Classes supported by the Upgrade Wizard?

Yes. In Visual Studio 6.0, module and class files have distinct file name extensions (.bas for modules, .cls for classes), and are organized in specific folders within the Project folder. In Visual Basic .NET, modules and class files both have the same file name extension, .vb, and are distinguished from one another by the structure within each file.

The upgrade wizard automatically handles file name upgrades. For each element, the upgrade wizard will compose a name based on a specific structure.

How are Visual Basic 6.0 interfaces handled by the Upgrade Wizard?

In VB 6.0, common classes can be treated as interfaces. The upgrade wizard generates both a class and an interface to replicate this behavior.

What is the VB.NET equivalent for Visual Basic 6.0 WebClass projects and how is this handled by the Upgrade Wizard?

In Visual Basic 6.0, WebClass projects (also known as IIS application projects) are used to create Web applications based on Active Server Pages (ASP) technology. In Visual Basic .NET, ASP.NET Web application projects are used to create Web applications based on the newer ASP.NET technology.

When upgrading WebClass projects with the upgrade wizard, there are some issues that you should consider.

There are two prerequisites for upgrading a WebClass project:

  • Internet Information Services (IIS) must be installed and running on the upgrade computer.
  • You must have administrative privileges that allow you to install applications.

How are Visual Basic 6.0 late-bound objects upgraded?

Both Visual Basic 6.0 and Visual Basic .NET support late-bound objects. However, during the upgrade process, late-bound objects can introduce problems when default properties are resolved, or in cases where the underlying object model has changed and properties, methods, and events need to be upgraded.

There are two ways to correctly upgrade late-bound objects:

  • You can rewrite the original Visual Basic 6.0 code using early-bound objects, so that the upgrade wizard will upgrade it automatically.
  • You can modify the Visual Basic .NET code obtained after the upgrade process to eliminate unnecessary late-bound variables and manually upgrade the affected class members.

You could also use the Visual Basic Upgrade Companion as an alternative solution to the late-bound variable problem. Its Type Inference feature deduces the most appropriate data types for variables, parameters, and returns values, and avoids using generic data types such as Object. When the companion tool encounters an Object variable, it declares the variable using the appropriate type so that you do not have to make manual modifications.

How are Visual Basic 6.0 Type Casts upgraded?

The upgrade wizard upgrades type casting statements using the appropriate type

restrictions. For example, this Visual Basic 6.0 code converts a 16-bit integer to a

string, and then back to an integer.

Are Enumerations supported by the upgrade wizard?

Enumerations, or enums, are a special type of value type. An enum has a name and a set of fields that define values for a primitive data type.

The upgrade wizard automatically upgrades enumerated types and their references to the format used by Visual Basic .NET.

How are the User-Defined Types implemented in Visual Basic .NET?

In Visual Basic 6.0, you can use user-defined types (UDTs) to create groups of data items of different types. In Visual Basic .NET, UDTs are called structures. A structure associates one or more members with each other and with the structure itself. When you declare a structure, it becomes a composite data type, and you can declare variables of that type.

How are Visual Basic 6.0 Native Libraries (VB, VBA, VBRUN) migrated by the upgrade wizard?

The Visual Basic 6.0 native libraries — which provide much of the language’s core functionality — have been replaced by the .NET Framework itself. The .NET Framework provides the .NET languages with core functionality through the System namespace and other namespaces. The upgrade wizard automatically replaces calls to the Visual Basic 6.0 native libraries with calls to the equivalent .NET Framework objects and classes.

How are Visual Basic 6.0 Forms upgraded to VB.NET?

The upgrade wizard converts VB 6.0 forms (files with the file name extension .frm) to Windows Forms, the .NET Framework’s form development system, which uses classes in the System.Windows.Forms.Form namespace. Upgraded form files are saved with the file name extension .vb, like other Visual Basic .NET code files. Each Visual Basic 6.0 form’s properties, methods, and events (PME) is upgraded to an equivalent System.Windows.Forms.Form PMEs.

How are Visual Basic 6.0 Resource Files handled by the upgrade wizard?

As you know, Visual Basic 6.0 supports resource files that have the file name extension .res. Each Visual Basic 6.0 project can have one resource file. Resource files in Visual Basic .NET have the file name extension .resx. They consist of XML entries that specify objects and strings inside XML tags.

When you use the upgrade wizard to upgrade a Visual Basic 6.0 project that has an associated resource file, the wizard automatically upgrades the Visual Basic 6.0 .res file to a Visual Basic .NET .resx file.

How does the Upgrade Wizard handles Form Resources?

Visual Basic 6.0 form binary files (files with the file name extension .frx) contain necessary resources for the main program form, such as images and icons. In Visual Basic .NET, binary resources are encoded into .resx files. Forms can retrieve resources automatically from associated resource files. The upgrade wizard upgrades .frx files to .resx files associated with a Form class.

How is the Measurement Unit Conversion implemented in Visual Basic .NET?

In Visual Basic 6.0, the ScaleMode property can be used to change the coordinate system for a form or PictureBox control from the default scale of twips. Visual Basic .NET does not support multiple coordinate systems; all measurements must be expressed in pixels. When you upgrade a project to Visual Basic .NET, the upgrade wizard automatically converts the design-time coordinates of visual components from twips to pixels. Code that sets the ScaleMode property at run time will cause a compilation error and must be manually modified.

The upgrade wizard also uses upgraded methods in the Microsoft.VisualBasic.Compatibility.VB6 namespace to upgrade run-time modifications of a control’s position.

Can all the Visual Basic 6.0 Native Controls be upgraded to Visual Basic .NET?

The .NET Framework provides equivalents for most of the Visual Basic 6.0 standard user interface controls; however, some Visual Basic 6.0 controls have no .NET equivalents, and others have been renamed.

Can the upgrade wizard convert Control Arrays to their .NET equivalents?

A control array is a group of controls that share the same name, type, and event procedures. Elements of the same control array have their own property settings. The upgrade wizard relies on functions and objects in the Microsoft.VisualBasic.Compatibility.VB6 namespace to upgrade control arrays.

How are the Data Environment modules upgraded to Visual Basic .NET?

Visual Basic 6.0 data environment modules have the file name extension .dsr. They contain information used to create ADO connections and commands to access data, which are upgraded to VB .NET using classes in the Microsoft.VisualBasic.Compatibility.VB6.BaseDataEnvironment, ADODB.Connection and ADODB.Command namespaces, respectively. The upgrade wizard converts Active Designer (.dsr) files to .vb files. Each .vb file contains a class that inherits from Microsoft.VisualBasic.Compatibility.VB6.BaseDataEnvironment.

What does the Upgrade Wizard create when it encounters ActiveX components in a Visual Basic 6.0 application?

The upgrade wizard generates two types of wrappers around each component:

  • A runtime callable wrapper (RCW): The .NET Framework’s Type Library Importer (Tlbimp.exe) creates a RCW for the ActiveX component and all dependent assemblies.
  • A Windows Forms wrapper (WFW): A WFW “merges” the ActiveX component’s native properties, methods, and events with those of System.Windows.Forms.AxHost. This is a class that inherits from System.Windows.Forms.Control and exposes ActiveX controls to the .NET Framework as fully functional Windows Forms controls.

The upgrade wizard adds these wrappers to the project as DLLs, migrates references to the ActiveX component and its properties, methods, and events, and adds any design-time initializations of the component’s properties to the InitializeComponent method.

How does the upgrade wizard converts Visual Basic 6.0 user controls?

VB 6.0 uses user controls that are also known as ActiveX Control projects, to create ActiveX controls. After user controls are compiled, they can be hosted in any container that supports ActiveX, including Visual Basic 6.0 forms and Internet Explorer.

In Visual Basic .NET, Windows Class Library projects are used to create reusable classes and components that can be shared with other projects and hosted in Windows Forms applications. The Windows Class Library template replaces the ActiveX DLL project template in Visual Basic 6.0.

The upgrade wizard transforms Visual Basic 6.0 user controls to Windows Class

Libraries. If the entire project is an ActiveX DLL, the upgrade is automatic. If the project is a standard Visual Basic project that contains User Controls, the upgrade wizard will not create a separate project for these components. After upgrading the application, you should manually create a Class Library project and move the components from the upgraded application to the new project.