Snippets for ArcGIS .NET developers

In this topic

• About snippets
• ArcGIS snippet types
• Adding ArcGIS snippets in your code
  • Using the ArcGIS Snippet Finder dialog box
  • Using the standard Insert Snippet context menu
• Comments in ArcGIS snippets
  • General information comments
  • XML documentation comments
• IntelliSense examples
• Using the Object Browser to view XML documentation comments
• Creating ArcGIS snippets

About snippets

ArcGIS snippet types

• function-sub-method: Those that act as a single sub or function (for VB .NET) or method (for C#)—Single sub or function and method types of ArcGIS snippets take zero or more input parameters and perform some operation (might or might not have a return value). All required input and output parameters are documented using Extensible Markup Language (XML) style coding practices (allows for IntelliSense to aid in coding when utilizing the procedures).
• statements: Chunks of code that must be inserted in existing code blocks (this type always has the Statements keyword  preceding its description)—The statements type of ArcGIS snippets consists of pieces of code that act as templates for you to complete. Usually, code from Statements snippets will not compile unless you make modifications. Ordinarily, Statements snippets are inserted in an existing method in your class unless otherwise directed. Statements snippets often require some modifications to be useful. When using the standard Microsoft snippet insertion technique, you can substitute your literal (string or number) or object value (variable). The section of code that needs modification is highlighted. Pausing the mouse pointer on the highlighted section of the method snippet causes a ToolTip to appear directing you to change the value to suit your coding requirements. These ToolTips indicate what the literal (string or number) or object value (variable) is and provide you with an example.
• other: Code that is comprised of a multiple function-sub-method(s)—The other type of ArcGIS snippets can be almost any code you want. It can be an entire class or multiple function-sub-method(s) put together in a logical grouping. Member (that is, global) variables can be used in conjunction with multiple function-sub-method(s).

Adding ArcGIS snippets in code

• ArcGIS Snippet Finder dialog box—The ArcGIS Snippet Finder is a custom dialog box for searching and inserting ArcGIS-based snippets into your Visual Studio code editor. This dialog box is only available as part of the Esri ArcObjects .NET SDK. This option to insert ArcGIS snippets allows Boolean-based keyword searches to find the necessary snippets. It also gives you the flexibility to customize how the ArcGIS snippet should be inserted into your Visual Studio project, including automatically adding references to dependent assemblies as required. For more information about the available features for this option, see ArcGIS Snippet Finder. 

• Standard Insert Snippet context menu—The standard Insert Snippet context menu uses the default Visual Studio options to find and insert ArcGIS snippets into your code editor. You traverse the hierarchy of ArcGIS snippets and insert the full code based on your selection. Using this option, you must manually add all required references to dependent assemblies to compile and use the ArcGIS snippet.

Using the ArcGIS Snippet Finder dialog box

1. Right-click and select ArcGIS Snippet Finder on the Visual Studio code editor window. See the following screen shot:

 

2. Click the drop-down arrow to select the top level directory of ArcGIS snippets you want to search and type the keyword or keywords in the Keyword(s) text box, then click Search or press the Enter key. See the following screen shot:

3. In the Snippets that meet criteria section, click the snippet title to view the code. The specified keyword or keywords are highlighted in the Snippet text section to assist you in evaluating whether a particular snippet is of interest. See the following screen shot:

 

4. Click Insert Code to add the ArcGIS snippet on the Visual Studio code editor. You can then review comments on how to use the code in your project. For easier code readability, most snippets can be expanded and collapsed by clicking the plus (+) or minus (-) sign on the # Region directive. See the following screen shot:

Using the standard Insert Snippet context menu

1. To show a list of available code snippets, right-click the active document in the code editor and click Insert Snippet. See the following screen shot:

2. Click ArcObjects to view the list of available ArcGIS snippets. See the following screen shot:
   
   

3. Scroll the list of available snippets to determine the functionality you want. A ToolTip appears when you pause on a snippet to provide more information on its functionality. See the following screen shot:
   
   

4. When the ArcGIS snippet code is inserted in the code editor, you can review comments on how to use the code in your project. For easier code readability, most snippets can be expanded and collapsed by clicking the plus (+) or minus (-) sign on the # Region directive. See the following screen shot:
   
   

Comments in ArcGIS snippets

• General information comments
• XML documentation comments

General information comments

• ArcGIS Snippet Title—ArcGIS snippet name.
• Long Description—More descriptive explanation for the functionality of the ArcGIS snippet.
• Add the following references to the project—ArcGIS assemblies that need to be added to your project for the snippets to successfully compile and run.
• Intended ArcGIS products for this snippet—ArcGIS products (that is, ArcGIS for Desktop, ArcGIS Engine, and ArcGIS for Server) for the applicable snippet.
• Applicable ArcGIS Product Versions—Specific ArcGIS software versions for which the ArcGIS snippet is applicable.
• Required ArcGIS Extensions—Specific ArcGIS add-on products (for example, ArcGIS Spatial Analyst or ArcGIS Network Analyst) that need to be used for the snippets to compile and run.
• Notes—Provide specific details on how the snippet should be used and often indicate the level in the code where the snippets should be inserted.

XML documentation comments

• <summary></summary>—Provides details on what the snippet does. It expounds more on the title's meaning. The same information that is in the ToolTip when inserting a snippet in your code from the Code Snippets Manager is in the summary tags.
• <param name></param name>—Outlines required inputs or parameters to call a specific ArcGIS snippet. There can be zero or more parameters that are necessary to invoke a particular procedure.
• <returns></returns>—Provides details on objects returned from calling a particular procedure. There can be zero or one return value.
• <remarks></remarks>—Provides additional information that helps to understand how the ArcGIS snippet works.

IntelliSense examples

• To view what the <summary></summary> tags provide in IntelliSense, type the name of the necessary ArcGIS snippet's sub or function, then type an open parenthesis and several commas (depending on the number of input parameters) to view the summary tag. See the following screen shot:
  
  
• To view what the <param name></param name> tags provide in IntelliSense, type the name of the necessary ArcGIS snippet's sub or function, then type the open parenthesis. If one or more parameters are used, they will show. For ArcGIS snippets that have two or more input parameters, type a comma for additional parameter arguments. See the following screen shots:
  
  
  
  

Using the Object Browser to view XML documentation comments

Microsoft Visual Studio also comes with a default Object Browser that can be used to view XML documentation comments embedded in ArcGIS snippets. The Object Browser details all XML documentation in the ArcGIS snippets and aids in the reuse of code. To open the Object Browser, choose Object Browser from the View menu in Visual Studio. See the following screen shot:

Creating ArcGIS snippets

ArcGIS snippets utilize an enhanced set of XML tags in addition to the standard Microsoft snippet format. It is these extra XML tags that give the ArcGIS Snippet Finder its ability to perform Boolean-based keyword searches and control what gets inserted into the Visual Studio code editor. The ArcGIS Snippet Editor is a system that allows .NET developers to create, edit, delete, and manage custom ArcGIS snippets. You can also edit Esri ArcGIS snippets to meet your development needs. To create ArcGIS snippets, highlight a block of code, right-click the active document in the code editor, then click ArcGIS Snippet Editor Wizard. See the following screen shot:



You can then proceed through the wizard dialog boxes to complete your ArcGIS snippet. The following screen shot shows the first ArcGIS Snippet Editor Wizard dialog box:

There is also an ArcGIS Snippet Editor Manager that is a central application where you can create, edit, and delete ArcGIS snippets. You can also manage where ArcGIS snippets are stored on disk and control the options for the ArcGIS Snippet Editor Wizard dialog boxes. To access the ArcGIS Snippet Editor Manager, choose Tools, then Options in Visual Studio. For more information, see Overview of the ArcGIS Snippet Editor Manager. 

See the following screen shot:

See Also: