Correcting the Visual Studio Event Code

The first change I need to make is to remove the view model from the MainPage.xaml.cs code-behind file. I have been moving the view model gradually to demonstrate the central role that it plays in a Windows app, and in this chapter, there are features I am going to show you that require the view model to be created as part of the life cycle. You can see the simplified MainPage.xaml.cs file in Listing 5-1.

Listing 5-1. Removing the View Model Instantiation from the MainPage.xaml.cs File

using GrocerApp.Data;
using System;
using Windows.Data.Xml.Dom;
using Windows.UI.Notifications;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Navigation;
  
namespace GrocerApp.Pages {
  
    public sealed partial class MainPage : Page {
        private ViewModel viewModel;
  
        public MainPage() {
            this.InitializeComponent();
        }
  
        private void UpdateBadge() {
            // . . .statements omitted for brevity. . .
        }
  
        private void UpdateTile() {
            // . . .statements omitted for brevity. . .
        }
  
        protected override void OnNavigatedTo(NavigationEventArgs e) {
            viewModel = (ViewModel)e.Parameter;
            this.DataContext = viewModel;
  
            MainFrame.Navigate(typeof(ListPage), viewModel);
  
            viewModel.GroceryList.CollectionChanged += (sender, args) => {
                UpdateTile();
                UpdateBadge();
            };
  
            UpdateTile();
            UpdateBadge();
        }
  
        private void NavBarButtonPress(object sender, RoutedEventArgs e) {
            Boolean isListView = (Button)sender == ListViewButton;
            MainFrame.Navigate(isListView ? typeof(ListPage)
                : typeof(DetailPage), viewModel);
  
        }
    }
}

I can now turn to the App.xaml.cs file and build on the template code to respond to changes in the app life cycle. Unfortunately, the code for handling the life-cycle events that Visual Studio adds to a project doesn’t work. It deals with activation and suspension quite happily, but it prevents the app from being notified when it is being restored. Fortunately, the solution to this is pretty simple, and you can see the changes required to App.xaml.cs in Listing 5-2.

Listing 5-2. Handling the Life-Cycle Notification Events

using GrocerApp.Data;
using System;
using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
  
namespace GrocerApp {
  
    sealed partial class App : Application {
        private ViewModel viewModel;
  
        public App() {
            this.InitializeComponent();
  
            viewModel = new ViewModel();
  
            viewModel.StoreList.Add("Whole Foods");
            viewModel.StoreList.Add("Kroger");
            viewModel.StoreList.Add("Costco");
            viewModel.StoreList.Add("Walmart");
  
            viewModel.GroceryList.Add(new GroceryItem {
                Name = "Apples",
                Quantity = 4, Store = "Whole Foods"
            });
            viewModel.GroceryList.Add(new GroceryItem {
                Name = "Hotdogs",
                Quantity = 12, Store = "Costco"
            });
            viewModel.GroceryList.Add(new GroceryItem {
                Name = "Soda",
                Quantity = 2, Store = "Costco"
            });
            viewModel.GroceryList.Add(new GroceryItem {
                Name = "Eggs",
                Quantity = 12, Store = "Kroger"
            });
  
            this.Suspending += OnSuspending;
            this.Resuming += OnResuming;
        }
  
        protected override void OnLaunched(LaunchActivatedEventArgs args) {
            Frame rootFrame = Window.Current.Content as Frame;
  
            if (rootFrame == null) {
                rootFrame = new Frame();
                if (args.PreviousExecutionState == ApplicationExecutionState.
                 Terminated)
                {
                    //TODO: Load state from previously suspended application
                }
                Window.Current.Content = rootFrame;
            }
  
            if (rootFrame.Content == null) {
  
                if (!rootFrame.Navigate(typeof(Pages.MainPage), viewModel)) {
                    throw new Exception("Failed to create initial page");
                }
            }
            Window.Current.Activate();
        }
  
        private void OnResuming(object sender, object e) {
            viewModel.GroceryList[1].Name = "Resume";
        }
  
        private void OnSuspending(object sender, SuspendingEventArgs e) {
            var deferral = e.SuspendingOperation.GetDeferral();
            viewModel.GroceryList[0].Name = "Suspend";
            deferral.Complete();
        }
    }
}

I have highlighted the most important change, which is to register for the Suspending and Resuming events, and added statements to the handler methods for those event. Visual Studio includes a handler for the Suspending event when it created the class, but I had to add the Resuming handler to get the event notification. I removed the code in the OnLaunched method, which tried (and failed) to work out when the app was being resumed.

My app doesn’t currently perform any tasks that are affected by the app being suspended and resumed at the moment, but I want to show you how to test for the events. To that end, I respond to the Suspending and Resuming events by changing the Name property of the first two items in the GroceryList collection in the view model to signal when these events have been received.

Simulating the Life-Cycle Events

The easiest way to simulate the life-cycle events is to use Visual Studio. When you start an app with the debugger, Visual Studio displays a menu to the toolbar that allows you to send the life-cycle events to the app, which I have highlighted in Figure 5-1.

If you select the menu items to suspend and then resume the app, you will see the changes in the view model data shown in Figure 5-2. (You won’t see the changes until you resume the app; once the app has been suspended, no UI updates are processed.)

Testing the Life-Cycle Events

The problem with simulating the life-cycle events is that you don’t get quite the same result as when they arise naturally. To do this, you need to start the app without the debugger, which is why indicating that the events have been received via the view model is so useful. Creating the circumstances in which the events are sent requires some specific actions, which I describe step-by-step in the following sections.

Extending the View Model

I am going to extend the view model so that it keeps track of the location data generated by the TrackLocation method. This will allow me to use data binding to display the data to the user. Listing 5-4 shows the additions I have made to the ViewModel class.

Listing 5-4. Updating the View Model to Capture the Location Data

using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.ComponentModel;
  
namespace GrocerApp.Data {
    public class ViewModel : INotifyPropertyChanged {
        private ObservableCollection<GroceryItem> groceryList;
        private List<string> storeList;
        private int selectedItemIndex;
        private string homeZipCode;
        private string location;
  
        public ViewModel() {
            groceryList = new ObservableCollection<GroceryItem>();
            storeList = new List<string>();
            selectedItemIndex = -1;
            homeZipCode = "NY 10118";
            location = "Unknown";
        }
  
        public string Location {
            get { return location; }
            set { location = value; NotifyPropertyChanged("Location"); }
        }
  
        // ...other properties removed for brevity...
  
  
        public event PropertyChangedEventHandler PropertyChanged;
        private void NotifyPropertyChanged(string propName) {
            if (PropertyChanged != null) {
                PropertyChanged(this, new PropertyChangedEventArgs(propName));
            }
        }
    }
}

Displaying the Location Data

I have updated the MainPage.xaml file to add controls that will display the location data to the user. The data binding ensures that the current information from the view model is used, which means that no changes are required to the code-behind file. Listing 5-5 shows the additional controls.

Listing 5-5. Adding Controls to the XAML File to Display the Location Data

<Page
    x:Class="GrocerApp.Pages.MainPage"
    xmlns=" http://schemas.microsoft.com/winfx/2006/xaml/presentation "
    xmlns:x=" http://schemas.microsoft.com/winfx/2006/xaml "
    xmlns:local="using:GrocerApp.Pages"
    xmlns:d=" http://schemas.microsoft.com/expression/blend/2008 "
    xmlns:mc=" http://schemas.openxmlformats.org/markup-compatibility/2006 "
    mc:Ignorable="d">
  
    <Page.TopAppBar>
        <AppBar>
            <StackPanel Orientation="Horizontal" HorizontalAlignment="Center">
                <Button x:Name="ListViewButton"
                    Style="{StaticResource AppBarButtonStyle}"
                    AutomationProperties.Name="List View"
                    Content="" Click="NavBarButtonPress"/>
                 
                <Button x:Name="DetailViewButton"
                    Style="{StaticResource AppBarButtonStyle}"
                    AutomationProperties.Name="Detail View"
                    Content="" Click="NavBarButtonPress"/>
            </StackPanel>
        </AppBar>
    </Page.TopAppBar>
  
    <Grid Background="{StaticResource AppBackgroundColor}">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>
  
        <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" >
            <TextBlock FontSize="30" Text="Your location is:" Margin="0,0,10,0" />
            <TextBlock FontSize="30" Text="{Binding Path=Location}" />
        </StackPanel>
         
        <Frame x:Name="MainFrame" Grid.Row="1" />
    </Grid>
</Page>
  

Declaring the App Capabilities

Apps must declare their need to access the location service in their manifest. Before running the updated app, open package.appxmanifest, switch to the Capabilities tab, ensure that the Location capability is checked (as shown in Figure 5-3), and save the file. Your app will also need the Internet (Client) capability, but this is declared by default when Visual Studio creates the project.

Controlling the Background Task

With all the plumbing in place, I can turn to the management of the background task and the integration with the life-cycle events, which are, after all, the point of this example. Listing 5-6 shows the changes I have made to the App.xaml.cs file.

Listing 5-6. Updating the App.xaml.cs File for the Background Task

using GrocerApp.Data;
using System;
using System.Threading;
using System.Threading.Tasks;
using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;
using Windows.UI.Core;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
  
namespace GrocerApp {
  
