I have a WPF GUI, where I want to press a button to start a long task without freezing the window for the duration of the task. While the task is running I would like to get reports on progress, and I would like to incorporate another button that will stop the task at any time I choose.
I cannot figure the correct way to use async/await/task. I can't include everything I've tried, but this is what I have at the moment.
A WPF window class :
public partial class MainWindow : Window
{
readonly otherClass _burnBabyBurn = new OtherClass();
internal bool StopWorking = false;
//A button method to start the long running method
private async void Button_Click_3(object sender, RoutedEventArgs e)
{
Task slowBurn = _burnBabyBurn.ExecuteLongProcedureAsync(this, intParam1, intParam2, intParam3);
await slowBurn;
}
//A button Method to interrupt and stop the long running method
private void StopButton_Click(object sender, RoutedEventArgs e)
{
StopWorking = true;
}
//A method to allow the worker method to call back and update the gui
internal void UpdateWindow(string message)
{
TextBox1.Text = message;
}
}
And a class for the worker method:
class OtherClass
{
internal Task ExecuteLongProcedureAsync(MainWindow gui, int param1, int param2, int param3)
{
var tcs = new TaskCompletionSource<int>();
//Start doing work
gui.UpdateWindow("Work Started");
While(stillWorking)
{
//Mid procedure progress report
gui.UpdateWindow("Bath water n% thrown out");
if (gui.StopTraining) return tcs.Task;
}
//Exit message
gui.UpdateWindow("Done and Done");
return tcs.Task;
}
}
This runs, but the WPF function window is still blocked once the worker method starts.
I need to know how to arrange the async/await/task declarations to allow
A) the worker method to not block the gui window
B) let the worker method update the gui window
C) allow the gui window to stop interrupt and stop the worker method
Any help or pointers are much appreciated.
Long story short:
private async void ButtonClick(object sender, RoutedEventArgs e)
{
// modify UI object in UI thread
txt.Text = "started";
// run a method in another thread
await HeavyMethod(txt);
// <<method execution is finished here>>
// modify UI object in UI thread
txt.Text = "done";
}
// This is a thread-safe method. You can run it in any thread
internal async Task HeavyMethod(TextBox textBox)
{
while (stillWorking)
{
textBox.Dispatcher.Invoke(() =>
{
// UI operation goes inside of Invoke
textBox.Text += ".";
// Note that:
// Dispatcher.Invoke() blocks the UI thread anyway
// but without it you can't modify UI objects from another thread
});
// CPU-bound or I/O-bound operation goes outside of Invoke
// await won't block UI thread, unless it's run in a synchronous context
await Task.Delay(51);
}
}
Result:
started....................done
You need to know about (1) how to write async
code and (2) how to run UI operations in another thread.
async
and await
:You can only await
in an async
method.
You can only await
an awaitable
object (i.e. Task
, Task<T>
or ValueTask<T>
etc)
The return type of an async
method is wrapped in a Task
and await
unwraps it. (see Wrapping and Unwrapping section)
Task.Run
usually queues a Task
in the thread pool
(i.e. it uses an existing thread or creates a new thread in the thread pool to run the task. Unless it's a pure operation)
The execution waits at await
for the task to finish and returns back its results, without blocking the main thread because of the magic:
The magic of async-await
is that it uses a state-machine to let the compiler give up and take back the control over the awaited Task
in an async
method.
(i.e. async
method does not run in another thread. async
and await
by themselves don't have anything to do with thread creation.)
Don't confuse the method with
async
keyword with the method wrapped within aTask
; TheTask
is responsible for threading, theasync
is responsible for the magic
So
By putting async
in the method signature you tell the compiler to use state machine to call this method (no threading so far). Then by running a Task
you use a thread to call the method inside the task. And by await
ing the task you prevent the execution flow to move past the await
line without blocking UI thread.
The event handler looks like the code below.
Two possible cases for presense of async in the signature of ExecuteLongProcedure
(case 1 and 2) and MyButton_Click
(case A and B) are explained:
private async void MyButton_Click(object sender, RoutedEventArgs e)
{
//queue a task to run on threadpool
// 1. if ExecuteLongProcedure is a normal method and returns void
Task task = Task.Run(()=>
ExecuteLongProcedure(this, intParam1, intParam2, intParam3)
);
// or
// 2. if ExecuteLongProcedure is an async method and returns Task
Task task = ExecuteLongProcedureAsync(this, intParam1, intParam2, intParam3);
// either way ExecuteLongProcedure is running asynchronously here
// the method will exit if you don't wait for the Task to finish
// A. wait without blocking the main thread
// -> requires MyButton_Click to be async
await task;
// or
// B. wait and block the thread (NOT RECOMMENDED AT ALL)
// -> does not require MyButton_Click to be async
task.Wait();
}
This is very important to know. Suppose you have the following declaration:
private async ReturnType Method() { ... }
If ReturnType
is void
you can't await
it
await Method();
, you will get a compile error saying cannot await void.Method();
and then go on with your life.Method
execution will be synchronous, however since it has async
it will allow you to take advantage of the magic, i.e. you can write await task
within the method to control the flow of execution.void
.If ReturnType
is Task
then await Method();
returns void
If ReturnType
is Task<T>
then await Method();
returns a value of type T
The return type of an async method must be
void
,Task
,Task<T>
, a task-like type,IAsyncEnumerable<T>
, orIAsyncEnumerator<T>
You might want to scroll down to WPF GUI section if you don't want to learn more!
async
methods wrap their return values in a Task
.
E.g., this method wraps a Task
around an int
and returns it:
// async Task<int>
private async Task<int> GetOneAsync()
{
int val = await CalculateStuff();
return val;
// returns an integer
}
To retrieve or unwrap the value which is wrapped inside a Task<>
:
await
task.Result
or task.GetAwaiter().GetResult()
or task.WaitAndUnwrapException()
or read How to call asynchronous method from synchronous method in C#?e.g. await
unwraps the int
out of the Task
:
Task<int> task = GetOneAsync();
int number = await task;
//int <- Task<int>
private Task<int> GetNumber()
{
Task<int> task;
task = Task.FromResult(1); // the correct way to wrap a quasi-atomic operation, the method GetNumber is not async
task = Task.Run(() => 1); // not the best way to wrap a number
return task;
}
private async Task<int> GetNumberAsync()
{
int number = await Task.Run(GetNumber); // unwrap int from Task<int>
// bad practices:
// int number = Task.Run(GetNumber).GetAwaiter().GetResult(); // sync over async
// int number = Task.Run(GetNumber).Result; // sync over async
// int number = Task.Run(GetNumber).Wait(); // sync over async
return number; // wrap int in Task<int>
}
Still confused? Read async return types on MSDN.
To unwrap a task result, Always try to use
await
instead of.Result
otherwise there will be no asynchronous benefit but only asynchronous disadvantages. The latter is called "sync over async".
await
is a asynchronous and is different from task.Wait()
which is synchronous. But they both do the same thing which is waiting for the task to finish.
await
is a asynchronous and is different from task.Result
which is synchronous. But they both do the same thing which is waiting for the task to finish and unwrapping and returning back the results.
To have a wrapped value, you can always use Task.FromResult(1)
instead of creating a new thread by using Task.Run(() => 1)
.
Task.Run
is newer (.NetFX4.5) and simpler version of Task.Factory.StartNew
Simply postfix the name of the method with the async
keyword with Async
.
Since avoiding async void
methods is a good practice (see patterns below), you can say only Task
returning methods should be postfixed with Async
.
The purpose of this convention is to make sure the Asynchronous Virality is respected.
This is where I explain how to run UI operations in another thread.
First thing you need to know about WPF async event handlers is that the Dispatcher
will provide a synchronization context. Explained here
CPU-bound or IO-bound operations such as Sleep
and task.Wait()
will block and consume the thread even if they are called in a method with async
keyword. but await Task.Delay()
tells the state-machine to stop the flow of execution on the thread so it does not consume it; meaning that the thread resources can be used elsewhere:
private async void Button_Click(object sender, RoutedEventArgs e)
{
Thread.Sleep(1000);//stops, blocks and consumes threadpool resources
await Task.Delay(1000);//stops without consuming threadpool resources
Task.Run(() => Thread.Sleep(1000));//does not stop but consumes threadpool resources
await Task.Run(() => Thread.Sleep(1000));//literally the WORST thing to do
}
If you have to access GUI asynchronously (inside ExecuteLongProcedure
method), invoke any operation which involves modification to any non-thread-safe object. For instance, any WPF GUI object must be invoked using a Dispatcher
object which is associated with the GUI thread:
void UpdateWindow(string text)
{
//safe call
Dispatcher.Invoke(() =>
{
txt.Text += text;
});
}
However, If a task is started as a result of a property changed callback from the ViewModel, there is no need to use Dispatcher.Invoke
because the callback is actually executed from the UI thread.
Accessing collections on non-UI Threads
WPF enables you to access and modify data collections on threads other than the one that created the collection. This enables you to use a background thread to receive data from an external source, such as a database, and display the data on the UI thread. By using another thread to modify the collection, your user interface remains responsive to user interaction.
Value changes fired by INotifyPropertyChanged are automatically marshalled back onto the dispatcher.
How to enable cross-thread access
Remember, async
method itself runs on the main thread. So this is valid:
private async void MyButton_Click(object sender, RoutedEventArgs e)
{
txt.Text = "starting"; // UI Thread
await Task.Run(()=> ExecuteLongProcedure1());
txt.Text = "waiting"; // UI Thread
await Task.Run(()=> ExecuteLongProcedure2());
txt.Text = "finished"; // UI Thread
}
Another way to invoke UI operations from UI thread is to use SynchronizationContext
as described here. SynchronizationContext
is a stronger abstraction than Dispatcher
and it's cross-platform.
var uiContext = SynchronizationContext.Current;
while (stillWorking)
{
uiContext.Post(o =>
{
textBox.Text += ".";
}, null);
await Task.Delay(51);
}
Fire and forget pattern:
For obvious reasons this is how your WPF GUI event handlers such as Button_Click
are called.
void Do()
{
// CPU-Bound or IO-Bound operations
}
async void DoAsync() // returns void
{
await Task.Run(Do);
}
void FireAndForget() // not blocks, not waits
{
DoAsync();
}
Fire and observe:
Task-returning methods are better since unhandled exceptions trigger the TaskScheduler.UnobservedTaskException
.
void Do()
{
// CPU-Bound or IO-Bound operations
}
async Task DoAsync() // returns Task
{
await Task.Run(Do);
}
void FireAndWait() // not blocks, not waits
{
Task.Run(DoAsync);
}
Fire and wait synchronously while wasting thread resources:
This is known as Sync over async, it is a synchronous operation but it uses more than one thread which may cause starvation. This happens when you call Wait()
or try to read results directly from task.Result
before the task is finished.
(AVOID THIS PATTERN)
void Do()
{
// CPU-Bound or IO-Bound operations
}
async Task DoAsync() // returns Task
{
await Task.Run(Do);
}
void FireAndWait() // blocks, waits and uses 2 more threads. Yikes!
{
var task = Task.Run(DoAsync);
task.Wait();
}
No. There is a lot more to learn about async
, its context and its continuation. This blogpost is especially recommended.
Not necessarily. Read this answer to know more about the true face of async
.
Stephen Cleary has explained async-await
perfectly. He also explains in his other blog post when there is no thread involved.
how-to-call-asynchronous-method-from-synchronous-method
async await
- Behind the scenes
Make sure you know the difference between Asynchronous, Parallel and Concurrent.
You may also read a simple asynchronous file writer to know where you should concurrent.
Investigate concurrent namespace
Ultimately, read this e-book: Patterns_of_Parallel_Programming_CSharp