Namespace NanoByte.Common.Tasks

Task system 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 CancellationTokens.

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 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 CancellationTokens to signal that a task should be cancelled and IProgress<T> 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 CancellationToken and IProgress<T> as the TAP, but takes care of managing them internally for most use cases.

As a rule of thumb:

Use await and 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).

API

Classes

ActionTask: A task that executes an Action that can be canceled. Only completion is reported, no intermediate progress.

AnsiCliProgress: Reports task progress updates using ANSI console output.

AnsiCliProgressContext: Container for one or more ANSI console progress bars.

AnsiCliTaskHandler: Informs the user about the progress of tasks and ask questions using ANSI console output.

CliProgress: Reports task progress updates using console output.

CliTaskHandler: Informs the user about the progress of tasks and ask questions using console output.

DeferredProgress<T>: Remembers the latest call made to Report(T). Forwards that call (if any) and all future calls to a target IProgress<T> implementation once it is set.

DialogTaskHandler: Uses simple WinForms dialog boxes to inform the user about the progress of tasks.

ForEachTask: Provides a static factory method for ForEachTask<T> as an alternative to calling the constructor to exploit type inference.

ForEachTask<T>: A task that executes an action once for each element of a collection.

GuiTaskHandlerBase: Common base class for WinForms ITaskHandler implementations.

PercentageTask: A task that executes an Action<T> and reports progress in percent.

ResultTask: Provides a static factory method for ResultTask<T> as an alternative to calling the constructor to exploit type inference.

ResultTask<T>: A task that executes a callback and the provides a result. Only completion is reported, no intermediate progress.

SilentTaskHandler: Executes tasks silently and suppresses any questions.

TaskBase: Abstract base class for ITask implementations.

TaskHandlerBase: Common base class for ITaskHandler implementations.

TaskHandlerExtensions: Extension methods for ITaskHandler

Structs

TaskSnapshot: Represents a progress snapshot of an ITask.

Interfaces

IResultTask<T>: A task the provides a result.

ITask: Represents an operation that can be cancelled and have its progress tracked.

ITaskHandler: Used to run and track ITasks and ask the user questions. Specific implementations provide different kinds of user interfaces.

Enums

TaskState: Represents different states a (usually Web- or IO-related) task can be in.

Verbosity

Delegates

PercentProgressCallback: A callback to be called by a workload to report its progress in percent.

Table of Contents