Snippets for ArcGIS .NET developers


This feature is no longer available. It was removed for the 10.3 release of the ArcObjects .NET SDK.

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

Snippets are chunks of reusable code that aid programmers in performing common tasks. A thorough understanding of the available ArcGIS snippets in the ArcObjects .NET software development kit (SDK) can greatly reduce the amount of time spent coding, encourage modularity, and improve continuity. ArcGIS snippets are utilized in the Visual Basic and C# code editors in Microsoft Visual Studio. For more information about the use of snippets in Visual Studio, see the Microsoft Developer Network (MSDN) Web site's topic, What's new in Code Editing.

ArcGIS snippet types

The following are the three basic types of ArcGIS snippets (function-sub-method, statements, and other):
  • 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

The following are the two methods for inserting ArcGIS snippets into your code in Visual Studio:
  • 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

Do the following steps to use 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:

 
  1. 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:
  1. 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:

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

Do the following steps to use 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:
  1. Click ArcObjects to view the list of available ArcGIS snippets. See the following screen shot:

  1. 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:

  1. 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:

By using the standard Insert Snippet context menu option, you are responsible for adding any required references to the appropriate assemblies for the code to compile. In the preceding screen shot, the blue wavy underlines exist under the various Esri types signifying that Visual Studio cannot determine the assemblies to which these features belong. Once the correct references are added, the blue wavy underlines disappear. To avoid this, use the ArcGIS Snippet Finder dialog box with its various insertion options.

Comments in ArcGIS snippets

Become familiar with the embedded comments in the ArcGIS snippets that are inserted in Visual Studio's code editor. The following are the two main types of comments in ArcGIS snippets:
  • General information comments
  • XML documentation comments

General information comments

General information comments are preceded by one single quotation mark (') for Visual Basic, double slashes (//) for C#, and contain the following information:
  • 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

XML comments are preceded by three single quotation marks (''') for Visual Basic and three forward slashes (///) for C# and allow XML documentation style comments to be used. For more information, see the MSDN Web site's topics, Documenting Your Code with XML (Visual Basic) and XML Documentation Comments (C# Programming Guide).
Using XML style documentation comments allow IntelliSense and Object Browser capabilities in ArcGIS snippets. The following are the four specific XML documentation tags used in ArcGIS snippets:
  • <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.
To preserve IntelliSense and Object Browser XML documentation capabilities, do not insert custom code between the XML documentation comments and the actual snippet code— a green wavy underline shows beneath the XML documentation comments. See the following screen shot:

IntelliSense examples

Most ArcGIS snippets have XML documentation comments that enhance your ability to see the code's functionality using IntelliSense. The following are the examples for using IntelliSense in Visual Studio:
  • 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

A feature of Esri's Visual Studio Integration tools is the ability to create ArcGIS snippets that can be used by the ArcGIS Snippet Finder. This feature is called the ArcGIS Snippet Editor.
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:

ArcGIS Snippet Finder
ArcGIS Snippet Editor




Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced
Engine Developer Kit Engine