Geoprocessing resources

In this topic

About geoprocessing resources

Geoprocessing resources are only supported with ArcGIS Server data sources. Using ArcGIS Desktop and ArcGIS Server products, you can publish a tool or model in a toolbox as a geoprocessing (GP) service by itself or in association with a map document. Once published, GP services can be added as a resource to a Web Application Developer Framework (ADF) application using GeoprocessingResourceManager. Each GP service can contain one or more models or tools known as a server task or a server tool.
Geoprocessing resources are Implemented by ArcGIS Server local and ArcGIS Server Internet.
IGeoprocessingFunctionality is the functionality type created by geoprocessing resources.
As with other ArcGIS Server resources, geoprocessing resources are divided between an Internet and a local implementation but share a common geoprocessing functionality. Since ArcGIS Server data source implementations in the Web ADF use the ArcGIS Server SOAP application programming interface (API), communication between GeoprocessingResource and a GP service uses value objects and a proxy as shown in the following diagram:
The GeoprocessingResourceLocal class provides access to server context via the ServerContextInfo.ServerContext property. Server context can be utilized in some situations as discussed later in this topic.

GeoprocessingFunctionality and IGeoprocessingFunctionality

The Web ADF Common API defines a set of generic geoprocessing types to work explicitly with geoprocessing functionality. You'll use these types when working with IGeoprocessingFunctionality methods to execute GP tasks on the server. Behind the scenes, these Common API types must map to data source-specific types (ArcGIS Server types), which must also map to geoprocessing types originally defined in the model or tool. Geoprocessing types defined in the model are the most comprehensive. ArcGIS Server SOAP API types expose a subset of those available in a model or tool. The Common API types must work with the data source-specific types in the ArcGIS Server SOAP API.
The following table lists the data types that can be defined in a geoprocessing model or tool. Of these data types (published data types in the table), a subset can be used in a published GP service. The ArcGIS Server ArcObjects API (IGPServer) and the SOAP API (GPServerProxy) contain data types—prefixed with GP—that are available for both server task inputs and outputs. The Web ADF Common API maps generic input and output types, also prefixed with GP, to data source implementation types (in the case of ArcGIS Server, to the GPServer data types). When working in the Web ADF, the Common API GP data types can be used with IGeoprocessingFunctionality methods.
Published data types
GPServer data types
Web ADF Common API data types
Data type label
Data type name
GPServer input
data type
GPServer output
data type
Web ADF input data type
Web ADF output data type
String
GPString
GPString
GPString
GPString
GPString
Long
GPLong
GPLong
GPLong
GPLong
GPLong
Double
GPDouble
GPDouble
GPDouble
GPDouble
GPDouble
Boolean
GPBoolean
GPBoolean
GPBoolean
GPBoolean
GPBoolean
Date
GPDate
GPDate
GPDate
GPDate
GPDate
Linear Unit
GPLinearUnit
GPLinearUnit
GPLinearUnit
GPLinearUnit
GPLinearUnit
Feature Set
GPFeatureRecordSetLayer
GPFeatureRecordSetLayer
GPFeatureRecordSetLayer
GPFeatureGraphicsLayer
GPFeatureGraphicsLayer
Feature Class
DEFeatureClass
Does not publish
GPFeatureRecordSetLayer
Not available
GPFeatureGraphicsLayer
Record Set
GPRecordSet
GPRecordSet
GPRecordSet
GPDataTable
GPDataTable
Table
DETable
Does not publish
Does not publish
Not available
GPDataTable
Table View
GPTableView
GPString
GPRecordSet
GPString
GPDataTable
Raster Dataset
DERasterDataset
GPRasterDataLayer
GPRasterDataLayer
GPRasterDataLayer
GPRasterDataLayer
File
DEFile
GPDataFile
GPDataFile
GPDataFile
GPDataFile
Feature Layer
GPFeatureLayer
GPString
GPFeatureRecordSetLayer
GPString
GPFeatureGraphicsLayer
Raster Layer
GPRasterLayer
GPString
GPRasterDataLayer
GPString
GPRasterDataLayer
Layer
GPLayer
GPString
GPString
GPString
GPString
Geodataset
DEGeodataset
Does not publish
GPString
Not available
GPString
Data Element
DataElement
Does not publish
Does not publish
Not available
Not available
Value
Table/ Multivalue
GPValueTable/
GPMultiValue
Does not publish
Does not publish
Not available
Not available
List
List/Series
Does not publish
Does not publish
Not available
Not available
Other
Other data types
GPString
GPString
GPString
GPString
Keep the following in mind when working with the various data types:
  • Published geoprocessing types are defined when editing the model in ArcCatalog.
  • ArcGIS Server ArcObjects geoprocessing types are included in the ESRI.ArcGIS.Geoprocessing library.
  • ArcGIS Server SOAP geoprocessing types are included in the ESRI.ArcGIS.ADF.ArcGISServer library. ArcGIS Server implementations for both local and Internet data sources in the Web ADF use these types.
  • Web ADF Common API geoprocessing types used by IGeoprocessingFunctionality are included in the ESRI.ArcGIS.ADF.Web.DataSources library.

