Building a custom geoprocessing function tool

In this topic

• Geoprocessing tool overview
• Rules
• Properties and methods
  • IGPFunction2
  • IGPParameter3
• Parameters
  • Direction and ParameterType
  • Name and DisplayName
  • Category
  • DisplayOrder
  • Enabled
• Parameter DataTypes
  • Supporting layers and tables
  • Multiple values
  • Lists
  • Composite
• Updating output data descriptions
• Parameter dependency
• Updating output data and using dependencies
  • Add field
  • Clip
• Domains
  • Feature type
  • String keywords
  • Boolean parameters
  • Dynamic domains
• ControlCLSID
• Methods
  • UpdateParameters()
  • UpdateMessages()
  • Validate()
  • Execute()
• Objects
  • GPEnvironmentManager
  • GPMessages
  • GPMessage
  • GPUtilities
• Implementing IGPFunctionFactory

Geoprocessing tool overview

 

Rules

• Always create a new array in ParameterInfo()
• Always have an output
• Do not localize keywords
• Use a coded value domain for a Boolean parameter

Properties and methods

• ParameterInfo()
• UpdateParameters()
• UpdateMessages()
• Execute()

IGPFunction2

• Name property - The name of the function tool. This name appears when executing the tool at the command line or in scripting. This name should be unique to each toolbox and cannot contain spaces.
• DisplayName property - The display name of the function tool. The user interface (UI) utilizes this property to display the name of the tool in ArcToolbox. This name is a user-friendly description of the function tool. The display name can be internationalized.
• FullName property - The function name object for the geoprocessing function tool. This name object is created and returned by a function factory. A function factory must be created before implementing this property.
• ParameterInfo property - The location where the parameters to the function tool are defined. This property returns an IArray of parameter objects (IGPParameter). These objects define the characteristics of the input and output parameters.
• UpdateParameters() method - Called each time a parameter is changed in the tool dialog box or command line. This updates the output data of the tool, which is useful for building models. After returning from UpdateParameters(), geoprocessing calls its internal validation routine, checking that a given set of parameter values are of the appropriate number, data type, and value.
• UpdateMessages() method - Called after returning from the internal validation routine. You can examine the messages created from internal validation and change them if desired.
• Validate() method - Validate is an IGPFunction method and no longer needs to be implemented. You stub it out in your class, but you don't have to provide code for it.
• Execute() method - Executes the tool given the array of parameter values.
• IsLicensed method - Returns whether the function tool is licensed to execute.
• HelpFile property (optional) - The path to a .chm file, which is used to describe and explain the function and its operation.
• HelpContext property (optional) - The unique context identifier in a [MAP] file (.h).
• MetadataFile property (optional) - The name of the .xml file containing the default metadata for this function object. The metadata file is used to supply the parameter descriptions in the help panel on the dialog box. If no .chm file is provided, the help is based on the metadata file. See Create documentation for custom Geoprocessing tools that are not models or scripts for details.
• GetRenderer method (optional) - Used to set a custom renderer for the output of the function tool.
• DialogCLSID property (not for external use) - For ESRI internal use only. DO NOT IMPLEMENT.

IGPParameter3

• Name - The name of the parameter, for example, input_featureclass. It must not contain spaces.
• DisplayName - The UI uses this name to display the parameter name, for example, Input Features. This can be internationalized.
• Enabled - Controls whether this parameter is enabled or disabled on the UI.
• ParameterType - The enumeration for setting the type of geoprocessing parameter. There are three parameter types: esriGPParameterTypeRequired, esriGPParameterTypeOptional, and esriGPParameterTypeDerived.
• Direction - The enumeration for setting the direction of the parameter. The options are esriGPParameterDirectionInput or esriGPParameterDirectionOutput.
• DataType - Defines the type of data for this parameter. Examples include FeatureClass, Raster, Table, String, and so on. DataType manages the value for the parameter. If the data type is a feature class, a raster cannot be entered as input.
• Schema - The structure or design of the feature class or table, raster, and workspace container. The design can be field information, geometry information, or extent.
• Value - This property defines the default value for a parameter. For every data type, there is an associated value. If the data type is a feature class, the default value for the parameter is a feature class. Values are used as the inputs to the tool containing scalars or a path to the data. For a complete list of value objects, see IGPValue.
• Domain (optional) - The Domain property can be specified to limit or filter a set of values. An example is a domain for a simple value object, limiting an integer to a range of 1 to 100 (RangeDomain).
• ParameterDependencies (optional) - Used to set one parameter dependent on another parameter. For example, a field parameter is commonly dependent on another table or feature class parameter, and a list of fields is dependent on the input table.
• ControlCLSID (optional) - A class identifier can be used to override the default control for the DataType.
• Category (optional) - Creates a collapsible section on the tool dialog box. This is useful for tools with many optional parameters.
• ChoiceList (optional) - Supplies a choice list for the command line.
• DefaultEnvironmentName (optional) - Initializes the environment value to use as the default environment for a parameter.
• DisplayOrder (optional) - The order in which the parameters are listed on the dialog box. The display order is always the order in the array. In the ParameterInfo property, the parameters should be in this order: required, optional, and derived.
• Altered - Indicates whether the parameter has been explicitly set by the user.
• HasBeenValidated - Indicates whether the parameter value has been modified since the last time the parameter was validated.

