Copies a file into the output project’s main directory and includes the file in the VB.NET project, so that it is automatically copied to the output folder when the project is compiled. It is useful to copy images, Access MDB files, and other data files into the target project. The filespec argument is mandatory: it must be a path relative to the VB6 project’s folder (can’t be an absolute path), can contain wildcards, and must be enclosed in double quotes if it includes spaces:

    '## Rem Add the books.mdb database and all the files in the Images subfolder
    '## AddDataFile books.mdb
    '## AddDataFiles Images\*.* 

Tells VB Migration Partner that a VB6 class is to be considered as a disposable type and be dealt with in a special way when a variable of this type is in the scope of an AutoDispose pragma. It is useful with COM objects that require finalization, for example objects that open a database connection. (Notice that VB Migration Partner recognizes as disposable ADODB objects such as Connection and Recordset.) The typename argument is mandatory and must include the type library name:

    '## AddDisposableType CALib.DatabaseManager

Imports a .NET namespace at the project-level. It is useful together with an AddReference pragma, to make all types of the referenced library accessible from the current project. The namespace argument is mandatory and must be enclosed in double quotes if it includes spaces:

    '## AddReference "c:\code architects\appframework.dll” 
    '## AddImports CodeArchitects.AppFramework

Notice that you don’t need this pragma to add an Imports statement at the top of a given source file. In this case an InsertStatement is ok:

    '## InsertStatement Imports CodeArchitects.AppFramework

Specifies folder where VB Migration Partner can search DLLs and type libraries that have been already converted to VB.NET. The path argument is the absolute name of a directory, recurse is a Boolean that specifies whether the search must be extended to subfolders. (If False or omitted, the search is limited to the directory specified in the first argument.)

    '## AddLibraryPath "c:\MyApps\Libraries"
    '## AddLibraryPath "c:\Projects\Net", True

You can apply this pragma only by storing it in a *.pragmas file. We suggest that you use the special file named VBMigrationPartner.pragmas, which you can conveniently share among all the projects of a complex application.

An important note: if you are migrating a VB6 project group, this pragma should be included in the *.pragmas file that accompanies each project, regardless of whether that specific project uses the classes defined in the DLLs the pragma points to. If the *.vbp files are all located in the same folder, you can use one single VBMigrationPartner.pragmas file in that directory.

Adds a VB.NET source file to the project generated by VB Migration Partner. The filename argument is the absolute path of a *.vb source file. The pragma recognizes form and usercontrol source files and automatically imports the *.Designer.vb and *.resx files, if they exist.

    '## AddSourceFile "c:\code architects\AppFrameworkFormBase.vb"
    '## AddSourceFile "c:\code architects\AppMainForm.vb"
    '## AddSourceFile "c:\code architects\AppFrameworkCommon.vb"

If the source file being imported requires a reference to an external DLL, you must provide an AddReference pragma; if the source file being imported assumes a project-level Imports, you must provide a suitable AddImports pragma. These pragma must be included in one of the original VB6 files:

    '## AddReference "c:\code architects\appframework.dll"
    '## AddImports CodeArchitects.AppFramework

Include a reference to a .NET assembly in the VB.NET project being created. It is useful when the code you inject by means of InsertStatement pragmas requires a .NET assembly that isn’t automatically referenced by default, for example System.Data.OracleClient. The filepath argument is mandatory, must be an absolute file path, and must be enclosed in double quotes if it includes spaces:

    '## AddReference C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Data.OracleClient.dll

Notice that you can’t use this pragma to add a reference to an assembly stored in the GAC. This isn’t a limitation, because all the assemblies in the GAC have a copy stored elsewhere on the hard disk, for example in the C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 folder.

Signs the VB.NET assembly that results from the conversion, using the specified .snk file. The filename.snk argument is the complete (absolute) path of the .snk file that contains the public/private key pair; delaysign is a Boolean that indicates whether the assembly must be delay-signed (default is False).

    '## AssemblyKeyFile "c:\codearchitects.snk"

Using this pragma is equivalent to tick the “Sign the assembly” option in the Signing tab of the My Project designer after the migration.

Enables the VB.NET application framework feature. The parameter passed to this pragma correspond to the settings you can find in the Application tab of the My Project designer in Visual Studio. The mainform argument is the name of the startup form and is the only mandatory parameter for this pragma; splashform is the name of the splash form, if any; visualstyles is True if you want to enable Windows XP styles (the default is False); shutdownmode is 0 (the default) if the application exits when the main form closes or 1 if the application exits when all forms close; singleinstance is True if you want to prevent multiple instances of this application (the default is False).
For example, the following pragma sets frmMain as the main form, frmSplash as the splash screen form, enables XP visual styes and forces the application to close only when all loaded forms are closed:

    '## EnableAppFramework frmMain, frmSplash, true, 1

You should use this pragma only in standard EXE projects. When this pragma is specified, the Sub Main form is ignored (if the application has one).

