Introduction to Async and Await in C# 5.0

All of the code necessary for this example is contained in the Program.cs file; there is a single Task return type async method called by main. The async method is static as well. The code is fully commented so you can follow along by reading those comments.

The main method calls a Task return type async method entitled, "GetGlobalWeatherCities" that accepts a country name as its required argument. Once the async method is called, note that we can check the status of the operation (amongst other things). Note also that we can press on with the main thread whilst the async method executes; this is illustrated by printing out some nonsense characters to the console window after calling the method.

When looking over the following code, notice too that the error handling was placed into the async method, as with void returning async methods, it is best to handle any errors in the method itself although with the task return type we can monitor and control the thread from main.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace AsyncAwait_4
{
    class Program
    {
        static void Main(string[] args)
        {
            // tell the user we are going to list available cities
            Console.WriteLine("List of Available Cities");
            // create a task and assign it to the async call
            Task t = GetGlobalWeatherCities("France");
            //, unlike void, since we have a return type of task, we can do things   
            // with it like check the status of the operation or wait for the task.   
            Console.WriteLine("Status: " + t.Status.ToString());
            // To prove the main thread continues after the call, write some  
            // nonsense out the screen whilst the thread runs   
            WasteTime();
            // hold the console open   
            Console.ReadLine();
        }

        /// <summary>
        /// Async call to retrieve a collection of cities available for   
        /// weather reports
        /// </summary>
        /// <param name="country"></param>
        /// <returns></returns>
        static async Task GetGlobalWeatherCities(string country)
        {
            try
            {
                // create an instance of the client
                GlobalWeather.GlobalWeatherSoapClient client = 
                    new GlobalWeather.GlobalWeatherSoapClient();
                // set up a variable to hold the result and use await to hold for the service   
                // to populate it before pressing on with the task   
                string cities = await client.GetCitiesByCountryAsync(country);
                // once the string variable is populated, print it out to the console   
                Console.WriteLine(cities);
            }
            catch (Exception ex)
            {
                // best to handle the exception here if one is encountered   
                Console.WriteLine("Error: " + ex.Message);
            }
        }

        /// <summary>
        /// Waste time drawing out some trash to the   
        /// console whilst the async method runs out  
        /// </summary>
        static void WasteTime()
        {
            for (int i = 0; i < 50; i++)
            {
                if (i % 2 == 0)
                    Console.Write("-");
                else
                    Console.Write("|");
            }
            Console.WriteLine();
        }
    }
}

Figure 2. Console Output for Example 2

Example 3. Task<T> Returning Methods

In this example, the main thread will make a call to an async method with a Task<T> return type. In this example, an async method will be used to call a web service to fetch a weather report and display it to a console window. As in the other examples, the web service used in this example can be found here.

All of the code necessary for this example is contained in the Program.cs file; there is a single Task<T> return type async method called by main. The async method is static as well. The code is fully commented so you can follow along with it by reading those comments.

The main method calls a Task<T> return type async method entitled, "GetGlobalWeather" that accepts a city name and a country name as its required arguments. Once the async method is called, note that we can check the status of the operation as we could with the Task return type. Note also that we can press on with the main thread whilst the async method executes; this is illustrated by printing a date string and a line separator to the console window after calling the method. The Task<T> return type async calls will block on the line that actually handles the returned value, in this case, a string containing a weather report.

When looking over the following code, notice that the error handling was placed into Main, a departure from how we handled errors on void and Task-returning async methods, you may still handle the errors in the async method if you'd like to do that, but you don't need to if you'd rather not.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace AsyncAwait_3
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                Console.WriteLine("Fetching Current Edinburgh Weather");
                // wx is a placeholder that will be populated through the synchronization context once the method returns
                Task<string> wx = GetGlobalWeather("Edinburgh", "United Kingdom");
                // display the status of the task
                Console.WriteLine("Task Status: " + wx.Status.ToString());
                // even though we called the service, this will execute concurrently whilst the async call is in play
                // and so the date will be displayed before the weather report
                Console.WriteLine(DateTime.Now.ToLongTimeString());
                Console.WriteLine("------------------------------------");
                // handled when the value returns - this will block on the console.writeline until the result returns
                Console.WriteLine(wx.Result);
            }
            catch (Exception ex)
            {
                // With Task<T>, we can handle the error in the calling thread
                Console.WriteLine("Error: " + ex.Message);
            }
            finally
            {
                Console.WriteLine("Operation complete, press any key to terminate session");
                Console.ReadLine();
            }
        }

        /// <summary>
        /// An async call returning Task of type string
        /// </summary>
        /// <param name="city"></param>
        /// <param name="country"></param>
        /// <returns></returns>
        static async Task<string> GetGlobalWeather(string city, string country)
        {
            // note there is no error handling in the async method on this call, that is not to say
            // one could not put error handling here but in this case it is possible to catch and handle
            // errors in the calling thread
            GlobalWeather.GlobalWeatherSoapClient client = new GlobalWeather.GlobalWeatherSoapClient();

            // we will await the call to fetch the weather and return the result immediately to the caller
            return await client.GetWeatherAsync(city, country);
        }
    }
}

Figure 3. Console Output for Example 3

Figure 4. An exception handled in the Main, outside the async method

Summary

In this article, we reviewed the rules for using Async and Await and provided examples of async methods returning void, Task, and Task<T>. The article further addressed some of the issues pertaining to error handling given each of the three potential return types. There is certainly much more to Async and Await than was covered in this simple introduction, and for that matter, with the Task Parallel Library (TPL) in the larger picture.

The article does try to illustrate how simple it is to implement this new language feature to make asynchronous calls within your C# 5.0 applications targeting the .NET 4.5 framework.