• What is a geoprocessing tool?
• Implementing IGPFunction
• Tool parameters
• ParameterType-Derived
• Parameter DataType–Supporting layers and tables
• Parameter DataType–Lists
• Parameter DataType–Composite
• Validate() method
• Execute() method
• GPEnvironmentManager
• GPMessages
• GPMessage
• GPUtilities
• Implementing IGPFunctionFactory

 

• Name property—This is 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 must not contain spaces.
• DisplayName property—This is 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. This display name can be internationalized.
• FullName property—This is 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.
• HelpFile property (optional)—This is the path to a .chm file, which is used to describe and explain the function and its operation.
• HelpContext property (optional)—This is the unique context identifier in a [MAP] file (.h).        
• MetadataFile property (optional)—This is 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.
• IsLicensed method—This is used to return whether the function tool is licensed to execute.                        
• GetRenderer method (optional)—This is used to set a custom renderer for the output of the function tool.                       
• DialogCLSID property (optional)—This is the class identifier (CLSID) used to override the default dialog box for a tool. By default, the toolbox will create a dialog box based on the parameters returned by the ParameterInfo property.
• ParameterInfo property—This is 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.
• Validate() method—This method checks that a given set of parameter values are of the appropriate number, DataType, and Value.
• Execute() method—This method executes the tool given the array of parameter values.

• 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—This is the enumeration for setting the type of geoprocessing parameter. The following are the three parameter types: esriGPParameterTypeRequired, esriGPParameterTypeOptional, and esriGPParameterTypeDerived.
• Direction —This is the enumeration for setting the direction of the parameter. The options are esriGPParameterDirectionInput or esriGPParameterDirectionOutput.
• DataType—This property defines the type of data for this parameter. Some examples include FeatureClass, Raster, Table, String, and so on. DataType manages the value for the parameter. If the DataType is a FeatureClass, a Raster cannot be entered as input. 

• Value—This property defines the default value for a parameter. For every DataType, there is an associated value. If the DataType is a FeatureClass, the default value for the parameter is a FeatureClass. Values are used as the actual inputs to the tool containing scalars or a path to the data. For a complete list of Value objects, see IGPValues.
• Domain (optional)—The Domain property can be specified to limit or filter a set of values. An example of this is a domain for a simple value object, limiting an integer to a range of 1 to 100 (RangeDomain).
• ParameterDependencies (optional) —The ParameterDependencies property is used to set one parameter dependent on another parameter. As an example, a field parameter is commonly dependent on another table or feature class parameter, for example, 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)— This property creates a collapsible section on the tool dialog box. This is useful for tools with many optional parameters.
• ChoiceList (optional)— This property supplies a choice list for the command line.
• DefaultEnvironmentName (optional)— This property initializes the environment value to use as the default environment for a parameter.
• DisplayOrder (optional)— This is the order in which the parameters are listed on the dialog box. The usage display order is always the order in the array. In the ParameterInfo property, the parameters should be ordered by required, optional, and derived.
• Altered—This property indicates whether the parameter has been explicitly set by the user.
• HasBeenValidated—This property indicates whether the parameter value has been modified since the last time the parameter was validated.

//Input DataType is GPFeatureLayerType.
IGPParameterEdit inputParameter = new GPParameterClass();
inputParameter.DataType = new GPFeatureLayerTypeClass();

' Input DataType is GPFeatureLayerType.
Dim inputParameter As IGPParameterEdit = New GPParameterClass 
inputParameter.DataType = New GPFeatureLayerTypeClass

// DataType is GPValueTableType.
IGPValueTableType valueTableType = new GPValueTableTypeClass();

// Value is GPValueTable.
IGPValueTable ValueTable = new GPValueTableClass();

// DataType for Column 1.
IGPDataType dataType1 = new GPFeatureLayerTypeClass();
valueTableType.AddDataType(dataType1, "input_Features", 100, Nothing);

// DataType for Column 2.
IGPDataType dataType2 = new GPLongTypeClass();
valueTableType.AddDataType(dataType2, "long", 100, Nothing);

// Add DataTypes to the GPValueTable.
valueTable.AddDataType(pDataType1);
valueTable.AddDataType(pDataType2);

// Set the Input Parameter.
IGPParameterEdit inputParameter = new GPParameterClass();
inputParameter.DataType = valueTableType;
inputParameter.Value = valueTable;

' DataType is GPValueTableType.
Dim valueTableType As IGPValueTableType = New GPValueTableTypeClass 

' Value is GPValueTable.
Dim ValueTable As IGPValueTable = New GPValueTableClass 

' DataType for Column 1.
Dim dataType1 As IGPDataType = New GPFeatureLayerTypeClass 
valueTableType.AddDataType(dataType1, "input_Features", 100, Nothing) 

' DataType for Column 2.
Dim dataType2 As IGPDataType = New GPLongTypeClass 
valueTableType.AddDataType(dataType2, "long", 100, Nothing) 

' Add DataTypes to the GPValueTable.
valueTable.AddDataType(pDataType1) 
valueTable.AddDataType(pDataType2) 

' Set the Input Parameter.
Dim inputParameter As IGPParameterEdit = New GPParameterClass 
inputParameter.DataType = valueTableType 
inputParameter.Value = valueTable

// Create the GPCompositeDataType.
IGPCompositeDataType composisteType = 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.
IGPParameterEdit inputParameter = new GPParameterClass();
inputParameter.DataType = compositeType;
inputParameter.Value = new GPTableViewClass();

' Create the GPCompositeDataType.
Dim composisteType 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 IGPParameterEdit = New GPParameterClass 
inputParameter.DataType = compositeType 
inputParameter.Value = New GPTableViewClass

• Basic validation—Basic validation of the parameter values is accomplished by calling a method on IGPUtilities called InternalValidate(). InternalValidate() tests the validity of a set of values against the set of parameters. This method checks whether all the required parameter values have been supplied, the parameter values are of the correct data type, and the input exists. However, if the input value is derived, meaning it is input to another tool in ModelBuilder, then its existence is not checked. This is accomplished by setting the honorDerivedFlag option for InternalValidate() to true.
• Complex 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 example of 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. Another argument to Validate() is updateValues. When set to true, Validate() can modify parameter value properties; for example, setting the default value of a parameter or enabling or disabling a parameter.
• Populate properties of the output parameter—If updateValues is true, the function should populate the properties of the output value. This is important for proper chaining of tools in ModelBuilder. The AddField tool is a good example. Add this tool to ModelBuilder and fill in its parameters. Then connect the output of AddField as input to another process such as Calculate Field. You now see the new field even though the model has not yet been executed. The sample tool associated with this topic adds a new field and provides an example of updating the output parameter.
• The following sample tool illustrates how the output parameter value is updated. A field is added to the input shapefile. To ensure that this field is visible to other tools in ModelBuilder without this tool being executed first, you must clone the input table value and populate this new table value with the new field. The following code example is used in this sample tool:

// Clone the input parameter value.
IGPParameter parameter = (IGPParameter)paramvalues.get_Element(0);
IGPValue parameterValue = m_GPUtilities.UnpackGPValue(parameter);
IClone parameterClone = (IClone)parameterValue;
IGPValue outputValue = (IGPValue)parameterClone.Clone();
IDETable inputTable = m_GPUtilities.DecodeDETable(outputValue);

// Add the Area field to the Output Value.
parameter = (IGPParameter)paramvalues.get_Element(1);
m_Field = parameter.Value.GetAsText();
if (inputTable != null)
{
IField areaField = m_GPUtilities.FindField(outputValue, m_Field);
       if (areaField == null)
       {
        IFieldsEdit fieldsEdit = (IFieldsEdit)inputTable.Fields;
               IFieldEdit fieldEdit = new FieldClass();
               fieldEdit.Name_2 = m_Field;
               fieldEdit.Type_2 = esriFieldType.esriFieldTypeDouble;
               fieldsEdit.AddField(fieldEdit);
               inputTable.Fields = fieldsEdit;
        }

        parameter = (IGPParameter)paramvalues.get_Element(2);
        m_GPUtilities.PackGPValue(outputValue, parameter);
}

' Clone the input parameter value.
Dim parameter As IGPParameter = CType(paramvalues.Element(0), IGPParameter)
Dim parameterValue As IGPValue = m_GPUtilities.UnpackGPValue(parameter)
Dim parameterClone As IClone = CType(parameterValue, IClone)
Dim outputValue As IGPValue = CType(parameterClone.Clone, IGPValue)
Dim inputTable As IDETable = m_GPUtilities.DecodeDETable(outputValue)

' Add the Area field to the Output Value.
parameter = CType(paramvalues.Element(1), IGPParameter)
m_Field = parameter.Value.GetAsText

If Not (inputTable Is Nothing) Then
 Dim areaField As IField = m_GPUtilities.FindField(outputValue, m_Field)

 If areaField Is Nothing Then
   Dim fieldsEdit As IFieldsEdit = CType(inputTable.Fields, IFieldsEdit)
   Dim fieldEdit As IFieldEdit = New FieldClass
   fieldEdit.Name_2 = m_Field
   fieldEdit.Type_2 = esriFieldType.esriFieldTypeDouble
   fieldsEdit.AddField(fieldEdit)
   inputTable.Fields = fieldsEdit
 End If

parameter = CType(paramvalues.get_Element(2), IGPParameter)
m_GPUtilities.PackGPValue(outputValue, parameter)

• Call Validate()—During Execute(), all input data must exist. To ensure that the input data exists and the parameter values are still valid, Validate() must be called. When calling the Validate() method in Execute(), ensure the Boolean arguments to InternalValidate() for updateValues and honorDerivedFlag are false to ensure newly created data exists.  
• Open Datasets—Opening the input datasets means creating objects from the inputs. For example, if the input value is a path to a feature class, try to 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. 
• Checking the OverwriteOutput setting—If your tool creates new output data, you must check if the OverwriteOutput setting is true or false. If the setting is true, it is necessary to delete that existing output before performing the operation. The following code example shows how to check for the OverwriteOutput setting:

// Check if OverWrite setting is set.
IGeoProcessorSettings settings = (IGeoProcessorSettings)envMgr;
if (settings.OverwriteOutput)
if (m_GPUtilities.Exists(parameterValue))
        m_GPUtilities.Delete(parameterValue);
       else
        if (m_GPUtilities.Exists(parameterValue))
               {
                message.AddError(2, "Output already exists.");
                       return;
               }

' Check if OverWrite setting is set.
Dim settings As IGeoProcessorSettings = CType(envMgr, IGeoProcessorSettings)

If settings.OverwriteOutput Then
 
 If m_GPUtilities.Exists(parameterValue) Then
 
   m_GPUtilities.Delete(parameterValue)
 
 Else
 
   If m_GPUtilities.Exists(parameterValue) Then

     message.AddError(2, "Output already exists.")
     Return

   End If

 End If

End If

• Execute the function—Executes the code to perform the operation.

• UnPackGPValue()—This method gets the value from the parameter and creates a GPValue object.
• PackGPValue()—This method places the GPValue object into the parameter.
• Exists()—Returns whether the input value exists or not.
• Delete()—Deletes the data.
• OpenDataset()—Opens the data source associated with the value.

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

See Also: