How to work with geoprocessing services



Executing geoprocessing services

You can use geoprocessing services that have been published on an ArcGIS server in ArcGIS for Desktop, ArcGIS Engine, ArcGIS Explorer, and Web applications. A geoprocessing service contains geoprocessing tasks accessible by clients. Tasks are created by publishing geoprocessing toolboxes or map documents containing tool layers. Once published, each service becomes a tool, and you can access and execute this tool similarly to a custom tool. 

Adding a custom toolbox

Toolboxes can be published on a local area network (LAN) or as a Web service on the Internet. To access the geoprocessing service, you must add the toolbox using the AddToolbox method of the Geoprocessor object. All parameters of AddToolbox are semicolon (;) delimited, whether adding the server toolbox from a local or Internet server.
The following code example shows how to add toolboxes published on an ArcGIS server using the AddToolbox method:
[C#]
public void SampleGeoprocessingServerTool(Geoprocessor GP)
{

    // Add the BestPath toolbox published on a LAN.
    // Entered as server name;folder/toolbox.
    GP.AddToolbox(@"flame7;SanDiego/BestPath");

    // Or, add the BestPath toolbox published as a geoprocessing Web service.
    // Entered as Web service;folder/toolbox.
    GP.AddToolbox(@"http://flame7/arcgis/services;SanDiego/BestPath");

    // Add your code here.

}
[VB.NET]
Public Sub SampleGeoprocessingServerTool(ByVal GP As Geoprocessor)
    
    ' Add the BestPath toolbox published on a LAN.
    ' Entered as server name;folder/toolbox.
    GP.AddToolbox("flame7;SanDiego/BestPath")
    
    ' Or add the BestPath toolbox published as a geoprocessing Web service.
    ' Entered as Web service;folder/toolbox.
    GP.AddToolbox("http://flame7/arcgis/services;SanDiego/BestPath")
    
    ' Add your code here.
    
End Sub

Running tools on the server

Toolboxes published on the server contain tools that require you to enter the input parameter values. There are restrictions on which data types can be used as input and output parameters for published tools. Variables with the Feature Class or Table data type are not allowed as input parameters. In these cases, the input needs to be specified as a feature set or record set. If a tool has a layer as input, the input parameter references a layer in a map document.
The following code examples show how to execute a service under various circumstances:
  • Execute a server tool where the data resides on the server and references layers in a map document:
[C#]
// The input parameters reference layers in a map document that contain the toolbox and tools. 

public void SampleExecuteServerToolByReference()
{

    // Initialize the geoprocessor.
    Geoprocessor GP = new Geoprocessor();

    // Add the BestPath toolbox.
    GP.AddToolbox(@"http://flame7/arcgis/services;GP/Bestpathtoolbox");

    // Inputs reference layers in a map document on the server. 
    IVariantArray parameters = new VarArrayClass();
    parameters.Add("source");
    parameters.Add("destination");

    // Execute the server tool by reference.
    IGeoProcessorResult result;
    result = (IGeoProcessorResult)GP.Execute("CalculateBestPath", parameters, null);

}
[VB.NET]
' Execute a tool by reference. The input parameters reference layers in a map document that
' contain the toolbox and tools.

Public Sub SampleExecuteServerToolByReference()
    
    ' Initialize the geoprocessor.
    Dim GP As Geoprocessor = New Geoprocessor()
    
    ' Add the BestPath toolbox.
    GP.AddToolbox("http://flame7/arcgis/services;GP/Bestpathtoolbox")
    
    ' Inputs reference layers in a map document on the server.
    Dim parameters As IVariantArray = New VarArrayClass()
    parameters.Add("source")
    parameters.Add("destination")
    
    ' Execute the server tool by reference.
    Dim result As ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult
    result = CType(GP.Execute("CalculateBestPath", parameters, Nothing), ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult)
    
End Sub
  • Execute a server tool where the data resides on the client. In this example, the data is loaded into a feature set:
[C#]
// The input parameter is a feature set referencing a feature class on the client. 
// Load the feature class into a record set to be passed to the server.

public void SampleExecuteServerToolByValue()
{

    // Initialize the geoprocessor.
    Geoprocessor GP = new Geoprocessor();

    // Add the BestPath toolbox.
    GP.AddToolbox(@"http://flame7/arcgis/services;GP/Bestpathtoolbox");

    // Create a record set from an input feature class. 
    IGPUtilities2 gputils = new GPUtilitiesClass();
    IFeatureClass fc = (IFeatureClass)gputils.OpenDatasetFromLocation(@
        "C:\sandiego\source.shp");
    IRecordSetInit recordset = new RecordSetClass();
    recordset.SetSourceTable((ITable)fc, null);
    IGPRecordSet gprecordset = new GPFeatureRecordSetLayerClass();
    gprecordset.Recordset = (IRecordSet)recordset;

    IVariantArray parameters = new VarArrayClass();
    parameters.Add(gprecordset);

    // Do the same for the destination feature class and add to the variant array.

    // Execute the server tool by reference. 
    IGeoProcessorResult result;
    result = (IGeoProcessorResult)GP.Execute("CalculateBestPath", parameters, null);

}
[VB.NET]
' The input parameter is a feature set referencing a feature class on the client.
' Load the feature class into a record set to be passed to the server.

Public Sub SampleExecuteServerToolByValue()
    
    ' Initialize the geoprocessor.
    Dim GP As Geoprocessor = New Geoprocessor()
    
    ' Add the BestPath toolbox.
    GP.AddToolbox("http://flame7/arcgis/services;GP/Bestpathtoolbox")
    
    Dim gpUtils As IGPUtilities
    gpUtils = New GPUtilitiesClass()
    
    Dim fc As IFeatureClass
    fc = gpUtils.OpenDatasetFromLocation("C:\sandiego\source.shp")
    Dim recordset As IRecordSetInit
    recordset = New RecordSetClass
    recordset.SetSourceTable = fc, Nothing
    Dim gpRecordSet As IGPRecordSet
    gpRecordSet = New GPFeatureRecordSetLayerClass
    gpRecordSet.RecordSet = recordset
    
    Dim parameters As IVariantArray = New VarArrayClass()
    parameters.Add(gprecordset)
    
    ' Do the same for the destination feature class and to the variant array.
    
    ' Execute the server tool by reference.
    Dim result As ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult
    result = CType(GP.Execute("CalculateBestPath", parameters, Nothing), ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult)
    
End Sub
  • Execute a server tool where the input is a feature set created using an insert cursor:
[C#]
// The input parameter is a feature set created using an insert cursor.

public void SampleExecuteServerToolByValue()
{

    // Initialize the geoprocessor.
    Geoprocessor GP = new Geoprocessor();

    // Add the BestPath toolbox.
    GP.AddToolbox(@"http://flame7/arcgis/services;GP/Bestpathtoolbox");

    // Create an OID field.
    IFieldsEdit fieldsEdit = new FieldsClass();
    IFieldEdit fieldEdit = new FieldClass();
    fieldEdit.Name_2 = "ObjectID";
    fieldEdit.Type_2 = esriFieldType.esriFieldTypeOID;
    fieldsEdit.AddField(fieldEdit);

    // Create a Shape field and assign a geometry definition.
    IGeometryDefEdit geomEdit = new GeometryDefClass();
    geomEdit.GeometryType_2 = esriGeometryType.esriGeometryPoint;

    // Create a spatial reference to assign to the geometry definition.
    ISpatialReferenceFactory srf = new SpatialReferenceEnvironmentClass();
    ISpatialReference sr = srf.CreateESRISpatialReferenceFromPRJFile(@
        "C:\Program Files\ArcGIS\Coordinate Systems\Projected Coordinate Systems\Utm\Nad 1983\NAD 1983 UTM Zone 21N.prj");
    ISpatialReferenceResolution srRes = sr as ISpatialReferenceResolution;
    srRes.ConstructFromHorizon();
    srRes.SetDefaultXYResolution();
    IControlPrecision2 cp2 = sr as IControlPrecision2;
    cp2.IsHighPrecision = true;
    geomEdit.SpatialReference_2 = sr;

    fieldEdit = new FieldClass();
    fieldEdit.Name_2 = "SHAPE";
    fieldEdit.Type_2 = esriFieldType.esriFieldTypeGeometry;
    fieldEdit.GeometryDef_2 = geomEdit;
    fieldsEdit.AddField(fieldEdit);

    // Create the record set.
    IRecordSetInit rsInit = new RecordSetClass();
    rsInit.CreateTable(fieldsEdit);
    IRecordSet rs = rsInit as IRecordSet;

    // Create a new point feature and insert into the feature set.
    ICursor cursor = rsInit.Insert();
    IPoint pnt = new PointClass();
    pnt.PutCoords(736204, 5269724);
    IRowBuffer rowBuffer = rsInit.CreateRowBuffer();
    rowBuffer.set_Value(1, pnt);
    cursor.InsertRow(rowBuffer);
    IGPRecordSet gpRS = new GPFeatureRecordSetLayerClass();
    gpRS.RecordSet = rs;

    IVariantArray parameters = new VarArrayClass();
    parameters.Add(gpRS);

    // Do the same for the destination point.  

    // Execute the server tool by reference. 
    IGeoProcessorResult result;
    result = (IGeoProcessorResult)GP.Execute("CalculateBestPath", parameters, null);
}
[VB.NET]
' The input parameter is a feature set created using an insert cursor.

Public Sub SampleExecuteServerToolByValue()
    
    ' Initialize the geoprocessor.
    Dim GP As Geoprocessor = New Geoprocessor()
    
    ' Add the BestPath toolbox.
    GP.AddToolbox("http://flame7/arcgis/services;GP/Bestpathtoolbox")
    
    ' Create an OID field.
    Dim pFieldsEdit As IFieldsEdit
    pFieldsEdit = New Fields
    Dim pFieldEdit As IFieldEdit
    pFieldEdit = New Field
    With pFieldEdit
        .Name_2 = "ObjectID"
        .Type_2 = esriFieldType.esriFieldTypeOID
    End With
    pFieldsEdit.AddField(pFieldEdit)
    
    ' Create a Shape field and assign a geometry definition.
    
    Dim pGeomDef As IGeometryDefEdit
    pGeomDef = New GeometryDef
    Dim psrf As ISpatialReferenceFactory3
    psrf = New SpatialReferenceEnvironment
    Dim psr As ISpatialReference3
    psr = psrf.CreateESRISpatialReferenceFromPRJFile("C:\Program Files\ArcGIS\Coordinate Systems\Projected Coordinate Systems\Utm\Nad 1983\NAD 1983 UTM Zone 21N.prj")
    Dim pSrResoltuion As ISpatialReferenceResolution
    pSrResoltuion = psr
    pSrResoltuion.ConstructFromHorizon()
    pSrResoltuion.SetDefaultXYResolution()
    Dim pPrecision As IControlPrecision2
    pPrecision = psr
    pPrecision.IsHighPrecision = True
    With pGeomDef
        .GeometryType_2 = esriGeometryType.esriGeometryPoint
        .SpatialReference_2 = psr
    End With
    pFieldEdit = New Field
    With pFieldEdit
        .Name_2 = "SHAPE"
        .Type_2 = esriFieldType.esriFieldTypeGeometry
        .GeometryDef_2 = pGeomDef
    End With
    pFieldsEdit.AddField(pFieldEdit)
    
    ' Create the record set.
    Dim pRecordSetInit As IRecordSetInit
    pRecordSetInit = New RecordSet
    pRecordSetInit.CreateTable(pFieldsEdit)
    Dim pRecordSet As IRecordSet
    pRecordSet = pRecordSetInit
    
    ' Create a new point feature and insert into the feature set.
    
    Dim pCursor As ICursor
    pCursor = pRecordSetInit.Insert
    Dim pPoint As IPoint
    pPoint = New Point
    pPoint.PutCoords(736204, 5269724)
    Dim pRowBuffer As IRowBuffer
    pRowBuffer = pRecordSetInit.CreateRowBuffer
    pRowBuffer.Value(1) = pPoint
    pCursor.InsertRow(pRowBuffer)
    Dim pGPRecordSet As IGPRecordSet
    pGPRecordSet = New GPFeatureRecordSetLayer
    pGPRecordSet.RecordSet = pRecordSet
    
    ' Do the same for the destination feature class and to the variant array.
    
    ' Create array of parameters.
    Dim parameters As IVariantArray = New VarArrayClass()
    parameters.Add(pGPRecordSet)
    
    ' Execute the server tool by reference.
    Dim result As ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult
    result = CType(GP.Execute("CalculateBestPath", parameters, Nothing), ESRI.ArcGIS.Geoprocessing.IGeoProcessorResult)
    
End Sub
For more information about publishing and consuming geoprocessing services on an ArcGIS server, see the ArcGIS Desktop Help.


See Also:

An overview of geoprocessing with ArcGIS Server.




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):