Specify the command line to be passed to the TlbImp.exe tool when importing a type library. typelibfilename is the name of the .dll or .tlb file to be imported (can be just the file name or the complete file path); tlbimpcommand is the complete command that must be passed to the TlbImp.exe tool. Notice that you need to specify the entire path in the first argument only if the current VB6 application uses two distinct type libraries with same file name:

    '## ImportTypeLib mytypelib.dll, "c:\myapp\mytypelib.dll /tlbreference:c:\myapp\support.dll
        /tlbreference:c:\myapp\interfaces.dll /keyfile:c:\mycompany.snk"

This pragma is necessary only when VB Migration Partner fails to correctly locate the type library to be imported or any of the *.dll or *.tlb files such a type library depends on, or when you need to specify any additional option for the TlbImp.exe tool, such as when you want to sign the imported assembly with a strong name. Notice that VB Migration Partner uses this pragma only to correctly resolve a reference to a type library: the type library is actually imported in the current project only if it was referenced by the original VB6 project.
You can apply this pragma only by storing it in a *.pragmas file. We suggest that you use the special file named VBMigrationPartner.pragmas, which you can conveniently share among all the projects of a complex application. (As explained above, a type library is effectively imported only if it is referenced by the original VB6 project and this pragma only teaches VB Migration Partner how the type library must be imported.)
As a special case, if the second argument starts with a “@” character it is interpreted as the path of a .NET assembly that is equivalent to the original type library. This syntax variation is useful in two cases: First, if you have already (manually) converted the type library and have obtained the corresponding .NET assembly; second, if the author of the original type library has provided a Primary Interop Assembly for the type library and VB Migration Partner fails to correctly locate such a PIA. Here’s an example of this technique

    '## ImportTypeLib msword.olb, "@c:\assemblies\microsoft.office.interop.word.dll”
    

Determines the type of the current project. It is useful to specify whether an ActiveX EXE project should be converted to an EXE or a DLL Visual Basic project. The prjkind argument is mandatory and can be equal to dll or exe:

    '## Rem convert the current ActiveX project as a class library
    '## ProjectKind dll

Specifies folder where VB Migration Partner can search DLLs and type libraries that have been already converted to VB.NET. The path argument is the absolute name of a directory, recurse is a Boolean that specifies whether the search must be extended to subfolders. (If False or omitted, the search is limited to the directory specified in the first argument.)

    '## AddLibraryPath "c:\MyApps\Libraries"
    '## AddLibraryPath "c:\Projects\Net", True

You can apply this pragma only by storing it in a *.pragmas file. We suggest that you use the special file named VBMigrationPartner.pragmas, which you can conveniently share among all the projects of a complex application.

Specifies how a class must be rendered during the migration process. The mode argument can be Class, Interface, ClassAndInterface, and Module. This pragma can’t be specified at the project-level:

    '## ClassRenderMode Interface

By default, all VB6 classes are rendered as VB.NET classes; however, if the class name appears in one or more Implements statements, the class is also rendered as an interface. This pragma allows developers to generate the interface even if the class doesn't appear in any Implements statement (which may be necessary when converting an ActiveX DLL or ActiveX EXE project without also converting a client application) as well as generate only the interface and not the original class. This pragma can also be useful to convert a GlobalMultiuse or GlobalSingleUse class into a VB.NET module.

Specifies whether the current file must be ignored by VB Migration Partner. It is useful for files containing modules and classes that have a VB.NET counterpart – for example, the methods in the VBMigrationPartner_Support module. If the argument is True or omitted, the current file is ignored by VB Migration Partner:

    '## ExcludeCurrentFile

This pragma can’t be specified at the project-level.

Specifies how event definitions in user controls should be rendered. By default, VB Migration Partner generate an event dispatcher class for each event exposed by the user control, and then uses the dispatcher’s Raise method instead of the standard RaiseEvent keyword. If the argument is False then the standard .NET event mechanism is used instead:

    '## Rem don’t use event dispatchers in this user control
    '## ExcludeCurrentFile

VB Migration Partner’s default implementation of events inside user controls ensures that events are handled correctly even if the control belongs to a control array or is instantiated dynamically by means of a Controls.Add method. You can disable this feature if you are sure that neither condition is met.

Specifies how array with a nonzero lower index must be converted to VB.NET. The valid values for the mode argument are Unchanged (arrays are migrated verbatim, the default behavior), ForceZero (the lower index is forced to be zero), Shift (both the lower and upper indexes are shifted so that the number of elements in the array doesn’t change), VB6Array (convert the array into a VB6Array object), or ForceVB6Array (convert the array into the VB6Array even if the lower index is zero):

    '## ArrayBounds VB6Array

Notice that this pragma, like all pragmas that can reference arrays, should be inserted immediately before the Dim statement that declares the array, rather than before the ReDim statement that actually creates the array. Pragmas inserted inside the method where the ReDim statement appears are ignored.

