Tools and add-ins  

VB6 Code Converter add-in

This add-in converts VB6 projects to work with ArcGIS 9.2. You can convert either the active project, or use the batch option to convert many projects at a time.

The steps carried out for each project are as follows:

  1. Remove project references to the old ArcObjects type libraries
  2. Replace all occurrences in code of the old library names with new library names (e.g. esriCore.IPolygon becomes esriGeometry.IPolygon)
  3. Replace all occurrences of tagesri with esri as long as replacement is found in the type libraries
  4. Log warnings for potential problems with MapControl and PageLayoutControl QueryInterfaces.
  5. Add project references to the new assemblies according to object types found in the code (e.g. if 'Dim pPoly As IPolygon' is found then a reference to esriGeometry is added)
  6. Compile the project. DLLs are not unregistered or reregistered as this should not be required.

Note - If your projects includes ArcGIS Controls or ControlCommands the code converter needs to shut down the project and the VB6 IDE in order to finish the conversion. In this case you need to reopen your project and compile it manually.

The add-in dialog is shown below.

NOTE - the ESRI Automatic References add-in also adds references to projects. Before running this code converter, be sure to uncheck the 'Set on project open' option from the Options menu of the ESRI Automatic References add-in. You will only need to do this once, as this preference is recorded in the registry.

A log file of the conversion details will be placed in the same folder as the VB project. The log will be shown after the conversion finishes.

Project compatibility option

The code conversion process cannot maintain binary compatibility for components that implement an ArcObjects interface. The ArcGIS 8.3 type libraries against which the existing compatible DLL was built are no longer available, so the interface definition for the implementation in the existing DLL cannot be found. If you upgrade the code and library references and compile with binary compatibility you will get a 'BadImplementsRefInCompatLib' error.

To avoid this problem, by default the code converter compiles with project compatibility, and if this succeeds, resets the project back to binary compatibility. Project compatibility maintains the GUIDs of the classes in your project, but makes new GUIDs for interfaces. This means the DLL does not need to be unregistered or reregistered, but clients to the DLL may need to be rebuilt in the following situations:

  1. If your classes have public properties and methods used by clients.
  2. If your project defines interfaces by using public classes

The checkbox at the bottom left of the dialog allows you to prevent binary compatibility being switched off. You might prefer this when converting projects that use ArcObjects, but do not implement any ArcObjects interfaces.

Project backup option

The code converter saves all its work, you will not be able to undo the changes without first having taken a backup of the project. By default, no backup is taken, since if you use source code control it is likely to be unnecessary. A checkbox at the bottom left of the dialog provides the option of an automatic backup of the Visual Basic projects. This is placed in a sub-folder called 'ESRICodeConverterBackup' alongside the project. For complete caution you should take your own backup of your files rather than rely on this automatic backup.

Batch conversion dialog

Use the Batch Conversion dialog to convert many Visual Basic Projects at once.

Use the file browser on the left of the dialog to select a folder. Clicking the Add button will select all the Visual Basic projects in that folder and recursively any sub-folders. You can alter the list of projects selected for conversion with the Remove and Clear buttons. A single log file is created for the conversion of all the selected projects. You can specify the location of this log file at the bottom right of the dialog.

The batch conversion honours the options set on the main add-in dialog, for example the project backup option.

Batch conversions may require some user interaction. For example, executable projects without a startup form or a Sub Main will pop up a dialog when the converter tries to compile the project. This user-interaction is unavoidable since Visual Basic add-ins cannot fully control the Visual Basic environment.

Other things to note about the code converter add-in

If your project uses old 8.3 library names as variable names, e.g. MapControl, the code converter will log errors for occurrences such as:

MapControl.Width = 555

The code converter will replace library names even if they occur in a commented section of code (though it does not add a reference in this case).

It is possible that the code converter could add an unnecessary reference to a project. Take for example the situation where ICamera is found in the code. (ICamera is one of the 3D Analyst ArcObjects interfaces). It is possible that a different ICamera interface is already referenced in another type library (perhaps something to do with photographs) and that adding an esri3DAnalyst reference would be incorrect. In the case where the type is already prefixed in the code by a non ESRI library name, for example, PhotoLib.ICamera, then the code converter does not add the ESRI reference. However, when the type is not prefixed, the ESRI reference is added. Any possible resulting ambiguity of references should not normally result in a change to program behavior. Since the original type library would have been added to the project first, it will occur with a higher priority in the references dialog box, which means it is favoured over the newly added ESRI reference. If there is any likelihood of ambiguity, it is recommended that you explicitly specify the type library when you use a type in Visual Basic code.

