NanoByte.Common 2.10.6
NanoByte.Common.Tasks.ITaskHandler Interface Reference

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

Inheritance diagram for NanoByte.Common.Tasks.ITaskHandler:
NanoByte.Common.Tasks.TaskHandlerBase NanoByte.Common.Tasks.CliTaskHandler NanoByte.Common.Tasks.GuiTaskHandlerBase NanoByte.Common.Tasks.SilentTaskHandler NanoByte.Common.Tasks.AnsiCliTaskHandler NanoByte.Common.Tasks.DialogTaskHandler NanoByte.Common.Tasks.ServiceTaskHandler

Public Member Functions

void RunTask (ITask task)
 Runs an ITask and tracks its progress. Returns once the task has been completed. More...
 
bool Ask ([Localizable(true)] string question, bool? defaultAnswer=null, [Localizable(true)] string? alternateMessage=null)
 Asks the user a Yes/No/Cancel question. More...
 
void Output ([Localizable(true)] string title, [Localizable(true)] string message)
 Displays multi-line text to the user. More...
 
void Output< T > ([Localizable(true)] string title, IEnumerable< T > data)
 Displays tabular data to the user. More...
 
void Output< T > ([Localizable(true)] string title, NamedCollection< T > data)
 Displays tree-like data to the user. More...
 
void Error (Exception exception)
 Displays an error message to the user. More...
 

Properties

CancellationToken CancellationToken [get]
 Used to signal when the user wishes to cancel the entire current process (and any ITasks it includes). More...
 
ICredentialProviderCredentialProvider [get]
 Used to ask the user or a keyring for NetworkCredentials for specific Uris; can be null.
 
Verbosity Verbosity [getset]
 The detail level of messages displayed to the user.
 

Detailed Description

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

Implementations of this interface are thread-safe.

Member Function Documentation

◆ Ask()

bool NanoByte.Common.Tasks.ITaskHandler.Ask ( [Localizable(true)] string  question,
bool?  defaultAnswer = null,
[Localizable(true)] string?  alternateMessage = null 
)

Asks the user a Yes/No/Cancel question.

Parameters
questionThe question and comprehensive information to help the user make an informed decision.
defaultAnswerThe default answer to preselect. May be chosen automatically if the user cannot be asked. null if the user must make the choice themselves.
alternateMessageA message to output with Log.Warn(string) when the defaultAnswer is used instead of asking the user.
Returns
true if the user answered with 'Yes'; false if the user answered with 'No'.
Exceptions
OperationCanceledExceptionThrow if the user answered with 'Cancel'.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase.

◆ Error()

void NanoByte.Common.Tasks.ITaskHandler.Error ( Exception  exception)

Displays an error message to the user.

Parameters
exceptionThe exception representing the error that occurred.

Implemented in NanoByte.Common.Tasks.DialogTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, NanoByte.Common.Tasks.CliTaskHandler, NanoByte.Common.Tasks.SilentTaskHandler, and NanoByte.Common.Tasks.TaskHandlerBase.

◆ Output()

void NanoByte.Common.Tasks.ITaskHandler.Output ( [Localizable(true)] string  title,
[Localizable(true)] string  message 
)

Displays multi-line text to the user.

Parameters
titleA title for the message.
messageThe string to display. Trailing linebreaks are appropriately handled or ignored.

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

Implemented in NanoByte.Common.Tasks.AnsiCliTaskHandler, NanoByte.Common.Tasks.DialogTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, NanoByte.Common.Tasks.CliTaskHandler, NanoByte.Common.Tasks.SilentTaskHandler, and NanoByte.Common.Tasks.TaskHandlerBase.

◆ Output< T >() [1/2]

void NanoByte.Common.Tasks.ITaskHandler.Output< T > ( [Localizable(true)] string  title,
IEnumerable< T >  data 
)

Displays tabular data to the user.

Parameters
titleA title for the data.
dataThe data to display.

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

Implemented in NanoByte.Common.Tasks.AnsiCliTaskHandler, NanoByte.Common.Tasks.DialogTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, and NanoByte.Common.Tasks.TaskHandlerBase.

◆ Output< T >() [2/2]

void NanoByte.Common.Tasks.ITaskHandler.Output< T > ( [Localizable(true)] string  title,
NamedCollection< T >  data 
)

Displays tree-like data to the user.

Parameters
titleA title for the data.INamed
dataThe data to display.

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

Implemented in NanoByte.Common.Tasks.AnsiCliTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, and NanoByte.Common.Tasks.TaskHandlerBase.

Type Constraints
T :INamed 

◆ RunTask()

void NanoByte.Common.Tasks.ITaskHandler.RunTask ( ITask  task)

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

Parameters
taskThe task to be run. (ITask.Run or equivalent is called on it.)
Exceptions
OperationCanceledExceptionThe user canceled the task.
IOExceptionThe task ended with TaskState.IOError.
WebExceptionThe task ended with TaskState.WebError.

Implemented in NanoByte.Common.Tasks.AnsiCliTaskHandler, NanoByte.Common.Tasks.DialogTaskHandler, NanoByte.Common.Tasks.CliTaskHandler, and NanoByte.Common.Tasks.TaskHandlerBase.

Property Documentation

◆ CancellationToken

CancellationToken NanoByte.Common.Tasks.ITaskHandler.CancellationToken
get

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

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


The documentation for this interface was generated from the following file: