Using the ArcGIS samples


This document was published with and applies to ArcGIS 9.3.
A 10 version also exists. A 9.2 version also exists.
Summary Each sample provides a description of how to get that specific sample to work, but there are common tasks you need, which you are assumed to be familiar with. These include opening the solution, compiling, setting up for debugging, running the sample, and unregistering it when you are done.

In this topic


About using the ArcGIS samples

The ArcGIS software development kits (SDKs) contain a number of samples for you to use. Each sample has an associated README file that provides the steps for using that sample. This file is located in the help system or in HyperText Markup Language (HTML) format on disk in the sample's folder. However, there are a few steps that must be taken for all samples. The following two steps are common to all samples:
 
The next steps (debugging and running the sample) differ based on the type of sample you use. The following are the sample types:
 
Sample type
Description
Executables
Create .exe files and are complete applications that are used alone; for example, a complete controls application.
Class libraries and components
Create .dll files that are used through other applications, such as ArcMap or a controls application. Some examples of dynamic-link libraries (DLLs) are commands, tools, extensions, custom layers, custom renderers, and custom symbols.
 
Visual Studio settings—The first time you start Visual Studio 2005 or Visual Studio 2008, you are prompted to choose development settings. Choosing different settings changes the options displayed in Visual Studio. Unless specified, dialog boxes and menu commands discussed in this topic are defined based on the general development settings in Visual Studio 2005 Professional Edition.

Downloading samples from the Web site

You can get the samples from an installation of the software; however, they are also available to download as zip files from the ESRI Resource Centers. If you have downloaded a sample, extract it to get the associated files.
 
If the sample has associated data, the sample's zip file includes a "data" folder along with the language folders. However, update the sample to point to the location of the data once you have extracted all the files.

Opening solution files

In Windows Explorer, browse to the sample's location on disk. The location will be in <Your ArcGIS install location>/DeveloperKit/SamplesNET (Desktop or Engine folder, or both) with the folder name in the README file. Open the C# or VB .NET version and double-click the solution file (.sln) to open in Visual Studio. If you are working in Visual Studio 2005, choose the solution file ending in 2005.sln. If you are working in Visual Studio 2008, choose the solution file ending in 2008.sln. See the following screen shot for selecting the Visual Studio 2005 solution file:
 
 
If you are working in Windows Vista with a sample that creates a .dll, run Visual Studio (2005 or 2008) as an administrator by doing the following:
  1. Click Start, All Programs, and Microsoft Visual Studio (2005 or 2008).
  2. Right-click the Visual Studio application and select Run as Administrator.
  3. Open the solution file in the integrated development environment (IDE). 
The reason to "Run as Administrator" is that ArcObjects are Component Object Model (COM) based. For COM applications to run, register them in the Windows Registry. Writing to the Windows Registry requires Administrator privileges.

Compiling samples

In the opened Visual Studio solution for the sample, choose Build Solution from the Build menu or press F6 to compile the sample.
 
Some samples can have code updates or edits you need to make, such as pointing the sample to data located on your machine. These steps are highlighted in the README's How to use section and need to be completed before you compile.

Debugging samples

This step is optional, as samples do not require debugging. However, stepping through the code of the sample to see what it is doing can be beneficial. To view what is happening, set breakpoints in the opened Visual Studio project so that code execution stops. To set breakpoints, click the border in Visual Studio next to the line of code where you want a breakpoint placed. If you want to debug an EXE, you can at this point. If you want to debug a DLL, set up the external application to use for debugging. For more information, see the Debugging DLLs section in this topic.
 
Before starting a debugging session, ensure the active configuration is set to Debug. Start the project by choosing Start Debugging on the Debug menu or press F5. The application (the .exe or the external one that was set for the .dll) launches. Interact as directed by the How to use steps in the README and outlined in Running samples. As you hit the breakpoints that were set, focus switches back to Visual Studio.
 
