This feature is no longer available. It was removed for the 10.3 release of the ArcObjects .NET SDK.
In this topic
- About the ArcGIS Snippet Editor source code
-
Using the ArcGIS Snippet Editor source code
- Code guidelines
- Fully qualify code
- Add XML documentation comments
- Make snippet code modular
- Create snippet statements type
- Create complex ArcGIS snippets
About the ArcGIS Snippet Editor source code
The Source code – ArcGIS Snippet Editor dialog box is the first in a series of dialog boxes that lets you create or edit an existing ArcGIS snippet. Use this dialog box to specify code that will be contained in the ArcGIS snippet. This code can be in the Visual Basic and C# .NET languages.
The .NET code can contain regular comments and Extensible Markup Language (XML) documentation comments. You must also specify the correct language information (that is, C# or Visual Basic) for your code. The following screen shot shows the Source code – ArcGIS Snippet Editor dialog box with sample code:
![Screen shot showing the Source code - ArcGIS Snippet Editor dialog box.](./bitmaps/2f1c7127-bd97-4e54-bd0e-98897fa12ed11.png)
Using the ArcGIS Snippet Editor source code
Do one of the following to add code into the Source code - ArcGIS Snippet Editor dialog box:
- Use the ArcGIS Snippet Editor Manager to create an ArcGIS snippet—Using this option sets the Source code - ArcGIS Snippet Editor to be the topmost (instead of modal) dialog box. This means you can copy a block of code from any Visual Basic or C# code editor class file, then paste it into the Source code - ArcGIS Snippet Editor dialog box. Click the Language option button before you click Next, then proceed through the remaining ArcGIS Snippet Editor dialog boxes. All subsequent ArcGIS Snippet Editor dialog boxes are modal after you click Next. Complete or cancel the creation of the ArcGIS snippet before you interact with the rest of Visual Studio.
- Create an ArcGIS snippet from a highlighted block of code in Visual Studio's code editor—In a Visual Basic or C# code editor window, highlight a block of code, then right-click and choose ArcGIS Snippet Editor Wizard from the popup context menu, which opens the ArcGIS Snippet Editor series of dialog boxes. By using this option, all ArcGIS Snippet Editor dialog boxes (including the Source code - ArcGIS Snippet Editor) are modal. Complete or cancel the creation of the ArcGIS snippet before you interact with the rest of Visual Studio. This option copies the highlighted block of code in Visual Studio's Visual Basic or C# code editor window, then pastes it into the Source code - ArcGIS Snippet Editor. The correct language is set based on the type of class file (that is, .vb or .cs from the copied highlighted block of code) to initiate the new ArcGIS snippet.
- Click Cancel to close the series of ArcGIS Snippet Editor dialog boxes. Starting the dialog boxes from the ArcGIS Snippet Editor Manager and clicking Cancel returns to the applicable ArcGIS Snippet Editor dialog box. For more information, see Overview of the ArcGIS Snippet Editor Manager.
- Click Next to proceed to the Title, Long Description, Type, Directory - ArcGIS Snippet Editor dialog box. For more information, see Title, long description, type, and directory options for the ArcGIS Snippet Editor.
Code guidelines
During the creation of the ArcGIS snippets, there were several lessons learned to make quality reusable snippets to maximize the purpose of the ArcGIS Snippet Finder. This section discusses some coding recommendations to follow when creating your library of ArcGIS snippets.
Fully qualify code
The ArcGIS Snippet Finder can adapt to the coding style of the developer modifying its code insertion preferences. If you write fully qualified code (that is, specify the names of all types by it full assembly name), you give other developers the option to choose if they want to have the code that is inserted by the ArcGIS Snippet Finder to be fully qualified, or trim the fully qualified name from the code and insert the appropriate using (C#) or Imports (Visual Basic) statements at the top of the class file. For more information, see Code insertion options.
- The following code example shows using fully qualified code on the Source code - ArcGIS Snippet Editor dialog box:
Public Sub Greeting1()
System.Windows.Forms.MessageBox.Show("Hello World")
End Sub
[C#]
public void Greeting1()
{
System.Windows.Forms.MessageBox.Show("Hello World");
}
- The following code example shows if the "Use fully qualified variable syntax" coding style on the Preferences dialog box of the ArcGIS Snippet Finder was selected:
Public Sub Greeting1()
System.Windows.Forms.MessageBox.Show("Hello World")
End Sub
[C#]
public void Greeting1()
{
System.Windows.Forms.MessageBox.Show("Hello World");
}
- The following code example shows if the "Use using (C#) or Imports (VB .NET) statements and shortened variable syntax" coding style on the Preferences dialog box of the ArcGIS Snippet Finder was selected:
Imports System.Windows.Forms
Public Sub Greeting1()
MessageBox.Show("Hello World")
End Sub
[C#]
using System.Windows.Forms;
public void Greeting1()
{
MessageBox.Show("Hello World");
}
If the code you inserted into the Source code - ArcGIS Snippet Editor dialog box is in the shortened syntax variable format, you will not be able to take advantage of the "Use fully qualified variable syntax" option on the ArcGIS Snippet Finder.
Tip: To ensure all of your code is fully qualified, comment out the using (C#) or Imports (Visual Basic) statements at the top of your class file, then verify the code still compiles.
Do not include using (C#) or Imports (Visual Basic) statements on the Source code – ArcGIS Snippet Editor dialog box. The using or Imports statements are automatically added into the code editor from the ArcGIS Snippet Finder and are part of the ArcGIS snippet by the remaining ArcGIS Snippet Editor dialog boxes.
Do not add additional comments in the ArcGIS snippets on the Source code – ArcGIS Snippet Editor dialog box. These additional comments are automatically added to the ArcGIS snippet by the remaining ArcGIS Snippet Editor dialog boxes.
Do not use #Region (Visual Basic) or #region (C#) directives to surround your code on the Source code – ArcGIS Snippet Editor dialog box. These directives are automatically added to the ArcGIS snippet by the remaining ArcGIS Snippet Editor dialog boxes.
Add XML documentation comments
It is important to have good comments in code examples to understand the code's purpose. Make sure XML comments use the .NET standard three forward slashes (///) for C# and three single quotation marks (''') for Visual Basic .NET comments.
If you do not want to view comments, remove them during the ArcGIS Snippet Finder's code insertion process by clearing the "Include XML code documentation" check box on the Preferences dialog box for the ArcGIS Snippet Finder.
Make snippet code modular
Using snippets promote code reuse. Do not use hard-coded property values. Also where possible, wrap your code into a method (C#), function, or sub routine (Visual Basic). This makes your code modular and promotes its longevity.
The following code example shows legitimate code and what you could have in an application's code; however, some would consider it to be a poor snippet:
[VB.NET]
Dim rgbColor As IRgbColor = New RgbColorClass
rgbColor.Red = 255
rgbColor.Green = 123
rgbColor.Blue = 0
rgbColor.UseWindowsDithering = True
[C#]
IRgbColor rgbColor = new RgbColorClass();
rgbColor.Red = 255;
rgbColor.Green = 123;
rgbColor.Blue = 0;
rgbColor.UseWindowsDithering = true;
The following code example has been modularized, fully qualified, and has XML documentation comments. It is a better example for a reusable ArcGIS snippet that developers can benefit from.
[VB.NET]
''' <summary>Generate an RgbColor by specifying the amount of red, green, and blue.</summary>
''' <param name="myRed">A byte (0 to 255) used to represent the color red. Example: 0.</param>
''' <param name="myGreen">A byte (0 to 255) used to represent the color green. Example: 255.</param>
''' <param name="myBlue">A byte (0 to 255) used to represent the color blue. Example: 123.</param>
''' <returns>The IRgbColor interface.</returns>
''' <remarks></remarks>
Public Function CreateRGBColor(ByVal myRed As System.Byte, _
ByVal myGreen As System.Byte, _
ByVal myBlue As System.Byte) As ESRI.ArcGIS.Display.IRgbColor
Dim rgbColor As ESRI.ArcGIS.Display.IRgbColor = New ESRI.ArcGIS.Display.RgbColorClass
rgbColor.Red = CInt(myRed)
rgbColor.Green = CInt(myGreen)
rgbColor.Blue = CInt(myBlue)
rgbColor.UseWindowsDithering = True
Return rgbColor
End Function
[C#]
/// <summary>Generate an RgbColor by specifying the amount of red, green, and blue.</summary>
/// <param name="myRed">A byte (0 to 255) used to represent the color red. Example: 0.</param>
/// <param name="myGreen">A byte (0 to 255) used to represent the color green. Example: 255.</param>
/// <param name="myBlue">A byte (0 to 255) used to represent the color blue. Example: 123.</param>
/// <returns>The IRgbColor interface.</returns>
/// <remarks></remarks>
public ESRI.ArcGIS.Display.IRgbColor CreateRGBColor(System.Byte myRed, System.Byte
myGreen, System.Byte myBlue)
{
ESRI.ArcGIS.Display.IRgbColor rgbColor = new ESRI.ArcGIS.Display.RgbColorClass();
rgbColor.Red = System.Convert.ToInt32(myRed);
rgbColor.Green = System.Convert.ToInt32(myGreen);
rgbColor.Blue = System.Convert.ToInt32(myBlue);
rgbColor.UseWindowsDithering = true;
return rgbColor;
}
By modularizing your code into a single method, function, or sub, set the drop-down list for the snippet type to be function-sub-method on the Title, Long Description, Type, Directory – ArcGIS Snippet Editor dialog box.
Create snippet statements type
You can create a snippet statements type if there are cases where parameterizing your code by wrapping it into a method (C#), function, or sub (Visual Basic) does not make sense, or you want to inject code into an existing method, function, or sub.
Statements snippet types are code fragments that act as templates for you to modify. Usually, code from statements snippets will not compile unless you make modifications. Unless otherwise directed, insert statements snippets inside of an existing method, function, or sub in your class. Typically, they do not perform a complete programming task.
The majority of snippets provided by Microsoft with Visual Studio are the statements types (that is, code fragments). Microsoft does not make a distinction between different snippet types (this is a term specific to ArcGIS snippets). For more information, see Statements option for the ArcGIS Snippet Editor.
The following code example shows a statements snippet type:
[VB.NET]
System.Windows.Forms.MessageBox.Show("Hello World")
[C#]
System.Windows.Forms.MessageBox.Show("Hello World");
Statements snippets can require modification to be useful. When you want to substitute your value, the section of code that needs modifying is highlighted with a green box (when using the Microsoft snippet insertion method).
Hovering over the green highlighted section of the statements snippet causes a ToolTip to appear directing you to change the value to meet your coding requirements. The ToolTip indicates the value and provides an example that you can use.
See the following screen shot that shows the standard Microsoft snippet insertion method that is based on an ArcGIS snippet statements type:
![Screen shot showing the standard Microsoft snippet insertion method based on an ArcGIS snippet statements type.](./bitmaps/2f1c7127-bd97-4e54-bd0e-98897fa12ed12.png)
The ArcGIS Snippet Finder does not have the ability to show ToolTips and change the substitution value like the standard Microsoft snippet insertion method. This functionality will be considered for a future release of the ArcGIS Snippet Finder.
The ArcGIS Snippet Editor dialog boxes can create statements snippet types with substitution values. To do this, encase the substitution value within dollar signs ($).
The following code example shows what to type in the text box of the Source code - ArcGIS Snippet Editor to accomplish this:
[VB.NET]
System.Windows.Forms.MessageBox.Show("Hello World")
[C#]
System.Windows.Forms.MessageBox.Show("Hello World");
The goal is to allow developers who use the standard Microsoft snippet insertion method the ability to replace the "Hello World" string with another value. The following code example shows what to type on the Source code - ArcGIS Snippet Editor to accomplish this:
[VB.NET]
System.Windows.Forms.MessageBox.Show($GREETING$)
[C#]
System.Windows.Forms.MessageBox.Show($GREETING $);
On the ArcGIS Snippet Editor dialog boxes, if you specified the snippet type to be statements, you have the option on the Statements - ArcGIS Snippet Editor dialog box to specify a replacement value, object type, and Help string for the substitution entries that begin and end with a dollar sign ($).
When you create an ArcGIS snippet with a few code fragments, set the drop-down list for the snippet type to be statements on the Title, Long Description, Type, Directory - ArcGIS Snippet Editor dialog box.
Create complex ArcGIS snippets
If your snippet has multiple methods, subs or functions, or global variables that need to be at the root of a class file, set the snippet type to "other" on the Title, Long Description, Type, Directory - ArcGIS Snippet Editor dialog box. The ArcGIS Snippet Editor can also be used if the snippet contains the complete contents of a class file.
See Also:
ArcGIS Snippet EditorOverview of the ArcGIS Snippet Editor Manager
Customization options for the ArcGIS Snippet Editor Manager
Title, long description, type, and directory options for the ArcGIS Snippet Editor
References option for the ArcGIS Snippet Editor
Extensions, products, and versions options for the ArcGIS Snippet Editor
Statements option for the ArcGIS Snippet Editor
Snippets for ArcGIS .NET developers
ArcGIS Snippet Finder
To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
System.Windows.Forms
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 |