Class TaskHandlerBase

Namespace

NanoByte.Common.Tasks

Assembly

NanoByte.Common.dll

Common base class for ITaskHandler implementations.

[MustDisposeResource]
public abstract class TaskHandlerBase : ITaskHandler

Inheritance

object

TaskHandlerBase

Implements

ITaskHandler

Derived

CliTaskHandler

GuiTaskHandlerBase

Extension Methods

TaskHandlerExtensions.OutputLow(ITaskHandler, string, string)

TaskHandlerExtensions.OutputLow<T>(ITaskHandler, string, NamedCollection<T>)

TaskHandlerExtensions.OutputLow<T>(ITaskHandler, string, IEnumerable<T>)

TaskHandlerExtensions.RunTaskAndReturn<T>(ITaskHandler, ResultTask<T>)

BinaryStorage.SaveBinary<T>(T, Stream)

BinaryStorage.SaveBinary<T>(T, string)

JsonStorage.SaveJson<T>(T, Stream)

JsonStorage.SaveJson<T>(T, string)

JsonStorage.ToJsonString<T>(T)

XmlStorage.SaveXml<T>(T, string, string?)

UpdateUtils.To<TIn, TOut>(TIn, Func<TIn, TOut>)

ConversionUtils.ConvertToString<TType>(TType)

JsonStorage.ReparseAsJson<T>(object)

JsonStorage.ReparseAsJson<T>(object, T)

XmlStorage.SaveXml(object, Stream, string?)

XmlStorage.ToXmlString(object, string?)

Remarks

This class is thread-safe.

Constructors

TaskHandlerBase()

Registers a Handler.

protected TaskHandlerBase()

Properties

CancellationToken

Used to signal when the user wants to cancel the entire current process (and any ITasks it includes).

public CancellationToken CancellationToken { get; }

Property Value

CancellationToken

Remarks

Once this has been signalled this ITaskHandler cannot be reused, since any subsequently started ITasks will be cancelled immediately.

CancellationTokenSource

Used to signal the CancellationToken.

protected CancellationTokenSource CancellationTokenSource { get; init; }

Property Value

CancellationTokenSource

CredentialProvider

Used to ask the user or a keyring for System.Net.NetworkCredentials for specific System.Uris; can be null.

protected virtual ICredentialProvider? CredentialProvider { get; }

Property Value

ICredentialProvider

IsInteractive

Indicates whether the user can provide input.

protected virtual bool IsInteractive { get; }

Property Value

bool

Verbosity

The detail level of messages displayed to the user.

public Verbosity Verbosity { get; set; }

Property Value

Verbosity

Methods

Ask(string, bool?, string?)

Asks the user a Yes/No/Cancel question.

public bool Ask(string question, bool? defaultAnswer = null, string? alternateMessage = null)

Parameters

question string

The question and comprehensive information to help the user make an informed decision.

defaultAnswer bool?

The default answer to preselect. May be chosen automatically if the user cannot be asked. null if the user must make the choice themselves.

alternateMessage string

A message to output with Warn(string, Exception?) when the defaultAnswer is used instead of asking the user.

Returns

bool

true if the user answered with 'Yes'; false if the user answered with 'No'.

Exceptions

OperationCanceledException

Throw if the user answered with 'Cancel' or if no answer can be obtained.

AskInteractive(string, bool)

Asks the user a Yes/No/Cancel question.

protected abstract bool AskInteractive(string question, bool defaultAnswer)

Parameters

question string

The question and comprehensive information to help the user make an informed decision.

defaultAnswer bool

The default answer to preselect.

Returns

bool

true if the user answered with 'Yes'; false if the user answered with 'No'.

Exceptions

OperationCanceledException

Throw if the user answered with 'Cancel'.

DisplayLogEntry(LogSeverity, string)

Hook called when a Log entry should be shown to the user.

protected abstract void DisplayLogEntry(LogSeverity severity, string message)

Parameters

severity LogSeverity

The type/severity of the entry.

message string

The message of the entry including.

Dispose()

Unregisters the Handler.

public virtual void Dispose()

Error(Exception)

Displays an error message to the user.

public abstract void Error(Exception exception)

Parameters

exception Exception

The exception representing the error that occurred.

LogHandler(LogSeverity, string?, Exception?)

Called for each Log entry. Handles exception messages.

protected virtual void LogHandler(LogSeverity severity, string? message, Exception? exception)

Parameters

severity LogSeverity

The type/severity of the entry.

message string

The message of the entry.

exception Exception

An optional exception associated with the entry.

Output(string, string)

Displays multi-line text to the user.

public abstract void Output(string title, string message)

Parameters

title string

A title for the message.

message string

The string to display. Trailing linebreaks are appropriately handled or ignored.

Remarks

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

Output<T>(string, NamedCollection<T>)

Displays tree-like data to the user.

public virtual void Output<T>(string title, NamedCollection<T> data) where T : INamed

Parameters

title string

A title for the data.INamed

data NamedCollection<T>

The data to display.

Type Parameters

T

Remarks

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

Output<T>(string, IEnumerable<T>)

Displays tabular data to the user.

public virtual void Output<T>(string title, IEnumerable<T> data)

Parameters

title string

A title for the data.

data IEnumerable<T>

The data to display.

Type Parameters

T

Remarks

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

RunTask(ITask)

Runs an ITask and tracks its progress. Returns once the task has been completed.

public virtual void RunTask(ITask task)

Parameters

task ITask

The task to be run. (Run(CancellationToken, ICredentialProvider?, IProgress<TaskSnapshot>?) or equivalent is called on it.)

Exceptions

OperationCanceledException

The user canceled the task.

IOException

The task ended with IOError.

WebException

The task ended with WebError.