User Guide |
This library provides improved support for writing asynchronous code targeting the .NET Framework 3.5 and newer. Additional information and links to project resources are located on the Welcome page.
The basic features of this library can be described as the following.
Extensions and utilities for legacy code: These extension methods provide select features which were added to the Task Parallel Library in .NET 4.5 as extension methods and static utility methods for .NET 3.5 and .NET 4.0 users.
Extensions for task continuations: These extension methods allow developers to write task continuations in asynchronous code that behave in similarly to / while maintaining support for .NET 3.5 and .NET 4.0.
Task building blocks: These utility methods allow developers to write efficient asynchronous code using high-level block constructs that resemble the methods produced by the keyword while maintaining support for .NET 3.5 and .NET 4.0.
The .NET Framework 4.5 introduces several new methods to simplify the use of the Task Parallel Library in common scenarios. This library provides extension methods and static utility methods for some of the most frequently used cases, allowing use of the functionality in .NET 3.5 and .NET 4.0. These methods are provided by the following classes.
CancellationTokenSourceExtensions: This class provides the CancelAfter(CancellationTokenSource, TimeSpan) extension method, allowing the use of this feature prior to the introduction of CancelAfter in .NET 4.5.
CompletedTask: This class provides static methods and properties for cases where code needs to return a Task which has already entered a completed state (either successfully or canceled).
DelayedTask: This class provides static methods to simplify the creation of tasks which represent a fixed delay or an operation to wait on one or more other tasks to complete.
Delay: These methods create tasks which complete after a specified delay period. Their implementation is intended to match the behavior of the Delay methods which were introduced in .NET 4.5.
WhenAll: These methods create tasks which complete after all of the specified antecedent tasks complete. Their implementation is intended to match the behavior of the WhenAll methods which were introduced in .NET 4.5.
WhenAny: These methods create tasks which complete after any of the specified antecedent tasks complete. Their implementation is intended to match the behavior of the WhenAny methods which were introduced in .NET 4.5.
StreamExtensions: This class introduces extension methods to support asynchronous operations on Stream instances, prior to the introduction of asynchronous methods for this class in .NET 4.5.
WebRequestExtensions: This class provides extension methods which offer extensive support for using WebRequest in asynchronous code, including support for both CancellationToken and traditional timeouts.
The ContinueWith methods provide comprehensive options for writing task continuations, but introduce a number of concerns regarding faulted and canceled tasks. Developers must also be careful regarding the use of the Unwrap method. While the / keywords introduced in C# 5 (and similar keywords in other select programming languages) provide a cleaner development experience, they are not available for users of earlier versions of the language and/or framework. This library provides extension methods to simplify the creation of efficient, "well-behaved" task continuations without requiring the use of /.
Each of the extension methods provided by this library is implemented in a manner that propagates exceptions and/or cancellation closely matching the behavior of code written with /. In particular, care is taken to not wrap single exceptions inside multiple layers of AggregateException.
Select: This extension method is intended for cases where code needs to run in-line following the completion of another task (called the antecedent task).
Then: This extension method is intended for cases where another Task needs to run following the completion of an antecedent task. The extension method automatically calls Unwrap, providing an experience similar to using the keyword on the call.
Catch: This extension method is intended for cases where exception handling code needs to run after an antecedent task is faulted or was canceled. Much like a catch block in code, this method does change the behavior of the antecedent task if it completed successfully, or if the exception it produced does not match the exception type handled by this method. If the catch method does execute, its result is used in place of the result of the antecedent task.
Finally: This extension method is intended for cases where cleanup code needs to run following the completion of an antecedent task, regardless of whether the antecedent succeeded, faulted, or was canceled. Much like a finally block in code, this method does not alter the result provided by the antecedent task unless an exception is thrown within the finally block itself.
ObserveExceptionsTTask(TTask): This extension method ensures the exception for a faulted task is "observed", i.e. the Exception property will be accessed if the task enters the Faulted state.
Task building blocks provide support for block-level programming constructs in asynchronous code. The resulting execution resembles the behavior of the state machines created by the C# compiler to support the / keywords, but does not depend on these features being available. As a result, .NET 3.5 and .NET 4.0 developers can enjoy clean, efficient asynchronous code.
The following blocks are currently supported by this library.
While: These methods create tasks which operate in a similar manner to a while block written in an method (for languages which support /.
Using: These methods create tasks which operate in a similar manner to a using block written in an method (for languages which support /. These methods expand on the using statement provided by C# by implementing support for IAsyncDisposable as described in IAsyncDisposable, using statements, and async/await.