Understanding Synchronization Context Task.ConfigureAwait In Action

public virtual void Send(SendOrPostCallback d, object state) => d(state);
public virtual void Post(SendOrPostCallback d, object state) => ThreadPool.QueueUserWorkItem(new WaitCallback(d.Invoke), state);

[STAThread]
static void Main() {
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    // SynchronizationContext is still null here
    Debug.Assert(SynchronizationContext.Current == null);
    var frm = new TasksForm();
    // Now SynchronizationContext is installed
    Debug.Assert(SynchronizationContext.Current != null && SynchronizationContext.Current is WindowsFormsSynchronizationContext);
    Application.Run(frm);
}

private void InitializeComponent() {
    this.ResultsListBox = new System.Windows.Forms.ListBox();
    this.RegularThreadsButton = new System.Windows.Forms.Button();
    this.UIThreadTest = new System.Windows.Forms.Button();
    this.SuspendLayout();
    //
    // ResultsListBox
    //
    this.ResultsListBox.FormattingEnabled = true;
    this.ResultsListBox.Location = new System.Drawing.Point(12, 12);
    this.ResultsListBox.Name = "ResultsListBox";
    this.ResultsListBox.Size = new System.Drawing.Size(516, 212);
    this.ResultsListBox.TabIndex = 1;
    //
    // RegularThreadsButton
    //
    this.RegularThreadsButton.Location = new System.Drawing.Point(12, 232);
    this.RegularThreadsButton.Name = "RegularThreadsButton";
    this.RegularThreadsButton.Size = new System.Drawing.Size(516, 23);
    this.RegularThreadsButton.TabIndex = 2;
    this.RegularThreadsButton.Text = "Regular Thread Test";
    this.RegularThreadsButton.UseVisualStyleBackColor = true;
    this.RegularThreadsButton.Click += new System.EventHandler(this.RegularThreadsButton_Click);
    //
    // UIThreadTest
    //
    this.UIThreadTest.Location = new System.Drawing.Point(12, 261);
    this.UIThreadTest.Name = "UIThreadTest";
    this.UIThreadTest.Size = new System.Drawing.Size(516, 23);
    this.UIThreadTest.TabIndex = 3;
    this.UIThreadTest.Text = "UI-Context Thread Test";
    this.UIThreadTest.UseVisualStyleBackColor = true;
    this.UIThreadTest.Click += new System.EventHandler(this.UIThreadTest_Click);
    //
    // ThreadsForm
    //
    this.AutoScaleDimensions = new System.Drawing.SizeF(6 F, 13 F);
    this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
    this.ClientSize = new System.Drawing.Size(540, 294);
    this.Controls.Add(this.UIThreadTest);
    this.Controls.Add(this.RegularThreadsButton);
    this.Controls.Add(this.ResultsListBox);
    this.FormBorderStyle = System.Windows.Forms.FormBorderStyle.FixedSingle;
    this.MaximizeBox = false;
    this.Name = "ThreadsForm";
    this.Text = "SynchronizationContext Sample";
    this.ResumeLayout(false);
}
private System.Windows.Forms.ListBox ResultsListBox;
private System.Windows.Forms.Button RegularThreadsButton;
private System.Windows.Forms.Button UIThreadTest;

private void RegularThreadsButton_Click(object sender, EventArgs e) {
    RunThreads(null);
}
private void UIThreadTest_Click(object sender, EventArgs e) {
    // SynchronizationContext.Current will return a reference to WindowsFormsSynchronizationContext
    RunThreads(SynchronizationContext.Current);
}
private void RunThreads(SynchronizationContext context) {
    this.ResultsListBox.Items.Clear();
    this.ResultsListBox.Items.Add($ "UI Thread {Thread.CurrentThread.ManagedThreadId}");
    this.ResultsListBox.Items.Clear();
    int maxThreads = 3;
    for (int i = 0; i < maxThreads; i++) {
        Thread t = new Thread(UpdateListBox);
        t.IsBackground = true;
        t.Start(context); // passing context to thread proc
    }
}
private void UpdateListBox(object state) {
    // fetching passed SynchrnozationContext
    SynchronizationContext syncContext = state as SynchronizationContext;
    // get thread ID
    var threadId = Thread.CurrentThread.ManagedThreadId;
    if (null == syncContext) // no SynchronizationContext provided
        this.ResultsListBox.Items.Add($ "Hello from thread {threadId}, currently executing thread is {Thread.CurrentThread.ManagedThreadId}");
    else syncContext.Send((obj) => this.ResultsListBox.Items.Add($ "Hello from thread {threadId}, currently executing thread is {Thread.CurrentThread.ManagedThreadId}"), null);
}

Control.CheckForIllegalCrossThreadCalls = true;

Let us dig into more details of the above illustration. await does not just wait for the worker thread to finish! Roughly what happens is that await captures the current synchronization context before performing the asynchronous task (leaving the current synchronization context.) After the asynchronous task returns, it references the original synchronization context again (re-entering the synchronization context) and the rest of the method continuous.

Let us see this in action. Fire a new project or add a new form to the existing project. Go to the designer code of the new form and update it to match the following,

private void InitializeComponent() {
    this.ResultsListBox = new System.Windows.Forms.ListBox();
    this.NoContextButton = new System.Windows.Forms.Button();
    this.UIContextButton = new System.Windows.Forms.Button();
    this.SuspendLayout();
    //
    // ResultsListBox
    //
    this.ResultsListBox.FormattingEnabled = true;
    this.ResultsListBox.Location = new System.Drawing.Point(13, 13);
    this.ResultsListBox.Name = "ResultsListBox";
    this.ResultsListBox.Size = new System.Drawing.Size(429, 264);
    this.ResultsListBox.TabIndex = 0;
    //
    // NoContextButton
    //
    this.NoContextButton.Location = new System.Drawing.Point(13, 284);
    this.NoContextButton.Name = "NoContextButton";
    this.NoContextButton.Size = new System.Drawing.Size(429, 23);
    this.NoContextButton.TabIndex = 1;
    this.NoContextButton.Text = "Task without Synchronization Context";
    this.NoContextButton.UseVisualStyleBackColor = true;
    this.NoContextButton.Click += new System.EventHandler(this.NoContextButton_Click);
    //
    // UIContextButton
    //
    this.UIContextButton.Location = new System.Drawing.Point(13, 313);
    this.UIContextButton.Name = "UIContextButton";
    this.UIContextButton.Size = new System.Drawing.Size(429, 23);
    this.UIContextButton.TabIndex = 2;
    this.UIContextButton.Text = "Task with UI Synchronization Context";
    this.UIContextButton.UseVisualStyleBackColor = true;
    this.UIContextButton.Click += new System.EventHandler(this.UIContextButton_Click);
    //
    // TasksForm
    //
    this.AutoScaleDimensions = new System.Drawing.SizeF(6 F, 13 F);
    this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
    this.ClientSize = new System.Drawing.Size(454, 345);
    this.Controls.Add(this.UIContextButton);
    this.Controls.Add(this.NoContextButton);
    this.Controls.Add(this.ResultsListBox);
    this.FormBorderStyle = System.Windows.Forms.FormBorderStyle.FixedSingle;
    this.MaximizeBox = false;
    this.Name = "TasksForm";
    this.Text = "TasksForm";
    this.ResumeLayout(false);
}
private System.Windows.Forms.ListBox ResultsListBox;
private System.Windows.Forms.Button NoContextButton;
private System.Windows.Forms.Button UIContextButton;

Now, go to the form code and add the following,

private void NoContextButton_Click(object sender, EventArgs e) {
    RunTask(null);
}
private void UIContextButton_Click(object sender, EventArgs e) {
    RunTask(SynchronizationContext.Current);
}
private void RunTask(SynchronizationContext context) {
    this.ResultsListBox.Items.Clear();
    this.ResultsListBox.Items.Add($ "UI Thread {Thread.CurrentThread.ManagedThreadId}");
    Task.Run(async () => {
        if (null != context) SynchronizationContext.SetSynchronizationContext(context);
        LogMessage($ "Task started");
        if (null == SynchronizationContext.Current) LogMessage($ "Task synchronization context is null");
        else LogMessage($ "Task synchronization context is {SynchronizationContext.Current.GetType().Name}");
        await Task.Delay(1000);
        LogMessage($ "Task thread is {Thread.CurrentThread.ManagedThreadId}");
        LogMessage($ "Control.InvokeRequired = {this.ResultsListBox.InvokeRequired}");
        LogMessage($ "Trying to manipulate UI...");
        try {
            this.ResultsListBox.Items.Add("Successfully accessed UI directly!");
        } catch (InvalidOperationException) {
            LogMessage($ "Failed!");
        }
        LogMessage($ "Task finished");
    });
}
private void LogMessage(string msg) {
    this.ResultsListBox.Invoke((Action)(() => {
        this.ResultsListBox.Items.Add(msg);
    }));
}

