Best practices for creating a custom geoprocessing function tool—ArcObjects 10.4 Help for Java

Summary

This topic discusses recommended practices for creating a custom geoprocessing tool. It details design specifications, naming conventions, parameter guidelines, and developer guidelines.

In this topic

Design specifications
Tool description
Naming convention guidelines
Parameter guidelines
Developer guidelines

Design specifications

Geoprocessing development starts with a design specification. Include the following in your geoprocessing design specifications when creating custom geoprocessing tools:

General description of the tool—The general description contains a textual write-up about the tool and the name of the toolbox and toolset to which it will belong. A tool executes one logical function or process. If your design allows for multiple functions in a tool, such as Create then Edit; or Add Field then Calculate Values, divide the functions into separate tools: one tool for Create and one for Edit; one for Add Field and one for Calculate Values.
Tool description—The tool description is the syntactical breakdown of your tool. See the Tool Description section for more information.
Mock-up tool dialog box—A draft of the tool dialog box.

Tool description

Before you begin developing a tool, create a tool description doc with the following information:

Tool name
Tool label
Brief description of the tool
Parameter name
Parameter label
Brief description of the parameter
Parameter data type (GPMultiValue, FolderType, and so on)
Parameter domain (if applicable)
Parameter type (required or optional)
Parameter direction (input or output)

The Clip (Analysis) tool is shown here as an example:

FC Clip function
USAGE: FCCLIP <in_feature_class> <clip_feature_class> <out_feature_class>
{PLANAR | NON_PLANAR} {SINGLE_PART | MULTI_PART} {cluster_tolerance}

<in_feature_class>—The input feature class.
    Parameter name = in_feature_class
    Parameter label = Input feature class:
    Data type       = DEFeatureClassType
    Domain          = FC in {POLY, POINT, LINE}
    Direction       = Input

<clip_feature_class>—The polygon feature class used to clip features in the input feature class.
    Parameter name = clip_feature_class
    Parameter label = Clip feature class:
    Data type       = DEFeatureClassType
    Domain          = FC in {POLY}
    Direction       = Input

<out_feature_class>—The output feature class.
    Parameter name = out_feature_class
    Parameter label = Output feature class:
    Data type       = DEFeatureClassType
    Domain          = N/A
    Direction       = Output

{PLANAR | NON_PLANAR}—Determines if output polygons can overlap (as with shapefiles).
    Parameter name = planar
    Parameter label = Allow overlapping polygons?
    Data type       = GPBooleanType
    Domain          = IN {PLANAR, NON_PLANAR}
    Direction       = Input

{SINGLE_PART | MULTI_PART}—

    Parameter name = multi_part
    Parameter label = Allow noncontiguous output?
    Data type       = GPStringType
    Domain          = IN {SINGLEPART, MULTIPART}
    Direction       = Input

{cluster_tolerance}—The minimum distance between coordinates in the output coverage.
    Parameter name = cluster_tolerance
    Parameter label = Cluster tolerance:
    Data type       = GPDoubleType
    Domain          = >= 0
    Direction       = Input

Naming convention guidelines

For consistency and continuity, adhere to the following naming convention guidelines when creating a custom geoprocessing function tool:

Do not use numbers or special characters in a toolbox name.
Begin a toolbox name with an initial capital letter for each word.
End a toolbox name should with the word "Tools" (for example, Conversion Tools).
Assign the toolbox an alias. The alias is related to the toolbox name. For example, analysis for the Analysis toolbox and SA for the Spatial Analyst toolbox.
Begin a toolset name with an initial capital letter for each word.
Do no use the words "Tools" or "Toolset" in a toolset name.
Toolset labels should only start with initial capitalization for each word.
Tool names shouldn't contain any spaces, numbers or special characters.
Tool names should not be pluralized.
Tool labels should mirror the tool name, with spaces separating multiple words. (ex: TableSelect > Table Select)
Tool labels should never end in the word "Tool".
Function tools metadata is read from an XML file found in the …\\ArcGIS\Help\gp folder of the install, that always follow the same naming scheme: toolname + "_" + toolboxAlias + ".xml" (Ex: tableselect_analysis.xml).
Tools should have their description property set.
Tools that add system attributes (fields) to their output should use a naming convention that doesn’t include plurals.

Parameter guidelines

For consistency and continuity reasons the following parameter guidelines must be adhered to by all developers. This will help insure the user experience is consistent.

Name parameters based on their data type. (Ex: <in_features> or <in_table>)
Input parameters should start with “in_”, followed by a reference to their data type. (Ex: <in_features> or <in_table>)
Output parameters should start with “out_”, followed by a reference to their data type. (Ex: <out_feature_class > or <out_view>)
Input parameters that allow for multiple values should list two inputs separated by a semi-colon, with an ellipse (…) at the end. (Ex: <in_features; in_features…> or <Features {Ranks};Features {Ranks}...>)
The order of precedence for parameters is “required first, optional last”. Within each parameter type (required/optional), input parameters should be listed before output parameters.
Keywords should appear in all capital letters. Syntactically, they should be listed with the default keyword first followed by all other keywords separated with a vertical bar “|”. (EX: {POINT | LINE | POLYGON})
Boolean parameters should have a domain of keywords that will appear as command line keyword options.

Developer guidelines

Adhere to the following developer guidelines when creating a custom geoprocessing function tool:

Do not store state in a tool.
Pack and unpack values using GPUtilities.pack() and GPUtilities.unpack() for tool parameters within the BaseGeoprocessingTool.execute() method. This allows the values to be used in ModelBuilder.
Test whether the tool is licensed with the BaseGeoprocessingTool.execute() method.
Create and populate a new parameter array in the BaseGeoprocessingTool.getParameterInfo() method; do not copy or clone it.
Always have an output parameter so that it can be chained to other processes in ModelBuilder. If your tool does not have an output, create one of ParameterType = Derived.
Test the tool from a script, model, dialog, and the command line.
Do not create pop-ups or expect user interaction during execution of the tool.

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