Parameters

 

 

Public IArray Parameterinfo
{
    get
    {
        // Array to hold the parameters. Always create a new array.
        IArray parameters=new ArrayClass();

        // Create a parameter and insert it into the parameter array.
        IGPParameterEdit3 inputParameter=new GPParameterClass();
        parameters.Add(inputParameter);

        // Create and insert more parameters as needed.
        // <Insert any required parameters following the steps shown with inputParameter above.>

        // Return the parameter array.
        return parameters;
    }
}

Public ReadOnly Property ParameterInfo() As IArray Implements IGPFunction2.ParameterInfo

Get

' Array to hold the parameters. Always create a new array.
Dim parameters As IArray=New ArrayClass()

' Create a parameter and insert it into the parameter array.
Dim inputParameter As IGPParameterEdit3=New GPParameterClass()
parameters.Add(inputParameter)

' Create and insert more parameters as needed.
' <Insert any required parameters following the steps shown with inputParameter above.>


' Return the array.
Return parameters

End Get

End Property

Direction and ParameterType

// Required input parameter.
IGPParameterEdit3 inputParameter=new GPParameterClass();
... inputParameter.Direction =
    esriGPParameterDirection.esriGPParameterDirectionInput;
inputParameter.ParameterType=esriGPParameterType.esriGPParameterTypeRequired;

' Create the parameter.
Dim inputParameter As IGPParameterEdit3=New GPParameterClass()

' Set parameters as input and required.
inputParameter.Direction=esriGPParameterDirection.esriGPParameterDirectionInput
inputParameter.ParameterType=esriGPParameterType.esriGPParameterTypeRequired

// Output parameter is derived and data type is same as input.
IGPParameterEdit3 outParameter=new GPParameterClass();
... 

// Set output parameter properties.
outParameter.Direction=esriGPParameterDirection.esriGPParameterDirectionOutput;
outParameter.DisplayName="Output Feature Class";
outParameter.Name="output_featureclass";
outParameter.ParameterType=esriGPParameterType.esriGPParameterTypeDerived;
parameters.Add(outParameter);

' Output parameter is derived and data type is same as input.
Dim outputParameter As IGPParameterEdit3=New GPParameterClass()

' Set output parameter properties.
outputParameter.Direction=esriGPParameterDirection.esriGPParameterDirectionOutput
outputParameter.DisplayName="Output FeatureClass"
outputParameter.Name="out_featureclass"
outputParameter.ParameterType=esriGPParameterType.esriGPParameterTypeDerived
parameters.Add(outputParameter)

Name and DisplayName

• Name parameters are based on the data type (for example, in_features or in_table)
• Input parameters start with in_, followed by a reference to their data type (for example, in_features or in_table)
• Output parameters start with out_, followed by a reference to their data type (for example, out_feature_class or out_view)

Category

 

DisplayOrder

Enabled

Parameter DataTypes

Supporting layers and tables

// Define input DataType as GPFeatureLayerType to support layers.
IGPParameterEdit3 inputParameter=new GPParameterClass();
inputParameter.DataType=new GPFeatureLayerTypeClass();

' Define input DataType as GPFeatureLayerType to support layers.
Dim inputParameter As IGPParameterEdit3=New GPParameterClass()
inputParameter.DataType=New GPFeatureLayerTypeClass()

Multiple values

// Multivalue parameter of Feature Layers/Feature Classes.
IGPParameterEdit3 inputFeatures=new GPParameterClass();
IGPDataType inputType=new GPFeatureLayerTypeClass();

IGPMultiValueType mvType=new GPMultiValueTypeClass();
mvType.MemberDataType=inputType;

IGPMultiValue mvValue=new GPMultiValueClass();
mvValue.MemberDataType=inputType;

inputFeatures.Name="input_features";
inputFeatures.DisplayName="Input Features";
inputFeatures.ParameterType=esriGPParameterType.esriGPParameterTypeRequired;
inputFeatures.Direction=esriGPParameterDirection.esriGPParameterDirectionInput;
inputFeatures.DataType=(IGPDataType)mvType;
inputFeatures.Value=(IGPValue)mvValue;

parameters.Add(inputFeatures);

' Multivalue parameter of Feature Layers/Feature Classes.
Dim inputParameter As IGPParameterEdit3=New GPParameterClass()
Dim inputType As IGPDataType=New GPFeatureLayerTypeClass()

Dim mvType As IGPMultiValue=New GPMultiValueClass()
mvType.MemberDataType=inputType