The above code simply has two options, one that does not set the synchronization context of the task, leaving it null, and one sets it to the synchronization context of the UI thread. The code awaits a task and tests UI accessibility from the current thread. When we run the application and hit the no-context button, we get the following results,

The code after await is running in a different thread, and it failed to access the controls directly. Now, hit the UI-context button and see the results,

The second option simply sets the synchronization context to the UI-thread synchronization context using a call to SynchronizationContext.SetSynchronizationContext(). And that affected our behavior, when we called await it captured the current synchronization context (which is WinFormsSynchronizationContext), then left the current context to the task given and waited for its completion. After the completion of the task, it re-entered the current context again, and you have been able to access the UI controls using the UI thread without any delegates or callbacks.

A little note here, you might ask yourself why we had to use SetSynchronizationContext()?! Isn’t await supposed to capture the synchronization context automatically? Yes, it is. But as we are running in the context of a new task (we used Task.Run()), it does not have a synchronization context. By default, worker tasks and threads do not have a synchronization context (you can investigate this by checking SynchronizationContext.Current.) That is why we had to reference the UI context first before our call to Task.Run() then we had to set it using SetSynchronizationContext(). In promise-style tasks and outside Task.Run() you may use the ConfigureAwait() option, explained in a moment.

ConfigureAwait in Action

One of the core concepts of synchronization context is context switching. It is what happens when you await a task. You capture the current context before awaiting the task, leaving it to the task context, then recovering (re-entering) it back when the task completes. This process is highly expensive and in many scenarios, you do not need it! As an example, if you are not handling UI-controls after the task, why switching to the original context again? Why don’t you save time and avoid this round?

The rule of thumb says that if you are developing a library, or you do not need access to the UI controls, or you can reference synchronization data (like HttpContext.Current) for later usage, save your time and effort and disable context switching.

Here comes Task.ConfigureAwait() in handy. It has a single parameter, continueOnCapturedContext, which enables context recovering if set to true (default behavior if ConfigureAwait() is not used) or disables it when set to false.

Let us see this in action.

ConfigureAwait in WinForms

Fire a new WinForms project or add a new form to the existing one. Switch to the form designer code and update it to match the following,

private void InitializeComponent() {
    this.ResultsListBox = new System.Windows.Forms.ListBox();
    this.ConfigureTrueButton = new System.Windows.Forms.Button();
    this.ConfigureFalseButton = new System.Windows.Forms.Button();
    this.SuspendLayout();
    //
    // ResultsListBox
    //
    this.ResultsListBox.FormattingEnabled = true;
    this.ResultsListBox.Location = new System.Drawing.Point(12, 12);
    this.ResultsListBox.Name = "ResultsListBox";
    this.ResultsListBox.Size = new System.Drawing.Size(517, 342);
    this.ResultsListBox.TabIndex = 0;
    //
    // ConfigureTrueButton
    //
    this.ConfigureTrueButton.Location = new System.Drawing.Point(12, 357);
    this.ConfigureTrueButton.Name = "ConfigureTrueButton";
    this.ConfigureTrueButton.Size = new System.Drawing.Size(516, 23);
    this.ConfigureTrueButton.TabIndex = 1;
    this.ConfigureTrueButton.Text = "Task.ConfigureAwait(true) Test";
    this.ConfigureTrueButton.UseVisualStyleBackColor = true;
    this.ConfigureTrueButton.Click += new System.EventHandler(this.ConfigureTrueButton_Click);
    //
    // ConfigureFalseButton
    //
    this.ConfigureFalseButton.Location = new System.Drawing.Point(12, 386);
    this.ConfigureFalseButton.Name = "ConfigureFalseButton";
    this.ConfigureFalseButton.Size = new System.Drawing.Size(516, 23);
    this.ConfigureFalseButton.TabIndex = 2;
    this.ConfigureFalseButton.Text = "Task.ConfigureAwait(false) Test";
    this.ConfigureFalseButton.UseVisualStyleBackColor = true;
    this.ConfigureFalseButton.Click += new System.EventHandler(this.ConfigureFalseButton_Click);
    //
    // ConfigureAwaitForm
    //
    this.AutoScaleDimensions = new System.Drawing.SizeF(6 F, 13 F);
    this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
    this.ClientSize = new System.Drawing.Size(541, 421);
    this.Controls.Add(this.ConfigureFalseButton);
    this.Controls.Add(this.ConfigureTrueButton);
    this.Controls.Add(this.ResultsListBox);
    this.FormBorderStyle = System.Windows.Forms.FormBorderStyle.FixedSingle;
    this.MaximizeBox = false;
    this.Name = "ConfigureAwaitForm";
    this.Text = "Task.ConfigureAwait Sample";
    this.ResumeLayout(false);
}
private System.Windows.Forms.ListBox ResultsListBox;
private System.Windows.Forms.Button ConfigureTrueButton;
private System.Windows.Forms.Button ConfigureFalseButton;

