Sharing, documenting, and deploying a custom tool

Summary
Geoprocessing tools that you create in .NET are one type of custom tool. This topic covers how to document, share, and deploy such a tool.

In this topic

Creating a custom tool in .NET

The process of creating a custom tool is elaborately covered in the ArcObjects software development kit (SDK). To get started with creating your own tool, see Custom geoprocessing function tools.
Custom tools are encapsulated in a dynamic-link library (DLL) created in the debug folder under the .NET project location. A single DLL can contain more than one tool.

Documenting a custom tool

A tool should be documented before sharing or distributing it for use. The process of documenting a custom tool is covered in the ArcGIS Desktop Help topic, A quick tour of documenting tools and toolboxes.
Before starting the documentation process, consult the following knowledge base article on the ArcGIS Resource Center:
You can use the Calculate area geoprocessing function tool sample that comes with the ArcObjects .NET SDK if you have not previously created a tool. This sample is used to demonstrate the deployment and sharing sections of this topic.
The tool document is stored in an *.xml file and is created when you use Item Description for the first time. The *.xml file is created in the location as specified by the MetadataFile property of IGPFunction2.
You need to edit the CanEditMetadata registry value to create or edit any tool document through Item Description. Read the previously referenced knowledge base article for details.

Deploying a custom tool

A user must deploy the custom tool before using it. Deploying custom tools require registering the DLL using the ESRIRegAsm utility. You can use a *.bat file to simplify the process. See the following code example of this type of batch file:
Echo Registering GPCalculateArea.dll
set COMMONPROGRAMFILESLOCATION=%COMMONPROGRAMFILES%
IF NOT "%PROCESSOR_ARCHITECTURE%" == "x86" set COMMONPROGRAMFILESLOCATION=%COMMONPROGRAMFILES(x86)%
"%COMMONPROGRAMFILESLOCATION%\ArcGIS\bin\ESRIRegasm.exe" "%~dp0\GPCalculateArea.dll" /p:desktop
Once registered, the tool can be used like any geoprocessing tool. You can use it in ArcMap as follows:
  1. In the ArcMap catalog tree, create a toolbox (or use an existing custom toolbox).
  2. Right-click the toolbox and select Add > Tool. The Add Tool dialog box appears.
  3. On the Add Tool dialog box, expand your category. For example, if you use the Calculate area sample, AreaCalculatoin is the category.
  4. Check the tool or tools you want to add, then click OK. The tool will be added to the toolbox.
  5. To create or edit the tool documentation, right-click the tool and select Item Description.

Sharing a custom tool

Sharing involves providing the following components in a compressed file:
  • DLL created by the .NET project
  • Tool metadata (the *.xml file)
  • Batch file to deploy the tool
In the Calculate area sample, MetadataFile returns the path of the DLL created by the project, which means that the DLL and the Extensible Markup Language (XML) file (along with the batch file) must be in the same location.
If the MetadataFile property returns just the name of the XML file, then metadata is created in the default location of <ArcGIS install directory>\help\gp folder. However, it is always better to supply a full path, which makes the sharing easier.
The following code example demonstrates how you can set the location of the metadata (*.xml) file. The same code is used in the Calculate area function tool sample.
[C#] 
public string MetadataFile
{
    // If you just return the name of an *.xml file:
    // get { return m_metadatafile; }
    // then the metadata file will be created 
    // in the default location - <install directory>\help\gp.

    // Alternatively, you can send the *.xml file to the location of the DLL.
    // 
    get
    {
        string filePath;
        filePath = System.IO.Path.GetDirectoryName
            (System.Reflection.Assembly.GetExecutingAssembly().Location);
        filePath = System.IO.Path.Combine(filePath, "CalculateArea_area.xml");
        return filePath;
    }
}
[VB.NET] 
Public ReadOnly Property MetadataFile() As String Implements IGPFunction2.MetadataFile
' If you just return the name of an *.xml file:
' Get
'   return m_MetaDataFile
' End Get
' then the metadata file will be created
' in the default location - <install directory>\help\gp.
' Alternatively, you can send the *.xml file to the location of the DLL.
'
Get
Dim filePath As String, fileLocation As String
fileLocation = System.Reflection.Assembly.GetExecutingAssembly().Location
filePath = System.IO.Path.GetDirectoryName(fileLocation)
filePath = System.IO.Path.Combine(filePath, "CalculateArea_area.xml")
Return filePath
End Get
End Property
The *.xml file is created when you use Item Description (in ArcMap) for the first time to document the tool and save it. When sharing the tool, the relative locations of the DLL and the *.xml file must be maintained. For example, in the preceding code example, they must be in the same location.


See Also:

A quick tour of sharing tools
Tool types