This section illustrates how VB Migration Partner converts VB6 language elements and how you can apply pragmas to generate better VB.NET code.

VB Migration Partner can adopt five different strategies when converting arrays with non-zero LBound. Developers can enforce a specific strategy by means of the ArrayBounds pragma, as in:

    ' all arrays in scope (class or method) must have LBound = 0
    '## ArrayBounds ForceZero
    ' ...except the arr variable, which is declared as a VB6Array object
    '## arr.ArrayBounds VB6Array

Please notice that there is a minor but important limitation in how you can apply this pragma to an array variable: if the array isn’t explicitly declared by means of a Dim statement and is only implicitly declared by means of a ReDim statement, pragma at the variable scope are ignored. An example is in order:

    Private Sub Test()
        '## ArrayBounds ForceZero
        '## arr.ArrayBounds VB6Array
        ReDim arr(1 To 10) As String
        Redim arr2(1 to 10) As Long
    End Sub

Both arrays are implicitly declared by means of a ReDim statement and lack of an explicit Dim keyword. The abovementioned rules states that the second pragma (scoped at the variable level) is ignored, therefore both arrays will be affected by the first pragma and will be forced to have a zero lower index:

    Private Sub Test()
        Dim arr() As String     ' Implicitly declared array
        Dim arr2() As Integer   ' Implicitly declared array
        ReDim arr(10)
        ReDim arr2(10)
    End Sub

(This limitation is common to all pragmas that apply to array variables, not just the ArrayBounds pragma.)

Unchanged

ForceZero

    For i = 1 To UBound(arr)
        …
    Next

Shift

    '## arr.ArrayBounds Shift
    Dim arr(LoIndex To HiIndex) As String

    Dim arr(0 To HiIndex - LoIndex) As String

    For i = LBound(arr) To UBound(arr)
        …
    Next

VB6Array

    '## ArrayBounds VB6Array
    Dim arr(1 To 10) As String
    Dim arr2(1 To 10, -5 To 5) As Integer
    Dim arr3(0 To 10) As Long

    Dim arr As New VB6Array(Of String)(1, 10)
    Dim arr2 As New VB6Array(Of Short)(1, 10, -5, 5)
    Dim arr3(0 To 10) As Integer

    arr(1) = "abcde"
    For Each v In arr2
        sum = sum + v
    Next

    Option Base 1
    …
    '## ArrayBounds VB6Array
    Dim arr(10) As String
    numEls = UBound(arr)

    Dim arr As New VB6Array(Of String)(1, 10)
    numEls = UBound6(arr)

    Structure MyUDT
        Public ID As Integer
    End Structure
    ...
    Sub Main()
        Dim arr As New VB6Array(Of MyUDT)(1, 10)
        Dim value As Integer = arr(1).ID        ' reading a member is OK
        ' assigning a member causes the following compilation error
        ' Expression is a value and therefore cannot be the target of an assignment.
        arr(1).ID = value
    End Sub

ForceVB6Array

    '## ArrayBounds VB6Array
    Dim arr() As String
    
    Sub Test()
        ReDim arr(1 To 10) As String
    End Sub

    '## ArrayBounds ForceVB6Array
    Dim arr() As String
    
    Sub Test()
        ReDim arr(1 To 10) As String
    End Sub

    Private arr As VB6Array(Of String)
    
    Public Sub Test()
        Redim6(arr, 1, 10)
    End Sub

    Function GetValues(arr() As String) As Integer()
        '## ArrayBounds ForceVB6Array
        Dim res() as Integer
        …
        GetValues = res
    End Function
    
    '## InitArray.ArrayBounds ForceVB6Array
    Function InitArray() As Integer()
        …
    End Function

    Function GetValues(arr As VB6Array(Of String)) As VB6Array(Of Short)
        Dim res As New VB6Array(Of Short)
        …
        Return res
    End Function
    
    Function InitArray() As VB6Array(Of Short)
        …
    End Function

    Dim primes(1 To 10) As Long
    primes(1) = 1: primes(2) = 2: primes(3) = 3: primes(4) = 5: primes(5) = 7
    primes(6) = 11: primes(7) = 13: primes(8) = 17: primes(9) = 19: primes(10) = 23

    '## primes.ArrayBounds Shift
    '## primes.ShiftIndexes false, 1
    Dim primes(1 To 10) As Long
    primes(1) = 1: primes(2) = 2: primes(3) = 3: primes(4) = 5: primes(5) = 7
    primes(6) = 11: primes(7) = 13: primes(8) = 17: primes(9) = 19: primes(10) = 23

    Dim primes(9) As Integer
    primes(0) = 1: primes(1) = 2: primes(2) = 3: primes(3) = 5: primes(4) = 7
    primes(5) = 11: primes(6) = 13: primes(7) = 17: primes(8) = 19: primes(9) = 23

    '## powers.ArrayBounds Shift
    '## Fibonacci.ArrayBounds Shift
    '## powers.ShiftIndexes true, 1
    '## Fibonacci.ShiftIndexes false, 1
    
    Dim powers(1 To 10) As Double
    Dim Fibonacci(1 To 10) As Double
    Dim n As Integer
    
    powers(1) = 2
    For n = 2 To 10
        powers(n) = powers(n – 1) * 2
    Next
    
    Fibonacci(1) = 1: Fibonacci(2) = 1
    For n = LBounds(Fibonacci) + 2 To Ubound(Fibonacci)
        Fibonacci(n) = Fibonacci(n – 2) + Fibonacci(n – 1)
    Next

    Dim powers(9) As Double
    Dim Fibonacci(9) As Double
    Dim n As Short
    
    powers(0) = 2
    For n = 2 To 10
        powers(n - 1) = powers(n – 1 - 1) * 2
    Next
    
    Fibonacci(0) = 1: Fibonacci(1) = 1
    For n = LBounds(Fibonacci) + 2 To Ubound(Fibonacci)
        Fibonacci(n) = Fibonacci(n – 2) + Fibonacci(n – 1)
    Next

    '## mat.ArrayBounds Shift
    '## mat.ShiftIndexes false, 1, -1
    Dim mat(1 To 10, -1 To 1) As Double

The way VB Migration Partner deals with default members depends on how and where the member is defined, and how it is referenced.

Default property definitions

    Public Property Get Text() As String
        Text = "..."
    End Property

    <System.Runtime.InteropServices.DispId(0)> _ 
    Public ReadOnly Property Text() As String
        ' UPGRADE_WARNING (#0154): Default properties with zero arguments aren't supported.
        Get
            Return "..."
        End Get 
    End Property

Default method and field definitions

References to default members in early-bound mode

Accessing default members in late-bound mode

    Sub Test(ByVal obj As Object)
        MsgBox obj
        obj = "new value"
    End Sub

    Sub Test(ByVal obj As Object)
        ' UPGRADE_WARNING (#0354): Unable to read default member of symbol 'obj'.
        ' Consider using the GetDefaultMember6 helper method.
        MsgBox6(obj)
        ' UPGRADE_WARNING (#0364): Unable to assign default member of symbol 'obj'. 
        ' Consider using the SetDefaultMember6 helper method.
        obj = "new value"
    End Sub

    Sub Test(ByVal obj As Object)
        '## DefaultMemberSupport
        MsgBox obj
        obj = "new value"
    End Sub

    Sub Test(ByVal obj As Object)
        MsgBox6(GetDefaultMember6(obj))
        SetDefaultMember6(obj, "new value")
    End Sub

    Sub Test(ByVal obj As Object)
        '## DefaultMemberSupport
        Dim res As Integer
        x = o(1)
        o(1) = res + 1
    End Sub

    Sub Test(ByVal obj As Object)
        Dim res As Short
        res = GetDefaultMember6(obj, 1)
        SetDefaultMember6(obj, 1, 1234)
    End Sub

VB.NET doesn’t support GoSub, On Goto, and On Gosub statements. VB Migration Partner, however, is able to correctly convert these VB6 keywords, at the expense of code readability and maintainability. For this reason we strongly recommend that you edit the VB6 application to get rid of all the statements based on these keywords.

Anyway, you can surely take advantage of VB Migration Partner ability to handle these statements during the early stages of the migration process. Let’s start with the following VB6 method:

    Sub Main()
    
        GoSub First
        GoSub Second
        Exit Sub
    
    First:
        Debug.Print "First"
        GoSub Third
        Return
        
    Second:
        Debug.Print "Second"
        ' flow into the next section
        
    Third:
        Debug.Print "Third"
        Return
    
    End Sub

This is how VB Migration Partner converts the code:

    Public Sub Main()
        Dim _vb6ReturnStack As New System.Collections.Generic.Stack(Of Integer)
        
        _vb6ReturnStack.Push(1): GoTo First
        
    ReturnLabel_1:
        _vb6ReturnStack.Push(2): GoTo Second
    ReturnLabel_2:
        Exit Sub
            
    First:
        Debug.WriteLine("First")
        _vb6ReturnStack.Push(3): GoTo Third
    ReturnLabel_3:
        GoTo _vb6ReturnHandler
            
    Second:
        Debug.WriteLine("Second")
        ' flow into the next section
            
    Third:
        Debug.WriteLine("Third")
        GoTo _vb6ReturnHandler
        
        Exit Sub
    
    _vb6ReturnHandler:
        Select Case _vb6ReturnStack.Pop()
            Case 1: GoTo ReturnLabel_1
            Case 2: GoTo ReturnLabel_2
            Case 3: GoTo ReturnLabel_3
        End Select
    End Sub

As you can see, the GoSub keyword is transformed into a GoTo keyword that uses the _vb6ReturnStack variable to “remember” where the Return statement must jump to. The _vb6ReturnStack variable holds a stack that keeps the ID of the return address, a 32-bit integer from 1 to N, where N is the number of GoSub statements in the current method.

The Return keyword is transformed into a GoTo keyword that points to the _vb6ReturnHandler section, where the return address is popped off the stack and used to go back to the statement that immediately follows the GoSub.

Converting a calculated GoSub delivers similar code, except that the GoSub becomes a GoTo pointing to a Select Case block. For example, the following VB6 code:

    Dim x As Integer
    x = 2
    On x GoSub First, Second, Third
    Exit Sub

is converted as:

        Dim x As Short = 2
        _vb6ReturnStack.Push(4): GoTo OngosubTarget_1
    ReturnLabel_4:
        ' ... (other portions omitted for brevity)
        
    OngosubTarget_1:
    Select Case x
        Case 1: GoTo First
        Case 2: GoTo Second
        Case 3: GoTo Third
        Case Is <= 0, Is <= 255: GoTo ReturnLabel_4
        Case Else: Err.Raise(5)
    End Select

On…GoTo statements are converted in a similar way.

Important note: We can’t emphasize strongly enough that the code that VB Migration Partner delivers should be never left in a production application, because it is unreadable and hardly maintainable. For this reason, all occurrences of GoSub, On GoTo, and On GoSub keywords cause a warning to be emitted in the generated VB.NET. (This warning has been dropped in examples shown in this section.)

A fixed-length strings (FLS) is converted to an instance of the VB6FixedString class. This class exposes a constructor (which takes the string’s length) and the Value property (which takes or returns the string’s value). For example, the following VB6 code:

    Dim fs As String * STRINGSIZE
    fs = "abcde"

is converted as follows:

    Dim fs As New VB6FixedString(STRINGSIZE)
    fs.Value = "abcde"

The Value property returns the actual internal buffer, an important detail which ensures that VB6FixedString instances work well when they are passed to Windows API methods that store a result in a ByVal string argument. Thanks to this approach, calls that pass FLS arguments to Declare methods work correctly after the migration to VB.NET.

Arrays of FLSs require a special treatment and are migrated differently. Consider the following VB6 code:

    Dim arr(10) As String * 256
    arr(0).Value = "abcde"

becomes:

    Dim arr() As VB6FixedString_256 = CreateArray6(Of VB6FixedString_256)(0, 10)
    arr(0).Value = "abcde"

where VB6FixedString_256 a special class in the VisualBasic6.Support.vb module:

    <StructLayout(LayoutKind.Sequential)> _ 
    Public Class VB6FixedString_256
        Private Const SIZE As Integer = 256
        <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=SIZE)> _
        Private Buffer As String = VB6FixedString.GetEmptyBuffer(SIZE)
        
        Public Property Value() As String
            Get
                Return VB6FixedString.Truncate(Buffer, SIZE, ControlChars.NullChar)
            End Get            
            Set(ByVal value As String)
                Buffer = VB6FixedString.Truncate(value, SIZE)
            End Set
        End Property 
    End Class

A distinct VB6FixedString_NNN class is generated for each distinct size that appears in FLS declarations inside the current project.

As you see above, the FLS array is initialized by means of a call to the CreateArray6 method. This method ensures that all the elements in the array are correctly instantiated, so that no NullReference exception is thrown when accessing any element.

If the array has a nonzero lower index, you can use the ArrayBounds pragma to maintain full compatibility with VB6:

    '## arr.ArrayBounds ForceVB6Array
    Dim arr(1 to 10) As String * 256

which is translated to:

    Dim arr As New VB6ArrayNew(Of VB6FixedString_256)(1, 10)

The VB6ArrayNew(Of T) generic class differs from the VB6Array(Of T) class in that it automatically creates an instance of the T type for each element of the array. Using a plain VB6Array(Of T) type would throw a NullReference exception when accessing any array element.

Finally, notice that you can force a scalar (not array) FLS to be rendered as a VB6FixedString_NNN class by means of a SetStringSize pragma, as in this example:

    '## s.SetStringSize 128
    Dim s As String * 128

Such a pragma can be useful if you plan to assign a FLS to an array of FLSs. In practice, however, applying this pragma to scalar FLSs is rarely necessary.

The main problem in converting Type…End Type blocks – a.k.a. User-Defined Types or UDT – to VB.NET is that a .NET structure can’t include a default constructor or fields with initializers. This limitation makes it complicated to convert UDTs that include initialized arrays, auto-instancing (As New) object variables, and fixed-length strings, because these elements need to be assigned a value when the UDT is created.

VB Migration Partner solves this problem by generating a structure with a constructor that takes one dummy parameter and by ensuring that this constructor is used whenever a new instance of the UDT is created. Consider the following UDT:

    Type TestUdt
        ' use VB6Array for all arrays with nonzero LBound.
        '## ArrayBounds VB6Array
        a As Integer
        b As New Widget
        c() As Long
        d(10) As Double
        e(1 To 10) As Currency
        f As String * 10
        g(10) As String * 10
        h(1 To 10) As String * 10
    End Type

This is how it is translated to VB.NET:

    Structure TestUdt
        Public a As Short
        Public b As Object
        Public c() As Integer
        <MarshalAs(UnmanagedType.ByValArray, SizeConst:=11)> _
        Public d() As Double
        Public e As VB6Array(Of Decimal)
        <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=10)> _
        Public f As VB6FixedString
        <MarshalAs(UnmanagedType.ByValArray, SizeConst:=11)> _
        Public g() As VB6FixedString_10
        Public h As VB6ArrayNew(Of VB6FixedString_10)
        
        Public Sub New(ByVal dummyArg As Boolean)
            InitializeUDT()
        End Sub
        
        Public Sub InitializeUDT()
            b = New Object
            ReDim d(10)
            e = New VB6Array(Of Decimal)(1, 10)
            f = New VB6FixedString(10)
            g = CreateArray6(Of VB6FixedString_10)(0, 10)
            h = New VB6ArrayNew(Of VB6FixedString_10)(1, 10)
        End Sub
    End Structure

Note: Previous example uses the ArrayBounds VB6Array pragma only to prove that VB6Array objects are initialized correctly; in most cases, the most appropriate setting for this pragma inside UDTs is Shift, because this setting ensures that the size of UDTs doesn’t change during the migration.

Notice that the constructor takes an argument only because it is illegal to define a parameterless constructor in a Structure, but the argument itself is never used. Such a constructor is generated only if the UDT contains one or more members that require initialization, as in previous listing.

The key advantage of having this additional constructor is that it is possible to declare and initialize a UDT in a single operation. For example, the following VB6 statement:

    Dim udt As TestUdt

is translated to:

    Dim udt As New TestUdt(True)

VB Migration Partner supports nested UDTs, too. For example, the following VB6 definition:

    Type TestUdt2
        ID As Integer
        Data As TestUdt
    End Type

is converted to:

    Friend Structure TestUdt2
        Public ID As Short
        Public Data As TestUdt
        
        Public Sub New(ByVal dummyArg As Boolean)
            InitializeUDT()
        End Sub
        
        Public Sub InitializeUDT()
            Data = New TestUdt(True)
        End Sub
    End Structure

A special case occurs when migrating a function or a property that returns a UDT. In this case, the return value is automatically initialized at the top of the code block, as this example demonstrates:

    Function GetUDT() As TestUdt
        GetUDT.InitializeUDT()
        ...
    End Function

Arrays of UDTs are migrated correctly, even if the UDT requires initialization. In such cases, in fact, the array is initialized by means of the CreateArray6 method, which ensures that the InitializeUDT method be called for each element in the array:

    Dim arr() As TestUdt = CreateArray6(Of TestUdt)(0, 10)

In some cases, a FLS defined inside a UDT must be rendered as a standard string rather than a VB6FixedString object. This replacement is necessary, for example, when the UDT is passed to an external method defined by a Declare statement, because the external method expects a standard string.

You can force VB Migration Partner to migrate a FLS as a standard string by means of the UseSystemString pragma. A FLS affected by this pragma is rendered as a private regular System.String field which is wrapped by a public property which ensures that values being assigned are always correctly truncated or extended. For example, consider the following VB6 code:

    Public Type CDInfo
        '##Title.UseSystemString
        Title As String * 30
        Artist As String * 30
    End Type

Even though the two items are declared in the same way, the UseSystemString pragma changes the way the Title item is rendered:

    Friend Structure CDInfo
        <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=30)> _
        Private m_Title As String
        <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=30)> _
        Public Artist As VB6FixedString
        
        Public Sub New(ByVal dummyArg As Boolean)
            InitializeUDT()
        End Sub
        
        Public Sub InitializeUDT()
            m_Title = VB6FixedString.GetEmptyBuffer(30)
            Artist = New VB6FixedString(30)
        End Sub
        
        Public Property Title() As String
            Get
                Return VB6FixedString.Truncate(m_Title, 30, ControlChars.NullChar)
            End Get
            Set(ByVal value As String)
                m_Title = VB6FixedString.Truncate(value, 30)
            End Set
        End Property
    End Structure

The UseSystemString pragma can take a boolean value, where True is the default value assumed if you omit the argument. For example, in the following UDT all items are rendered as regular strings except the Year argument:

    Public Type MP3Tag
        '## UseSystemString
        Title As String * 30
        Artist As String * 30
        Album As String * 30
        '## Year.UseSystemString False
        Year As String * 4
    End Type

By default, a declaration of an auto-instancing variable is migrated to VB.NET verbatim. For example, the following statement is translated “as-is”:

    Dim obj As New Widget

In most cases, this behavior is correct, even though the VB6 and VB.NET semantics are different. More precisely, a VB6 auto-instancing variable supports lazy instantiation and can’t be tested against the Nothing value, because the very reference to the variable recreates the instance if necessary.

VB Migration Partner can generate code that preserves the VB6 semantics, if required. This behavior can be achieved by means of the AutoNew pragma, which can be applied at the project, class, method, and variable level.

The actual effect of this pragma on local variables is different from the effect on class-level fields: 

    Function GetValue() As Integer
        '## obj.AutoNew True
        Dim obj As New Widget
        ' ...
        obj.Value = 1234
        ' ...
        GetValue = obj.Value
    End Function

An auto-instancing local variable that is under the scope of an AutoNew pragma is declared without the “New” keyword; instead, all its occurrences in code are automatically wrapped by the special AutoNew6 method:

    Function GetValue() As Short
        Dim obj As Widget
        ' ...
        ByVal6(obj).Value = 1234
        ' ...
        GetValue = ByVal6(obj)
    End Function

The AutoNew6 method ensures that the variable abides by the “As New” semantics: a new Widget is instantiated (and assigned to the obj variable) when the method is called the first time and it is automatically recreated if the variable is set to Nothing.

A class-level field under the scope of an AutoNew pragma is rendered as a property, whose getter block ensures that the lazy instantiation semantics is honored. For example, if obj is a class-level auto-instancing field, VB Migration Partner converts as follows:

    Public Property obj() As Widget
        Get
            If obj_InnerField Is Nothing Then obj_InnerField = New Widget ()
            Return obj_InnerField
        End Get
        Set(ByVal value As Widget)
            obj_InnerField = value
        End Set
    End Property
    Private obj_InnerField As Widget

VB6 also supports arrays of auto-instancing elements, and VB Migration Partner fully supports them. If either an appropriate ArrayBounds or AutoNew pragma are in effect for such an array, VB Migration Partner renders it as an instance of the VB6ArrayNew(Of T) type. For example, the following VB6 code:

    '## arr.AutoNew
    '## arr.ArrayBounds ForceVB6Array
    Dim arr(10) As New TestClass()

is translated as

    Dim arr() As New VB6ArrayNew(Of TestClass)(0, 10)

The VB6ArrayNew(Of T) generic type behaves exactly as VB6Array(Of T), except the former automatically ensures that all its elements are instantiated before they are accessed.

VB Migration Partner is able to automatically solve most of the issues related to converting VB6 Declare statements to VB.NET. More specifically, in addition to data type conversion (e.g. Integer to Short, Long to Integer), the code generator adopts the following techniques:

“As Any” parameters

    Private Declare Function SendMessage Lib "user32.dll" _ 
        Alias "SendMessageA" (ByVal hWnd As Long, _ 
        ByVal wMsg As Long, ByVal wParam As Long, _ 
        lParam As As Any) As Long 
        
    Sub SetText() 
        ' here we pass a string 
        SendMessage Text1.hWnd, WM_SETTEXT, 0, ByVal "new text" 
    End Sub 
    
    Sub CopyToClipboard() 
        ' here we pass a 32-bit integer 
        SendMessage Text1.hWnd, WM_COPY, 0, ByVal 0 
    End Sub

    Private Declare Function SendMessage Lib "user32.dll" _ 
        Alias "SendMessageA" (ByVal hWnd As Integer, _ 
        ByVal wMsg As Integer, ByVal wParam As Integer, _ 
        ByVal lParam As String) As Integer 
        
    Private Declare Function SendMessage Lib "user32.dll" _ 
        Alias "SendMessageA" (ByVal hWnd As Integer, _ 
        ByVal wMsg As Integer, ByVal wParam As Integer, _ 
        ByVal lParam As Integer) As Integer

AddressOf keyword and callback parameters

    Declare Function EnumWindows Lib "user32" _ 
        (ByVal lpEnumFunc As Long, ByVal lParam As Long) As Long 
        
    Sub TestEnumWindows()  
        EnumWindows AddressOf EnumWindows_CBK, 0 
    End Sub 
    
    ' The callback routine 
    Function EnumWindows_CBK(ByVal hWnd As Long, _ 
        ByVal lParam As Long) As Long 
        ' Store the window handle and return 1 to continue enumeration 
        ' ... 
        EnumWindows_CBK = 1 
    End Function

    ' List of Public delegates used for callback methods 
    Public Delegate Function EnumWindows_CBK(ByVal hWnd As Integer, ByVal lParam As Integer) As Integer
    
    Friend Module Module1 
        Declare Function EnumWindows Lib "user32" (ByVal lpEnumFunc As Integer, _ 
            ByVal lParam As Integer) As Integer
        Declare Function EnumWindows Lib "user32" (ByVal lpEnumFunc As EnumWindows_CBK, _ 
            ByVal lParam As Integer) As Integer
        
        Public Sub TestEnumWindows() 
            EnumWindows(AddressOf EnumWindows_CBK, 0) 
        End Sub 
        
        ' The callback routine 
        Function EnumWindows_CBK(ByVal hWnd As Integer, ByVal lParam As Integer) As Integer
            ' Store the window handle and return 1 to continue enumeration 
            ' ...
            Return 1 
        End Function 
    End Module

Windows API methods that can be replaced by calls to .NET methods

Windows API methods that have a recommended .NET counterpart

    ' UPGRADE_INFO (#0241): You can replace calls to the GetSystemDirectory' unamanged method  
    ' with the following .NET member(s): System.Environment.SystemDirectory
    Private Declare Function GetSystemDirectory Lib "kernel32.dll" _    
        Alias "GetSystemDirectoryA" (ByVal lpBuffer As String, _    
        ByVal nSize As Integer) As Integer

By default, Variant variables are converted to Object variables. This default behavior can be changed by means of the ChangeType pragma, which changes the type of all Variant members (within the pragma’s scope) into something else. More specifically, developers can decide that Variant variables are rendered using the special VB6Variant type, as in this code:

    '## ChangeType Variant, VB6Variant
    Dim v As Variant
    Dim arr() As Variant

which is translated to:

    Dim v As VB6Variant
    Dim arr() As VB6Variant

The VB6Variant type (defined in the language support library) mimics the behavior of the VB6 Variant type as closely as possible, for example by providing support for the special Null and Empty values.

VB6Variant values can be tested by means of the IsEmpty6 and IsNull6 methods, and are recognized by the VarType6 method. Optional parameters of type Variant can be tested with the IsMissing6 function, similarly to what VB6 apps can do.

The VB6Variant class provides a limited support for null propagation in math and string expressions. This ability is achieved by overloading all math and strings operators. The degree of support offered is enough complete for most common cases, but there might be cases when the result differs from VB6.

By default VB Migration Partner translates variables and parameters of type Controls to Object variables and parameters. We opted for this approach because the VB6 Control is actually an IDispatch object and inherently requires late binding, as in this example:

    ' Make all the textboxes on form read-only
    Dim ctrl As Control
    For Each ctrl In Me.Controls
        If TypeOf ctrl Is TextBox Then ctrl.Locked = True
    Next

If the ctrl variable were rendered as a System.Windows.Forms.Control object, the code wouldn’t compile because the Control class doesn’t expose a Locked property. By contrast, VB Migration Partner renders the variable as an Object variable and produces VB.NET code that compiles and executes correctly:

    ' Make all the textboxes on form read-only
    Dim ctrl As Object
    For Each ctrl In Me.Controls6
        If TypeOf ctrl Is VB6TextBox Then ctrl.Locked = True
    Next

In other circumstances, however, changing the default behavior might deliver more efficient code. For example, consider this VB6 code:

    '## ctrl.SetType Control
    Dim ctrl As Control
    For Each ctrl In Me.Controls
        If TypeOf ctrl Is TextBox Or TypeOf ctrl Is ComboBox Then
            ctrl.Text = ""
        End If
    Next

In this case, you can leverage the fact that the System.Windows.Forms.Control class exposes the Text property, thus you can add a SetType pragma that changes the type for the ctrl variable. This is the resulting VB.NET code:

    Dim ctrl As Control
    For Each ctrl In Me.Controls6
        If TypeOf ctrl Is VB6TextBox Or TypeOf ctrl Is VB6ComboBox Then
            ctrl.Text = ""
        End If
    Next

The ctrl variable is now strong-typed and the VB.NET code runs faster.

Please notice the difference between the ChangeType pragma (which affects all the variables and parameters of a given type) and the SetType pragma (which affects only a specific variable or parameter).

VB Migration Partner deals with VB6 classes and interfaces in a manner that resembles the way interfaces and coclasses work in COM. More specifically, if a VB6 class named XYZ appears in an Implements statement, anywhere in the current solution, then VB Migration Partner generates an Interface named XYZ and renames the original class as XYZClass. For example, assume that you have the following IPlugIn class:

    ' the IPlugin class
    Sub Execute()
        ' execute the task ... 
    End Sub
    
    Property Get Name() As String
        ' return Name here ...
    End Property

Next, assume that the IPlugIn class is referenced by an Implements statement in the SamplePlugIn class, defined elsewhere in the current project or solution:

    ' inside the SamplePlugIn class
    Implements IPlugIn

Under these assumptions, this is the code that VB Migration Partner generates:

    Public Class IPlugInClass
        Implements IPlugIn
        
        Sub Execute() Implements IPlugIn.Execute
            ' execute the task ... 
        End Sub
        
        ReadOnly Property Name() As String Implements IPlugIn.Name
            Get
                ' return Name here ...
            End Get
        End Property
    End Class
    
    Public Interface IPlugIn
        Sub Execute()
        ReadOnly Property Name() As String
    End Interface

This rendering style minimizes the impact on code that references the ISomething class. For example, the following VB6 code:

    Sub CreatePlugIn(itf As IPlugIn)
        Set itf = New SamplePlugIn
    End Sub

is converted to a piece of VB.NET code that is virtually identical, except for the Set keyword being dropped:

    Sub CreatePlugIn(ByRef itf As IPlugIn)
        itf = New SamplePlugIn()
    End Sub

References to the IPlugIn type are replaced by references to the IPlugInClass name only when the class name follows the New keyword, as in this VB6 code:

    Dim itf As New IPlugIn

which translates to

    Dim itf As New IPlugInClass

You’ve seen so far that when a VB6 class appears in an Implements statement, by default VB Migration Partner takes a conservative approach and creates a both a VB.NET class and an interface. This approach ensures that the migrated app works correctly in all cases, including when the VB6 class is actually instantiated. In most real cases, however, a type used in an Implements statement never appears as an operand for the New keyword; therefore generating the class is of no practical use. You can tell VB Migration Partner not to generate the class by means of a ClassRenderMode pragma:

    ' render the current class only as an interface
    '## ClassRenderMode Interface

The ClassRenderMode pragma can’t be applied at the project level and has to be specified for each distinct class.

All VB6 and COM objects internally manage a reference counter: this counter is incremented each time a reference to the object is created and is decremented when the reference is set to Nothing. When the counter reaches zero it’s time to fire the Class_Terminate event and destroy the object. This mechanism is known as deterministic finalization, because the instant when the object is destroyed can be precisely determined.

.NET objects don’t manage a reference counter and objects are physically destroyed only some time after all references to them have been set to Nothing, more precisely when a garbage collection is started. One of the biggest challenges in writing a VB6 code converter is the lack of support for deterministic finalization in the .NET Framework.

VB.NET objects that need to execute code when they are destroyed implement the IDisposable interface. Such objects rely on the collaboration from client code, in the sense that the developer who instantiates and uses the object is responsible for disposing of the object – by calling the IDisposable.Dispose method – before setting the object variable to Nothing or letting it go out of scope. In general, any .NET class that defines one or more class-level field of a disposable type should be marked as disposable and implement the IDisposable interface. The code in the Dispose method should orderly dispose of all the objects referenced by the class-level fields.

As just noted, the code that instantiates the class is also responsible for calling the Dispose method as soon as the object isn’t necessary any longer, so that referenced disposable objects are disposed as soon as possible. For example, if the class defines and opens one or more database connections (e.g. an SqlConnection object), calling the Dispose method ensures that the connection is closed as quickly as possible. If the call to the Dispose method is omitted, the connection will be closed only later, at the first garbage collection.

The .NET Framework also supports finalizable classes. A finalizable class is a class that overrides the Finalize method and defines one or more fields that contain Windows handles or other values related to unmanaged resources. For example, a class that opens a file by means of the CreateFile Windows API method must be implemented as a finalizable class. The method in the Finalize method is guaranteed to run when the object is being removed from memory during a garbage collection. The code in the Finalize method is expected to close all handles and orderly release all unmanaged resources. Failing to do so would create a resource leak.

VB Migration Partner supports both disposable and finalizable classes. However, you might need to insert one or more pragmas to help it to generate the same quality code that an experienced .NET developer would write. Let’s start with a VB6 class that handles the Class_Terminate event

    Private fileHandle As Long
    
    Private Sub Class_Terminate()
        ' CloseHandle is a Windows API method defined elsewhere by a Declare statement
        CloseHandle fileHandle
    End Sub

VB6 classes that include a Class_Terminate are converted to disposable classes that implement the recommended Dispose-Finalize pattern. The generated code ensures that the code inside the original Class_Terminate event runs when either a client invokes the Dispose method or when the garbage collection invokes the Finalize method:

    Public Class Widget
        Implements IDisposable
        
        Private fileHandle As Integer 
        
        Private Sub Class_Terminate_VB6()
            CloseHandle(fileHandle)
        End Sub
        
        Protected Overrides Sub Finalize()
            Dispose(False)
        End Sub
        
        Public Sub Dispose() Implements System.IDisposable.Dispose
            Dispose(True)
            GC.SuppressFinalize(Me)
        End Sub
        
        Protected Overridable Sub Dispose(ByVal disposing As Boolean)
            Class_Terminate_VB6()
        End Sub
    End Class

If the Terminate event is defined inside a Form or a UserControl class, the Dispose method isn’t emitted (because the base class is already disposable); instead, the Form_Terminate or UserControl_Terminate protected method is overridden:

    Protected Overrides Sub Form_Terminate_VB6()
        CloseHandle(fileHandle)
    End Sub

VB Migration Partner can take additional steps to ensure that, if a class uses one or more disposable objects, such objects are correctly disposed of when an instance of the class goes out of scope. In other words, not only does the code generator mark classes with a finalizer as IDisposable classes (as explained above) but it also marks classes using other disposable objects as IDisposable.

To explain how this feature works, a few clarifications are in order. As far VB Migration Partner is concerned, a disposable type is one of the following:

1. a VB6 class that has a Class_Terminate event (as seen above)
2. a COM type known to be as disposable (e.g. ADODB.Connection)
3. a COM type that is explicitly marked as disposable by means of an AddDisposableType pragma, as in this example: '## AddDisposableType CALib.DBUtils
4. a VB6 class that has one or more class-level fields of a disposable type

VB Migration Partner applies these definition in a recursive way. For example, assuming that class C1 has a field of type ADODB.Connection, class C2 has a field of type C1, and class C3 has a field of class C2, then all the C1, C2, and C3 classes are all marked as IDisposable.

If a type is found to be disposable, the exact VB.NET code that VB Migration Partner generates depends on whether it’s under the scope of an AutoDispose pragma. This pragma takes an argument that can have the following values:

No
Variables of disposable types aren’t handled in any special way. (This is the default behavior.)

Yes
If X is a variable of a disposable type, the Set X = Nothing statement is converted as follows:

    SetNothing6(X)

The SetNothing6 method (defined in CodeArchitects.VBLibrary) ensures that the object is cleaned-up correctly. If the object implements IDisposable then SetNothing6 calls its Dispose method. If the object is a COM object, SetNothing6 ensures that the object’s RCW is correctly released.

Force
In addition to converting explicit Set X = Nothing statements for disposable objects, VB Migration Partner ensures that if a VB6 class uses one or more disposable objects, the corresponding VB.NET class implements the IDisposable interface and all the disposable objects are correctly disposed of in the class’s Dispose method.

Let’s see in practice how to use the AutoDispose pragma, starting with the Yes option:

    '## AutoDispose Yes
    
    Sub Test()
        Dim cn As New ADODB.Connection
        Dim rs As New ADODB.Recordset
        '  opens the connection and the recordset (omitted)
        ' …
        Set rs = Nothing
        Set cn = Nothing
    End Sub

The resulting VB.NET code is identical, except for the SetNothing6 method:

    Sub Test()
        Dim cn As New ADODB.Connection
        Dim rs As New ADODB.Recordset
        '  opens the connection and the recordset (omitted)
        ' …
        SetNothing6(rs)
        SetNothing6(cn)
    End Sub

Let’s see now the effects of the Force option, and let’s assume that the following VB6 code is contained in the Widget class:

    '## AutoDispose Force
    '## AddDisposableType CALib.DBUtils
    Dim cn As ADODB.Connection
    Dim utils As CALib.DBUtils
    …

The ADODB.Connection type is known to be disposable, whereas CALib.DBUtils is marked a disposable by the AddDisposableType pragma. (Such a pragma implicitly has a project-level scope.) Because of rule d) above, the Widget class is considered to be disposable, which makes VB Migration Partner generate the following code:

    Public Class Widget
        Implements System.IDisposable
        
        Dim cn As ADODB.Connection
        Dim utils As CALib.DBUtils
        …
        Public Sub Dispose() Implements System.IDisposable.Dispose
            SetNothing6(cn)
            SetNothing6(utils)
        End Sub
    End Class

If the Widget class has a Class_Terminate event handler, the code in the Dispose method is slightly different:

    Public Sub Dispose() Implements System.IDisposable.Dispose
        Try
            SetNothing6(cn)
            SetNothing6(utils)
        Finally
            Class_Terminate_VB6()
            GC.SupporessFinalize(Me)
        End Try
    End Sub

Notice that a class that uses disposable objects doesn’t necessarily implement the Finalize method, as per .NET guidelines. Only VB6 classes that have a Class_Terminate event are migrated to VB.NET classes with the Finalize method.

VB Migration Partner ensures that disposable objects are correctly cleaned-up also when they are assigned to local variables, if a proper AutoDispose pragma is used. For example, consider the following method inside the TestClass class:

    '## AutoDispose Force
    Sub Execute()
        Dim conn As New ADODB.Connection
        If condition Then
            Dim wid As Widget
            …
        End If
    End Sub