Generic methods

A number of generic methods are available on the IGeoprocessingFunctionality interface. Server tasks in a GP service can function synchronously or asynchronously, depending on how the service is configured. Synchronous execution means that the caller (client) executes a server task and waits for a response before proceeding. Asynchronous execution means that the caller submits a job and continues to function. The client is then responsible for checking with the GP service to determine if the job was finished, using a unique job ID. If finished, the results can be retrieved and processed by the client.
The following table lists generic methods of IGeoprocessingFunctionality:
Method
Description
GetExecutionType()
Returns the type of server task execution, either asynchronous or synchronous.
GetTask()
Returns a GPToolInfo object associated with a server task.
GetTaskNames()
Returns a string array of server task names available in a GP service.
GetTasks()
Return an array of GPToolInfo objects, each associated with a server task in a GP service.

ArcGIS Server GP services

An ArcGIS Server implementation of IGeoprocessingFunctionality includes methods to work with geoprocessing resources provided by ArcGIS Server. The following table lists methods that are commonly used to interact with ArcGIS Server GP services:
Method
Description
Execute()
Returns a GPResult object with the task execution results or outputs. For synchronous use.
GetJobMessages()
Returns a JobMessage array for verbose information about the status of job processing on the server.
GetJobResult()
Returns a GPResult object with task execution results or output. For asynchronous use.
GetJobStatus()
Returns a JobStatus enumeration to determine the current state of the job being processed. For asynchronous use.
SubmitJob()
Submits a job for processing by a server task. Returns a job ID to check status. For asynchronous use.
The following sample code shows how to work with an ArcGIS Server geoprocessing functionality:
[C#] 
IGeoprocessingResource igp = GeoprocessingResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality agp = 
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality)
    igp.CreateFunctionality(typeof
    (ESRI.ArcGIS.ADF.Web.DataSources.IGeoprocessingFunctionality), null);
agp.Initialize();

