Duration

15 minutes

Goals

The primary goal of this lab is to modify an existing application to use the event-based async pattern to download search results from a web service.

Required assets

The provided Exercise 1 folder contains a subfolder named Start with a solution you will use as starting point. There is also a Completed folder with a solution you can use to check your work. Please make sure you have these folders before you begin.

Challenge

Update an existing application to use the event-based async pattern when searching for movies.

1. Examine the start solution.
2. Add a new method to MovieApi.cs called SearchAsync that uses WebClient's DownloadStringAsync method and the DownloadStringCompleted event.
3. In MovieApi.cs, create a public Action named SearchComplete and invoke it when the search completes, passing in the movie data.
4. In SearchPage.xaml.cs, update the OnSearch method to use the new SearchAsync method and SearchComplete action.

Steps

Examine the Start Solution

1. Open the MediaPhone shared project.
2. Inspect SearchPage.xaml; it displays a SearchBar and a ListView.
3. Open the Data folder in the solution explorer. The code in MovieApi.cs is used to query the iTunes movie database.
SearchResult.cs holds a model object class to hold the returned data.
4. Run the application and try searching for a movie.
5. Perform a search using a keyword that will return multiple results (try captain). Try to interact with the UI before the search results are returned? What happened?

Add an Asynchronous Search Method

1. Open MovieApi.cs.
2. Create a new void method named SearchAsync that accepts a single string parameter named text.
3. Copy the null check code, the creation of the local query string and the creation of the WebClient from the old Search method.

   Show Code

   public void SearchAsync(string text)
   {
       if (String.IsNullOrEmpty(text))
           throw new ArgumentNullException("text");
   
       string query = String.Format(SearchUrl, WebUtility.HtmlEncode(text));
   
       WebClient wc = new WebClient();
   }   
   

4. Instead of calling the WebClient's DownloadString method, subscribe to the DownloadStringCompleted EventHandler. You may use any subscription method you prefer; the completed solution uses a lambda expression.
5. Within the handler, check the DownloadStringCompletedEventArgs's Error property for null.
6. If Error is null, we can assume the download completed successfully. Save the DownloadStringCompletedEventArgs's Result property to a local string variable named resultText.
7. Parse the resultText using the static JsonConvert.DeserializeObject method and save to local variable named results.
8. Call the WebClient wc's DownloadStringAsync method. For the parameter, create a new Uri passing query into the constructor of the Uri.

Show Code

public void SearchAsync(string text)
{
    ...
    wc.DownloadStringCompleted += (sender, e) => 
    {
        if (e.Error == null)
        {
            string resultText = e.Result;

            var results = JsonConvert.DeserializeObject<SearchResult>(resultText);
        }
    };
    wc.DownloadStringAsync(new Uri(query));
}   

Provide the Search Results

We'll create a public action that will provide the deserialized results to a subscriber when the results are ready.

1. In MovieApi.cs, create a public Action that accepts an IEnumerable of SearchItems and an Exception named SearchComplete.
2. Add the event keyword before the Action declaration to limit its accessibility.
The deserialized results variable contains a property that is also named results which is a List of SearchItems. When invoking the Action, pass in results.results as the first parameter and null for 2nd Exception parameter.
3. If e.Error is not null, invoke the SearchComplete Action passing in null for the first parameter and the error for the second parameter.

Show Code

public event Action<IEnumerable<SearchItem>, Exception> SearchComplete;
public void SearchAsync(string text)
{
    ...
    wc.DownloadStringCompleted += (sender, e) => 
    {
        if (e.Error == null)
        {
            string resultText = e.Result;

            var results = JsonConvert.DeserializeObject<SearchResult>(resultText);
            SearchComplete?.Invoke(results.results, null);
        }
        else
        {
            SearchComplete?.Invoke(null, e.Error);
        }
    };
    ...
}

Invoke the Async Search method

1. Open SearchPage.xaml.cs.
2. In the OnSearch method, delete the try, catch, and finally blocks.

Show Code

void OnSearch(object sender, EventArgs e)
{
    if (String.IsNullOrEmpty(searchBar.Text))
        return;

    Data.Clear();
    searchProgress.IsRunning = true;
}

3. Create a local instance of MovieApi named api. Subscribe to its SearchComplete event that we created in the last step.
4. In the handler, check if the Exception exists, and if so return.
5. If the Exception is null, use a foreach loop to add each item from the passed in IEnumerable of SearchItems to the ListView's data source named Data.
6. Set the searchProgress's IsRunning property to null to hide the activity indicator.
7. After the handler, call api's SearchAsync method, passing in the search terms text from the searchBar.
8. Run the application. Notice that the ActivityIndicator is now visible during searches.

Show Code

void OnSearch(object sender, EventArgs e)
{
    ...

    MovieApi api = new MovieApi();
    api.SearchComplete += (results, ex) => {
        if (ex != null)
        {
            DisplayAlert("Error", ex.Message + "\r\nAre you connected to the Internet?", "OK");
            return;
        }

        foreach (var item in results)
            Data.Add(item);

        searchProgress.IsRunning = false;
    };

    api.SearchAsync(searchBar.Text);
}

Summary

In this exercise, you updated an existing application to use the event-based async pattern to query a web service for search results. This allowed the UI to remain responsive while waiting for the results from the web service.