Development in Arc8: Migrating from ArcView 3.x

In this document I have tried to record the lessons of migrating to development within Arc8, in particular from the perspective of Avenue programming and developing within ArcView 3.x. I have tried to capture those hurdles that I have had to jump over and hope that these questions and answers will smooth the ride for others. This document is a work in progress, and I would appreciate any feedback on suggestions, changes, errors, etc.

Sections

• General getting started issues
• Specific programming tasks
• Programming in Visual Basic
• Creating Extensions
• XML in Arc8

Do first!

Fix the Component Category Manager With nothing running, open an MS-DOS window and surf to the \arcgis\arcexe81\ArcObjects Developer Kit\Utilities directory. There type in:

FixRegistry /R

If any "problems" are identified by the program, then type:

FixRegistry /F

Without this fix, ESRI's Component Category Manager (categories.exe) won't display all available categories, i.e. half of the examples won't work because you can't register the components. Why this isn't documented better, I don't know.

General

Is there a way to translate my Avenue code to VBA?

No, not with ESRI products. There is a consulting group, TaigaGIS, that claim to be able to convert Avenue to VB/VBA—I don’t how expensive this service is.

This company has also created a tool that will convert Dialog Designer dialogs to VB(?) forms in the ESRI ArcScripts site. I haven’t used it.

Where’s the best place to get starting in learning to develop in Arc8?

Open the “Exploring ArcObjects” Acrobat document and read Chapters 1 & 2 (first couple of sections). This book presents the simplest introduction to ArcObjects and the VBA interface. It also walks you through several examples in detail. Don’t try to start in the Help files—they’re mainly designed for reference. Additionally, you’ll want paper copies of the object diagrams. The “Exploring ArcObject” book contains abridged versions that are good to start with.

I found that reading some, coding until I got stuck, and reading some more helped me to understand what I was reading and come up with new questions to ask.

Beyond this book, I’ve found the “Object Model Overviews” within the ArcObjects Developers Help useful for starting to work with a specific set of objects. Additionally, the samples provided with Arc8 are extensive and contain a lot of useful code. For example, the file dbUtil.bas in the directory \arcgis\arcexe81\ArcObjects Developer Kit\Samples\3D Analyst\Utilities contains several routines for manipulating and getting information on feature classes.

How to I debug my program?

In the VBA environment, there are several tools to figure out what’s wrong with the script you just wrote. First, you can add Debug.Print statements to your code to write a message when the program reaches a particular execution point or if you need to know the value of a variable. To see these statements, open the View → Immediate Window. This is the window where these statements are printed.

Second, when an error occurs, VBA will halt execution at the line of code generating the error. The error message will be practically useless—it’ll do more to confuse than clarify the problem. At this point, you can fix the error and continue execution (hitting the ► button) or you can look at the values of your variables. Open the View → Locals Window to see the value, class, and interface of your variables.

Third, you can add breakpoints to stop execution at a particular line of code. This is a useful way of examining the variables that are giving you grief.

Fourth, you can step through the code line-by-line using Debug → Step Into or the F8 key.

What line of code is my error in?

Sometimes VBA doesn’t highlight the line of code that generated a particular error (why?!). To get around this little bug, step through the code as described above to see which line the program baulks at.

Where do I save my code?

In ArcMap, you’ll want to use a project template file (*.mxt) to develop your tools and customizations in.

How do I develop in ArcCatalog?

All VBA development in ArcCatalog has to be saved in the normal.gxt document. There are no other templates that ArcCatalog loads. Unfortunately, this means that errors in your VBA scripts “corrupt” the normal.gxt file.

What if I mess up “normal.gxt?”

You can delete normal.gxt or normal.mxt in your working directory and Arc8 will create a new, blank copy on the next startup of ArcCatalog or ArcMap. (GD)

What is an “interface?”

