ProConcepts Tasks

The ArcGIS.Desktop.TaskAssistant namespace provides access to the classes and members that offer the ability to access, open, close or export task items.

ArcGIS.Desktop.TaskAssistant.dll

Language:      C#
Subject:       Tasks
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          12/21/2022
ArcGIS Pro:    3.1
Visual Studio: 2022

In this topic

• Task items
• .esriTasks files
• Task item information
• Task events

Task items

A project can contain multiple task items, and each item defines a collection of tasks. A task is a set of preconfigured steps that represents a workflow or business process. A task can be used to implement a best-practice workflow, improve the efficiency of a workflow, or create a series of interactive tutorial steps.

You retrieve the task items in a project using the Project.Current.GetItems method:

IEnumerable<TaskProjectItem> taskItemss = Project.Current.GetItems<TaskProjectItem>();

A TaskProjectItem has all the methods and properties inherited from its parent ArcGIS.Desktop.Core.Item. It also has two additional properties, TaskItemGuid and IsOpen. The TaskItemGuid property returns the unique GUID of the task item and is passed as the parameter to the OpenTaskItemAsync, CloseTaskItemAsync, and ExportTaskItemAsync methods. IsOpen is used to determine the task item currently open in the Tasks pane.

// get the first project task item
var taskItem = Project.Current.GetItems<TaskProjectItem>().FirstOrDefault();
// if there isn't a project task item, return
if (taskItem == null)
  return;

try
{
  // Open it  
  // At 2.x
  //System.Guid guid = await TaskAssistantModule.OpenTaskItemAsync(taskItem.TaskItemGuid);
  var guid = await TaskAssistantFactory.Instance.OpenTaskItemAsync(taskItem.TaskItemGuid);
}
catch (OpenTaskException e)
{
  ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(e.Message);
}

.esriTasks files

A task item is shared by exporting the task item to an .esriTasks file. An .esriTasks file can be imported and opened in a different project.

Use the static ExportTaskItemAsync method to export a task item. ExportTaskException is in the ArcGIS.Desktop.TaskAssistant.Exceptions namespace.

// Get the first project task item
var taskItem = Project.Current.GetItems<TaskProjectItem>().FirstOrDefault();
// If there isn't a project task item, return
if (taskItem == null)
  return;

try
{
  // Export the task item to the c:\Temp folder
  string exportFolder = @"c:\temp";
  //At 2.x
  //string fileName = await TaskAssistantModule.ExportTaskAsync(taskItem.TaskItemGuid, exportFolder);
  string fileName = await TaskAssistantFactory.Instance.ExportTaskItemAsync(taskItem.TaskItemGuid, exportFolder);
  ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show("Task saved to " + fileName); 
}
catch (ExportTaskException e)
{
  ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show("Error saving task " + e.Message);
}

Use the static OpenTaskFileAsync method to import and open an .esriTasks file. OpenTaskException is in the ArcGIS.Desktop.TaskAssistant.Exceptions namespace.

// Open a task file
try
{
  // substitute your own .esriTasks file to be opened
  // retain the taskItem guid returned 
  string taskFile = @"c:\Tasks\Get Started.esriTasks";
  //At 2.x
  //System.Guid guid = await TaskAssistantModule.OpenTaskAsync(taskFile);
  System.Guid guid = await TaskAssistantFactory.Instance.OpenTaskFileAsync(taskFile);
}
catch (OpenTaskException e)
{
  // exception thrown if task file doesn't exist or has incorrect format
  ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(e.Message);
}

Task item information

Retrieve information from a task item using the GetTaskItemInfoAsync method available off the TaskProjectItem object. You can obtain the Name, Description and Guid of the task item along with information about the tasks within the task item. This can be useful if you want to open a specific task within a task item.

// find the first task item in the project
var taskItem = Project.Current.GetItems<TaskProjectItem>().FirstOrDefault();
// if there isn't a project task item, return
if (taskItem == null)
  return;

string message = await QueuedTask.Run(async () =>
{
  bool isOpen = taskItem.IsOpen;
  Guid taskGuid = taskItem.TaskItemGuid;

  string msg = "";
  try
  {
    TaskItemInfo taskItemInfo = await taskItem.GetTaskItemInfoAsync();

    msg = "Name : " + taskItemInfo.Name;
    msg += "\r\n" + "Description : " + taskItemInfo.Description;
    msg += "\r\n" + "Guid : " + taskItemInfo.Guid.ToString("B");
    msg += "\r\n" + "Task Count : " + taskItemInfo.GetTasks().Count();

    // iterate the tasks in the task item
    IEnumerable<TaskInfo> taskInfos = taskItemInfo.GetTasks();
    foreach (TaskInfo taskInfo in taskInfos)
    {
      string name = taskInfo.Name;
      Guid guid = taskInfo.Guid;

      // do something 
    }
  }
  catch (OpenTaskException e)
  {
    // exception thrown if task file doesn't exist or has incorrect format
    msg = e.Message;
  }
  catch (TaskFileVersionException e)
  {
    // exception thrown if task file does not support returning task information
    msg = e.Message;
  }
  return msg;
});

ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(message, "Task Information");

You can obtain the same information from an .esriTasks file using the static GetTaskItemInfoAsync method from the TaskAssistantFactory object.

Task events

Tasks supports two events; TaskStartedEvent and TaskEndedEvent. The TaskStartedEvent is raised when execution of a task commences; the TaskEndedEvent is raised when execution of a task is completed or cancelled. TaskStartedEvent and TaskEndedEvent are in the ArcGIS.Desktop.TaskAssistant.Events namespace.

public void MainMethodCode()
{
  TaskStartedEvent.Subscribe(OnTaskStarted);
  TaskEndedEvent.Subscribe(OnTaskCompletedOrCancelled);
}

private void OnTaskStarted(TaskStartedEventArgs args)
{
  // do something

  // TaskStartedEventArgs contains information regarding the task 
  // item and task that was commenced including the UserID who 
  // executed the task and start time.

}

private void OnTaskCompletedOrCancelled(TaskEndedEventArgs args)
{
  // do something

  // TaskEndedEventArgs contains information regarding the task 
  // item and task that was ended including whether the task was 
  // completed or cancelled, the UserID who executed the task, 
  // start time, end time, duration. 

}