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.
This commit is contained in:
Christian Coffey
2019-02-24 21:03:33 -05:00
committed by Christopher McCormack
parent 97834c64d2
commit 145a94f192

View File

@ -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<T>` 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<T>` 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). The core of the `async` and `await` are the `Task<T>` 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<T>` 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<string> DoSomethingAsync()
{
/* Async code containing the 'await' keyword.
This method will return a string as denoted by Task<string> 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) 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)