string taskname = "BufferPoints";
Although a geoprocessing resource item has been added to a GeoprocessingResourceManager control, it is not initialized unless used by a GeoprocessingTask control. As a result, a GeoprocessingFunctionality must be created and initialized first. Once initialized, you can get the server task you want to work with and review the input types to determine what it needs to execute. In this code, an asynchronous server task is used, so you need to submit a job for processing and check it periodically for completion. The server task name is BufferPoints, and it accepts two inputs: the points to buffer (Feature Set) and the buffer distance (Linear Unit).
The following code shows how to get the server task to work via the ArcGIS Server GeoprocessingFunctionality and iterate through the input and output parameters:
[C#] 
ESRI.ArcGIS.ADF.Web.DataSources.GPToolInfo gpti = agp.GetTask(taskname);
ESRI.ArcGIS.ADF.Web.DataSources.GPParameterInfo[] paramInfos = gpti.ParameterInfo;
ESRI.ArcGIS.ADF.Web.DataSources.GPParameterInfo paramInfo;
for (int i = 0; i < paramInfos.Length; i++)
{
    paramInfo = paramInfos[i];
    System.Diagnostics.WriteLine(paramInfo.Name);
}
The first input is the Feature Set, which contains the points to buffer. Since you're working with the ArcGIS Server implementation of the Common API, you can use the Common API GP types. As shown in the previous data types table, a Feature Set input in a published model is a GPFeatureGraphicsLayer type in the Web ADF. This type provides a wrapper for an ArcGIS Server GPFeatureRecordSet and can be used as a Web ADF graphics layer.
In this example, a Map control contains a graphics resource with a graphics layer that contains a set of Web ADF points. Iterate through the graphics layer in the map and add the points to the FeatureGraphicsLayer that is part of the GPFeatureGraphicsLayer input to the GP server task as shown in the following code:
[C#] 
GPFeatureGraphicsLayer gfl = (GPFeatureGraphicsLayer)paramInfos[0].Value;
FeatureGraphicsLayer glayer = gfl.Layer;
IEnumerable gfc = Map1.GetFunctionalities();
ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource gResource = null;
foreach (IGISFunctionality gfunc in gfc)
{
    if (gfunc.Resource.Name == "Points")
    {
        gResource = (ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)
            gfunc.Resource;
        break;
    }
}

if (gResource == null)
{
    throw new Exception("No Points in Graphics layer to buffer.");
}

ESRI.ArcGIS.ADF.Web.Display.Graphics.ElementGraphicsLayer player = 
    (ElementGraphicsLayer)gResource.Graphics.Tables[0];
foreach (DataRow dr in player.Rows)
{
    ESRI.ArcGIS.ADF.Web.Geometry.Point pnt = (ESRI.ArcGIS.ADF.Web.Geometry.Point)
        player.GeometryFromRow(dr);
    glayer.Add(pnt);
}
The second input is the buffer distance. The Common API type for a Linear Unit in the published GP server task is a GPLinearUnit. A GPLinearUnit has to store the value (or distance) and the unit. In the following code, both are maintained as session variables and converted into the appropriate type:
[C#] 
GPLinearUnit gpLU = new GPLinearUnit();
string bufferunits = (string)Page.Session["BufferUnits"];
ESRI.ArcGIS.ADF.Web.DataSources.Units adf_bufferunits;
adf_bufferunits = (ESRI.ArcGIS.ADF.Web.DataSources.Units)Enum.Parse(typeof
    (ESRI.ArcGIS.ADF.Web.DataSources.Units), bufferunits, true);

gpLU.Units = adf_bufferunits;
string strbd = (string)Session["BufferDistance"];
float bufferdistance;
if (!Single.TryParse(strbd, out bufferdistance))
{
    bufferdistance = 0.0F;
}

gpLU.Value = bufferdistance;
Once the input properties are set, they are packaged in a GPValue array. The order of the parameters in the GP server task must match the order in the GPValue array. Calling the SubmitJob() method on the GP server task and passing the input values returns a unique job ID as shown in the following code:
[C#] 
GPValue[] gpvalues = new GPValue[2];
gpvalues[0] = gfl;
gpvalues[1] = gpLU;
string JobID;
JobID = agp.SubmitJob(taskname, gpvalues);
Store the job ID in a manner sufficient for the application. If the results of the GP process are expected before the end of the user session, a session variable on the Web server or JavaScript variable on the client might be appropriate. If the job ID needs to be persisted across sessions, a Web application accessible database is the best option.
The following code checks if a submitted GP server task has completed. If so, it gets the results:
[C#] 
IGeoprocessingResource igp = GeoprocessingResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality agp = 
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality)
    igp.CreateFunctionality(typeof
    (ESRI.ArcGIS.ADF.Web.DataSources.IGeoprocessingFunctionality), null);
agp.Initialize();
if (agp.GetJobStatus(JobID) != JobStatus.Succeeded)
{
    return ;
}
Note that the geoprocessing functionality must be initialized again. The JobStatus enumeration provides a number of options for determining the state of a GP process.
The task results are available once the GP server task has completed. In the following code, the GPResult object returned from the completed server task maintains a GPValue array. Since this example expects a single output parameter, the buffer geometry, you can retrieve the first item in the GPValue array. The output type in the published GP server task is a Feature Class. The Web ADF Common API wraps this type as a GPFeatureGraphicsLayer. As a result, it contains a Web ADF FeatureGraphicsLayer that can be rendered in a graphics resource in a map.
[C#] 
GPResult gpr = agp.GetJobResult(taskname, JobID, parameternames, false);
GPValue[] gpvs = gpr.Values;
GPFeatureGraphicsLayer gfl = (GPFeatureGraphicsLayer)gpvs[0];
FeatureGraphicsLayer glayer = gfl.Layer;

General spatial operations vs. geoprocessing

ArcGIS Server (and in some cases the Web ADF) provide the ability to perform general spatial operations, such as using a spatial filter to select features, buffering feature geometry, or creating a feature class. ArcGIS Server provides access to a geoprocessing framework that enhances interaction with general spatial operations as geoprocessing tools or tasks. It does this by enabling the consolidation of multiple operations into a model and providing a common set of data type inputs and outputs for cross-application compatibility. Multiple models, or tasks, can be combined in a single geoprocessing service.
In general, both options are founded in ArcObjects, but use different libraries, classes, and techniques. You can work with either via the Web ADF Common API, ArcGIS Server SOAP API, or ArcGIS Server ArcObjects API. The Web ADF Common API maintains a set of interfaces that expose some level of access to general spatial operations, such as using IQueryFunctionality to query a feature layer. For ArcGIS Server data sources, the Common API provides the implementation of IGeoprocessingFunctionality to expose a full range of operations available via geoprocessing services. The ArcGIS Server SOAP API enables you to work with ArcGIS Server services using SOAP strings. Some general spatial operations are supported via a map server proxy, but the geoprocessing server proxy provides comprehensive access to geoprocessing service and task capabilities. The ArcGIS Server ArcObjects API provides the most fine-grained API for working with standard spatial operations and geoprocessing remotely via server context.
In every API, general spatial operations are designed to be synchronous. However, geoprocessing tasks can be synchronous or asynchronous. You decide which capability provides what you need in a timely manner. In general, a process that takes a few seconds or less is a good candidate for a synchronous process. An operation that takes longer can benefit from the asynchronous model and would likely be deployed as a geoprocessing task.
You can package multiple spatial operations in a single ArcObjects component and make it available on the GIS Server. Two techniques are available to extend the GIS Server in this way: utility Component Object Model (COM) objects and server object extensions. Both off load the bulk of the remote ArcObjects calls from an ArcGIS Server client to the server so ArcObjects can run locally with the server object container (SOC). This saves time, but both still operate within a synchronous process since the client must wait for the method call on the remote COM object to complete before continuing.
You can write your own COM utility or extension to work with ArcObjects asynchronously on the GIS Server if you need to do intensive ArcObjects work over a length of time and check on its status. However, the ArcGIS Server geoprocessing framework also has this capability, as long as the tools necessary to provide you with a solution are available.

Known limitations

The .NET ADF does not have access to a projection engine. For output features to show on the map, one of the following is required:
  • The GP service has an associated map service where the output features can be drawn.
  • The GP service can project output geometries to the spatial reference of the input geometries (model implementation).
  • The GP service output projection is the same as the ADF Map control’s primary map resource spatial reference. This is a known limitation at ArcGIS 9.2.


See Also:

Resources and functionalities in the Web ADF
Data source-specific APIs
Map resources
Geocode resources