How to use ArcGIS samples

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

• Opening solution files
• Compiling samples

• 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

Downloading samples from the Web site

Opening solution files

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. 

2. Open the C# or VB .NET folder.
3. Double-click the solution file (.sln). The solution file opens in Visual Studio. 

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

1. Start Visual Studio and open the sample's solution file.

Debugging 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.

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

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.

Running samples

Running add-ins

Running EXEs

Running DLLs

Adding customizations to an application

Adding a button, tool, command, tool palette, or combo 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 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.

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:

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

Dim sProgID As String
sProgID="esriControls.ControlsMapFullExtentCommand"
axToolbarControl1.AddItem(sProgID, -1, -1, False, 0, esriCommandStyles.esriCommandStyleIconOnly)

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.

• <your ArcGIS Developer Kit install location>/Samples/ArcObjectsNET/ToolbarControlCustomization

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.

Adding a toolbar

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.

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

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.

Adding a root menu

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.

Adding a dockable window, multi-item, or menu

Creating an application extension

• 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

Unregistering DLLs

ESRIRegAsm /p:desktop /u "C:\Test\MyAssembly.dll"

ESRIRegAsm /p:engine /u "C:\Test\MyAssembly.dll"

1. Click the Start menu.
2. Click All Programs, Accessories, and Command Prompt.

1. Click the Start menu.
2. Click All Programs, Accessories, then right-click the Command Prompt.
3. Choose Run as Administrator.

See Also: