Execute Method

In This Topic

Submits the job for execution

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
Public Function Execute( _
   ByVal options As JobExecutionSettings _
) As ExecuteJobResult

public ExecuteJobResult Execute( 
   JobExecutionSettings options
)

public:
ExecuteJobResult^ Execute( 
   JobExecutionSettings^ options
)

Parameters

options: Options and settings for executing the job

Return Value

An ExecuteJobResult containing the status of the execution request

Remarks

This method submits the job for execution and returns immediately; it does not wait for execution to complete.

If the job cannot be submitted (e.g., because the caller does not have Execute permission for the job), ExecuteJobResult.JobSubmitted will be false and Messages will contain one or more messages giving the error.

If the job is submitted, ExecuteJobResult.JobSubmitted will be true and ExecuteJobResult.Instances will contain ExecutionHistoryItem(s) representing the instances created as a result of the request. There may be more than one instance for a job in a Queue that runs on multiple targets (agents). In that case there will be one instance for each computer where the job will execute.

You also retain the JobExecutionSettings.ExecutionRequestID and use it in a call to JobServices.GetInstancesForRequest to retrieve the instances for this execution request.

To wait for the outcome of the job

Example

This example demonstrates how to submit a job for execution and then wait until execution has completed. To do this, you must periodically refresh the status of each of the instances created by the execution request and wait until all have finished running.

C#
VB.NET

void RunJobAndWait(Job job)
{
    var options = new JobExecutionSettings();
 
    //submit the job
    var result = job.Execute(options);
 
    if (!result.JobSubmitted)
    {
        //The job could not be submitted. The result.Messages collection will contain the error message(s)
        return;
    }
 
    var waitingInstances = new List<ExecutionHistoryItem>();
 
    //result.Instances has all the instances created for this request
    //make a new collection of them
    waitingInstances.AddRange(result.Instances);
 
    while (waitingInstances.Any())
    {
        //Sleep for some reasonable period before checking again
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(30));
 
        //look at each instance that we're still waiting on
        foreach (var instance in waitingInstances.ToArray())
        {
            //Refresh the instance to get its latest status from the server
            instance.Refresh();
 
            //The instance is created with state NotRun. If we poll the server before the execution process has gotten
            //underway it's possible the instance will still have that state, so we treat that the same as if it were running.
            //The IsRunning property returns true if the job is in any of the active job states
            if (instance.Status != JobState.NotRun && !instance.IsRunning)
            {
                //if the instance is no longer running, remove it from the list of instances we're waiting on.
                waitingInstances.Remove(instance);
            }
        }
 
        //if all instances have completed, waitingInstances will be empty and we're finished
    }
}

Private Sub RunJobAndWait(ByVal job As Job)
    Dim options = New JobExecutionSettings()
    
    'submit the job
    Dim result = job.Execute(options)
 
    If Not result.JobSubmitted Then
        'The job could not be submitted. The result.Messages collection will contain the error message(s)
        Return
    End If
 
    'result.Instances has all the instances created for this request
    'make a new collection of them
    Dim waitingInstances = New List(Of ExecutionHistoryItem)()
    waitingInstances.AddRange(result.Instances)
 
    While waitingInstances.Any()
        'Sleep for some reasonable period before checking again
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(30))
 
        'look at each instance that we're still waiting on
        For Each instance In waitingInstances.ToArray()
            'Refresh the instance to get its latest status from the server
            instance.Refresh()
 
            'The instance is created with state NotRun. If we poll the server before the execution process has gotten
            'underway it's possible the instance will still have that state, so we treat that the same as if it were running.
            'The IsRunning property returns true if the job is in any of the active job states
            If instance.Status <> JobState.NotRun AndAlso Not instance.IsRunning Then
                'if the instance is no longer running, remove it from the list of instances we're waiting on.
                waitingInstances.Remove(instance)
            End If
        Next
        
        'if all instances have completed, waitingInstances will be empty and we're finished
    End While
End Sub

Reference

Job Class
Job Members