Interfaces are different sets of ways to interact with an object. In Avenue, an object or class only had one way to interact with it, i.e. only one set of methods or class requests. In Arc8, an object or class can have different interfaces or multiple objects can share the same interface depending on the programming context and how you’d like to use it. For example, both ArcMap and ArcCatalog are instances of the Application class, but ArcMap uses the IMxApplication interface and ArcCatalog uses the IGxApplication interface.

How do I use “interfaces?”

In declaring a variable, you use both the “Dim” and “Set” statement to define the object and the interface that you want to use. For example, ...

How do I figure out the interface or class of an unknown object?

This is much more difficult than it ought to be (or was in Avenue). Most of my problems in VBA are not having the correct interface or object, but not quite sure what I do have. The VBA tools TypeOf and Is are supposed to help. From the VB Environment help:

To check whether an object supports an interface, you can use Visual Basic's TypeOf keyword. For example, given an item selected in ArcMap's table of contents, you can test whether it is a FeatureLayer using the following code:

Dim pDoc As IMxDocument
Dim pUnk As IUnknown
Dim pFeatLyr As IGeoFeatureLayer
Set pDoc = ThisDocument
Set pUnk = pDoc.SelectedItem
If TypeOf pUnk Is IGeoFeatureLayer Then
    ' can we QI for IGeoFeatureLayer?
    Set pFeatLyr = pUnk         ' actually QI happens here
    ' Do something with pFeatLyr
End If

This code, then, doesn’t determine that class a particular object is, but it tells you if that object supports a particular interface.

I’ve got the right object, but want to use a different interface? How do I switch?

One thing they drill into you at the esri course is QI, Query Interface. Basically, you've done it already I think in your stuff. Dim a pointer as an interface, set the pointer to an object (that uses that interface), dim another pointer to a different interface (one that the object also recognizes) then set that pointer to the other pointer. That'll still point to the same object, but through the other interface. Example:

Dim pWorkspace as IWorkspace
Set pWorkspace = CreateAccessGDB("C:\temp","Test") ' Workspace class
Dim pFeatureWS as IFeatureWorkspace
Set pFeatureWS = pWorkspace

you now have the IFeatureWorkspace interface on pWorkspace. (GD)

What is a ProgID and why do I use them?

I don’t know yet. If someone has a good description, please let me know.

What are “Factories?”

Some classes, workspaces for example, can’t be created by just instantiating an object of the class. Instead, the various class “factories” are used to create instances of these objects.

Naming conventions?

Look on page 114 of Exploring ArcObjects or see the VB Reference Sheet.

How do I distribute my code?

In Arc8, there are several ways distributing your code and tools to other users. However, none are very straightforward. Here are your options: 1) Give the user a copy of the VBA code (as a *.bas file). They'll need to know how to import this file in the Visual Basic editor and add any buttons to connect to the script(s). 2) Give the user a copy of your normal.gxt or *.mxt file that contains your customizations. For ArcMap, this is a viable solution, the user merely needs to add this template (*.mxt) file to their project. For ArcCatalog, however, this approach doesn't work as well. By replacing their normal.gxt file, the user will erase any customizations they've made. 3) Develop in Visual Basic and create a DLL or extension. See below for more details.

What are "references?"

If you invoke objects in either VBA and VB, the compiler will only recognize the objects if they are in the compiler's list of references. Otherwise, the compiler will generate an error. In VB, the references dialog is under "Project -> References". For example, if I want to open Excel from ArcMap, I would need to add a reference to the Microsoft Excel Object Library. Note that your code should handle the contingency that the client machine doesn't have access to the library, e.g. Excel isn't installed.

Specific programming tasks in VBA

How do I test a form?

Make the form the active object and click the play button.

How do I reference a UserForm in VBA?

You use the UserForm’s name (which you can set in the UserForm’s property window). For example, a control button would open a form “fHello” using the following code:

    Private Sub UIButtonControl5_Click()
        fHello.Show
    End Sub

How can I change the name of the custom buttons and tools from the default, i.e. UIButtonControl5?

How do I manipulate the status bar and messages?

There are several different progress dialogs available. The simplest is the IStepProgreessor which allows for a progress bar and message. The IProgressDialog and IProgressdialog2 objects allow for more complicated progress dialogs (they both open a new window) but are more difficult to set up and use.

Where is Avenue’s “list” and “dictionary” variable types?

The VBA equivalents are collections and dictionaries. They’re created as follows:

Dim pCollection As New Collection
pCollection.Add "Eric"
pCollection.Add "Lori"
For Each sString in pCollection
  ' do something
Next

In Avenue, it was so easy to use a For Each loop to iterate through lists. In VB, the same is partially true for collections. The For Each A in B doesn't work for collections of just any arbitrary object type, e.g. GxObjects. I have yet to figure out the rhyme or reason for when it does or does not work. 

How do I easily have the user select a file or directory?

Use the front ends to Window API calls in the Visual Basic module basWin32API.bas. Add this module to either a VBA document or a VB project. Usage directions are in the comments of the module.

Programming in VB

The most straightforward way of developing and testing new tools is by using VBA within ArcCatalog or ArcMap. However, to share these new tools, especially with non-technical users, you'll need to create Extensions to package and distribute tools within. For this, you'll need the full power of Visual Basic.

Programming within Visual Basic for Arc8 is more complicated than in VBA. Instead of writing code and immediately testing it in ArcCatalog or ArcMap, you have to first create a DLL (dynamic linked library) from your code and then register different components of your code (commands, extensions, etc.) as ESRI components. ArcCatalog or ArcMap have to be restarted before you can view and test the changes.

In general, I suggest developing, debugging, and testing individual tools within VBA and then copying the code into a VB project. However, this procedure isn't always possible. Forms developed in VB can't be loaded into VBA, so any project containing forms has to be debugged from within VB.

For this section, all code and suggestions were developed within Visual Basic 6.0

How do I get started?

Open a new project in Visual Basic. Under "Project -> References..." check, at a minimum, the "ESRI Object Library." You'll probably want to add references to "ESRI ArcCatalog Object Library" or "ESRI ArcMap Object Library." Depending on which Arc8 functions you'll be calling, you may need to add references to additional libraries.

How do I debug my code within VB?

Debugging code generated in Visual Basic is much more difficult than in VBA. I suggest three alternatives:

1) Two of ESRI's Add-in tools are useful: an automated error handler and an automated line number generator. Used together, they generate run-time error messages from commands or extensions to help in debugging a VB project. To use these tools, first run the ESRI Line Number Generator and add line numbers to all source code. Second, run the ESRI ErrorHandler Generator for each module, class, or form that you'd like to debug. Compile the project (either with VB's "File -> Make..." or with ESRI Compile and Register Add-in) and open ArcCatalog or ArcMap. Run the command and see what error messages are generated. Unfortunately, this procedure is not dynamic. For each debugging iteration, it requires closing of ArcCatalog or ArcMap, regeneration of line number (if new lines are added), and recompiling of the project.

2) Another way to debug a VB project is to copy the error causing code into ArcCatalog's or ArcMap's VBA window and use VBA debugging tools. This works well for discrete sections of code that can be isolated easily, but not so well with intricate dependencies. 

3) Create a special form to emulate the "Immediate" window in VBA that you can open and leave open while testing. Any debugging messages can be sent to this window.

How do I "register" my tools?

You need to register the classes you've created (such as ToolBars or Commands) in order for Arc8 to know that they exist. This can either be done manually by editing the Windows Registry, using ESRI's Categories.exe program (in \arcgis\arcexe81\Bin), or by using the "ESRI Compile and Register" Visual Basic Add-In. I suggest the latter approach. To register classes: 1) open the compile and register tool; 2) select the class to register, e.g. clsE00ImportCommand; 3) and then check the "component category" that the class belongs to, e.g. ESRI GX Commands. If the category you're looking for doesn't appear in the list, choose the "Select Component Categories..." from the "Categories" menu of this window. You'll be able to add your category from this master list. When you compile your project with this tool, it automatically registers each class you've created. Notes: 1) You must run the FixRegistry.exe program to be able to view all ESRI component categories; see "Do First!" above. 2) Sometimes this add-in loses its information and the categories selected. 

What happened to "ThisDocument" and "Application" objects that I used in VBA?

Since ArcObjects are designed for developing standalone applications, these objects no longer exist and getting access to the main application or document become a little more difficult. There are two main ways of getting references to these objects:

1) In interfaces for Commands and Extensions, there is a "hook" to the application object given when these classes are created.

2) There is a special object called "AppRef," that can be used to get a reference to the application object.

How come scripting objects, e.g. dictionaries, FileSystemObject, don't work in VB?

You need to go to Project -> References and add a reference to the "Microsoft Scripting Runtime" library. 

How do I read and write an Access database?

You'll need to create a reference to the ADO library (I'm using Microsoft ActiveX Data Access Objects 2.6 Library and the Microsoft .

How do I add an icon to the taskbar/window bar for my form/application?

First, you need to create an icon using an icon editor. IMAGEDIT.EXE comes with Visual Basic and is in the C:\Program Files\Microsoft Visual Studio\Common\Tools folder. Note: when you're creating your icon, use the "screen" color for any areas that you want to be transparent. Save this icon (*.ico) file. An NPS icon is available here.

Second, open your form in Visual Basic. Under properties, scroll down to the "Icon" property and click on it. Then, click on the ellipses button that appears to select the icon file you've created. 

Creating Extensions

You wouldn't know it from ESRI's documentation, but Extensions aren't that difficult to implement. 

How do I build an Extension?

Look at the Sample Extension sample in ESRI’s online examples. I’ve successfully used this project as a template for creating my own extensions.

What are Premier Toolbars?

"Premier Toolbars" is a poorly named process for having a toolbar in your extension show up the first time the user loads your extension. You'll want to set your toolbars as Premier Toolbars when you distribute your extension. Otherwise, the user won't see your extension's toolbar when they load it.

Where are extensions stored?

Extensions, i.e. the DLL file, can be stored anywhere on the machine. It needs to be registered as a COM object on the particular machine it's being used on. When including extensions as part of an install package, you may want to create a

XML in Arc8

XML shows up in Arc8 when dealing with metadata. All metadata is stored in an XML file that by default is similar to the FGDC standard with a few changes. It is very similar to the SGML files that were previously used to store metadata but with quite a few more capabilities.

What is XML?

XML stands for "eXtensible Markup Language" and is a standard for storing almost any type and form of data.

What are XML stylesheets or XSL?

XSL, or XML stylesheet language, is a programming language to convert (or "transform" in its parlance) data from XML to other formats. For example, the stylesheets in ArcCatalog convert the XML metadata into HTML that ArcCatalog can display. It allows you to add HTML tags, rearrange the data, filter, and sort. Stylesheets are important in Arc8 for creating custom displays of metadata. See the NPS metadata stylesheet for a simple example.

What are XML Schemas?

Schemas are a way of validating the structure and data content of an XML file. For example, they could determine if bounding coordinates were within a valid range and contained a sufficient number of digits. It is a replacement for DTD or "document type definition." They are currently only used within ArcIMS. The USGS metadata parser (mp) serves this function for XML metadata currently using a DTD. Note: a different type of "schema" is used in geodatabases to validate their structure and data.

Contact

For any questions, comments, and complaints, please email Eric Compas at edcompas@wisc.edu. 

Last Updated: 9/9/2003
http://www.nature.nps.gov/im/units/mwr/gis/migrate.htm