Running a geoprocessing tool using background geoprocessing

In this topic

• Geoprocessing
• Background geoprocessing
• Submitting a tool
• Checking tool execution status
  • Geoprocessor events
  • ToolExecuting event
  • ProgressChanged event
  • ToolExecuted event 
  • IGeoProcessorResult
• Canceling a tool
• Layer and data usage during tool execution
• Edit sessions and background geoprocessing
  • Start editing then execute in the background
  • Execute in the background then start editing

Geoprocessing

Background geoprocessing

• Submitting the tool for execution.
• Checking the tool's execution status.

Submitting a tool

ESRI.ArcGIS.Geoprocessor.Geoprocessor gp=new ESRI.ArcGIS.Geoprocessor.GeoProcessor
    ();
gp.OverwriteOutput=true;
//Register to receive the geoprocessor event when the tools have completed execution.
gp.ToolExecuted += new EventHandler < ESRI.ArcGIS.Geoprocessor.ToolExecutedEventArgs
    > (gpToolExecuted);
IGeoProcessorResult2 gpResult=gp.ExecuteAsync("CopyFeatures", parameters)as
    IGeoProcessorResult2;

Dim gp As ESRI.ArcGIS.Geoprocessor.Geoprocessor=New ESRI.ArcGIS.Geoprocessor.Geoprocessor()
gp.OverwriteOutput=True
'Register to receive the geoprocessor event when the tools have completed execution.
AddHandler gp.ToolExecuted, AddressOf gpToolExecuted
Dim gpResult As IGeoProcessorResult2=CType(gp.ExecuteAsync("CopyFeatures", parameters), IGeoProcessorResult2)

Checking tool execution status

• Register and listen for the Geoprocessor.ToolExecuted events and, optionally, the other events (this is the most common option).
• Periodically query IGeoprocessorResult.

Geoprocessor events

• The ToolExecuting event is fired by all tools before a tool is taken from the geoprocessing queue and executed in the background. At this time, the tool's IGeoProcessorResult.Status property is still esriJobStatus.esriJobWaiting.
• The MessagesCreated event and the ProgressChanged event can fire during tool execution. These events fire depending on which tool is executing and how much data the tool is processing.
• The ToolExecuted event is fired by all tools when background execution has stopped.

ToolExecuting event

public void gpToolExecuting(object sender, ToolExecutingEventArgs e)
{
    IGeoProcessorResult2 result=e.GPResult as IGeoProcessorResult2;
    //Determine if this is the tool to handle this event.
    if (result.Process.Tool.Name.Equals("CopyFeatures") && result.GetInput(0)
        .GetAsText().Equals(@"c:\Europe_Roads\Europe_Roads") && result.GetOutput(0)
        .GetAsText().Equals(@"c:\Europe_Roads\Europe_Roads_Copy"))
    {
        //Application specific code.
    }
}

Public Sub gpToolExecuting(ByVal sender As Object, ByVal e As ToolExecutingEventArgs)
    Dim result As IGeoProcessorResult2=CType(e.GPResult, IGeoProcessorResult2)
    'Determine if this is the tool to handle this event.
    If (result.Process.Tool.Name.Equals("CopyFeatures") _
           And result.GetInput(0).GetAsText().Equals("c:\Europe_Roads\Europe_Roads") _
           And result.GetOutput(0).GetAsText().Equals("c:\Europe_Roads\Europe_Roads_Copy")) Then
        'Application specific code.
    End If
End Sub

ProgressChanged event

public void gpProgressChanged(object sender, ProgressChangedEventArgs e)
{
    System.Windows.Forms.ProgressBar progressBar=myProgressBar;
    IGeoProcessorResult2 gpResult=(IGeoProcessorResult2)e.GPResult;
    switch (e.ProgressChangedType)
    {
        case (ProgressChangedType.Show): 
        //The tool that is running reports progress or has stopped reporting progress; make the 
        // progress bar visible if appropriate. 
        progressBar.Visible=e.Show;
        break;
        case (ProgressChangedType.Message): 
        //The application does not use these, since a tool being used reports percentage progress.
        break;
        case (ProgressChangedType.Percentage): progressBar.Value=(int)
            e.ProgressPercentage;
        break;
        default:
            throw new ApplicationException(
                "unexpected ProgressChangedEventsArgs.ProgressChangedType");
            break;
    }
}

Public Sub gpProgressChanged(ByVal sender As Object, ByVal e As ProgressChangedEventArgs)
    Dim progressBar As System.Windows.Forms.ProgressBar=myProgressBar
    Dim gpResult As IGeoProcessorResult2=(CType(e.GPResult, IGeoProcessorResult2))
    Select Case (e.ProgressChangedType)
        Case (ProgressChangedType.Show)
            'The tool that is running reports progress or has stopped reporting progress;
            'make the progress bar visible if appropriate.
            progressBar.Visible=e.Show
        Case (ProgressChangedType.Message)
            'The application does not use these, since a tool being used reports percentage progress.
        Case (ProgressChangedType.Percentage)
            progressBar.Value=CType(e.ProgressPercentage, Integer)
        Case Else
            Throw New ApplicationException("unexpected ProgressChangedEventsArgs.ProgressChangedType")
    End Select
End Sub

ToolExecuted event

public void gpToolExecuted(object sender, ToolExecutedEventArgs e)
{
    IGeoProcessorResult2 result=e.GPResult as IGeoProcessorResult2;
    if (result.Status.Equals(esriJobStatus.esriJobSucceeded))
    {
        //Check that there are no information or warning messages.
        if (result.MaxSeverity == 0)
        {
            //Get the return value.
            object returnValue=result.ReturnValue;
            //Application specific code, 
            //for example, find the layer to which this return value corresponds.
        }
        else
        {
            //Application specific code.
        }
    }
    else
    {
        //Get all messages.
        IGPMessages msgs=result.GetResultMessages();
        for (int i=0; i < result.MessageCount; i++)
        {
            IGPMessage2 msg=msgs.GetMessage(i)as IGPMessage2;
            //Application specific code.
        }
    }
}

Public Sub gpToolExecuted(ByVal sender As Object, ByVal e As ToolExecutedEventArgs)
    Dim result As IGeoProcessorResult2=CType(e.GPResult, IGeoProcessorResult2)
    If (result.Status.Equals(esriJobStatus.esriJobSucceeded)) Then
        'Check that there are no information or warning messages.
        If (result.MaxSeverity=0) Then
            'Get the return value.
            Dim returnValue As Object=result.ReturnValue
            'Application specific code,
            'for example, find the layer to which this return value corresponds.
        Else
            'Application specific code.
        End If
    Else
        'Get all messages.
        Dim msgs As IGPMessages=result.GetResultMessages()
        Dim i As Integer
        For i=0 To result.MessageCount
            Dim msg As IGPMessage2=CType(msgs.GetMessage(i), IGPMessage2)
            'Application specific code.
        Next i
    End If
End Sub

IGeoProcessorResult

Canceling a tool

Layer and data usage during tool execution 

• Changing the visibility, select ability, and connection details of a layer input to or output from an executing geoprocessing tool.
• Searching and selecting data input to a geoprocessing tool, for example, using the IFeatureLayer.Search and IFeatureClass.Select methods.

• Editing table rows of input or output data in or out of an edit session.
• Using the IFeatureLayer.Search and IFeatureClass.Select methods on output data. The set of table rows returned is undefined, since the table is in the process of being populated.

Edit sessions and background geoprocessing

Start editing then execute in the background

public void gpToolExecuting(object sender, ToolExecutingEventArgs e)
{
    IGeoProcessorResult2 result=e.GPResult as IGeoProcessorResult2;
    //Get the single feature class input parameter.
    IGPParameter parameter=result.Process.InputParameters.get_Element(0)as
        IGPParameter;
    string parameterPath="";
    if (parameter.DataType.DisplayName.Equals("FeatureClass"))
    {
        parameterPath=parameter.Value.GetAsText();
    }

    //Check whether this dataset is being edited.
    ESRI.ArcGIS.Controls.EngineEditor engineEditor=new
        ESRI.ArcGIS.Controls.EngineEditor();
    if (engineEditor.EditState == esriEngineEditState.esriEngineStateEditing &&
        engineEditor.EditWorkspace != null)
    {
        IEnumDatasetName datasetNames=engineEditor.EditWorkspace.get_DatasetNames
            (esriDatasetType.esriDTAny);
        IDatasetName name=datasetNames.Next();
        while (name != null)
        {
            string path=engineEditor.EditWorkspace.PathName + @
                "\" + name.Name;if (path.Equals(parameterPath))
            {
                //This datset is being edited. Prompt the user to stop editing.
            }
        }
    }
}

Public Sub gpToolExecuting(ByVal sender As Object, ByVal e As ToolExecutingEventArgs)
    Dim result As IGeoProcessorResult2=CType(e.GPResult, IGeoProcessorResult2)
    'Get the single feature class input parameter.
    Dim parameter As IGPParameter=CType(result.Process.InputParameters.get_Element(0), IGPParameter)
    Dim parameterPath As String=""
    If (parameter.DataType.DisplayName.Equals("FeatureClass")) Then
        parameterPath=parameter.Value.GetAsText()
    End If
    'Check whether this dataset is being edited.
    Dim engineEditor As ESRI.ArcGIS.Controls.EngineEditor=New ESRI.ArcGIS.Controls.EngineEditor()
    If (engineEditor.EditState=esriEngineEditState.esriEngineStateEditing And Not engineEditor.EditWorkspace Is Nothing) Then
        Dim datasetNames As IEnumDatasetName=engineEditor.EditWorkspace.get_DatasetNames(esriDatasetType.esriDTAny)
        Dim Name As IDatasetName=datasetNames.Next()
        While (Not Name Is Nothing)
            Dim Path As String=engineEditor.EditWorkspace.PathName + "\" + Name.Name
            If (Path.Equals(parameterPath)) Then
                'This datset is being edited. Prompt the user to stop editing.
            End If
        End While
    End If
End Sub

End Class

Execute in the background then start editing

See Also:

• ESRI.ArcGIS.Geoprocessing
• ESRI.ArcGIS.Geodatabase