For projects using objects that have the same name in two referenced type libraries, the code conversion may fail. An example would be code such as the following:

Dim pPoint as IPoint
Set pPoint = New Point

The Point and IPoint types are defined in both the esriGeometry library, and the Microsoft Excel object library. The code is inappropriate usage of the Excel objects, so if the Excel library is referenced in the project, this code will only compile if the ESRI library is given priority in Visual Basic's References Dialog Box. The Code Converter add-in will add the new esriGeometry library reference after (that is, with a lower priority than) the Excel library reference, and so the project will not compile after conversion. This kind of situation is straightforward to resolve by using Visual Basic's Object Browser to identify which libraries define the type that is causing the compilation error. It is good practice to avoid this problem altogether, by explicitly specifying the type library in the code where there is a danger of ambiguity; for example:

Dim pPoint as esriGeometry.IPoint
Set pPoint = New esriGeometry.Point

Note that this problem can occur with IStatusBar (in esriSystem) and the StatusBar control that is in the Microsoft Windows Common Controls library. The controls libraries are normally referenced via Visual Basic's Components Dialog Box, rather than the References Dialog Box.

Extending the code converter add-in to work with your own libraries

The VB6 Code Converter is extensible, so it can be used to upgrade code for projects where non-ESRI objects have been migrated to new libraries. To do this you will need to implement an extension class that details the old superseded libraries that your developers used to use, and also the new, current, libraries that your developers will be using from now on.

The extension class must implement just one interface: ILibLookupExtension. You will find the type library information for this interface in Support.dll, which is in the Tools folder of the Developer Kit. When adding a reference to this library in the Visual Basic references dialog, its name appears as 'ESRI Developer Kit Support Type Library'. ILibLookupExtension is fairly easy to implement - it is designed to provide lists of 'library name- library GUID' pairs for your old libraries and new libraries.

Here is an example implementation of the NewLibraryCount and NewLibrary members:

Private Sub ILibLookupExtension_NewLibrary(lIndex As Long, sLibName As String, sGuid As String)
  Select Case lIndex
    Case 0
      sLibName = "NewLib1"
      sGuid = "{688A0CD2-E640-4FEA-98D1-D7A2D8020FEB}"
    Case 1
      sLibName = "NewLib2"
      sGuid = "{890D5FB2-C3FE-4176-BE09-DA22F976963F}"
    Case Else
      sLibName = ""
      sGuid = ""
  End Select
End Sub

Private Property Get ILibLookupExtension_NewLibraryCount() As Long
  ILibLookupExtension_NewLibraryCount = 2
End Property

If your type libraries define enumerations, your extension must also provide the strings that are used at the start of your enumeration value names. The ESRI enumeration value names start with 'esri', for example 'esriDTTable'. Providing these prefix strings enables the code converter to correctly add library references when the enumeration values are used in developer code for example:

eRequiredDatasetType = esriDTTable

One point to note is that the enumeration prefixes are required for your new libraries, not your old libraries. The code converter does not automatically convert old enumeration value names to new ones, apart from those starting 'tagesri'. Here is an example implementation of the two members of ILibLookupExtension that provide the enumeration name information:

Private Function ILibLookupExtension_EnumValPrefix(lIndex As Long) As String
  Select Case lIndex
    Case 0
      ILibLookupExtension_EnumValPrefix = "acme"
    Case Else
      ILibLookupExtension_EnumValPrefix = ""
  End Select
End Function

Private Property Get ILibLookupExtension_EnumValPrefixCount() As Long
  ILibLookupExtension_EnumValPrefixCount = 1
End Property

Once you have implemented your class, it must be registered to the correct component category. The registration of Support.dll, which happens automatically with the ArcGIS Developer Kit, creates the 'ESRI Developer Kit Library Handling Extensions' category (whose CATID is {D25CC5EB-97E5-456C-88D2-66849B9C42CE}). If developing with VB6, you can easily create a .reg script to register your classes to this category with the ESRI Compile and Register Add-in.

Once you have installed and correctly registered your extension on your client PC, you are ready to test the ESRI VB6 Code Converter Add-In against your own libraries. The new libraries must be registered on the client PC for the code converter to work. You may also notice that the Library Locator tool can now be used to report the appropriate library for your types - this is because the extension works on a component that is shared by both the Code Converter Add-In and the Library Locator tool.

How to set up the ESRI VB6 add-ins