Specifies the rank of an array. It is useful when VB Migration Partner isn’t able to determine the correct rank of a multi-dimensional array taken as an argument, returned by a property or function, or declared at the class level but initialized elsewhere. Consider the following VB6 example:

    '## arr.ArrayRank 2 
    '## GetArray.ArrayRank 2
    Dim arr() As Integer
    
    Function GetArray(initialize As Boolean) As Integer()
        If initialize Then ReDim arr(10, 10)
        GetArray = arr
    End Function

If it weren’t for the ArrayRank pragma, the field and the method would return a vector instead of a two-dimensional array:

    Dim arr(,) As Short 
    
    Function GetArray(initialize As Boolean) As Integer(,) 
        If initialize Then ReDim arr(10, 10) 
        Return arr.Clone() 
    End Function 

Notice that this pragma must have a nonempty scope.

Also notice that this pragma, like all pragmas that can reference arrays, should be inserted immediately before the Dim statement that declares the array, rather than before the ReDim statement that actually creates the array. Pragmas inserted inside the method where the ReDim statement appears are ignored.

Informs VB Migration Partner that a given Object, Variant, or Control variable must be translated as if it were of a specific VB6 type. It is useful to correctly solve default properties even in late-bound references. For example, consider the following VB6 code:

    '## ctrl.AssumeType TextBox 
    Dim ctrl As Control 
    
    For Each ctrl In Me.Controls 
        If TypeOf ctrl Is TextBox Then ctrl = "" 
    Next

If it weren’t for the AssumeType pragma, VB Migration Partner wouldn’t know how to convert the reference to the default property:

    Dim ctrl As Object
    
    For Each ctrl In Me.Controls
        If TypeOf ctrl Is VB6TextBox Then ctrl.Text = ""
    Next

Notice that this pragma must have a nonempty scope.

Specifies how fields pointing to disposable objects must be converted. The mode argument can be No, Yes, or Force. If equal to Yes or omited, all Set x = Nothing statements are converted into calls to the SetNothing6 method; if equal to Force, classes that contain disposable field is marked as IDisposable and all such fields are disposed of in the Dispose method; if equal to No, disposable objects aren’t handled in any special way (this setting represents the default behavior and can be useful to override a pragma with a broader scope). The AutoDispose pragma can be applied to the project, file, class, or individual field or variable level.

    '## Rem force disposal of all disposable objects in current class
    '## Rem except those of the Test method
    '## AutoDispose Force
    '## Test.AutoDispose No

Specifies how auto-instancing object – that is, fields and variables declared with the As New clause - must be converted. By default, such declarations are converted verbatim to VB.NET, even though the VB.NET semantics differs from VB6. If the mode argument is True or omitted, then VB Migration Partner generates code that ensures that the VB.NET is identical to VB6.

    '## Rem ensure that Connection and Recordset objects have auto-instancing semantics 
    '## Connection.AutoNew 
    '## Recordset.AutoNew
    Public Recordset As New ADODB.Recordset
    Public Connection As New ADODB.Recordset

The actual code being generated is different for local variables and fields: if the object is declared as a class-level field, VB Migration Partner converts it into a property whose Get block contains code that implements the auto-instancing behavior; if the object is declared as a local variable, all occurrences are wrapper by AutoNew6 method calls, that ensure that the object is instantiated if necessary.

Specifies that all members of a given VB6 type in the pragma’s scope must be converted to a given .NET type. It is useful to convert Variant variables to VB6Variant objects and Control variables to System.Windows.Forms.Control variables (without this pragma, such variables would be migrated as Object variables):

    '## ChangeType Variant, VB6Variant
    '## ChangeType Control, Control

Specifies whether VB Migration Partner should generate one Dim statement for each local variable that isn’t declared explicitly. If the argument is True or omitted, all local variables in the converted VB.NET methods under the pragma’s scope are declared explicitly.

    '## Rem generate code for implicitly-declared variables in current file
    '## InsertStatement Option Explicit On
    '## DeclareImplicitVariables

Specifies whether VB Migration Partner should generate a method overload for methods that take a ParamArray argument and that modify an element of the array argument inside the method. The method overload uses Optional ByRef parameters instead of one single ParamArray parameter, and the maxargs value specifies the maximum number of arguments that you expect. For example, assume that you have the following VB6 code:

    '## FixParamArray 3
    Sub Increment(ParamArray arr() As Variant)
        Dim i As Integer
        For i = 0 To UBound(arr)
            arr(i) = arr(i) + 1
        Next
    End Sub

Notice that the elements of the arr ParamArray array are modified inside the method and these changes are propagated back to callers under VB6 but not under VB.NET. However, the FixParamArray pragma causes the following code to be generated:

    Public Sub Increment(Optional ByRef arr0 As Object = Nothing, _
        Optional ByRef arr1 As Object = Nothing, _
        Optional ByRef arr2 As Object = Nothing)
        
        Dim arr() As Object = GetParamArray6(arr0, arr1, arr2)
        Try
            Increment(arr)
        Finally
            SetParamArray6(arr, arr0, arr1, arr2)
        End Try
    End Sub
    
    Public Sub Increment(ByVal ParamArray arr() As Object)
        Dim i As Short
        For i = 0 To UBound6(arr)
            arr(i) += 1
        Next
    End Sub

