How to use ArcGIS samples


Summary
Each sample provides a description of how to get that specific sample to work, but there are common tasks shared among all samples, with which you are assumed to be familiar. 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 ArcGIS samples
  • Downloading samples from the Web site 
  • Opening solution files
  • Compiling samples
  • Debugging samples
    • Debugging add-ins and DLLs
  • Running samples
    • Running add-ins
    • Running EXEs
    • Running DLLs
  • Adding customizations to an application
    • Adding a button, tool, command, tool palette, or combo box
    • Adding a toolbar
    • Adding a context menu
    • Adding a root menu
    • Adding a dockable window, multi-item, or menu
    • Creating an application extension
    • Loading an editor extension
  • Unregistering DLLs

About using ArcGIS samples

The ArcObjects software development kit (SDK) for the Microsoft .NET Framework contains the samples shown in the following table :
 
Sample type
Description
Add-ins
Create an ArcGIS for Desktop add-in that can be used through the ArcGIS for Desktop application. Some examples of add-ins are buttons, tools, toolbars, menus, extensions, and dockable windows. For more information, see Building add-ins for ArcGIS for Desktop.
 
Some add-ins contain functionality that is also available in ArcGIS Engine; however, using them with ArcGIS Engine requires conversion of an add-in sample to an ArcGIS Engine component. For more information, see Converting an ArcGIS for Desktop add-in to an ArcGIS custom component.
Executables (EXEs)
Create .exe files that are complete applications and are used alone, for example, a complete controls application. For development information, see Building stand-alone applications.
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. For more information, see Extending ArcObjects.
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.
The following are common to all samples:
  • Opening solution files
  • Compiling samples
The following differ based on the type of sample you are using:
  • Debugging samples (optional)
    • No special steps required for EXEs
    • Set up the external application for debugging add-ins or DLLs
  • Running samples
    • Running add-ins
    • Running EXEs
    • Running DLLs (class libraries and components)
  • Adding customizations to an application
  • Unregistering DLLs
Visual Studio settings—The first time you start Visual Studio, you are prompted to choose development settings. Choosing different settings changes the options shown 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.

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 ArcGIS Resource Center. 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. Update the sample to point to the location of the data once you have extracted all the files.

Opening solution files

Before you can use a sample, do the following steps to open its solution file:
  1. In Windows Explorer, browse to the sample's location on disk. The location will be in <Your ArcGIS Developer Kit install location>\Samples\ArcObjectsNET with the folder name specified in the README file. 
  • If you are working with a Visual C++ sample, it will be in the <Your ArcGIS Developer Kit install location>\Samples\ArcObjectsVCPP folder.
  • In the installed developer Help system, the sample's location is in the sample's README file after the table of files.
  • If opening a sample downloaded from the ArcGIS Resource Center Web site, the README files are included in the downloaded zip file.
  1. Open the C# or VB .NET folder.
  2. Double-click the solution file (.sln). The solution file opens in Visual Studio. 
If you are working in Windows Vista with a sample that creates a .dll file, run Visual Studio as an administrator by doing the following:
  1. Click Start, All Programs, and choose the folder for your version of Visual Studio.
  2. Right-click the Visual Studio application and select Run as Administrator.
    • The reason to select Run as Administrator is that ArcObjects are Component Object Model (COM) based. For COM applications to run, they are registered in the Windows registry. Writing to the Windows registry requires administrator privileges.
  3. Open the solution file in the integrated development environment (IDE).

Compiling samples

Do the following steps to compile samples:
  1. Start Visual Studio and open the sample's solution file.
If you are working on a Vista or Windows 7 machine, you will need to run Visual Studio with Administrator permissions in order to compile DLL samples.
  1. Click the Build menu and choose Build Solution or press F6 to compile the sample.
If you are working on a 64-bit machine and using the VC++ samples, you will need to update the OLB path in the .h files for the samples to work.
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 file's "How to use" section and needs to be completed before you compile. If you are working with a sample from your ArcObjects SDK for the Microsoft .NET Framework installation but have copied the sample to a working location, update the path from the sample to any data used.
If you are compiling a custom component that works in both ArcGIS Engine and ArcGIS for Desktop, but you only have one of the products installed on your development machine, you will see a warning at compile time. You do not need to do anything to address this warning.
If your machine only has ArcGIS for Desktop on it, you will see a warning similar to the following:
WARNING The command "esriRegasm.exe "C:\Program Files\ArcGIS\DeveloperKit10.0\Samples\ArcObjectsNET\RSSWeatherGraphicTracker\CSharp\RSSWeatherGraphicTracker\bin\Debug\RSSWeatherGraphicTracker.dll" /p:Engine /s" exited with code -1.
If your machine only has ArcGIS Engine on it, you will see a warning similar to the following:
WARNING The command "esriRegasm.exe "C:\Program Files\ArcGIS\DeveloperKit10.0\Samples\ArcObjectsNET\RSSWeatherGraphicTracker\CSharp\RSSWeatherGraphicTracker\bin\Debug\RSSWeatherGraphicTracker.dll" /p:Desktop /s" exited with code -1.
 
Make sure that it is marked as a warning; if you see an error with that same message, it means your component has failed to register.

Debugging samples

This step is optional, as samples do not require debugging; however, stepping through the sample's code to view what it is doing can be beneficial. Do the following steps to debug samples: 
  1. 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.
  2. If you want to debug an EXE, do so now. If you want to debug a DLL, set up the external application to use for debugging. For more information, see the Debugging add-ins or DLLs section in this topic.
Before starting a debugging session, ensure the active configuration is set to Debug by doing the following:
  1. Start the project by clicking the Debug menu and choosing Start Debugging, or press F5. The application (the .exe file or the external one that was set for the .dll file) starts.
  2. Interact as directed by the "How to use" steps in the README file and outlined in the Running samples section in this topic. As you hit the breakpoints that were set, focus switches back to Visual Studio.

Debugging add-ins or DLLs

Since an add-in and a DLL are used through another application, set up Visual Studio to use that application as the debugging start action if you want to debug the code. Do the following steps to debug an add-in or DLL:
  1. Access the opened sample project in Visual Studio.
  2. Double-click the Properties node in the Solution Explorer (if it is available). If it is not available, click the Project menu and select the <project name> Properties. The project's property pages appear.
  3. Click the Debug tab.
  4. Click the Configuration drop-down arrow and select Debug.
  5. On the Start Action section, click the Start external program option button.
  6. Set the external program that you want to use. The README file helps you determine which of the following options you should choose:
    • Add-in—If the sample creates an add-in, it only works with ArcMap, ArcCatalog, ArcGlobe, or ArcScene. Set the external application to the ArcGIS application where the customization is used. Browse to the location of the .exe file for that application, located in <your ArcGIS install location>/Bin (for example, <your ArcGIS install location>/Bin/ArcMap.exe).
    • ArcGIS for Desktop sample—If the sample creates a DLL that only works with ArcMap, ArcCatalog, ArcGlobe, or ArcScene, set the external application to the ArcGIS application where the custom class is used. Browse to the location of the .exe file for that application, located in <your ArcGIS install location>/Bin (for example, <your ArcGIS install location>/Bin/ArcMap.exe).
    • ArcGIS Engine sample—If the sample creates a .dll file that works in a controls application, browse to the location of the controls application to use. If you do not have one, determine if there is a controls sample that meets your requirements.
      • If the sample is a command or tool that needs to be added to a toolbar linked to a MapControl, use the Allow run time customization of the ToolbarControl sample (only applies to ArcGIS Engine). This application lets you add the command at run time.
    • If you are working with a sample command or tool that can be added to an ArcGIS for Desktop application or a controls application, use the previous ArcGIS for Desktop sample or ArcGIS Engine sample option, depending on the one you have installed and want to use to try the sample.
If you are using the Visual C# Express Edition or Visual Basic 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 determine if you need to take additional steps before using the sample (for example, adding specific data, starting an edit session, and so on).

Running add-ins

If the sample produces an add-in, this indicates that the sample provides customization (such as a button or tool) to ArcGIS for Desktop applications. The sample's README file indicates which ArcGIS application the add-in customizes. To use the add-in, start the application that it customizes and follow the README steps for using the sample.

Running EXEs

An EXE sample can be used like any .exe file on your machine by double-clicking the compiled .exe file in Windows Explorer. Alternatively, you can run the .exe file 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. Adding customizations to an application is discussed in the following section.
COM components must be registered with the system before they can be used. Previously, this was accomplished using the following Microsoft utilities:
  • RegSvr32.exe for native code
  • RegAsm.exe for managed code
Starting with ArcGIS 10, it has been decided to move away from the COM component category approach. The replacement consists of a new registration utility (ESRIRegAsm.exe) and an Extensible Markup Language (XML) database stored in published per product and version configuration folders, independent of the system registry. Therefore, for ArcGIS 10 and later, the registration of component and category information for a developer’s assembly or DLL is achieved using the ESRIRegAsm utility.

Adding customizations to an application

Running a customization involves enabling it in the application (either an ArcGIS for Desktop application or an ArcGIS Engine application) that it customizes, indicated in the sample's README file. The steps to take to add the customization to the application depend on the type of customization you're using. The following sections outline the necessary steps to take to add custom components to an application.

Adding a button, tool, command, tool palette, or combo box 

Running a button, tool, or command DLL involves adding it to a toolbar. The sample's README file indicates the kind of toolbar the command or tool works with, 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 application the command or tool works with.
Do the following steps for an ArcGIS for Desktop application (ArcMap, ArcCatalog, ArcGlobe, or ArcScene): 
  1. Run the application with which the command, button, or tool works.
  2. Click the Customize menu and choose Customize Mode. The Customize dialog box appears.
  3. Click the Commands tab.
  4. Click the item's category on the Categories pane. This information is available in the sample README file.
  5. Click the item on the Commands pane, then drag and drop it onto the toolbar.
Do the following steps for an ArcGIS Engine application (on the ToolbarControl):
  1. With the ArcGIS Engine controls applications, unless the toolbar is set up to allow customization at run time, add the command or tool to the application at design time.
  2. To add it at design time, you have the following option:
    • Add the command or tool programmatically. Once the ToolbarControl is created, initialized, and buddied, call AddItem on the ToolbarControl in the MainForm_Load method. See the following code example:
