We all know that writing software requires a vast assortment of skills and, above all, a lot of patience. You usually need the latter to feel comfortable when you realize that you've wasted hours and days over someone else's bug.  Here's the story.

Like many commercial applications, VB Migration Partner has a splash screen. No big deal. VB Migration Partner is written in VB2005, therefore we could use VB.NET application framework. As a matter of fact, defining a splash screen in VB.NET is as easy as selecting an item in a combobox in the Application tab of the My Project designer.

During the beta test period a few users reported that at times VB Migration Partner threw an exception at launch, immediately after closing the splash screen. We never managed to reproduce the problem on our computers. Fortunately the exception occured quite rarely. Until a user running Windows 2000 reported that he was seeing the exception at nearly every launch. After installing VB Migration Partner on Windows 2000 in our lab, we could indeed verify that we had a problem.

It took a while to find out that we weren't  the only ones suffering from this issue. As a matter of fact, Microsoft recognizes that it is a VB.NET bug. Fortunately, they also offer a workaround. According to whis workaround you must create an invisible form from inside the Form_Load event of your splash screen, something like this:

   Private Sub Form_Load(ByVal sender As Object, ByVal e As EventArgs) _
          Handles MyBase.Load
     Dim frm As New Form
      frm.Opacity = 0
      frm.ShowInTaskbar = False
      frm.FormBorderStyle = FormBorderStyle.None
      frm.Show()
      Return frm
   End Function

Unbelievably, this code makes the problem vanish away! You can find more details in this Microsoft KB article.

We realized that *all* applications written in VB.NET could suffer from this issue, thus we added a method to our support library, named SplashScreenBugFix6, which creates the invisible form for you. You just need to add an InsertStatement pragma in the original VB6 splash screen form, so that a call to this method is automatically generated anytime you convert the VB6 project:

    ' in the VB6 project
    Private Sub Form_Load()
      '## InsertStatement SplashScreenBugFix6()
      ' more code in the Load event
   End Sub

VB Migration Partner does a superb in dealing with Windows API calls. Here's a summary of the features that it supports and that are out of reach for the Upgrade Wizard included in Visual Studio 2005/2008:

• converts As Any parameters, by creating all the necessary overloads
• deals correctly with API methods that take a callback address (e.g. EnumWindows, EnumFonts)
• provides recommendation about the .NET object/method that can effectively replace the API method; we cover 300+ different API calls
• in a few cases, it automatically replace API calls with calls to the corresponding .NET object/method
• ensures that string immutability doesn't prevent the VB.NET code from working correctly (see this article)
• generates the correct MarshalAs attributes for elements in Type (Structure) blocks
• correctly translates fixed-length strings inside Type blocks, so that they work correctly when passed to the Windows API method
• automatically initializes static arrays inside Type blocks, so that you don't get unexpected crashes when invoking an API method that expects to find a buffer there
• creates a wrapper method that ensures that orphaned delegates don't cause an unexpected runtime exception, an advanced programming technique discussed in this KB article
• includes the VB6WindowsSubclasser class that helps you correctly migrate subclassing-based techniques (as explained here)

In spite of all these innovations, there are cases when you still need to manually edit either the original VB6 code or the converted VB.NET. This happens, for example, if the original code uses the VarPtr, StrPtr, or ObjPtr functions to pass memory pointers to an external API method. These three functions aren't supported under VB.NET and there is no simple way to simulate them.

The good news is that in the vast majority of cases you don't need to deal with memory pointers under .NET, because the .NET Framework offer a valid "pure" alternative to the API method in question. In this article I'll illustrate how you can take advantage of VB Migration Partner features to reduce manual edits to the very minimum and take advantage of the convert-test-fix methodology.

For simplicity's sake, let's focus on one of the simplest API methods, the GetSystemDirectory Windows API. Here's a piece of VB6 code that displays the system directory path:

    ' Main.Bas module
    Public Declare Function GetSystemDirectory Lib "kernel32.dll" Alias "GetSystemDirectoryA" _
        (ByVal lpBuffer As String, ByVal nSize As Long) As Long

    Sub Main()
        Dim buffer As String, length As Long, windir As String
        buffer = Space(256)
        length = GetSystemDirectory(buffer, Len(buffer))
        winDir = Left(buffer, length)
        MsgBox winDir
    End Sub

The first step is in refactoring this code so that you make all the Declares private and move them to another BAS module, that exposes them by means of standard VB6 methods. (If you usually write tidy and maintainable VB6 code, odds are that you have already taken this step.)

    ' This is the APIHelpers.Bas file
    Private Declare Function GetSystemDirectory Lib "kernel32.dll" Alias "GetSystemDirectoryA" _
        (ByVal lpBuffer As String, ByVal nSize As Long) As Long

    ' returns the Windows directory
    Public Function SystemDirectory() As String
        Dim buffer As String, length As Long
        buffer = Space(256)
        length = GetSystemDirectory(buffer, Len(buffer))
        SystemDirectory = Left(buffer, length)
    End Function

The code that actually displays or otherwise uses the Windows directory path is now simpler. Notice that we explicitly include the module name (APIHelpers) in the method call. This tip reduces the odds that another method with same name exists elsewhere in the project, but the technique explained later works even if you don't include such a name:

    ' the Main.Bas module
    Sub Main()
        Dim windir As String
        winDir = APIHelpers.SystemDirectory
        MsgBox winDir
    End Sub

At this point you have a VB6 project that works exactly like the original one, but it is better organized and structured, with all Declares statements gathered in one single module. Let's see how to migrate this code to VB.NET and get rid of all dependencies from non-NET code.

First and foremost, we prepare a VB.NET module that exposes the same methods as the original APIHelpers.bas but doesn't use any Declare statement. Here's how we can render the SystemDirectory function using native .NET calls:

    ' This is the APIHelpers.vb file (VB.NET)
    Module APIHelpers
        Public Function SystemDirectory() As String
            Return Environment.SystemDirectory
        End Function
    End Module

Next, we use an ExcludeCurrentFile pragma to exclude the APIHelpers.bas VB6 module from migration process and we use an AddSourceFile pragma to add the APIHelpers.vb VB.NET file to the converted Visual Studio project. The neat result is that the code in Main now calls the .NET version of the method, which doesn't use any unmanaged calls:

    ' This is the APIHelpers.Bas file
    '## ExcludeCurrentFile
    '## AddSourceFile "c:\vbnet\modules\apihelpers.vb"

    Private Declare Function GetSystemDirectory Lib "kernel32.dll" Alias "GetSystemDirectoryA" _
        (ByVal lpBuffer As String, ByVal nSize As Long) As Long
    ' ... remainder of module as before...

This solution works great, but we can improve it. In fact, a (minor) problem is that the resulting VB.NET code still uses wrapper methods and doesn't look like the "native" .NET code that an experienced VB.NET developer would write. Fear not, because all you need is a project-level PostProcess pragma:

    ' This is the APIHelpers.Bas file
    '## ExcludeCurrentFile
    '## project:PostProcess "(APIHelpers\.)?SystemDirectory", "Environment.SystemDirectory"

Notice that I dropped the AddSourceFile pragma because you don't need the wrapper method any longer (at least in this simplified example). Using similar techniques you can provide a .NET equivalent for most methods that require API calls under VB6, including methods that take arguments.

One of the long-terms goals we have in Code Architects is to apply these concepts on a larger scale to create VB6 helper modules and their corresponding VB.NET versions, to help all VB6 developers to easily migrate their API-intensive applications. Just stay tuned, as usual!

We routinely spend a lot of time at our customers' site, to help them in their migration needs. If you haven't written an application's source code, understanding what the migration challenges are is a difficult and time-consuming process. It gets quickly much worse if the application is scattered over dozens or hundreds VB6 projects, as is often the case with N-tier (DNA) Visual Basic applications. In such cases, even getting a broad idea of how large the application is, how many forms it has, which controls it uses, and which technologies it relies on is a nightmare. On top of that, if the application is really huge, few people in the company (if any) have a 360° view of the entire application.

For this and other reasons, this week I decided to lock my office door and build the VB6 Bulk Analyzer tool. It's a simple command-line utility that gathers a lot of information about all the VB6 projects and source files inside a specified directory tree and then creates a concise but quite thorough report. You can download the beta build here.

Using this tool is quite easy: just open a command window, move to the root of the directory tree that contains all the VB6 source files that you want to parse, and run the utility. I will show the name of the files being processed, and then a summary of all the code it has parsed. If you parse more than a few dozens files, odds are that the relevant information will scroll away from the window, but you also have a permanent copy in the file named VBAnalyser_Report.txt, in the current directory. The tool supports a few options too, such as /quiet for omitting file names, /out to select a different report file, and /help to display a short explanation. You can also specify multiple folder names, in case your source code is scattered in directories that don't have a common root, as in this example:
       VB6ANALYZER c:\firstapp c:\secondapp  /out:c:\report.txt

The report file contains much useful info, including:

• number of projects and source files, grouped by type
• statistics about the source code (code lines, empty and remark lines, etc.), number of methods, properties, etc.
• statistics about ActiveX classes (grouped by their Instancing property, number of MTS classes, etc.)
  
• all the type libraries used in all projects, with how many times the typelib is referenced
• names of all used controls and components, with a count beside each control
• list of all the Declare definition, with number of occurrences of each declare
• list of problematic keywords (GoSub, On...Goto/Gosub, VarPtr, ObjPtr, StrPtr, etc.), with number of times the keyword is used
• list of problematic data types (Variant, fixed-length strings, etc., with number of times the keyword is used
• list of problematic control properties, methods, events (e.g. members related to classic Drag-and-drop or DDE)
• list of problematic constants (e.g. adOpenDynamic and adOpenKeyset means that a piece of ADO code can't be easily ported to ADO.NET)
• list of COM classes that are instantiated via CreateObjects
• list of OLEDB data providers explicitly mentioned in a connection string

VB6Analyzer is quite precise, especially if you consider that it doesn't really interpret the VB6 source code. It uses plain regular expressons, yet it doesn't suffer from "false matches" (eg. a keyword that appears in a remark or in a quoted string). Regular expressions make it very fast: on a 3GHz system it analyzes over 600K characters per second, or nearly 9,000 lines per second. 

Please keep in mind that this build is just a beta version which I rolled out in a couple days. Please write me if you find any problem or inconsistent result.

PS: if you are interested in our VB Migration Partner or our migration services, just run VB6 Bulk Analyzer on your project and then send its report from the Contact Us page.

We received (and happily publish) another great feedback from one of our beta testers. The original text is in Italian, but I translated it for you here:

Thanks, CodeArchitects! And a special thank to Francesco Balena for the job he did in developing this great VB6/.NET migration tool.