From 145a94f192879d6226f9f0a66a8521013162ab6c Mon Sep 17 00:00:00 2001 From: Christian Coffey <31052077+ccoffey1@users.noreply.github.com> Date: Sun, 24 Feb 2019 21:03:33 -0500 Subject: [PATCH] Update index.md (#30085) Removed an unnecessary example as well as changed the description for the usage of the 'await' keyword. Also added an example for async method declarations. --- guide/english/csharp/async-await/index.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/guide/english/csharp/async-await/index.md b/guide/english/csharp/async-await/index.md index 6d0266a26e..8d493b78f1 100644 --- a/guide/english/csharp/async-await/index.md +++ b/guide/english/csharp/async-await/index.md @@ -8,7 +8,17 @@ The `async`/`await` keywords in C# provide convenient ways of managing resource- The core of the `async` and `await` are the `Task` class. When using it along with the `async` keyword as the return type of a method, we indicate that the method has promised to return an object of the `T` type (for methods that wouldn't return any value, use `Task` as the return type instead). `Task` is a sophisticated topic of its own, for more information, please refer to the official documents: [Task Class](https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task?view=netframework-4.7.1). -Once encountering `async` methods, the work will be queued in a thread-pool for execution, while the caller will continue its execution without waiting on the return values from the `async` methods. However, in most occasions, our UI and service rely on the values returned from the `async` methods: for example, when we query a local database using the `async` methods, we would eventually want to know what are the query results and act on them, synchronously. This is where the `await` keyword shall be used: if using the `await` keyword when invoking an `async` method, the caller will pause the execution until a result is returned from the `async` method, and meanwhile, the parent method will continue execution without waiting on the caller to finish. With that said, any method that uses `await` keyword have to be an `async` function itself -- this is enforced by the C# compiler as well, if using Visual Studio to write your C# code, the IDE will warn you if a method violate the `async-await` contract. +Once encountering `async` methods, the work will be queued in a thread-pool for execution, while the caller will continue its execution without waiting on return values. However, in most cases our UI and service rely on the values returned from asychronous method calls. This is where the `await` keyword comes in. If an asynchronous method call is preceded by the `await` keyword, control will then be returned to the parent method while the result from that asynchronous method is being computed. Additionally, any methods that contain the `await` keyword must be `async` methods themselves, which is enforced by the compiler. Such a method is declared with the access control modifier followed by async and finally the return type, as in: + +```csharp + public async Task DoSomethingAsync() + { + /* Async code containing the 'await' keyword. + This method will return a string as denoted by Task above. */ + } +``` + +**Note that it is convention in C# for an asynchronous method such as `DoSomethingAsync()` to contain `Async` at the end of its name.** To learn more about using the promise model to handle asynchrony, check out this Wikipedia page: [Achieving Asynchrony through Promises](https://en.wikipedia.org/wiki/Futures_and_promises)