Debugging DLLs
Since a DLL is used through another application, set up Visual Studio to use that application as the debugging start action if you want to debug the DLL code. Access the opened sample project in Visual Studio. Double-click the Properties entry in the Solution Explorer (if it is available). If it is not available, click the Project menu and select <Project name> Properties. When the property pages open, click the Debug tab and in the Start Action section, choose Start external program; be sure to choose Debug in the Configuration drop-down list.
 
Next, set the external program that you want to use. The README file helps you figure out which of the following options you should choose: 
 
If you are using Visual C# 2005 Express Edition or Visual Basic 2005 Express Edition, you cannot debug DLLs because these versions do not have the option to start an external application for debugging.

Running samples

Now that you have opened and compiled the sample, it is ready to use. Refer to the Additional Requirements and How to use sections of the sample's README file to see if you need to take additional steps before using the sample (for example, adding specific data, starting an edit session, and so on).
 
Running EXEs
An executable sample can be used like any .exe on your machine by double-clicking the compiled .exe in Windows Explorer. Alternatively, you can run the .exe in debug mode as discussed in Debugging samples.
 
Running DLLs
If the sample produces a DLL, this indicates that the sample provides custom classes to extend ArcGIS applications, such as a custom command. The sample's README file indicates the application—one of the ArcGIS applications or a custom one—the custom class should be used with. To use it, start the application and follow the README steps for using the sample.
 
DLLs need to be registered with the Component Object Model (COM) and can require registering classes to component categories. The sample code takes care of this registration, and the samples will be registered appropriately at compile time.
Adding commands or tools to a toolbar
Running a command or tool DLL involves adding it to a toolbar. The sample's README file indicates the kind of toolbar the command or tool works with and provides the category the command or tool is in and the name of the command or tool. The following outlines the necessary steps to take based on the kind of toolbar the command or tool works with:

[C#]
string progID = "esriControls.ControlsMapFullExtentCommand";
axToolbarControl1.AddItem(progID,  - 1,  - 1, false, 0,
  esriCommandStyles.esriCommandStyleIconOnly);

[VB.NET]
Dim sProgID As String
sProgID = "esriControls.ControlsMapFullExtentCommand"
ToolbarControl1.AddItem sProgID
    1. Add the command or tool through the ToolbarControl property pages:
      1. In the design view of the application, right-click the ToolbarControl.
      2. On the property page, click the Items tab, then click the Add button to open the Control Commands dialog box.
      3. Click the command or tool category in the Categories pane.
      4. In the Commands pane, click the command or tool. Double-click the command or tool, or drag and drop it on the toolbar on the Items tab of the property page. 
        • If you are using an application that is set up to allow customization of the ToolbarControl at run time, follow that application's steps for adding a command or tool to the ToolbarControl.
The Allow run time customization of the ToolbarControl is a recommended sample that is used to test sample tools and commands (only applies to ArcGIS Engine). The sample needs to be placed on a ToolbarControl that is buddied with a MapControl. The following is the sample's location:

<your ArcGIS install location>/DeveloperKit/SamplesNET/Engine/ToolbarControlCustomization
 
If you have not used this sample, choose the C# or VB .NET version of the sample and compile it, then browse to and launch the created .exe.
  1. Click the Customize check box to open the Control Commands dialog box and click the Commands tab. 
  2. Choose the category the command is in from the Categories pane, click the command or tool from the Commands pane, then drag and drop it on the application's toolbar.

Unregistering DLLs

You can unregister a DLL sample from your machine when you are done. To unregister a DLL, use the Assembly Registration Tool (regasm.exe) with the command line flag /unregister. See the following example:
 
regasm MySample.dll /unregister
 
Do the following to open a command prompt in Microsoft Windows XP:
 
Do the following to open a command prompt in Microsoft Windows Vista:
To use the Regasm.exe utility, run the program from its location on disk. Using DOS commands at the command prompt, navigate to the appropriate Microsoft .NET Framework installation location. Regasm.exe can be found in %windir%\Microsoft.NET\Framework\v2.0.xxxx (where xxxx is the build number of the .NET framework you are using).
On the taskbar, click Start and click Run. In the Run dialog box, type cmd to get a command prompt.


See Also:

Sample: Allow run time customization of the ToolbarControl (Engine)