The neat effect is that any call to the Increment method that takes 3 arguments or fewer will use the first overload, which ensures that changes to any argument are correctly propagated back to callers even in VB.NET.
If the maxargs argument is 0 or omitted, no overloaded method is generated. (This behavior is useful to override another FixParamArray pragma with broader scope.) Values higher than 20 are rounded down to 20.

Specifies whether a specific local variable (or all local variables in a method) must be merged with the first statement that assigns it a value. By default, VB Migration Partner merges a variable declaration with its first assignments only if the value being assigned is constant and if the variable isn’t used in any statement after the declaration and before the assignment. You can use this pragma to inform VB Migration Partner that it is safe to do the merge even if the value being assigned isn’t constant. For example, consider this VB6 code:

    Sub Test(value As Integer)
        '## MergeInitialization Force
        Dim x As Integer, y As Integer
        x = value * 2
        y = x * value * 3
        ' ...
    End Sub

The values being assigned aren’t constant, therefore by default VB Migration Partner wouldn’t attempt to merge the declaration and the assignment statements. Thanks to the MergeInitialization pragma, the code generator produces the following code:

    Sub Test(value As Short)
        Dim x As Short = value * 2
        Dim y As Short = x * value * 3
        ' ...
    End Sub

Other possible values for this pragma are No (always disable the merging) or Yes (apply the merging if it is safe to do so). The Yes value represents the default behavior, but this setting can be necessary to override the effect of another MergeInitialization pragma with a broader scope:

    ' Disable initialization merging for all variables except n1
    '## MergeInitialization No
    '## n1.MergeInitialization Yes

Specifies whether the current project, class, method, property or variable must have a different name in the converted VB.NET application. It can be useful to avoid name clashes with reserved VB.NET keywords or names of .NET Framework classes and methods. Consider the following VB6 code:

    ' ... (inside the Console VB6 class) 
    '## SetName ConsoleNET
    '## Id.SetName Identifier 
    Public Id As String 
    
    Sub AddHandler() 
        '## SetName AddEventHandler 
        ' 
    End Sub 
    
    Sub Test() 
        Dim c As New Console 
        c.Id = "abc" 
        c.AddHandler
    End Sub

Here’s how the code inside the Test method is converted to VB.NET:

    Sub Test() 
        Dim c As New ConsoleNET 
        c.Identifier = "abc" 
        c.AddEventHandler() 
    End Sub

Specifies whether the indexes of the element of an array should be adjusted by a given value. The applytovariables argument is False if only constant indexes should be adjusted, True if all indexes should be adjusted; delta1 is the value that must be subtracted from the first index; delta2 and delta3 are the values that must be subtracted from the second and third index, respectively.
This pragma is typically used together with the ArrayBounds pragma. Consider the following VB6 code:

    Sub Test()
        '## ArrayBounds Shift
        '## primes.ShiftIndexes False, 1
        Dim primes(1 To 10) As Integer
        primes(1) = 1: primes(2) = 2: primes(3) = 3: primes(4) = 5: primes(5) = 7
    
        '## powers.ShiftIndexes False, 1
        Dim powers(1 To 10) As Double
        powers(1) = 1
        Dim i As Integer
        For i = LBounds(powers) + 1 To UBound(powers)
            powers(i) = powers(i – 1) * 2
        Next
    End Sub

The ShiftIndexes pragmas ensure that the array elements whose index is constants are scaled by 1 when this code is converted to VB.NET:

    Sub Test()
        Dim primes(9) As Short
        primes(0) = 1: primes(1) = 2: primes(2) = 3: primes(3) = 5: primes(4) = 7
        
        Dim powers(9) As Double
        powers(0) = 1
        Dim i As Short
        For i = LBounds6(powers) + 1 To UBound6(powers)
            powers(i) = powers(i – 1) * 2
        Next
    End Sub

In most cases, the first argument of the ShiftIndexes pragma is False, which prevents this pragma from affecting array elements whose index is a variable or an expressions, as it usually happens inside a loop. However, this isn’t a fixed rule and the value for the applytovariables argument actually depends on how the loop is defined. For example, consider a variations of the above code:

    '## powers.ShiftIndexes True, 1
    Dim powers(1 To 10) As Double
    powers(1) = 1
    Dim i As Integer
    For i = 2 To 10
        powers(i) = powers(i – 1) * 2
    Next

In this case the lower and upper bounds of the loop are constants and aren’t expressed in terms of LBound and UBound functions, therefore you need to pass True in the first argument of the ShiftIndexes pragma to adjust the indexes inside the loop. This is the generated VB.NET code:

    Dim powers(9) As Double
    powers(0) = 1
    Dim i As Short
    For i = 2 To 10
        powers(i - 1) = powers(i – 1 - 1) * 2
    Next

When dealing with a multi-dimensional array you need to pass more than two elements to the ShiftIndexes pragma, as in the following code:

    '## mat.ArrayBounds Shift
    '## mat.ShiftIndexes False, 1, 2
    Dim mat(1 To 10, 2 To 20) As Double
    mat(1, 2) = 1: mat(2, 3) = 2

