Guide to the Language

 Custom Async Methods
In order to call a method asynchronously, it has to be wrapped in another 
method that returns a started task. To illustrate, the following method 
defines, starts, and returns a task which takes 2000 milliseconds to execute 
before it returns the letter “Y”. The task is here defined through the use of a 
lambda expression for conciseness.
using System.Threading.Tasks;
using System.Threading;
// ...
Task MyTask()
{
return Task.Run( () => {
Thread.Sleep(2000);
return "Y";
});
}
This task method can be called asynchronously from an async method. 
The naming convention for these methods is to append “Async” to the 
method name. The asynchronous method in this example awaits the result 
of the task and then prints it.
async void MyTaskAsync()
{
string result = await MyTask();
System.Console.Write(result);
}
Chapter 30 asynChronous Methods

---

180
The async method is called in the same way as a regular method, as 
can be seen in the following Main method. The output of the program will 
be “XY”.
static void Main()
{
new MyApp().MyTaskAsync();
System.Console.Write("X");
System.Console.ReadKey();
}
 Extended Return Types
C# 7.0 lessened the restriction on what return types an async method can 
have. This can be useful when an async method returns a constant result 
or is likely to complete synchronously, in which case the extra allocation of 
a Task object may become an undesired performance cost. The condition 
is that the returned type must implement the GetAwaiter method, which 
returns an awaiter object. To make use of this new feature, .NET provides 
the ValueTask type, which is a lightweight value type that includes
this method.
To give an example, the following PowTwo async method gives 
the result of the argument raised to the second power (a
2
). It executes 
synchronously if the argument is less than plus or minus ten and therefore 
returns a ValueTask type in order to not have to allocate a Task 
object in such a case. Note that the Main method here has the async 
modifier. This is allowed as of C# 7.1 and is used for cases like this when 
the Main method calls an async method directly.
using System.Threading.Tasks;
public class MyAsyncValueTask
{
Chapter 30 asynChronous Methods

---

181
static async Task Main()
{
double d = await PowTwo(10);
System.Console.WriteLine(d); // "100"
}
private static async ValueTask PowTwo(double a)
{
if (a < 10 && a > -10) {
return System.Math.Pow(a, 2);
}
return await Task.Run(() => System.Math.Pow(a, 2));
}
}
To use the ValueTask type, you need to add a NuGet package to your 
project. NuGet is a package manager providing free and open source 
extensions to Visual Studio. The package is added by right-clicking 
References in the Solution Explorer and choosing Manage NuGet 
Packages. Switch to the Browse tab and search for “Tasks” to find the 
System.Threading.Tasks.Extensions package. Select this package and
click install.