Task system

The NanoByte.Common.Tasks namespace provides a framework for managing long-running tasks and reporting progress to the user.

Tasks

Tasks are represented using the ITask interface.

This library provides general-purpose implementations such as ActionTask and ForEachTask, as well as use-case specific ones such as DownloadFile and ReadFile. You can also implement your own.

Handlers

The ITaskHandler interface represents a user interface for reporting task progress as well as displaying prompts and outputs to the user. This library provides a number of implementations:

• CliTaskHandler for a basic command-line interface
• AnsiCliTaskHandler for a more advanced command-line interface using ANSI codes
• DialogTaskHandler for a graphical interface using WinForms dialog boxes
• SilentTaskHandler for background execution or unit tests
• ServiceTaskHandler for integration with Microsoft.Extensions.DependencyInjection

Methods that want to run ITasks should take an ITaskHandler as an input parameter.
To run an ITask, pass it to the ITaskHandler.RunTask() method. This will then internally call ITask.Run() and take care of setting up progress tracking, cancellation, etc.. Additional methods such as ITaskHandler.Ask() can be used for user interaction.

Threading

ITasks provide no threading or asynchronicity concept by themselves. Their .Run() methods block until the tasks is complete. However, they can be cancelled from other threads via <xref:System.Threading.CancellationToken>s.

ITaskHandler implementations are thread-safe and support running multiple ITasks concurrently.
ITaskHandler.RunTask() blocks until the tasks is complete, however some implementations may perform the actual task execution on a separate thread.
DialogTaskHandler keeps the WinForms message loop pumping while a task is running, so calling .RunTask() from the GUI thread will not freeze the GUI. However it does prevent user interaction (other than canceling the task) via a modal dialog box.

Comparison with async/await

While ITask has some superficial similarities with the <xref:System.Threading.Tasks.Task> class used by the C# async/await keywords, these two concepts should not be confused.

The async/await keywords are part of the Task Asynchronous Programming model (TAP). The TAP provides an abstraction over asynchronous code, enabling the execution of continuations after tasks have completed. This is intended to increase the performance and responsiveness of applications. Many TAP methods accept <xref:System.Threading.CancellationToken>s to signal that a task should be cancelled and <xref:System.IProgress`1> to report a task's progress.

NanoByte.Common's Task system is intended for managing long-running tasks. It provides an abstraction over UIs for interacting with such tasks. It uses the same <xref:System.Threading.CancellationToken> and <xref:System.IProgress`1> as the TAP, but takes care of managing them internally for most use cases.

As a rule of thumb:

• Use await and <xref:System.Threading.Tasks.Task> if you want to trigger a short task from a GUI thread.
• Use ITaskHandler.RunTask() and ITask if you want to run a longer task on a non-GUI thread (potentially reporting back to a GUI thread).