Dim mvValue As IGPMultiValue=New GPMultiValueClass()
mvValue.MemberDataType=inputType

inputFeatures.Name="input_features"
inputFeatures.DisplayName="Input Features"
inputFeatures.ParameterType=esriGPParameterType.esriGPParameterTypeRequired
inputFeatures.Direction=esriGPParameterDirection.esriGPParameterDirectionInput
inputFeatures.DataType=CType(mvType, IGPDataType)
inputFeatures.Value=CType(mvValue, IGPValue)

parameters.Add(inputFeatures)

Lists

// DataType and value.
IGPValueTableType valueTableType=new GPValueTableTypeClass();
IGPValueTable valueTable=new GPValueTableClass();

// First DataType is GPFeatureLayerType.
IGPDataType inputLayerType=new GPFeatureLayerTypeClass();
valueTableType.AddDataType(inputLayerType, "input_features", 75, null);
valueTable.AddDataType(inputLayerType);

// Second DataType is GPLongType.
IGPDataType inputLongType=new GPLongTypeClass();
valueTableType.AddDataType(inputLongType, "Rank", 25, null);
valueTable.AddDataType(inputLongType);

// Set input parameter.
IGPParameterEdit3 inParameter=new GPParameterClass();
inParameter.DataType=(IGPDataType)valueTableType;
inParameter.Value=(IGPValue)valueTable;
...... parameters.Add(inParameter);

' DataType and value.
Dim valueTableType As IGPValueTableType=New GPValueTableTypeClass()
Dim valueTable As IGPValueTable=New GPValueTableClass()

' First data type is GPFeatureLayerType.
Dim inputLayerType As IGPDataType=New GPFeatureLayerTypeClass()
valueTableType.AddDataType(inputLayerType, "Input Features", 75, Nothing)
valueTable.AddDataType(inputLayerType)

' Second type is GPLongType.
Dim inputLongType As IGPDataType=New GPLongTypeClass()
valueTableType.AddDataType(inputLongType, "Rank", 25, Nothing)
valueTable.AddDataType(inputLongType)

' Set the input parameter.
Dim inputParameter As IGPParameterEdit3=New GPParameterClass()
inputParameter.DataType=CType(valueTableType, IGPDataType)
inputParameter.Value=CType(valueTable, IGPValue)
....
parameters.Add(inputParameter)

Composite

// Create the GPCompositeDataType.
IGPCompositeDataType compositeType=new GPCompositeDataTypeClass();

// Create the DataTypes that are permitted as input.
IGPDataType dataType1=new GPTableViewTypeClass();
IGPDataType dataType2=new GPRasterLayerTypeClass();

// Add DataTypes.
compositeType.AddDataType(dataType1);
compositeType.AddDataType(dataType2);

// Set the input parameter.
IGPParameterEdit3 inputParameter=new GPParameterClass();
inputParameter.DataType=compositeType;
inputParameter.Value=new GPTableViewClass();

' Create the GPCompositeDataType.
Dim compositeType As IGPCompositeDataType=New GPCompositeDataTypeClass()

' Create the DataTypes that are permitted as input.
Dim dataType1 As IGPDataType=New GPTableViewTypeClass()
Dim dataType2 As IGPDataType=New GPRasterLayerTypeClass()

' Add DataTypes.
compositeType.AddDataType(dataType1)
compositeType.AddDataType(dataType2)

' Set the input parameter.
Dim inputParameter As IGPParameterEdit3=New GPParameterClass()
inputParameter.DataType=CType(compositeType, IGPDataType)

Updating output data descriptions

 

• Make a copy of the input dataset description and add a new field to its list of fields (such as Add Field), or add a list of fixed fields (such as Add XY Coordinates).
• Set the list of output fields to be all the fields in a collection of datasets and, optionally, add fields to contain the feature IDs from the collection of datasets (such as Union and Intersect).
• Set the extent to that of a dataset in another parameter, or the union or intersection (such as Clip) of datasets in a list of parameters.
• Set a specific geometry type (point, line, or polygon), or set the geometry type to that of a dataset in another parameter, or to minimum or maximum type in a list of parameters. The definition of minimum and maximum geometry type is: points=0, polylines=1, and polygons=2. Consequently, the minimum geometry type in the set (point, polyline, polygon) is point and the maximum is polygon.

 

Parameter dependency

// Create the field parameter.
IGPParameterEdit3 fieldParameter=new GPParameterClass();
fieldParameter.DataType=new FieldTypeClass();
... 
// Add dependency to the input feature class parameter by name.
fieldParameter.AddDependency("input_features");

' Create the field parameter.
Dim fieldParameter As IGPParameterEdit3=New GPParameterClass();
fieldParameter.DataType=New FieldTypeClass();
...
' Add dependency to the input feature class parameter by name.
fieldParameter.AddDependency ("input_features");

Updating output data and using dependencies

Add field