    sealed partial class App : Application {
        private ViewModel viewModel;
        private Task locationTask;
        private CancellationTokenSource locationTokenSource;
  
        public App() {
            this.InitializeComponent();
  
            viewModel = new ViewModel();
  
            // ...test data removed for brevity...
  
            this.Suspending += OnSuspending;
            this.Resuming += OnResuming;
        }
  
        protected override void OnLaunched(LaunchActivatedEventArgs args) {
            Frame rootFrame = Window.Current.Content as Frame;
  
            if (rootFrame == null) {
                rootFrame = new Frame();
                Window.Current.Content = rootFrame;
            }
  
            if (rootFrame.Content == null) {
  
                if (!rootFrame.Navigate(typeof(Pages.MainPage), viewModel)) {
                    throw new Exception("Failed to create initial page");
                }
            }
            Window.Current.Activate();
            StartLocationTracking(rootFrame);
        }
  
        private void OnResuming(object sender, object e) {
            viewModel.Location = "Unknown";
            StartLocationTracking(Window.Current.Content as Frame);
        }
  
        private void OnSuspending(object sender, SuspendingEventArgs e) {
            StopLocationTracking();
            SuspendingDeferral deferral = e.SuspendingOperation.GetDeferral();
            locationTask.Wait();
            deferral.Complete();
        }
  
        private void StartLocationTracking(Frame frame) {
            locationTokenSource = new CancellationTokenSource();
            CancellationToken token = locationTokenSource.Token;
  
            locationTask = new Task(async () => {
                while (!token.IsCancellationRequested) {
                    await frame.Dispatcher.RunAsync(CoreDispatcherPriority.
                    Normal,
                        async () => {
                            viewModel.Location = await Location.
                            TrackLocation();
                        });
                    token.WaitHandle.WaitOne(5000);
                }
            });
            locationTask.Start();
        }
  
        private void StopLocationTracking() {
            locationTokenSource.Cancel();
        }
    }
}
  

The changes to this class represent two different activities. The first is to track the location of the user as a background task and is contained in the StartLocationTracking and StopLocationTracking methods. I want you to treat these methods as black boxes because I can’t explore the TPL concepts and features I rely on. The important information is that the StartLocationTracking method starts a background activity that reports on the location every five seconds, and the StopLocationTracking method cancels that task.

What I do want to talk about is how I integrate this background task with the life-cycle events. Responding when the app is started or in response to the Resuming event is easy; I simply call the StartLocationTracking method.

For the Suspending event, I want to make sure that my background task has completed before the app is suspended. If I don’t take this step, then I run the risk of either displaying stale data when the app is resumed or causing an error by trying to read from a network request that has been closed by the server during the period that my app was suspended.

To help work around this problem, the SuspendingEventArgs.SuspendingOperation.GetDeferral method tells the Windows runtime that I am not quite ready for my app to be suspended and that I need a little more time. This gives me a short window in which to wait for my task to complete. The GetDeferral method returns a SuspendingDeferral object, and I call its Complete method when I am ready for my app to be suspended.

Asking for a deferral grants an extra five seconds to prepare for suspension. This may not sound like a lot, but it is pretty generous given that Window may be under a lot of pressure to get your app out of the way to make system resources available.

. . .
await frame.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
    async () => {
        viewModel.Location = await Location.TrackLocation();
});
. . .

The application called an interface that was marshalled for a different thread

Declaring Support for the Contract

The first step toward implementing a contract is to update the manifest. Open the Package.appxmanifest file and switch to the Declarations tab. If you open the Available Declarations menu, you will see the lists of contracts that you can declare support for. Select Search and click the Add button. The Search contract will appear on the Supported Declarations list, as shown in Figure 5-5.

Ignore the Properties section for the contract; these allow you to delegate your obligations under the search contract to another app, which I won’t be doing.

Implementing the Search Feature

The purpose of the search contract is to connect the operating system search system with some kind of search capability within your app. For my example app, I am going to handle search requests by iterating through the items on the grocery list and selecting the first one that contains the string the user is looking for. This won’t be the most sophisticated search implementation, but it will let me focus on the contract without getting bogged down in creating lots of new code to handle searches. I have added a method to the ViewModel class called SearchAndSelect, as Listing 5-7 illustrates.

Listing 5-7. Adding Search Support to the View Model

using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.ComponentModel;
  
namespace GrocerApp.Data {
    public class ViewModel : INotifyPropertyChanged {
        private ObservableCollection<GroceryItem> groceryList;
        private List<string> storeList;
        private int selectedItemIndex;
        private string homeZipCode;
        private string location;
  
        public ViewModel() {
            groceryList = new ObservableCollection<GroceryItem>();
            storeList = new List<string>();
            selectedItemIndex = -1;
            homeZipCode = "NY 10118";
            location = "Unknown";
        }
  
