Geoprocessing resources are only supported with ArcGIS Server data sources.  Using ArcGIS Desktop and Server products, you can publish a tool or model in a toolbox as a geoprocessing (GP) service by itself or associated with a map document.  Once published, GP services can be added as a resource to a Web ADF application using a GeoprocessingResourceManager.  Each GP service can contain one or more models or tools, each regarded as a "server task" or "server tool".

Implemented by : ArcGIS Server Local, ArcGIS Server Internet

Functionality types created: IGeoprocessingFunctionality

As with other ArcGIS Server resources, geoprocessing resources are split between an internet and local implementation, but share a common geoprocessing functionality.  Since ArcGIS Server data source implementations in the Web ADF utilize the ArcGIS Server SOAP API, communication between a GeoprocessingResource and a GP service uses Values objects and a proxy.  The GeoprocessingResourceLocal class provides access to server context via the ServerContextInfo.ServerContext property.  Server context may be utilized in some situations - see the Discussion on Geoprocessing in ArcGIS Server below for more details.



GeoprocessingFunctionality: 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 methods on IGeoprocessingFunctionality 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 table below defines the data types that may be defined in a geoprocessing model or tool under the heading "Published Data Types".  Of these data types, a subset can be utilized within a published GP service.  Whether using the ArcGIS Server ArcObjects API (IGPServer) or the SOAP API (GPServerProxy) a set of data types, prefixed with "GP", 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 within the Web ADF, the Common API GP data types can be utilized with IGeoprocessingFunctionality methods.

• Published geoprocessing types are defined while 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.
  

A number of generic methods are available on the IGeoprocessingFunctionality interface.  Note that server tasks within a GP service can function synchronously or asynchronously, depending on how the service was 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.    

Property or Method	Description
GetExecutionType()	Returns the type of server task execution: asynchronous or synchronous
GetTask()	Return a GPToolInfo object associated with a server task
GetTaskNames()	Return 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 implementation of IGeoprocessingFunctionality includes some methods to work with geoprocessing resource provided by ArcGIS Server. The table below lists methods that will commonly be used to interact with ArcGIS Server GP services:

Property or Method	Description
Execute()	Returns a GPResult object with the task execution results\outputs.  Designed for synchronous use.
SubmitJob()	Submits a job for processing by a server task.  Returns a job id to check status.  Designed for asynchronous use.
GetJobStatus()	Returns a JobStatus enumeration to determine the current state of the job being processed.  Designed for asynchronous use.
GetJobResult()	Returns a GPResult object with task execution results\output.   Designed for asynchronous use.
GetJobMessages()	Returns a JobMessage array for verbose information about the status of job processing on the server.

The sample code below illustrates how to work with an ArcGIS Server geoprocessing functionality.  Note that 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 discover the input types to determine what it needs to execute.  In this example, an asynchronous server task is used, so we will submit a job for processing and check periodically for completion.  The server task name is "BufferPoints" and is designed to accept two inputs: the points to buffer (Feature Set) and the buffer distance (Linear Unit).