public IArray ParameterInfo
{
    get
    {
        //Array to hold the parameters.
        IArray parameters=new ArrayClass();
        ... 

        // Output parameter (derived) and data type is DEFeatureClass.
        IGPParameterEdit3 outputParameter=new GPParameterClass();
        outputParameter.DataType=new GPFeatureLayerTypeClass();

        // Value object is DEFeatureClass.
        outputParameter.Value=new DEFeatureClassClass();

        // Set output parameter properties.
        outputParameter.Direction =
            esriGPParameterDirection.esriGPParameterDirectionOutput;
        outputParameter.DisplayName="Output FeatureClass";
        outputParameter.Name="out_featureclass";
        outputParameter.ParameterType =
            esriGPParameterType.esriGPParameterTypeDerived;

        // Create a schema object. Schema means the structure or design of the feature class 
        // (field  information, geometry information, extent).
        IGPFeatureSchema outputSchema=new GPFeatureSchemaClass();
        IGPSchema schema=(IGPSchema)outputSchema;

        // Clone the schema from the dependency.
        //This means update the output with the same schema by copying the definition of an input parameter.
        schema.CloneDependency=true;

        // Set the schema on the output, because this tool adds an additional field.
        outputParameter.Schema=outputSchema as IGPSchema;
        outputParameter.AddDependency("input_features");
        parameters.Add(outputParameter);

        return parameters;
    }
}

// This method updates the output parameter value with the additional field.
public void UpdateParameters(IArray paramvalues, IGPEnvironmentManager pEnvMgr)
{
    m_Parameters=paramvalues;

    // Retrieve the input parameter value.
    IGPValue parameterValue=m_GPUtilities.UnpackGPValue(m_Parameters.get_Element(0)
        );

    // Get the derived output feature class schema and empty the additional fields. This ensures 
    // that you don't get dublicate entries. 
    // Derived output is the third parameter, so use index 2 for get_Element.
    IGPParameter3 derivedFeatures=(IGPParameter3)paramvalues.get_Element(2);
    IGPFeatureSchema schema=(IGPFeatureSchema)derivedFeatures.Schema;
    schema.AdditionalFields=null;

    // If you have an input value, create a field based on the field name entered.            
    if (parameterValue.IsEmpty() == false)
    {
        // Area field name is the second parameter, so use index 1 for get_Element.
        IGPParameter3 fieldNameParameter=(IGPParameter3)paramvalues.get_Element(1);
        string fieldName=fieldNameParameter.Value.GetAsText();

        // Check if the input field already exists.
        IField areaField=m_GPUtilities.FindField(parameterValue, fieldName);
        if (areaField == null)
        {
            IFieldsEdit fieldsEdit=new FieldsClass();
            IFieldEdit fieldEdit=new FieldClass();
            fieldEdit.Name_2=fieldName;
            fieldEdit.Type_2=esriFieldType.esriFieldTypeDouble;
            fieldsEdit.AddField(fieldEdit);

            // Add the additional field to the derived output.
            IFields fields=fieldsEdit as IFields;
            schema.AdditionalFields=fields;
        }
    }
}

Public ReadOnly Property ParameterInfo() As IArray Implements IGPFunction2.ParameterInfo
Get

' Array to the hold the parameters. Always create a new array.
Dim parameters As IArray=New ArrayClass()

' Output parameter (derived).
Dim outputParameter As IGPParameterEdit3=New GPParameterClass()
outputParameter.DataType=New DEFeatureClassTypeClass()

' Value object is DEFeatureClass.
outputParameter.Value=New DEFeatureClassClass()

' Set output parameter properties.
outputParameter.Direction=esriGPParameterDirection.esriGPParameterDirectionOutput
outputParameter.ParameterType=esriGPParameterType.esriGPParameterTypeDerived
outputParameter.Name="out_featureclass"
outputParameter.DisplayName="Output Feature Class"

' Create a schema object. Schema means the structure or design of the feature class
' (field  information, geometry information, extent).
Dim outputSchema As IGPFeatureSchema=New GPFeatureSchemaClass()
Dim schema As IGPSchema=CType(outputSchema, IGPSchema)

' Clone the schema from the dependency.
' This means update the output with the same schema by copying the definition of an input parameter.
schema.CloneDependency=True

' Set the schema on the output, because this tool adds an additional field.

outputParameter.Schema=CType(outSchema, IGPSchema)
outputParameter.AddDependency("input_features")
parameters.Add(outputParameter)

Return parameters

End Get
End Property


' This method updates the output parameter value with the additional field.

Public Sub UpdateParameters(ByVal paramvalues As IArray, ByVal pEnvMgr As IGPEnvironmentManager) Implements IGPFunction2.UpdateParameters
    
    ' m_Parameters is a class member.
    ' Private m_Parameters As IArray.
    m_Parameters=paramvalues
    
    ' Retrieve the input parameter value.
    Dim parameterValue As IGPValue=m_GPUtilities.UnpackGPValue(m_Parameters.Element(0))
    
    ' Get the derived output feature class schema and empty the additional fields.
    ' This will ensure you don't get dublicate entries.
    ' Derived output is the third parameter, so use index 2 for get_Element.
    Dim derivedFeatures As IGPParameter3=CType(paramvalues.Element(2), IGPParameter3)
    Dim schema As IGPFeatureSchema=CType(derivedFeatures.Schema, IGPFeatureSchema)
    schema.AdditionalFields=Nothing
    
    ' Retrieve the field parameter value.
    Dim fieldNameParameter As IGPParameter3=CType(paramvalues.Element(1), IGPParameter3)
    
    ' If you have an input value, create a field based on the field name the user entered.
    If parameterValue.IsEmpty()=False Then
        Dim fieldNameParameter As IGPParameter3
        fieldNameParameter=CType(paramvalues.Element(1), IGPParameter3)
        
        Dim fieldName As String
        fieldName=fieldNameParameter.Value.GetAsText()
        
        ' Check if the user's entered value already exists.
        Dim areaField As IField=m_GPUtilities.FindField(parameterValue, fieldName)
        
        If areaField Is Nothing Then
            
            Dim fieldsEdit As IFieldsEdit=New Fields
            Dim fieldEdit As IFieldEdit=New Field
            
            fieldEdit.Name_2=fieldName
            fieldEdit.Type_2=esriFieldType.esriFieldTypeDouble
            fieldsEdit.AddField(fieldEdit)
            
            ' Add the additional field to the derived output.
            Dim pFields As IFields=fieldsEdit
            
            schema.AdditionalFields=pFields
        End If
    End If
    
End Sub

Clip

public IArray ParameterInfo
{
    get
    {
        //Array to hold the parameters.
        IArray parameters=new ArrayClass();
        ... 
        // New output features.
        outParameter=new GPParameterClass();
        outParameter.DataType=new DEFeatureClassTypeClass();
        outParameter.Value=new DEFeatureClassClass();
        outParameter.Direction =
            esriGPParameterDirection.esriGPParameterDirectionOutput;
        outParameter.ParameterType=esriGPParameterType.esriGPParameterTypeRequired;
        outParameter.Name="Output_Feature_Class";
        outParameter.DisplayName="Output Feature Class";

        // Set the dependencies for the output and its schema properties.
        outParameter.AddDependency("input_features");
        outParameter.AddDependency("clip_features");

        // Feature type, geometry type, and fields all come from the first dependent - the input features.
        IGPFeatureSchema outSchema=new GPFeatureSchemaClass();
        outSchema.FieldsRule =
            esriGPSchemaFieldsType.esriGPSchemaFieldsFirstDependency;
        outSchema.FeatureTypeRule =
            esriGPSchemaFeatureType.esriGPSchemaFeatureFirstDependency;
        outSchema.GeometryType=esriGeometryType.esriGeometryPolygon;
        outSchema.ExtentRule=esriGPSchemaExtentType.esriGPSchemaExtentIntersection;

        IGPSchema schema=outSchema as IGPSchema;
        // Generate the default output path.
        schema.GenerateOutputCatalogPath=true;
        outParameter.Schema=(IGPSchema)outSchema;

        parameters.Add(outParameter);

        return parameters;
    }
}

Public ReadOnly Property ParameterInfo() As IArray Implements IGPFunction2.ParameterInfo
Get

' Array to hold the parameters.
Dim parameters As IArray=New ArrayClass()

' New Output Features - Convex Hull Polygons.
Dim outParameter As IGPParameterEdit3=New GPParameterClass()
outParameter.DataType=New DEFeatureClassTypeClass()
outParameter.Value=New DEFeatureClassClass()
outParameter.Direction=esriGPParameterDirection.esriGPParameterDirectionOutput
outParameter.ParameterType=esriGPParameterType.esriGPParameterTypeRequired
outParameter.Name="out_featureclass"
outParameter.DisplayName="Output Feature Class"

' Set the dependencies for the output and its schema properties.
outParameter.AddDependency("input_features")
outParameter.AddDependency("clip_features")

' Feature type, geometry type, and fields all come from the first dependent - the input features.
Dim outSchema As IGPFeatureSchema=New GPFeatureSchemaClass()
outSchema.FieldsRule=esriGPSchemaFieldsType.esriGPSchemaFieldsFirstDependency
outSchema.FeatureTypeRule=esriGPSchemaFeatureType.esriGPSchemaFeatureFirstDependency
outSchema.GeometryType=esriGeometryType.esriGeometryPolygon
outSchema.ExtentRule=esriGPSchemaExtentType.esriGPSchemaExtentIntersection

' Generate the default output path, which is available through the IGPSchema interface.
Dim schema As IGPSchema=CType(outSchema, IGPSchema)
schema.GenerateOutputCatalogPath=True
outParameter.Schema=CType(outSchema, IGPSchema)