[C#]
string progID = "esriControls.ControlsMapFullExtentCommand";
axToolbarControl1.AddItem(progID,  - 1,  - 1, false, 0,
    esriCommandStyles.esriCommandStyleIconOnly);
[VB.NET]
Dim sProgID As String
sProgID = "esriControls.ControlsMapFullExtentCommand"
axToolbarControl1.AddItem(sProgID, -1, -1, False, 0, esriCommandStyles.esriCommandStyleIconOnly)
Do the following steps to add the command or tool using 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. The Controls Commands dialog box appears.
  3. Click the command or tool category on the Categories pane.
  4. Click the command or tool on the Commands pane, then drag and drop it onto the toolbar on the Items tab of the property page.
Add the command or tool at run time. 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 enabling customization and adding a command or tool to the ToolbarControl.
The previously mentioned "Allow run time customization of the ToolbarControl" sample can be used to test sample ArcGIS Engine tools and commands that work with a MapControl. The following is the sample's location:
  • <your ArcGIS Developer Kit install location>/Samples/ArcObjectsNET/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 start the created .exe file by doing the following:
  1. Select the Customize check box. The Control Commands dialog box appears. 
  2. Click the Commands tab. 
  3. On the Categories pane, choose the category the command is in.
  4. Click the command or tool from the Commands pane, then drag and drop it onto the application's toolbar.
For an ArcGIS for Desktop application or a controls application—depending on what you have installed on your machine—follow the previous steps for an ArcGIS for Desktop application or an ArcGIS Engine application, respectively.

Adding a toolbar

Before you can use a custom toolbar, it needs to be open in the application it customizes. Do the following steps based on the application the toolbar works with.
An ArcGIS for Desktop application (ArcMap, ArcCatalog, ArcGlobe, or ArcScene) allows toolbars to be added at run time. Adding a custom toolbar is done as follows:
  1. Run the application the toolbar customizes.
  2. Click the Customize menu and choose Customize Mode.
  3. Click the Toolbars tab.
  4. Select the custom toolbar, whose name is indicated in the sample README file or (for an add-in) in the Toolbar tag's caption attribute in the config.esriaddinx XML file.
An ArcGIS Engine application requires that the toolbar be added during development. A custom toolbar can be added to a ToolbarControl as follows:
  1. Right-click the ToolbarControl and select Properties. The Properties dialog box appears.
  2. Click the Items tab.
  3. Click Add.
  4. Click the Toolsets tab on the Control Commands dialog box . The Toolsets list contains the ArcGIS Engine toolbars that you have registered on your machine, listed by their captions. From that list, drag and drop the toolbar you want to add onto your ToolbarControl.

Adding a context menu

Custom context menus must also be added to the application before they can be used. Do the following steps based on the application the context menu works with.
An ArcGIS for Desktop application (ArcMap, ArcCatalog, ArcGlobe, or ArcScene) allows context menus to show on the Customize dialog box:
  1. Run the application with which the context menu works.
  2. Click the Customize menu and choose Customize Mode.
  3. Click the Toolbars tab.
  4. On the Toolbars list, select the Context Menus option, which is located near the bottom of the list.
An ArcGIS Engine application requires context menus be set up during development. For more information, see the "Displaying the custom context menu" section in How to add a context menu using the Visual Studio Integration tools.

Adding a root menu

Root menus can also be added to applications similar to how commands are added. Do the following based on the application the root menu works with.
An ArcGIS for Desktop application (ArcMap, ArcCatalog, ArcGlobe, or ArcScene) allows root menus to be shown on the Customize dialog box:
  1. Run the application with which the command, button, or tool works.
  2. Click the Customize menu and choose Customize Mode. The Customize dialog box appears.
  3. Click the Commands tab.
  4. Click the Menus category on the Categories pane, which is located near the bottom of the list.
  5. On the Commands pane, click the item, then drag and drop the menu onto the menu bar at the top of the application.
ArcGIS Engine does not support root menus.

Adding a dockable window, multi-item, or menu

Dockable windows, multi-items, and menus (except root and context menus) cannot be added to the application on the Customize dialog box (these must be added programmatically). Samples that use them include how to activate the customization in the README file. Most samples that create dockable windows, for example, provide a button or command that shows the customization.

Creating an application extension

The following are the types of application extensions that can be created (each is loaded differently):
  • Basic extensions automatically load when the application starts; therefore, you will not have to take any steps for those.
  • Just-In-Time extensions only load programmatically; therefore, samples that implement them will also handle loading them.
  • Configurable extensions, which implement IExtensionConfig are enabled as follows:
    1. Run the application that the add-in customizes.
    2. Click the Customize menu and choose Extensions.
    3. Select the custom extension, whose name is indicated in the sample README file or in the Extension tag's productName attribute in the config.esriaddinx XML file.

Loading an editor extension

Nothing needs to be done to load editor extension add-ins. They are loaded when the editor session starts (click Editor, then Start Editing).

Unregistering DLLs

You can unregister a sample DLL from your machine when you are done using that sample. To unregister a DLL, use the ESRI Assembly Registration utility (esriRegasm.exe) with the command line flag /u. See the following code example for DLLs for ArcGIS for Desktop applications:
ESRIRegAsm /p:desktop /u "C:\Test\MyAssembly.dll"
See the following code example for DLLs used with ArcGIS Engine applications:
ESRIRegAsm /p:engine /u "C:\Test\MyAssembly.dll"
Do the following to open a command prompt in Microsoft Windows XP:
  1. Click the Start menu.
  2. Click All Programs, Accessories, and Command Prompt.
Do the following to open a command prompt in Microsoft Windows Vista:
  1. Click the Start menu.
  2. Click All Programs, Accessories, then right-click the Command Prompt.
  3. Choose Run as Administrator.
To use the esriRegasm.exe utility, run the program from its location on disk. The esriRegasm.exe utility can be found in the %CommonProgramFiles%\ArcGIS\bin location.


See Also:

Sample: Allow run time customization of the ToolbarControl