[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";

Get the server task to work with via the ArcGIS Server GeoprocessingFunctionality. Interate 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 contains the points to buffer. Since we're working with the ArcGIS Server implementation of the Common API, we will use the Common API GP types. Using the table above, we can see that 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 has the ability to be utilized 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.  We need to 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. 

[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 two properties to store the value (or distance) and the unit.  In the code below, both are maintained as session variables and converted into the appropriated 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.  The job id should be stored in a sufficient manner 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 may be appropriate.  If the job id needs to be persisted across sessions, a Web application accessible database may provide the best option.  

[C#]

GPValue[] gpvalues = new GPValue[2];
gpvalues[0] = gfl;
gpvalues[1] = gpLU;
string JobID;        
JobID = agp.SubmitJob(taskname, gpvalues); 		
			

The following code checks to determine if a submitted GP server task has completed. If so, it will get the results.  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.   


[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;
}

Once the GP server task has completed, the task results are available. 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, we 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, is contains a Web ADF FeatureGraphicsLayer which can easily be rendered in a graphics resource within a map.

[C#]

GPResult gpr = agp.GetJobResult(taskname, JobID, parameternames, false);

GPValue[] gpvs = gpr.Values;

GPFeatureGraphicsLayer gfl = (GPFeatureGraphicsLayer)gpvs[0];
FeatureGraphicsLayer glayer = gfl.Layer;			
			

Comparing general spatial operations with 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 to enhance 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 both 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 the 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.   Again, 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.  On the other hand, geoprocessing tasks can be synchronous or asynchronous. You get to 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.  Any operation that takes longer may benefit from the asynchronous model, and thus would likely be deployed as a geoprocessing task.

Packaging multiple spatial operations in a single ArcObjects component and making it available on the GIS Server is possible.  Two techniques are available to extend the GIS Server in this way: utility COM objects or a Server Object Extensions.  Both are designed to offload the bulk of the remote ArcObjects calls from an ArcGIS Server client to the server so ArcObjects can run locally with the 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 some intensive ArcObjects work over a length of time and check on its status.   However, the ArcGIS Server geoprocessing framework already provides this capability, as long as the tools necessary to provide you with a solution are available.  
 
Known Limits

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

Discussion on Geoprocessing with ArcGIS Server

There are a number of methods and techniques for working with geoprocessing capabilities of ArcGIS Server. The following discussion presents the options for working with geoprocessing using the Web ADF, from an ArcGIS Server developer perspective.

Web ADF Geoprocessing components

Assuming that a toolbox has been published as a GP service - and creating a Web application, the easiest option for working with a GP service is to use the Web ADF task framework to configure a geoprocessing task (Web task). Each Web task is associated with a tool or model in a GP service (server task). If the geoprocessing server task is associated with a map document, the Web task will recognize and utilize it.

1. For non-developers, you can use Manager to consume a geoprocessing server task and configure the geoprocessing Web task, without opening Visual Studio 2005 or writing any code.
2. For developers, in Visual Studio 2005 you can:
   1. Work with task framework controls (e.g. TaskManager, TaskResults, GeoprocessingTask). At runtime, the Web ADF geoprocessing task dialog is generated for you, based on the inputs required for the GP service task (see GP data type conversion table below).  If working with the Web Mapping Application template (e.g. the website created by Manager), the Web ADF controls needed to utilize geoprocessing tasks have been added for you.  In general, the GP server task input and outputs are managed for you.
   2. Work with Web ADF’s IGeoprocessingFunctionality via custom code. You can create the user interface for the GP server task and explicitly manage input and output values. The IGeoprocessingFunctionality interface enables you to submit asynchronous jobs, execute synchronous jobs, check their status, get results, etc. It works with a Web ADF maintained set of the GP value types (prefixed GP* in ESRI.ArcGIS.ADF.Web.DataSources). 
   3. Work with the Web ADF GP proxies and Value objects.  In general, if working with existing GP services and you need more control over the GP process than provided in IGeoprocessingFunctionality -or- you don't need the overhead associated with a resource manager, resource and functionality, use the GPServer proxy and Value objects (in ESRI.ArcGIS.ADF.ArcGISServer). There is a Web service proxy (GPServerProxy) for ArcGIS Server Internet data sources and a DCOM proxy (GPServerDcomProxy) for ArcGIS Server local data sources – both can be used with an existing resource or standalone. The Web service proxy is available via the GeoprocessingResourceInternet.GPServerProxy property. The DCOM proxy is available via the GeoprocessingResourceLocal.GPServerProxy property. Both also work with the GP Value object types in the ESRI.ArcGIS.ADF.ArcGISServer namespace (prefixed GP*).   This is a good lightweight option for implementation within a custom Web service.

Basic Geoprocessing components for .NET

The Web ADF includes some basic geoprocessing components available for the Microsoft .NET development environment.  They can be utilized in a Web ADF application, but are not restricted to it.  You have a few options depending on the type of access, local or internet, you have to ArcGIS Server.  

1. Local access to ArcGIS Server
   
   If you want to work with a well known toolbox, tool and/or model on the GIS Server, without using an existing GP service, use the .NET Geoprocessor wrapper with an empty server context. 
   1. IGPServer – The server object type available for existing GP services. Probably the easiest way to work with existing GP services using ArcObjects. Full control over task execution on the server. Works with a specific set of GP value types provided in ESRI.ArcGIS.Geoprocessing. You can provide a set of features entered by the user as well as work with layers in an associated map document.
   2. Geoprocessor - .NET wrapper for the IGeoProcessor COM object. Can be used with existing system toolboxes and custom toolboxes on the server (empty server context) or locally. The wrapper is meant to provide .NET developers with better design-time information (intellisense) than working with COM objects and interfaces. It does not provide data type information for tools or models explicitly. More information about tool or model parameters can be discovered using ArcObjects – IToolboxWorkspace, IGPToolbox, IGPTool, IGPParameter.
   3. IGeoProcessor – COM interface to the ArcObjects GeoProcessor COM object. Like the .NET Geoprocessor wrapper, it can be used with existing system and custom toolboxes on the server (empty server context) or locally. It provides the finest level of detail for working with geoprocessing tools and models. Like the .NET wrapper, it does not provide data type information for tools or models explicitly. More information about tool or model parameters can be discovered using ArcObjects – IToolboxWorkspace, IGPToolbox, IGPTool, IGPParameter.
2. Internet access to ArcGIS Server
   1. GPServer proxy – Existing GP services can be exposed as ArcGIS Server Web services. They provide a GP service specific WSDL which can be used to generate a set of client-side Value objects and a Web service proxy to work with geoprocessing on the GIS Server. The Value objects include a set of GP specific types (prefixed GP*) and the Web service proxy provides a set of methods to submit asynchronous jobs, execute synchronous jobs, check their status, get results, etc. This option can be used without installing any ESRI software.