AsyncLocal<T> Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents ambient data that is local to a given asynchronous control flow, such as an asynchronous method.
generic <typename T>
public ref class AsyncLocal sealed
public sealed class AsyncLocal<T>
type AsyncLocal<'T> = class
Public NotInheritable Class AsyncLocal(Of T)
Type Parameters
- T
The type of the ambient data.
- Inheritance
-
AsyncLocal<T>
Examples
The following example uses the AsyncLocal<T> class to persist a string value across an asynchronous flow. It also contrasts the use of AsyncLocal<T> with ThreadLocal<T>.
using System;
using System.Threading;
using System.Threading.Tasks;
class Example
{
static AsyncLocal<string> _asyncLocalString = new AsyncLocal<string>();
static ThreadLocal<string> _threadLocalString = new ThreadLocal<string>();
static async Task AsyncMethodA()
{
// Start multiple async method calls, with different AsyncLocal values.
// We also set ThreadLocal values, to demonstrate how the two mechanisms differ.
_asyncLocalString.Value = "Value 1";
_threadLocalString.Value = "Value 1";
var t1 = AsyncMethodB("Value 1");
_asyncLocalString.Value = "Value 2";
_threadLocalString.Value = "Value 2";
var t2 = AsyncMethodB("Value 2");
// Await both calls
await t1;
await t2;
}
static async Task AsyncMethodB(string expectedValue)
{
Console.WriteLine("Entering AsyncMethodB.");
Console.WriteLine(" Expected '{0}', AsyncLocal value is '{1}', ThreadLocal value is '{2}'",
expectedValue, _asyncLocalString.Value, _threadLocalString.Value);
await Task.Delay(100);
Console.WriteLine("Exiting AsyncMethodB.");
Console.WriteLine(" Expected '{0}', got '{1}', ThreadLocal value is '{2}'",
expectedValue, _asyncLocalString.Value, _threadLocalString.Value);
}
static async Task Main(string[] args)
{
await AsyncMethodA();
}
}
// The example displays the following output:
// Entering AsyncMethodB.
// Expected 'Value 1', AsyncLocal value is 'Value 1', ThreadLocal value is 'Value 1'
// Entering AsyncMethodB.
// Expected 'Value 2', AsyncLocal value is 'Value 2', ThreadLocal value is 'Value 2'
// Exiting AsyncMethodB.
// Expected 'Value 2', got 'Value 2', ThreadLocal value is ''
// Exiting AsyncMethodB.
// Expected 'Value 1', got 'Value 1', ThreadLocal value is ''
Imports System.Threading
Imports System.Threading.Tasks
Module Example
Dim _asyncLocalString As New AsyncLocal(Of String)()
Dim _threadLocalString As New ThreadLocal(Of String)()
Async Function AsyncMethodA() As Task
' Start multiple async method calls, with different AsyncLocal values.
' We also set ThreadLocal values, to demonstrate how the two mechanisms differ.
_asyncLocalString.Value = "Value 1"
_threadLocalString.Value = "Value 1"
Dim t1 = AsyncMethodB("Value 1")
_asyncLocalString.Value = "Value 2"
_threadLocalString.Value = "Value 2"
Dim t2 = AsyncMethodB("Value 2")
' Await both calls
await t1
await t2
End Function
Async Function AsyncMethodB(expectedValue As String) As Task
Console.WriteLine("Entering AsyncMethodB.")
Console.WriteLine(" Expected '{0}', AsyncLocal value is '{1}', ThreadLocal value is '{2}'",
expectedValue, _asyncLocalString.Value, _threadLocalString.Value)
await Task.Delay(100)
Console.WriteLine("Exiting AsyncMethodB.")
Console.WriteLine(" Expected '{0}', got '{1}', ThreadLocal value is '{2}'",
expectedValue, _asyncLocalString.Value, _threadLocalString.Value)
End Function
Public Sub Main()
AsyncMethodA.Wait()
End Sub
End Module
' The example displays the following output:
' Entering AsyncMethodB.
' Expected 'Value 1', AsyncLocal value is 'Value 1', ThreadLocal value is 'Value 1'
' Entering AsyncMethodB.
' Expected 'Value 2', AsyncLocal value is 'Value 2', ThreadLocal value is 'Value 2'
' Exiting AsyncMethodB.
' Expected 'Value 2', got 'Value 2', ThreadLocal value is ''
' Exiting AsyncMethodB.
' Expected 'Value 1', got 'Value 1', ThreadLocal value is ''
Remarks
Because the task-based asynchronous programming model tends to abstract the use of threads, AsyncLocal<T> instances can be used to persist data across threads.
The AsyncLocal<T> class also provides optional notifications when the value associated with the current thread changes, either because it was explicitly changed by setting the Value property, or implicitly changed when the thread encountered an await
or other context transition.
Constructors
AsyncLocal<T>() |
Instantiates an AsyncLocal<T> instance that does not receive change notifications. |
AsyncLocal<T>(Action<AsyncLocalValueChangedArgs<T>>) |
Instantiates an AsyncLocal<T> local instance that receives change notifications. |
Properties
Value |
Gets or sets the value of the ambient data. |
Methods
Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
GetType() |
Gets the Type of the current instance. (Inherited from Object) |
MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
ToString() |
Returns a string that represents the current object. (Inherited from Object) |