Spring 2011 Edition
By Craig Gallant, LJB Inc.
This article as a PDF.
You might ask this after installing ArcGIS 10. With the release of ArcMap 10, Visual Basic for Applications (VBA) is on the way out. As the online help article "Migrating VBA customizations to ArcGIS 10" explains, "VBA no longer provides the best toolset for customizing ArcGIS and is not included in the default installation."
At ArcGIS 10, there are two new ways to customize in ArcGIS 10: Python and the new ArcGIS Desktop Add-in. [Add-ins are a new way to customize and extend ArcGIS 10. They are authored in .NET or Java and Extensible Markup Language (XML). They provide a declaratively based framework for creating a collection of customizations that can be conveniently packaged in a single compressed file that is easily shared. Add-ins do not require installation programs or Component Object Model (COM) registration.] Both options have advantages and disadvantages. You need to pick the option that best suits your application. This article shows how, with a little refactoring, existing VBA code can quickly be converted to an ArcGIS Desktop Add-in.
The VBA sample for this exercise is a simple form that reads the selected county on the map and displays its information on the form. You will need at least Visual Studio Express 2008 SP1 (which is a free download from Microsoft). You will also need the ArcObjects SDK for the .NET Framework that is included with ArcMap 10. The SDK will install templates in the Visual Studio environment that will create the Desktop Add-in project. If the ArcGIS templates do not show up when creating a new project, make sure you have .NET Framework 3.5.
Because this article is intended to demonstrate the ease of converting VBA code to .NET, some of the description of the project creation process is not detailed. For more detailed information, Esri has created a very good example. Search the online help for the article "Walkthrough: Migrating VB6 to VB .NET for ArcGIS 10."
When converting a VBA to an ArcGIS Desktop Add-in, creating the form will take the most time because there is no easy way to copy. It must be manually re-created. However, as demonstrated in the next section, the code is reusable and easily upgraded.
The VBA sample is a simple program that has four parts:
There is one other major piece: a subroutine called ReadData. This is where the work is done in the VBA sample, and this code needs to be copied and converted. An easy way to do this is to export the form to be upgraded out of the VBA editor and open the exported file with the .frm extension in Notepad. Copy the subroutine and paste it into the newly created form in the add-in project.
In this example, open the included file called Form1.frm in Notepad and copy the subroutine ReadData. Right-click the form created in Visual Studio and pick View Code. Paste the subroutine in the code behind.
When the code is pasted, several errors will show up. Most of these will go away once the right references are added. Because the project was created in Visual Studio and not the VBA editor, you have to add references to ArcObjects.
This example requires two references. From Project Menu, pick Add Reference and choose Esri.ArcGIS.Carto and Esri.ArcGIS.Geodatabase from the .NET tab. Just adding the references won't fix the problems because the code that was copied worked in VBA because the VBA editor understood the shorter names for ArcObjects. This is easily fixed by adding import statements at the top of the code. Doing this lets Visual Studio use the shorter names also.
At the very top of the code for the form, above the public class, add three import statements (Figure 4). Type
Once the imports and references have been added, the number of errors decreases from 10 to 5.
The next fix addresses something that happens a lot when converting code from VBA to .NET. To set the text to the labels in VBA, the property is called Caption. In .NET, to set the text to the label, the property is called Text. This is easy enough to fix.
One way would be to simply replace the word caption with the word text. Another way demonstrates one of the benefits of using the Visual Studio environment. Go to the error lblCountyName.Caption and delete .Caption. Place the cursor at the end of the word lblCountyName and press the period key. This brings up Intelli-Sense and shows all the properties available to set on the label. Scroll down and pick the word Text.
While it might have been easier to just retype Caption to Text, if the correct property is not known, this is a very useful feature. After changing the labels from caption to text, only one error remains. This is really the only major error in converting the code.
An error is triggered by ThisDocument. Although the VBA editor had a reference to ThisDocument, Visual Studio does not know what ThisDocument is. To fix this error, change ThisDocument to My.ArcMap.Document, which is the ArcGIS Desktop Add-in reference to the current ArcMap document.
When all errors are fixed, Visual Studio displays the warning error "'pFCursor' is passed before it is assigned." To fix this, go to the line of code
Dim pFCursor as IfeatureCursor
To the end of this line, add
From the Window menu, pick Form1.vb [Design]. This will switch back to the Form Design view.
All the code has been converted for the form. Figure 5 shows the code before and after. Not much has changed in the conversion between VBA and the add-in. However, note that when pasting the code, Visual Studio did convert some code automatically. In this example, it removed the word Set and it put parentheses around the command pFLayer.SelectionSet.Search.
There is one last thing to do before the code is ready to use. To show the VBA form, it had to be assigned to a button UIControl from the Customize menu. When the add-in project was created, the Button checkbox was checked. This added a command button to the project.
From the Solution Explorer, right-click FormButton.vb and pick View Code. This opens the code for the button. In the OnClick() event, add the following two lines:
Dim frm As New Form1
This tells the button when it is clicked to create a new form and show it.
That's it for converting the code. Now go to the Build menu and build the project. After the project is built, the files are bundled as an add-in and automatically installed in ArcMap.
Open the USA.mxd sample included with the developer kit. It contains counties and states for the entire United States. Go to the Customize menu and pick Add-In Manager (Figure 6), verify the add-in loaded, and close the dialog box. Go to the Customize menu and pick Customize Mode.
In the Customize dialog box, click the Commands tab (Figure 7). Choose Add-In Controls from Categories (the category that was defined when creating the add-in). Drag the My Form Button from Commands and drop it on any toolbar. Close the Customize dialog box.
In ArcMap, select a county on the map. Click the button to show the county form that was just dragged to the toolbar. This opens the County Info dialog box. With a county selected, click the Read Data button on the dialog box. This will read the selected county information and display it on the form. Click the Close button to close the County Info dialog box.
This code could be improved. The add-in model has many more options. For more information on these topics, see the online help for ArcObjects for .NET. The Esri online help is very useful.
In conclusion, even though VBA is gone, with a little refactoring and a good bit of copying and pasting, existing VBA code can be reused in the new .NET environment.
Craig Gallant is a senior designer at LJB Inc. in Dayton, Ohio. He can be contacted at firstname.lastname@example.org.