Now switch to the form code and add the following,

private void ConfigureTrueButton_Click(object sender, EventArgs e) {
    AsyncTest(true);
}
private void ConfigureFalseButton_Click(object sender, EventArgs e) {
    AsyncTest(false);
}
private async void AsyncTest(bool configureAwait) {
    this.ResultsListBox.Items.Clear();
    try {
        Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("ar-EG");
        this.ResultsListBox.Items.Add("Async test started");
        this.ResultsListBox.Items.Add(string.Format("configureAwait = {0}", configureAwait));
        this.ResultsListBox.Items.Add(string.Format("Current thread ID = {0}", Thread.CurrentThread.ManagedThreadId));
        this.ResultsListBox.Items.Add(string.Format("Current culture = {0}", Thread.CurrentThread.CurrentCulture));
        this.ResultsListBox.Items.Add("Awaiting a task...");
        await Task.Delay(500).ConfigureAwait(configureAwait);
        this.ResultsListBox.Items.Add("Task completed");
        this.ResultsListBox.Items.Add(string.Format("Current thread ID: {0}", Thread.CurrentThread.ManagedThreadId));
        this.ResultsListBox.Items.Add(string.Format("Current culture: {0}", Thread.CurrentThread.CurrentCulture));
    } catch (InvalidOperationException ex) {
        var threadId = Thread.CurrentThread.ManagedThreadId;
        this.ResultsListBox.BeginInvoke((Action)(() => {
            this.ResultsListBox.Items.Add($ "{ex.GetType().Name} caught from thread {threadId}");
        }));
    }
}

The code simply awaits a task and switches ConfigureAwait() based on the button clicked. It also changes the cultural information of the current thread before the switch. Run the form and click the “ConfigureAwait(true)” button.

The behavior is as expected. We recovered the original synchronization context, we preserved thread environment data like culture, and we were able to access UI controls directly with ease.

Now hit the “ConfigureAwait(false)” button and see the results,

When setting ConfigureAwait.continueOnCapturedContext to false, we were not able to return to the original context, we also received an InvalidOperationException error due to cross-thread access.

ConfigureAwait in ASP.NET MVC

Fire a new MVC project, and update index.cshtml file to match the following,

@model IEnumerable<String>

@if (null != Model && Model.Any())
{
  <ul>
    @foreach (var val in Model)
    {
      <li>@val</li>
    }
  </ul>
}

Now, go to the Home controller and add the following code,

private List < string > results = new List < string > ();
public async Task < ActionResult > Index(bool configureAwait = false) {
    await AsyncTest(configureAwait);
    return View(results);
}
private async Task AsyncTest(bool configureAwait) {
    results.Add($ "Async test started, ConfigureAwait = {configureAwait}");
    if (null == System.Web.HttpContext.Current) results.Add($ "HttpContext.Current is null");
    else results.Add($ "HttpContext.Current is NOT null");
    results.Add($ "Current thread ID = {Thread.CurrentThread.ManagedThreadId}");
    results.Add("Awaiting task...");
    await Task.Delay(1000).ConfigureAwait(configureAwait);
    results.Add("Task completed");
    results.Add($ "Current thread ID = {Thread.CurrentThread.ManagedThreadId}");
    if (null == System.Web.HttpContext.Current) results.Add($ "HttpContext.Current is null");
    else results.Add($ "HttpContext.Current is NOT null");
}

Run the app and examine the difference between the two scenarios.

You can now see that when setting ConfigureAwait.continueOnCapturedContext to false, the original synchronization context is not recovered, and we lost access to HttpContext.Current. On the other hand, when set to true, we recover the original synchronization context, and we gain access to HttpContext.Current. Note that switching to the original thread is non-relevant here, as there is no UI thread in ASP.NET, unlike desktop apps.

Final Note

We can sum up all the above in two points:

• For better performance, use ConfigureAwait(false) when in the library or when you do not need to access UI elements after await.
• Use SynchronizationContext.Set() when you need to recapture the original context in a thread scenario.

Finally, I hope I was able to simplify things and demonstrate various aspects of the synchronization context. Please feel free to share with me your thoughts and your feedback.

Code is available on GitHub.