which is converted to VB.NET as follows:

    Dim mat(9, 18) As Double
    mat(0, 0) = 1: mat(1, 2) = 2

Finally, notice that the delta values don’t have to be constants, as in this example:

    Sub Test(arr() As Double, firstEl As Integer, numEls As Integer)
        '## arr.ArrayBounds Shift
        '## arr.ShiftIndexes True, firstEl
        ReDim arr(firstEl To lastEl) As Double
        arr(firstEl) = 1
    End Sub

which is converted as follows:

    Sub Test(ByRef arr() As Double, ByRef firstEl As Short, ByRef numEls As Short)
        ReDim arr(lastEl – (firstEl)) As Double
        arr(firstEl - firstEl) = 1
    End Sub

Notice that this pragma, like all pragmas that can reference arrays, should be inserted immediately before the Dim statement that declares the array, rather than before the ReDim statement that actually creates the array. Pragmas inserted inside the method where the ReDim statement appears are ignored.

Specifies that a fixed-length string must be converted as a VB6FixedString_NNN type instead of the VB6FixedString type. For example, the following VB6 code:

    '## name.SetStringSize 128
    Dim id As String * 20, name * As String * 128

is converted to VB.NET as follows:

    Dim id As New VB6FixedString(20)
    Dim id As New VB6FixedString_128

where the VB6FixedString_128 class is defined in the VisualBasic6.Support.vb file under the My Project folder.

Specifies that the specified variable, field, property or method must be rendered with a different .NET type. It is useful to specify a type other than Object for Variant and Control variables. For example, the following VB6 code:

    '## m_Name.SetType String 
    '## Name.SetType String
    Private m_Name As Variant
    Property Get Name() As Variant
        Name = m_Name
    End Property

is translated to VB.NET as follows:

    Private m_Name As String
    Public ReadOnly Property Name() As String
        Get
            Return m_Name
        End Get
    End Property

Notice that this pragma must have a nonempty scope.

Specifies how to convert by-reference parameters that might be rendered using by-value semantics. The mode argument can be Yes (the ByVal keyword is used for the parameter unless an explicit ByRef keyword is present), Force (the ByVal keyword is used for the parameter, regardless of whether an explicit ByRef keyword is present), No (the parameter is translated as is):

    '## project:UseByVal Yes

If the parameter is omitted, the Yes value is assumed.

Specifies whether fixed-length strings inside inside Type…End Type blocks must be converted to VB.NET. If the argument is True or omitted, fixed-length strings inside the pragma’s scope are converted as properties that take or return System.String values.

    '## testudt.UseStringString

Specifies whether VB Migration Partner must wrap references to default members inside calls to the special GetDefaultMember6 and SetDefaultMember6 methods defined in the language support library:

    '## Rem enable default member support for this class, except for the Test member
    '## DefaultMemberSupport
    '## Test.DefaultMemberSupport False

Specifies how VB Migration Partner must convert VB6 remarks that start with three consecutive apostrophes. By default they are prefixed by an additional apostrophe+space, so that the VB.NET compiler doesn’t mistakenly interpret them as XML remarks. You can use False for the argument to disable such automatic fix, which can be useful if you decide to insert VB.NET XML remarks right in the VB6 code:

    '## project:FixRemarks False

Specifies whether And and Or VB6 keywords must be translated to AndAlso and OrElse VB.NET keywords. For example, the following code:

    Sub Test(ByVal x As Integer) 
        '## LogicalOps True 
        If x < 0 And x > 100 Then Err.Raise 9 
        ' ... 
    End Sub

The pragma can have project, class, and method scope, and can issued multiple times inside the same method, to selectively enable and disable this feature. For example, this VB6 code:

    '## LogicalOps True 
    If x > 0 Or (x = 0 And y < 0) Then … 
    '## LogicalOps False 
    If x1 > 0 Or (x1 = 0 And y1 < 0) Then …

translates to:

    If x > 0 OrElse (x = 0 AndAlso y < 0) Then … 
    If x1 > 0 Or (x1 = 0 And y1 < 0) Then …

Specifies whether VB Migration Partner must generate code that provides better support for null propagation in expressions. For example, consider the following VB6 code:

    '## NullSupport
    Sub Test(name As Variant, city As Variant)
        name = UCase(name) + Trim(city)
    End Sub

and its VB.NET translation

    Sub Test(ByRef name As Object, ByRef city As Object)
        name = UCase6(name) + Trim6(city)
    End Sub

Methods affected by this pragma are: Chr, CurDir, Environ, Error, Hex, LCase, LTrim, Mid, Oct, Right, RTrim, Space, and UCase. The corresponding method in the language support library has same name plus a "6" suffix.

Includes a text file before the parsing process begins. The argument is the path to the text file that contains the text to be included. (It can be an absolute path or a path relative to the folder that contains the .vbp project file.). The argument never needs to be included in double quotes:

    '## PreInclude c:\includes\copyright.txt