        public void SearchAndSelect(string searchTerm) {
            int selIndex = -1;
            for (int i = 0; i < GroceryList.Count; i++) {
                if (GroceryList[i].Name.ToLower().Contains(searchTerm.
                ToLower())) {
                    selIndex = i;
                    break;
                }
            }
            SelectedItemIndex = selIndex;
        }
         
        // ...properties removed for brevity...
  
        public event PropertyChangedEventHandler PropertyChanged;
        private void NotifyPropertyChanged(string propName) {
            if (PropertyChanged != null) {
                 PropertyChanged(this, new PropertyChangedEventArgs(propName));
            }
        }
    }
}

This method will be passed the string that the user is searching for. It looks for items in the grocery list and sets the selection to the first matching item it finds or to -1 if there is no match. Since the SelectedItemIndex property is observable, this means that searching for an item will select it and display its details in the app layout.

I want the ListView control in the ListPage to select the matching item, so I have made a minor change to the ListPage.xaml.cs code-behind class, as shown in Listing 5-8.

Listing 5-8. Ensuring That the Selection Is Properly Displayed

. . .
protected override void OnNavigatedTo(NavigationEventArgs e) {
  
    viewModel = (ViewModel)e.Parameter;
  
    ItemDetailFrame.Navigate(typeof(NoItemSelected));
    viewModel.PropertyChanged += (sender, args) => {
        if (args.PropertyName == "SelectedItemIndex") {
            groceryList.SelectedIndex = viewModel.SelectedItemIndex;
            if (viewModel.SelectedItemIndex == -1) {
                ItemDetailFrame.Navigate(typeof(NoItemSelected));
                AppBarDoneButton.IsEnabled = false;
            } else {
                ItemDetailFrame.Navigate(typeof(ItemDetail), viewModel);
                AppBarDoneButton.IsEnabled = true;
            }
        }
    };
}
. . .

Responding to the Search Life-Cycle Event

The Application class makes it very easy to implement contracts by providing methods you can override for each of them. Listing 5-9 shows my implementation of the OnSearchActivated method, which is the one called when the user targets my app with a search.

Listing 5-9. Responding to Searches

using GrocerApp.Data;
using System;
using System.Threading;
using System.Threading.Tasks;
using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;
using Windows.UI.Core;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
  
namespace GrocerApp {
  
    sealed partial class App : Application {
        private ViewModel viewModel;
        private Task locationTask;
        private CancellationTokenSource locationTokenSource;
  
        public App() {
            this.InitializeComponent();
  
            viewModel = new ViewModel();
  
            // ...test data omitted for brevity...
            this.Suspending += OnSuspending;
            this.Resuming += OnResuming;
        }
  
        protected override void OnLaunched(LaunchActivatedEventArgs args) {
            Frame rootFrame = Window.Current.Content as Frame;
  
            if (rootFrame == null) {
                rootFrame = new Frame();
                Window.Current.Content = rootFrame;
            }
  
            if (rootFrame.Content == null) {
  
                if (!rootFrame.Navigate(typeof(Pages.MainPage), viewModel)) {
                    throw new Exception("Failed to create initial page");
                }
            }
            Window.Current.Activate();
            StartLocationTracking(rootFrame);
        }
  
        protected override void OnSearchActivated(SearchActivatedEventArgs args) {
            viewModel.SearchAndSelect(args.QueryText);
        }
  
        private void OnResuming(object sender, object e) {
            // ...statements omitted for brevity...
        }
  
        private void OnSuspending(object sender, SuspendingEventArgs e) {
            // ...statements omitted for brevity...
        }
  
        private void StartLocationTracking(Frame frame) {
            // ...statements omitted for brevity...
        }
  
        private void StopLocationTracking() {
            locationTokenSource.Cancel();
        }
    }
}

That is all that is required to satisfy the obligations of the search contract; by overriding the OnSearchActivated method, I have added the ability for Windows to search my app on behalf of the user.

Testing the Search Contract

To test the contract, start the example app. It doesn’t matter if you start it with or without the debugger. Bring up the charms bar and select the search icon. The example app will be selected as the target of the search automatically. To begin a search, just start typing.

When you press the search button to the right of the textbox, Windows will invoke the search contract and pass the query string to the example app. You want to search for something that will make a match, so type hot (so that your search will match against the hot dogs item in the grocery list) and click the button. You will see something similar to Figure 5-6.

I really like the contract approach. This is a very simple implementation of the search contract, but you can see how easy it is to integrate into Windows with just a few lines of code. You can go well beyond what I have done here and completely customize the way that your app deals with and responds to search.