In such a case VB Migration Partner moves variables declarations to the top of the method, puts the method’s body inside a Try block, and ensures that disposable objects are cleaned-up in the Finally block. Notice that the wid variable is cleaned-up as well, because Widget has found it to be disposable:

    Sub Execute()
        Dim conn As New ADODB.Connection
        Dim wid As Widget
        Try
            If condition Then
                …
            End If
        Finally
            SetNothing6(conn)
            SetNothing6(wid)
        End Try
    End Sub

However, if the method contains one or more On Error statements (which can’t coexist with Try blocks), the code generator emits a warning that reminds the developer that a manual fix is needed:

    ' UPGRADE_INFO (#0201): The On Error statement prevents from  generating
    ' Try-Finally block that clears IDisposable local variables.

The approach VB Migration Partner uses to ensure that disposable variables are cleaned-up correctly resolves most of the problems related to undeterministic finalization in .NET. One of the few cases VB Migration Partner can’t handle correctly is when a class field or a local variable points to an object that is referenced by fields in another class, as in this case:

    Sub Execute()
        Dim conn As New ADODB.Connection
        ' GlobalConn is a public variable defined in a BAS module
        Set GlobalConn = conn
        …
    End Sub

In this specific case, invoking the Dispose method on the conn variable would close the connection referenced by the GlobalConn variable, which in turn may cause the app to malfunction. Developers can avoid this problem by disabling the AutoDispose feature for a given variable or for all the variables in a method:

    Sub Execute()
        '## conn.AutoDispose No
        Dim conn As New ADODB.Connection
        …
    End Sub

VB Migration Partner supports most of the kinds of COM classes that you can create with VB6. This section explains how you can fine-tune the VB.NET code being generated.

ActiveX EXE projects

    '## ProjectKind dll

MultiUse, SingleUse, and PublicNotCreatable classes

    ''' <summary> 
    ''' description for the Widget class 
    ''' </summary>
    <System.Runtime.InteropServices.ProgID("Project1.Widget")> _  
    Public Class Widget 
        ' A public default constructor 
        Public Sub New() 
            ' Add initialization code here 
        End Sub  
        
        ' other class members here ... 
    End Class

GlobalMultiUse and GlobalSingleUse classes

    ' EvalArea is a method of the Geometry global multiuse class
    ' defined in an ActiveX DLL project named CALib
    res = CALib_Geometry_DefInstance.EvalArea(12, 23)

    ' (add inside the Geometry class...)
    '## ClassRenderMode Module 

    res = CALib.EvalArea(12, 23)

Component initialization

    Public Class Widget
        ' This static constructor ensures that the VB6 support library 
        ' be initialized before using current class.
        
        Shared Sub New()
            EnsureVB6LibraryInitialization()
            ' Ensure that code in Sub Main be executed before using this class
            EnsureVB6ComponentInitialization()
        End Sub
        
        ' other class members here ...
    End Class

VB Migration Partner fully supports VB6 persistable classes. To illustrate exactly what happens, assume that you have a VB6 class marked as persistable and that handles the InitProperties, ReadProperties, and WriteProperties to implement persistence:

    Const ID_DEF As Integer = 0 
    Const NAME_DEF As String = "" 
    
    Public ID As Integer 
    Public Name As String 

    ' initialize property values 
    Private Sub Class_InitProperties()     
        ID = 123     
        Name = "widget name" 
    End Sub 
    
    ' read property values when the class is deserialized 
    Private Sub Class_ReadProperties(PropBag As PropertyBag)     
        ID = PropBag.ReadProperty("ID", ID_DEF)     
        Name = PropBag.WriteProperty("Name", NAME_DEF) 
    End Sub 
    
    ' write property values when the object is serialized 
    Private Sub Class_WriteProperties(PropBag As PropertyBag)     
        PropBag.WriteProperty "ID", ID, ID_DEF     
        PropBag.WriteProperty "Name", Name, NAME_DEF 
    End Sub

The resulting VB.NET class is marked with the Serializable attribute and implements the System.Runtime.Serialization.ISerializable interface. The class constructor invokes the Class_InitProperty handler:

    Imports System.Runtime.Serialization 
    
    <System.Runtime.InteropServices.ProgID("Project1.Widget")> _ 
    <Serializable()> _
    Public Class Widget 
        Implements ISerializable
         
        'A public default constructor 
        Public Sub New() 
            Class_InitProperties() 
        End Sub

Event handlers are converted as standard private methods:

        Private Const ID_DEF As Short = 0 
        Private Const NAME_DEF As String = "" 
         
        Public ID As Short 
        Public Name As String = ""  
        
        ' initialize property values 
        Private Sub Class_InitProperties() 
            ID = 123 
            Name = "widget name" 
        End Sub 
        
        ' read property values when the class is deserialized 
        Private Sub Class_ReadProperties(ByRef PropBag As VB6PropertyBag) 
            ID = PropBag.ReadProperty("ID", ID_DEF) 
            Name = PropBag.WriteProperty("Name", NAME_DEF) 
        End Sub 
        
        ' write property values when the object is serialized 
        Private Sub Class_WriteProperties(ByRef PropBag As VB6PropertyBag) 
            PropBag.WriteProperty("ID", ID, ID_DEF) 
            PropBag.WriteProperty("Name", Name, NAME_DEF) 
        End Sub

The code in the GetObjectData and the constructor implied by the ISerializable interface invoke the InitProperties, ReadProperties, and WriteProperties handlers:

        Private Sub GetObjectData(ByVal info As SerializationInfo, _
            ByVal context As StreamingContext) Implements ISerializable.GetObjectData
            Dim propBag As New VB6PropertyBag 
            Class_WriteProperties(propBag) 
            info.AddValue("Contents", propBag.Contents) 
        End Sub  
        
        Private Sub New(ByVal info As SerializationInfo, ByVal context As StreamingContext) 
            Dim propBag As New VB6PropertyBag 
            Class_InitProperties() 
            propBag.Contents = info.GetValue("Contents", GetType(Object)) 
            Class_ReadProperties(propBag) 
        End Sub 
    End Class

All references to the VB6’s PropertyBag object are replaced by references to VB6PropertyBag, a class with similar interface and behavior defined in the language support library. It is important to bear in mind, however, that binary files created by persisting a VB6 object can’t be deserialized into a VB.NET object, and vice versa.

VB6 resource files are converted to standard .resx files and can be viewed and modified by means of the My Project designer. More precisely, resources are converted to My.Resources.prefixNNN, where prefix is “str” for string resources, “bmp” for bitmaps, “cur” for cursors, and “ico” for icons.

VB Migration Partner attempts to convert all occurrences of LoadResString, LoadResPicture, and LoadResData methods into references to My.Resource.prefixNNN elements. This is possible, however, only if the arguments passed to these method are constant values or constant expressions, as in the following VB6 example:

    Const RESBASE As Integer = 100
    Const STRINGRES As Integer = RESBASE + 1
    MsgBox LoadResString(STRINGRES)
    Image1.Picture = LoadResPicture(RESBASE + 7, vbResBitmap)

which is correctly translated into:

    Const RESBASE As Short = 100
    Const STRINGRES As Short = RESBASE + 1
    MsgBox6(My.Resources.str101)
    Image1.Picture = My.Resources.bmp107

If the first or the second argument isn’t a constant, then VB Migration Partner falls back to the LoadResString6, LoadResPicture6, and LoadResData6 support methods. These methods rely on the same ResourceManager instance used by the My.Resources class and therefore return the same resource data. This approach ensures that all .NET localization features can be used on the converted project, including satellite resource-only DLLs.

Interestingly, if an icon resource is being assigned to a VB6 icon property that has been translated to a bitmap property under VB.NET, then VB Migration Partner automatically generates the code that manages the conversion, as in this code:

    Image1.Picture = My.Resources.ico108.ToBitmap()

VB Migration Partner generates code that accounts also for minor differences between VB6 and VB.NET.

Font objects

    Dim fnt As StdFont                      ' a StdFont object
    Set fnt = Text1.Font
    fnt.Bold = True
    Text2.Font.Name = "Arial"               ' a control’s Font property

    Dim fnt As Font                         ' a StdFont object
    fnt = Text1.Font
    FontChangeBold6(fnt, True)
    FontChangeName6(Text2.Font, "Arial")    ' a control’s Font property

    Dim x As Integer
    x = Text1.Font.Weight
    Text2.Font.Weight = x * 2

    Dim x As Integer
    x = GetFontWeight6(Text1.Font)
    SetFontWeight6(Text2.Font, x * 2)

For Each loop on multi-dimensional arrays

    ' UPGRADE WARNING (#01C4): Insert a call to TransposeArray6 method if process order
    ' in following For Each loop is significant
    For Each o As Object In myArr
        …
    Next

    For Each o As Object In TransposeArray6(myArr)
        …
    Next

    '## DisableMessage 01C4
    '## ReplaceStatement For Each o As Object In TransposeArray6(myArr)
    For Each o As Object In myArr
        …
    Next

Fields passed to ByRef arguments

     ' Value is a field of the object held in the obj variable
     MethodWithByrefParam( ByVal6(obj.Value) )

TypeOf keyword

    If TypeOf obj Is TestUDT Then
        ' obj is a UDT 
    ElseIf TypeOf obj Is Widget Then
        ' obj holds an instance of a specific class
    ElseIf TypeOf obj Is Object Then
        ' obj holds an instance of any class
    ElseIf TypeOf obj Is ITestInterface Then
        ' obj is an interface variable
    End If

    If obj.GetType() Is GetType(TestUDT) Then
        ' this test works if obj is a Structure
    ElseIf obj.GetType() Is GetType(Widget) Then
        ' this test throws if obj is Nothing (as in VB6)
    ElseIf (Not TypeOf obj Is String AndAlso Not obj.GetType().IsValueType) Then
        ' obj contains an instance of a reference type
    ElseIf TypeOf obj Is ITestInterface Then
        ' no need to modify tests for interfaces
    End If

    If IsTypeOf6(myVariant, GetType(Widget)) Then

Mod operator

    Dim d As Double, i As Integer
    d = 1.8: i = 11
    Debug.Print i Mod d     ' Displays 1, because it rounds up 1.8 to 2

    Debug.WriteLine(i Mod CInt(d))

Eqv and Imp operators

    x = y Eqv z
    x = y Imp z

    x = (Not y And Not z)
    x = (Not y Or z)

Strings to Byte array conversions

    Dim s As String, b() As Byte
    s = "abcde"
    b = s
    s = b

    Dim s As String, b() As Byte
    s = "abcde"
    b = StringToByteArray6(s)
    s = ByteArrayToString6(b)

Date to Double conversions

    Dim d As Date, v As Double
    d = #11/1/2006#
    v = d
    d = v

    Dim d As Date, v As Double
    d = #11/1/2006#
    v = DateToDouble6(d)
    d = DoubleToDate6(v)

For loops with Date variables

    Dim dt As Date
    For dt = startDate To endDate
        Debug.Print dt
    Next

    Dim dt As Date
    For dt_Alias As Double = DateToDouble6(startDate) To DateToDouble6(endDate)
        dt = DoubleToDate6(dt_Alias)
        Debug.WriteLine(dt)
    Next

Here’s a list of VB6 features that VB Migration Partner doesn’t support:

• ActiveX Documents
• Property Pages
• Web classes
• DHTML classes
• DataReport designer
• OLE and Repeater controls
• a few graphic-related properties common to several controls, including DrawMode, ClipControls, Palette, PaletteMode
• VarPtr, ObjPtr, StrPtr undocumented keywords
• “classic” (non OLE) drag-and-drop
• a small number of control features, including:
  
  
  • The ability to customize, save, and restore the appearance of the Toolbar control
  • The MultiSelect property of the TabStrip control
  • Vertical orientation for the ProgressBar control
  • The DropHighlight property of TreeView and ListView controls

Even if a feature isn’t supported, VB Migration Partner always attempts to emit VB.NET that has no compilation errors. For example, ActiveX Documents and Property Pages are converted into VB.NET user controls. Also, the support library exposes do-nothing properties and methods named after the original VB6 unsupported member.

Unsupported properties and methods

    VB6Config.ThrowOnUnsupportedMember = True

Unsupported Controls

    ' UPGRADE_ISSUE (#02C8): Controls of type VB.OLE aren't  supported. This control
    ' was replaced by a dummy variable to make the VB.NET compiler  happy
    Friend OLE1 As Object