If the includefile argument points to a non-existing file, no text is included and no migration warning is generated. The PreInclude pragma supports recursion, in the sense that the file being included can contain additional PreInclude pragmas, up to any nesting level. VB Migration Partner doesn’t allow circular references among include files.

Keep in mind that you typically can’t use this pragma to include a standard CLS or BAS file, because such VB6 files contains hidden text and attributes that would be included in the wrong position and might deliver unexpected results or even crash VB Migration Partner. You use this pragma at your own risk.

A good use for this pragma is as a simple way for multiple project to share the same set of project-level pragmas. For example, let’s assume that you have to migrate ten VB6 projects that require the same set of PostProcess pragmas. Instead of copying the pragma text in each and every project, you can gather them in a text file and reference the text from inside any source file in each project:

    '## PreInclude c:\code\pragmas.txt

Notice, however, that in this specific case, the pragma.txt file can’t contain the special pragmas that must be parsed before the project itself and that are necessarily to be stored in the VBMigrationPartner.pragmas file. However, quite conveniently PreInclude pragmas are honored even inside *.pragmas files, therefore each folder might contain a VBMigrationPartner.pragmas file that contains only one line containing the PreInclude pragma pointing to the text file that contains the actual pragmas that are shared among multiple projects.

Applies a replace regular expression to the VB6 code before it is parsed. The first argument is the search regex pattern string. The second argument is the replace regex pattern and can reference match groups defined in the search pattern; it abides to the same syntax rules as the Regex.Replace method but it also recognizes character sequences such as \n (newline), \r (carriage return) and \t (tab). Backslash characters in the replace regex must be doubled (as in \\). The third argument is a Boolean value that specifies whether searches are case insensitive (if omitted, it defaults to True). The fourth argument is True if this pragma applies also to the .vbp file and to the hidden portion of an .frm or .ctl file, False (or omitted) if it applies only to the VB6 code that you see inside the code editor.

For example, the following pragma pre-processes the VB6 code and converts all OLE_COLOR variables into plain Long variables:

    '## PreProcess "As OLE_COLOR\b", "As Long"

The following pragma renames a button named “AddHandler” into “btnAddHandler”, to avoid the problem caused by AddHandler being a reserved VB.NET keyword. In this case it is necessary to apply the pragma to the hidden portion of the file and to account for event names, where the control’s name is followed by an underscore

    '## PreProcess "(\bAddHandler\b|(?<=\bSub\s+)AddHandler(?=_))", "btnAddHandler", True, True

You can apply this pragma at the project-level only by storing it in a *.pragmas file – for example, in the Widgets.vbp.pragmas file for all the files in the Widgets.vbp project. An important note: this pragma can’t have a project: prefix: if the pragma appears in a source file it is implicitly scoped at the file level; if it appears in a *.pragmas file, it is implicitly scoped at the project level.

Includes a text file after the conversion process has been completed. The argument is the path to the text file that contains the text to be included. (It can be an absolute path or a path relative to the folder that contains the .vbp project file.). The argument never needs to be included in double quotes:

    '## PreInclude c:\includes\copyright.txt

If the includefile argument points to a non-existing file, no text is included and no migration warning is generated. The PostInclude pragma supports recursion, in the sense that the file being included can contain additional PostInclude pragmas, up to any nesting level. VB Migration Partner doesn’t allow circular references among include files.

A good use for this pragma is to add one or more methods or classes to the resulting VB.NET code.

Applies a replace regular expression to the VB.NET code generated by the migration process. The first argument is the search regex pattern string. The second argument is the replace regex pattern and can reference match groups defined in the search pattern; it abides to the same syntax rules as the Regex.Replace method but it also recognizes character sequences such as \n (newline), \r (carriage return) and \t (tab). Backslash characters in the replace regex must be doubled (as in \\). The third argument is a Boolean value that specifies whether searches are case insensitive (if omitted, it defaults to True). The fourth argument specifies whether the PostProcess pragma applies only to “hidden” files such as AssemblyInfo.vb and *.Designer.vb files (if omitted, it defaults to False and the pragma applies only to standard *.vb files).
For example, the following pragma changes the base form for the converted application:

    '## project:PostProcess "Inherits CodeArchitects.VB6Library.VB6Form", 
        "Inherits AppFramework.FormBase", False, True

The search pattern can include match groups and you can reference these search groups in the replacement pattern. For example, the following pragma moves the declaration of the controlling variable into a For Each loop, if the variable is defined immediately before the loop:

    '## PostProcess "Dim (?<name>\w+) As (?<type>\w+)( = .+)?\s+For Each \k<name> In", 
        "For Each ${name} As ${type} In"

Specifies whether VB Migration Partner must generate additional code to ensure that delegate objects passed to Declare statements aren’t orphaned during garbage collections:

    '## project:WrapDeclareWithCallbacks True

Changes the z-order of a control and brings it in front of all other controls. This pragma can be only scoped at the control level. When using this pragma for two or more controls on the same form, the last control becomes the topmost control:

    '## Rem bring the ListView1 in front of all other controls, except Text1
    '## ListView1.BringToFront
    '## Text1.BringToFront

Set the default font for a specific form or (if the pragma has project scope) all the forms in the application. The fontname argument is the name of the form (embedded in double quotes if contains spaces), the optional fontsize argument is the size of the font:

    '## Rem set the default font for forms that don’t define a custom font
    '## project:FormFont Arial, 10

This pragma allows you to specify a different default font for forms; it affects only fonts that use the default font and don’t specify a specific font. If the fontsize argument is omitted, the original font size is retained.

Specifies whether VB Migration Partner should discard assign design-time assignments to properties that aren’t supported under VB.NET. Such properties are marked as obsolete in the control language library and, by default, they aren’t included in the converted project. If the argument is True or omitted, assignments to these properties are preserved in the converted VB.NET project:

    '##  KeepObsoleteProperties True

You can scope this pragma at the project, file, and individual control level. This pragma can be useful to browse all the properties that are usually discarded during the migration process.

Replace all occurrences of a font with another font, for all controls in current form or in all forms in current project (depending on the pragma’s scope):

    '## Rem replace all occurrences of MS Sans Serif with Helvetica font
    '## project:ReplaceFont "MS Sans Serif", "Helvetica"

VB.NET doesn’t support system fonts, a group which includes the following fonts: Courier, Fixedsys, Modern, MS Sans Serif, MS Serif, Roman, Script, Small Fonts, System, and Terminal. Because of this limitation, VB Migration Partner converts Courier and Fixedsys fonts to Courier New and all other fonts to Arial, while preserving the font size. You can use this pragma to enforce a different substitution schema.

Replaces all occurrences of a font/size combination with a different font/size combination, for all controls in current form or in all forms in current project (depending on the pragma’s scope):

    '## Rem replace all occurrences of MS Sans Serif 12 with Helvetica 10 font
    '## project:ReplaceFont "MS Sans Serif", 12, "Helvetica", 10

See the ReplaceFont pragma for more information on the automatic font replacement mechanism that VB Migration adopts.

Changes the z-order of a control and sends it behind all other controls. This pragma can be only scoped at the control level. When using this pragma for two or more controls on the same form, the first control becomes the bottommost control:

    '## Rem send the ListView1 behind all other controls, except Text1
    '## Text1.BringToFront
    '## ListView1.BringToFront

Assigns a design-time property to the current form or to a specific control:

    '## Rem change the caption of current form
    '## WriteProperty Text, ".NET Framework options"
    '## Rem set the  DTPicker1.Format property equal to 2
    '## DTPicker1.WriteProperty Format, 2

This pragma is useful in many cases, for example to manually assign a control property that VB Migration Partner can’t migrate correctly (as is the case of the DTPicker’s Format property) or to purposely introduce minor differences between the VB6 and VB.NET applications.

Specifies a list of properties that have a different name in the .frm file. The propertylist argument is a comma-delimited list of oldname=newname pairs, as in this example:

    '## TranslateProperties "FC=ForeColor,BC=BackColor"

When storing properties in a .frm file, VB6 doesn’t necessarily use the property name; more precisely, the actual name used in the .frm file is equal to the name specified when saving the value in the WriteProperties event handler. If the name specified in the event handler is different from the property name, you should use this pragma to tell VB Migration Partner which name is used in .frm files.
This pragma can’t have a scope prefix and is implicitly scoped at the file level. It is ignored if it appears in a VB6 file other than a .ctl (user control ) class.

Specifies a list of events that must be renamed when migrating a UserControl class. The eventlist argument is a comma-delimited list of oldname=newname pairs, as in this example:

    '## TranslateEvents "KeyPress=KeyPress6,KeyDown=KeyDown6,KeyUp=KeyUp6"

When this pragma is used, VB Migration Partner marks the converted UserControl class with a TranslateEvents attribute. In turn, this attribute is taken into account when VB Migration Partner converts any VB6 form that contains one or more instances of the user control. Renaming an event is sometimes necessary because the original name used under VB6 conflicts with events exposed by the .NET UserControl class.

This pragma can’t have a scope prefix and is implicitly scoped at the file level. It is ignored if it appears in a VB6 file other than a .ctl (user control ) class.

Specifies a list of properties and methods that should be ignored when translating a VB6 user control. The memberlist argument is a pipe-delimited list of member names:

    '## IgnoreMembers "Appearance|Bindings|CompanyName"

This pragma can’t have a scope prefix and is implicitly scoped at the file level. It is ignored if it appears in a VB6 file other than a .ctl (user control ) class.

Inserts a statement in the converted application. The code argument is an (unquoted) string that represents a valid VB.NET statement (or statements):

    '## InsertStatement MsgBox6("End of  processing"): Exit Sub

Inserts an UPGRADE_NOTE remark in the converted VB.NET:

    '## Note Double-check following statement
    x =  Abs(y) Mod y