parameters.Add(outParameter)

Return parameters

End Get
End Property

1. When the tool dialog box is opened, ParameterInfo() is called. You set the static rules for describing the output. No output description is created since you haven't specified values for the parameters.
2. Once you interact with the tool dialog box, UpdateParameters() is called. UpdateParameters() can modify Schema to account for dynamic behavior that can't be determined from the parameter dependencies, such as adding a new field (Add Field) for example.
3. After returning from UpdateParameters(), the internal validation routines are called, and the rules in the Schema object are applied to update the description of the output data.
4. UpdateMessages() is called. You can examine the warning and error messages that internal validation may have created and modify them, or add warnings and errors based on the interaction of actual parameter values.

Domains

• Defining input feature types (point, line, polygon)
• Creating a fixed list of string keywords (point, multipoint, polygon, polyline)
• Defining a Boolean choice
• Filtering field types (text, long, double, object ID, and so on)

Feature type

// Filter the input features to polygon features only.
IGPFeatureClassDomain fcDomain=new GPFeatureClassDomainClass();
fcDomain.AddFeatureType(esriFeatureType.esriFTSimple);
fcDomain.AddType(esriGeometryType.esriGeometryPolygon);
... 

inputParameter.Domain=(IGPDomain)fcDomain;

' Filter the input features to polygon features only.
Dim fcDomain As IGPFeatureClassDomain=New GPFeatureClassDomainClass()
fcDomain.AddFeatureType(esriFeatureType.esriFTSimple)
fcDomain.AddType(esriGeometryType.esriGeometryPolygon)
...

inputParameter.Domain=CType(fcDomain, IGPDomain)

String keywords

// Create a fixed list of string values. 
IGPCodedValueDomain cvDomain=new GPCodedValueDomainClass();
cvDomain.AddStringCode("TEXT", "TEXT");
cvDomain.AddStringCode("FLOAT", "FLOAT");
... inputParameter.Domain=IGPDomain(cvDomain);

' Create a fixed list of string values
Dim cvDomain As IGPCodedValueDomain=New GPCodedValueDomainClass()
cvDomain.AddStringCode("TEXT", "TEXT")
cvDomain.AddStringCode("FLOAT", "FLOAT")
...
inputParameter.Domain=CType(cvDomain, IGPDomain)

Boolean parameters

// Always create a coded value domain for Boolean parameters.
IGPParameterEdit3 pContinueCompare=new GPParameterClass();
... IGPCodedValueDomain pContinueDomain=new GPCodedValueDomainClass();
IGPBoolean pVal1=new GPBooleanClass();
pVal1.Value=true;
IGPBoolean pVal2=new GPBooleanClass();
pVal2.Value=false;

pContinueDomain.AddCode((IGPValue)pVal1, "CONTINUE_COMPARE");
pContinueDomain.AddCode((IGPValue)pVal2, "NO_CONTINUE_COMPARE");
... pContinueCompare.Domain=(IGPDomain)pContinueDomain;

' Always use a coded value domain for Boolean parameters
Dim pContinueCompare As IGPParameterEdit3=New GPParameterClass()
...
Dim pContinueDomain As IGPCodedValueDomain=New GPCodedValueDomainClass()
Dim pVal1 As IGPBoolean=New GPBooleanClass()
pVal1.Value=True
Dim pVal2 As IGPBoolean=New GPBooleanClass()
pVal2.Value=False
pContinueDomain.AddCode(CType(pVal1, IGPValue), "CONTINUE_COMPARE")
pContinueDomain.AddCode(CType(pVal2, IGPValue), "NO_CONTINUE_COMPARE")
...
pContinueCompare.Domain=CType(pContinueDomain, IGPDomain)

Dynamic domains

ControlCLSID

 

// Create Accumulators parameters.
IGPParameterEdit3 pAccumulators=new GPParameterClass();

IGPDataType pGPDataType2=new GPStringTypeClass();
IGPMultiValue pMultiValue2=new GPMultiValueClass();
pMultiValue2.MemberDataType=pGPDataType2;

IGPCodedValueDomain pAccumulatorsDomain=new GPCodedValueDomainClass();
pAccumulatorsDomain.AddStringCode("Minutes", "Minutes");
pAccumulatorsDomain.AddStringCode("Meters", "Meters");

IGPMultiValueType pMultiValueType2=new GPMultiValueTypeClass();
pMultiValueType2.MemberDataType=pGPDataType2;

pAccumulators.Name="accumulators";
pAccumulators.DisplayName="Accumulators";
pAccumulators.ParameterType=esriGPParameterType.esriGPParameterTypeOptional;
pAccumulators.Direction=esriGPParameterDirection.esriGPParameterDirectionInput;
pAccumulators.Domain=(IGPDomain)pAccumulatorsDomain;
pAccumulators.DataType=(IGPDataType)pMultiValueType2;
pAccumulators.Value=(IGPValue)pMultiValue2;