Sets VB Migration Partner’s output mode. The mode argument can be one of the following: On (enables code generation), Off (disable code generation), Remarks (generate remarked out code)), Uncomment (removes a leading apostrophe). The count argument is the number of VB.NET statements affected by this pragma; if zero or omitted, the effect extends to the next OutputMode pragma:

    '## Rem don’t output the next line (two statements, counting the remark) 
    '## OutputMode Off, 2 
    PrintReport  "Products”, 1, 10    ' print pages 1-10 of the Products Report 
    
    '## Rem don’t output the next method 
    '## OutputMode Off
    Private Sub TestReport() 
        ' ... (any number of lines here) 
        ' ... 
    End Sub  
    '## OutputMode On

The Uncomment setting is especially useful for including a portion of VB.NET code that doesn’t exist in the original VB6 project:

   	'## OutputMode Uncomment
   	'' This is a piece of VB.NET code
   	'Debug.Print("x={0}", x)
   	' ...
   	' ...
   	'## OutputMode On
   	

Sets VB Migration Partner’s parsing mode. The mode argument can be one of the following: On (enables parsing), Off (disable parsing), Remarks (consider next statements as remarks). The count argument is the number of VB6 statements affected by this pragma; if zero or omitted, the effect extends to the next ParseMode pragma:

    '## Rem don’t parse the next line (two statements, counting the remark) 
    '## ParseMode Off, 2 
    PrintReport  "Products”, 1, 10    ' print pages 1-10 of the Products Report 
    '## Rem don’t parse the next method 
    '## ParseMode Off
    
    Private Sub TestReport() 
        ' ... (any number of lines here) 
        ' ... 
    End Sub  
    '## ParseMode On

Notice the subtle difference between OutputMode and ParseMode pragmas. If parsing is enabled when a variable or method is parsed, VB Migration Partner creates a symbol for that method and correctly solves all references to it; if parsing is disabled, no symbol can be created, which prevents VB Migration Partner from correctly resolving references to that symbol.
If you don’t want to include a VB6 member in the VB.NET program, in most cases it is preferable to have VB Migration Partner parse the symbol and then use an OutputMode pragma to omit it during the code generation phase.

Replace the following line of VB6 code with a different line. The replacement is performed before the parsing takes place, therefore you can use this pragma to change the way a method is declared, the scope of a variable, and so forth:

    '## ParseReplace Sub Test(Optional Byval arg As Integer = -1)
    Sub Test()

Notice that this pragma replaces an entire line of code, therefore it can replace multiple statements if the next line contains multiple statements. It can even replace a portion of a statement if the next line has a trailing underscore.

Inserts a remark in the VB6 source code that won’t be translated to VB.NET. This pragma is useful to explain what other pragmas do:

    '## Rem we use the Shift option to preserve number of array elements 
    '## arr.ArrayBounds Shift
    Dim arr(1 To 10) As Integer

Replaces the next statement with a piece of code. The code argument is an (unquoted) string that represents a valid VB.NET statement (or statements):

    '## ReplaceStatement Dim obj As Widget = Widget.Create(12)
    Dim  obj As New Widget

Keep in mind that this pragma replaces only the VB6 statement (not the line) that follows immediately the pragma. If the following line includes two statements separated by a semicolon, only the first statement is replaced by this pragma.

Disables generation for a specific message. The messageid argument is the hex numeric value of the message:

    '## Rem disable the message “Controls of type XYZ aren’t supported…” 
    '## DisableMessage 02C8

Disables message generation for a specific language category. The argument can be: Info, ToDo, Warning, Issue, Syntax, Language, CodeAnalysis, Library, All:

    '## Rem disable all messages except issues and warnings
    '## DisableMessages All
    '## EnableMessages Issue
    '## EnableMessages Warning

Enables generation for a specific message. The messageid argument is the hex numeric value of the message:

    '## Rem disable all messages except “Controls of type XYZ aren’t supported…” 
    '## DisableMessages All 
    '## EnableMessage 02C8 

Enables message generation for a specific language category. The argument can be: Info, ToDo, Warning, Issue, Syntax, Language, CodeAnalysis, Library, All:

    '## Rem disable messages except those related to code analysis 
    '## DisableMessages All 
    '## EnableMessages CodeAnalysis

Specifies that a specific symbol should be considered as used even if VB Migration Partner can’t detected any reference to it. It is useful when the member is accessed through late binding or the CallByName method:

    '## Rem consider the PrintReport method as referenced 
    '## PrintReport.MarkAsReferenced

Notice that this pragma must have a scope prefix.

Specifies that all public members of current user control or class should be considered as used even if VB Migration Partner can’t detected any reference to it. It is useful inside ActiveX DLL or EXE projects that aren’t migrated together with their clients:

    '## Rem mark all public members in all public classes as referenced 
    '## project:MarkPublicAsReferenced

Creates a tag with a given name and value. This pragma can be only useful when a VB Migration Partner extender recognizes and uses it. The following example assumes that you have installed an extender that recognizes the pragma tag named “DatabaseName”

    '## SetTag DatabaseName, “SqlServer”