// MdList Control's GUID - Use OLE Object view to get this.
UID pUID=new UIDClass();
pUID.Value="{38C34610-C7F7-11D5-A693-0008C711C8C1}";
pAccumulators.ControlCLSID=pUID;

m_pParameters.Add(pAccumulators);

' Create Accumulators parameter.
Dim pAccumulators As IGPParameterEdit3=New GPParameterClass()

Dim pGPDataType2 As IGPDataType=New GPStringTypeClass()
Dim pMultiValue2 As IGPMultiValue=New GPMultiValueClass()
pMultiValue2.MemberDataType=pGPDataType2

Dim pAccumulatorsDomain As IGPCodedValueDomain=New GPCodedValueDomainClass()
pAccumulatorsDomain.AddStringCode("Minutes", "Minutes")
pAccumulatorsDomain.AddStringCode("Meters", "Meters")

Dim pMultiValueType2 As IGPMultiValueType=New GPMultiValueTypeClass()
pMultiValueType2.MemberDataType=pGPDataType2

pAccumulators.Name="accumulators"
pAccumulators.DisplayName="Accumulators"
pAccumulators.ParameterType=esriGPParameterType.esriGPParameterTypeOptional
pAccumulators.Direction=esriGPParameterDirection.esriGPParameterDirectionInput
pAccumulators.Domain=CType(pAccumulatorsDomain, IGPDomain)
pAccumulators.DataType=CType(pMultiValueType2, IGPDataType)
pAccumulators.Value=CType(pMultiValue2, IGPValue)

' MdList Control's GUID - Use OLE Object view to get this.
Dim pUID As UID=New UIDClass()
pUID.Value="{38C34610-C7F7-11D5-A693-0008C711C8C1}"
pAccumulators.ControlCLSID=pUID

parameters.Add(pAccumulators)

Methods

UpdateParameters()

• Parameter interaction - For some tools, it may be necessary to set rules for parameters. For example, when adding a field to an input table, one rule may be to limit the length of the field name by setting a maximum number of allowable characters. Another parameter interaction is enabling and disabling parameters. For instance, when using Add Field and selecting TEXT as the type of field to add, the field length parameter is enabled. The following code is an example of enabling and disabling a parameter based on user input:

// Get the Boolean parameter value (second parameter for this tool).
IGPBoolean val1=(IGPBoolean)pGPUtilities.UnpackGPValue(m_Parameters.get_Element(1))
    ;

// Get the string parameter (third parameter for this tool).
IGPParameterEdit3 stringParam=(IGPParameterEdit3)m_Parameters.get_Element(2);

if (val1.Value == true)
{
    stringParam.Enabled=false;
}

else
{
    stringParam.Enabled=true;
}

' Get the Boolean parameter value (second parameter for this tool).
Dim val1 As IGPBoolean=CType(m_GPUtilities.UnpackGPValue(m_Parameters.Element(1)), IGPBoolean)

' Get the string parameter (third parameter for this tool).
Dim stringParam As IGPParameterEdit3=CType(m_Parameters.Element(2), IGPParameterEdit3)

If val1.Value=True Then
    stringParam.Enabled=False
Else
    stringParam.Enabled=True
End If

// Get the Boolean parameter value (second parameter for this tool).
IGPBoolean val1=(IGPBoolean)pGPUtilities.UnpackGPValue(m_Parameters.get_Element(1))
    ;

// Get the coded value parameter.
IGPParameter3 cvParam=(IGPParameter3)m_Parameters.get_Element(3);
IGPParameterEdit3 cvParamEdit=cvParam as IGPParameterEdit3;

IGPCodedValueDomain cvDomain;

// If the Boolean parameter value is true, update the domain with new values.
if (val1.Value == true)
{
    stringParam.Enabled=true;
    cvDomain=new GPCodedValueDomainClass();
    cvDomain.AddStringCode("Seconds", "Seconds");
    cvDomain.AddStringCode("Feet", "Feet");
    cvParamEdit.Domain=cvDomain as IGPDomain;
}

'Get the Boolean parameter value (second parameter for this tool).
Dim val1 As IGPBoolean=CType(m_GPUtilities.UnpackGPValue(m_Parameters.Element(1)), IGPBoolean)

'Get the coded value parameter (third parameter for this tool).
Dim cvParam As IGPParameter3=CType(m_Parameters.Element(0), IGPParameter3)
Dim cvParamEdit As IGPParameterEdit3=CType(cvParam, IGPParameterEdit3)

Dim cvDomain As IGPCodedValueDomain

Dim stringParam As IGPParameterEdit3=CType(m_Parameters.Element(0), IGPParameterEdit3)

' If the Boolean parameter value is true, update the domain with new values.
If val1.Value=True Then
    stringParam.Enabled=True
    cvDomain=New GPCodedValueDomainClass()
    cvDomain.AddStringCode("Seconds", "Seconds")
    cvDomain.AddStringCode("Feet", "Feet")
    cvParamEdit.Domain=CType(cvDomain, IGPDomain)
End If

//  Set a default distance value if the user has not set a specific distance (Altered is true).
IGPParameter3 distParam=(IGPParameter3)m_Parameters.get_Element(7);
if (distParam.Altered == false)
{
    distParam.Value.SetAsText("100");
}

' Set a default distance value if the user has not set a specific distance (Altered is true).
Dim distParam As IGPParameter3=CType(m_Parameters.Element(7), IGPParameter3)
If distParam.Altered=False
    distParam.Value.SetAsText("100")
End If

UpdateMessages()

// Check if the distance is greater than zero.
IGPLinearUnit distVal=(IGPLinearUnit)pGPUtilities.UnpackGPValue
    (paramvalues.get_Element(7));

if (distVal.Value <= 0)
{
    Messages.ReplaceError(7, 2, 
        "Zero or a negative distance is invalid when using a fixed distance band. Use a positive value greater than zero.");
}

' Check if the distance is greater than zero.
Dim distVal As IGPLinearUnit=CType(pGPUtilities.UnpackGPValue(paramvalues.Element(7)), IGPLinearUnit)

If distVal.Value <= 0 Then
    Messages.ReplaceError(7, 2, "Zero or a negative distance is invalid when using a fixed distance band. Use a positive value greater than zero.")
End If

public IGPMessages Validate(IArray paramvalues, bool updateValues,
    IGPEnvironmentManager envMgr)
{
    return null;
}

Public Function Validate(ByVal paramvalues As IArray, ByVal updateValues As Boolean, ByVal envMgr As IGPEnvironmentManager) As IGPMessages Implements IGPFunction2.Validate
    Return Nothing
End Function

Execute()

• Opens datasets and verifies all inputs are valid - Opening the input datasets means creating objects from the inputs. For example, if the input value is a path to a feature class, create an IFeatureClass object. This ensures that this data still exists and is not locked by another application. The same is true for other inputs, such as Fields.
• Checks if the Overwrite Output setting is true or false - If your tool creates new output data, you must check if the OverwriteOutput setting is true of false. If the setting is true, then it is necessary to delete the existing output before performing the operation. The following code example shows how to check for the OverwriteOutput setting:

// Check the overwrite output option.
IGeoProcessorSettings gpSettings=(IGeoProcessorSettings)envMgr;
if (gpSettings.OverwriteOutput == true)
{
    // Check if the output exists.
    if (m_GPUtilities.Exists(outputValue))
    {
        m_GPUtilities.Delete(outputValue);
    }
}

else
{
    if (m_GPUtilities.Exists(outputValue))
    {
        message.AddError(2, "Output already exists: " + outputValue.GetAsText());
    }
}

' Check the overwrite output option.
Dim gpSettings As IGeoProcessorSettings=CType(envMgr, IGeoProcessorSettings)
If gpSettings.OverwriteOutput=True Then
    ' Check if the output exists.
    If m_GPUtilities.Exists(outputValue)=True Then
        m_GPUtilities.Delete(outputValue)
    End If
Else
    If m_GPUtilities.Exists(outputValue)=True Then
        message.AddError(2, "Output already exists: " + outputValue.GetAsText())
    End If
End If

• Executes the function - Executes the code to perform the operation.

Objects

GPEnvironmentManager

IGPEnvironment gpExtent=pEnvMgr.FindEnvironment("extent");

Dim gpExtent As IGPEnvironment=envMgr.FindEnvironment("extent")

GPMessages

GPMessage

GPUtilities

• UnPackGPValue() - Gets the value from the parameter and creates a GPValue object.
• PackGPValue() - Places the GPValue object into the parameter.
• Exists() - Returns whether or not the input value exists.
• Delete() - Deletes the data.
• Open() - Opens the data source associated with the value.
• DecodeFeatureLayer - Returns the feature class and query filter specified by the given geoprocessing value object. This should be used when the input is a GPFeatureLayerType. This ensures you open the feature class and retrieve any existing query filter.
• DecodeTableView - Returns the table and query filter specified by the given geoprocessing value object. This ensures you open the table and retrieve any existing query filter.

Implementing IGPFunctionFactory

• CLSID property - The class ID of the factory.
• Name property - Name of the function factory. This is used when generating the toolbox containing the factory function. This can be internationalized.
• Alias property - Alias name of the factory. This is used when specifying the functions contained in the factory from the command line or scripting.
• GetFunction() method - Creates and returns a function object based on the input name.
• GetFunctionName() method - Creates and returns a function name object based on the input name.
• GetFunctionNames() method - Creates and returns an enumeration of function names that the factory supports.
• GetFunctionEnvironments() method (optional) - Creates and returns an enumeration of GPEnvironment objects. If tools published by this function factory require new environment settings, define additional environment settings here. This is similar to how parameters are defined.

See Also: