In order to have a fully functioning app and eventually publish it to the Windows Store, you will need to properly handle application state while also considering the user’s bandwidth, disk space, and other system resources. I’ve simplified this to what I would call being a developer good citizen of the platform. This means providing users with an optimal experience regardless of the device or the presence of network connectivity. Whether you value user experience or not, Microsoft has a set of guidelines that must be followed to pass certification for the Windows Store. These guidelines value user experience, and if you plan to release your app through the Windows Store, you should consider these guidelines from the beginning. For more information on what’s required by the Windows Store, see Chapter 5.

This chapter describes core components of a more complex application than the Bing Simple Search app we explored in the previous chapter. These concepts will be used throughout the book, and I will reference various aspects of the application through the use of these techniques. If you are familiar with previous XAML-based technologies, you will likely be familiar with these concepts. As a reminder, all the code for the book’s full application is available online at https://github.com/bendewey/GettingStartedWithMetroApps. I encourage you to download the code ahead of time so you can follow along.

Figure 3-1. Bing Image Search App

Before I get too deep into the code, let’s step back and review the goals of the Bing Image Search app (Figure 3-1).

In order to accomplish the goals laid out in this chapter, the Bing Image Search app needs to be small and easy to navigate. With that in mind, the app is broken up into three pages:

The primary page that the user sees is the SearchHistoryPage; this outlines the user’s searching history and is the home screen for the application. Once a user has performed a search, she is navigated to a SearchResultsPage. The SearchResultsPage provides multiple views of the images. There are buttons on the bottom of the app bar that allow users to switch between views. Once an image is selected, the user has the ability to load a DetailsPage where she can perform a number of Windows 8 tasks. Figure 3-2 shows a detailed diagram of the navigation events in the Bing Image Search app.

Figure 3-2. Navigation Diagram of Bing Image Search App

In addition to the overall design of the application, Figure 3-2 also shows the different entry points into the app. All of these entry points, described in Table 3-1, occur in the App.xaml.cs file. This App.xaml file contains the resource, or style, definitions for use throughout the application. The associated App.xaml.cs file contains the App class, which, like WPF and Silverlight, hosts the application startup and shutdown event or overrides. This App class, or application class, creates a new Shell control, assigns it to the current window, and activates that window, as seen in Example 3-1. This main application Shell is responsible for the navigation, title, back button, and the PreferencesPage. In the case of the OnFileOpenPickerActivated entry point, the full application UI won’t suffice for a number of reasons, primarily because the resolution is different and the app bar will not work. This is why it loads a custom page, specifically the FileOpenPickerPage, to run the application. The file picker will be described in more detail in Chapter 4.

Window.Current.Content = new Shell();
Window.Current.Activate();

The Bing Image Search app is made of Models, Views, ViewModels, application services, and Windows services. Figure 3-3 describes the structure of the Bing Image Search application. This diagram is simplified in a number of ways, but the core components in the application services layer remain. You will also notice that the ViewModels don’t talk to the Windows services directly. The application services act as a proxy to the Windows services, which maintains code testability.

Figure 3-3. Application Diagram

The application services are broken up into five categories and I’ll review them in the order in which they occur when the application activates:

Model-View-ViewModel (MVVM) is a common practice in XAML and C# that was made popular by WPF and Silverlight. MVVM makes extensive use of the data binding capabilities in XAML. The ViewModel exposes properties on the Model objects to the View, which uses data binding to display that information to the user. In addition to binding data from the ViewModel to the View, events from the View are routed to the ViewModel via commands.

<Application.Resources>
    <common:ViewModelLocator x:Key="ViewModelLocator" />

    <!-- Other styles and resources --->
</Application.Resources>

public SearchHistoryPageViewModel SearchHistoryPageViewModel
{
    get { return Container.Resolve<SearchHistoryPageViewModel>(); }
}

<Page x:Class="BingImageSearch.SearchHistoryPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    DataContext="{Binding SearchHistoryPageViewModel,
            Source={StaticResource ViewModelLocator}}">
    <!-- code removed for clarity -->
</Page>

public SearchHistoryPageViewModel(/*  insert dependencies here */)
{
    // ViewModel setup code
    SearchCommand = new DelegateCommand(Search);
}

public void Search()
{
    // Send a message to the MessageHub.
}

Numerous Inversion of Control (IoC) containers have been created by the .NET community and make the process of configuring types for your application quite easy. When leveraging the Dependency Inversion principle (or Dependency Injection) your services will likely have nested dependencies, which lead to quite a bit of setup. The IoC container solves this by handling the setup of your application type mappings in a centralized location. In addition, the IoC container is responsible for maintaining the lifetime of each object in your application. If you want more info about IoC containers, there is plenty of information online. My favorite resource is still the DNR TV video James Kovacs’ roll-your-own IoC container at http://www.dnrtv.com/default.aspx?showNum=126.

Since the .NET Windows 8 App Profile is new, the options for containers are limited. I’d imagine that many more containers will become available with time. For now, I am using a nice container that is available from codeplex called MetroIoC (http://metroioc.codeplex.com/).

The ViewModelLocator maintains a reference to the application’s only IoC container and uses it to create all the ViewModels. Example 3-6 shows how the container is created in the ViewModelLocator. It uses a Lazy<T> object that builds the container the first time it’s requested. The constructor for the lazy object takes a delegate to create an object of the requested type. In the case of Example 3-6, the lazy construction is offloaded to the IoC.BuildContainer method, which can be seen in Example 3-7.

private Lazy<IContainer> _container;
public IContainer Container
{
        get { return _container.Value; }
}

public ViewModelLocator()
{
        _container = new Lazy<IContainer>(IoC.BuildContainer);
}

public class IoC
{
        public static IContainer BuildContainer()
        {
                var container = new MetroContainer();
                container.RegisterInstance(container);
                container.RegisterInstance<IContainer>(container);

                container.Register<IHub, MessageHub>(lifetime: new SingletonLifetime());
                /* more type registrations */
        }
}

Once the container is set up, the app is free to use the Dependency Inversion principle throughout. When you look at the SearchHistoryPageViewModel class (Example 3-8), you see that the only way to create the object is by supplying two required dependencies in the constructor. The container will automatically determine the requirements and perform the necessary steps to resolve them first and ensure that these requirements are satisfied so that a newly created SearchHistoryPageViewModel can be provided.

public class SearchHistoryPageViewModel : BindableBase
{
        private readonly INavigationService _navigationService;
        private readonly IHub _hub;

        public SearchHistoryPageViewModel(INavigationService navigationService, IHub hub)
        {
                _navigationService = navigationService;
                _hub = hub;
        }
}

The Bing Image Search app is small, but regardless of your app size, you’ll probably need to handle local navigation. There are two main ways to do this: first is to change the Window.Current property to a new UserControl and allow changes in navigation to update that property. The second uses a Frame, which can be set to a Type reference, typically using the typeof keyword, for the XAML page you’d like to display. Both of these approaches have a place, but for the Bing Image Search app, I am going to use the Frame control (Example 3-9). The Frame control works best because it has built-in support for navigation, both forward and backward, and because it allows me to treat the container page (the Shell) as a form of master page or master layout where I can place common UI elements across all pages.

<Frame x:Name="MainFrame" />

This Frame is located in the Shell.xaml file. The purpose of the Shell, and the reason I am using a Frame, can be seen in Figure 3-4. The Bing Image Search app will use a consistent title and back button across all pages. The Shell will also be used for the preferences page, which will be available from any page.

Figure 3-4. Shell sketch with frame marker

In order to tell your app to use the Shell.xaml file as its default page, you’ll need to specify this in the OnLaunching event of the App.xaml.cs file. Example 3-10 shows what’s required to initialize your Shell page. In addition to creating the new control and assigning it to the Window, the OnLaunching event registers the frame with the ViewModelLocator’s NavigationService. If you remember, the ViewModelLocator holds the only container, and the properties on it simply return whatever the container provides, in this case, a SingletonLifetime instance of the NavigationService.

shell = new Shell();
ViewModelLocator.NavigationService.InitializeFrame(shell.Frame);
Window.Current.Content = shell;
Window.Current.Activate();

While this code works well for the OnLaunched event, the same logic will be needed on the OnSearchActivated method. In order to reuse the code between the different activation models, extract this code into a new method and call this from either activation method as in Example 3-11.

public override void OnLaunched(/* ... */)
{
        await EnsureShell(args.PreviousExecutionState);
        ViewModelLocator.NavigationService.Navigate(typeof(SearchHistoryPage));
}

public override void OnSearchActivated(/* ... */)
{
        await EnsureShell(args.PreviousExecutionState);
        await ViewModelLocator.Hub.Send(new SearchQuerySubmittedMessage(args.QueryText));
}

public void EnsureShell()
{
        // setup shell and activate window
}

public class NavigationService : INavigationService
{
        private Frame _frame;

        public void InitializeFrame(Frame frame)
        {
                if (_frame != null)
                {
                        _frame.Navigating -= Frame_Navigating;
                }

                _frame = frame;
                _frame.Navigating += Frame_Navigating;
        }

        public void Navigate(Type source, object parameter = null)
        {
                if (_frame == null)
                {
                        throw new InvalidOperationException("Frame has not been initialized.");
                }
                _frame.Navigate(source, parameter);
        }

        /* more proxy methods, CanGoBack, GoBack */
}

public class SearchQuerySubmittedHandler : IHandler<SearchQuerySubmittedMessage>
{
        private readonly INavigationService _navigationService;

        public SearchQuerySubmittedHandler(INavigationService navigationService)
        {
                _navigationService = navigationService;
        }

        public void Handle(SearchQuerySubmittedMessage message)
        {
                // execute the search against the Bing Search API
                _navigationService.Navigate(typeof(SearchResultsPage));
        }
}

One of the goals for the Bing Image Search app is to handle application and operate system-level events in a centralized location. To accomplish this, I’ve implemented a MessageHub, which routes all messages to dedicated handlers that are created by the container, and thus can have their dependencies injected. The MessageHub is made up of four components described in Table 3-2.

protected override async void OnSearchActivated(SearchActivatedEventArgs args)
{
        await EnsureShell(args.PreviousExecutionState);
        await ViewModelLocator.Hub.Send(new SearchQuerySubmittedMessage(args.QueryText));
}

public class MessageHub : IHub
{
        private readonly IContainer _container;

        public MessageHub(IContainer container)
        {
                _container = container;
        }

        public async Task Send<TMessage>(TMessage message) where TMessage : IMessage
        {
                var handler = _container.TryResolve<IHandler<TMessage>>(null);
                if (handler != null)
                {
                        handler.Handle(message);
                        return;
                }

                var asyncHandler = _container.TryResolve<IAsyncHandler<TMessage>>(null);
                if (asyncHandler != null)
                {
                        await asyncHandler.HandleAsync(message);
                        return;
                }
        }
}

public class SearchQuerySubmittedHandler : IAsyncHandler<SearchQuerySubmittedMessage>
{
    public SearchQuerySubmittedHandler(/* dependencies */)
    {
    }

    public async Task HandleAsync(SearchQuerySubmittedMessage message)
    {
        // execute search using message.Query
    }
}

The new application model for Windows 8 apps will suspend your app shortly after your app leaves the user’s foreground. It’s up to the app to handle reloading to the correct location and retaining the state of the application when the user was last active. This process is known as tombstoning your application and is common practice on phones and tablet devices. One approach to handling this is to save your application state when the OnSuspending event occurs in the App.xaml.cs file. An alternative approach—and the approach that is used by the Bing Image Search app—is to constantly save state while the user navigates through the application. The latter allows us to use the same tracking mechanism to pass state between different objects in the system.

To accomplish this, the Bing Image Search app uses an ApplicationSettings class. This class is a strongly typed wrapper over the internal ISuspensionManager that maintains the settings in a Dictionary of key-value pairs and contains two methods: SaveAsync and RestoreAsync.

Example 3-17 shows how the SearchResultsPageViewModel updates the ApplicationSettings with the currently selected image and then navigates to the DetailsPage, which loads the selected image from the same application settings location.

public class SearchResultsPageViewModel : BindableBase
{
        private readonly ApplicationSettings _settings;
        private readonly INavigationService _navigationService;

        public SearchResultsPageViewModel(ApplicationSettings settings,
                INavigationService navigationService)
        {
                _settings = settings;
                _navigationService = navigationService;

                // Additional ViewModel setup code
                ViewDetailsCommand = new DelegateCommand(ViewDetails);
        }

        public ImageResult SelectedImage
        {
                get { return _settings.SelectedImage;  }
                set
                {
                        _settings.SelectedImage = value;
                        OnPropertyChanged();
                }
        }

        public void ViewDetails()
        {
                _navigationService.Navigate(typeof(DetailsPage));
        }
}

Now that all the settings and other relevant information about the state within the application have been saved, the only remaining concern is reloading the data for the user’s return to the app. Example 3-18 shows how, with a simple modification to the EnsureShell method, you can restore the application state.

public async void EnsureShell()
{
        if (previousState == ApplicationExecutionState.Terminated
                || previousState == ApplicationExecutionState.ClosedByUser)
        {
                var settings = ViewModelLocator.Container.Resolve<ApplicationSettings>();
                await settings.RestoreAsync();
        }

        // Remaining EnsureShell logic from earlier
}

One of the charms on the new Windows 8 Start Bar is the Settings charm. This mechanism is consistent across all apps for providing settings to the user. In the case of the Bing Image Search app, there is only one settings page called Preferences. The preferences UI exists in a UserControl that is located in the main Shell (see Example 3-19). By default, the PreferencesPage is hidden. In order to display the PreferencesPage, you need to register a setting as a SettingsCommand and provide a callback to show the page. Example 3-20 shows the registration command and the callback.

<UserControl x:Class="BingImageSearch.Shell"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:BingImageSearch"
        Loaded="UserControl_Loaded">

        <Grid x:Name="LayoutRoot">
                <!-- Some code removed for clarity -->

                <local:PreferencesPage x:Name="PreferencesPage" Grid.RowSpan="2" />
        </Grid>
</UserControl>

private void RegisterSettings()
{
        SettingsPane.GetForCurrentView().CommandsRequested += (s, e) =>
        {
                var settingsCommand = new SettingsCommand("Preferences", "Preferences", (h) =>
                {
                        this.PreferencesPage.Show();
                });

                e.Request.ApplicationCommands.Add(settingsCommand);
        };
}

While the ApplicationSettings class stores settings for application state, it is also used to store the user settings for the application. The PreferencesViewModel, Example 3-21 uses the same ApplicationSettings class to instantly store any changes made by the user. You can see this by the call to _settings.Rating = value after calling the base class SetProperty method. When the user closes the settings view, these changes are immediately available for use within the app.

public class PreferencesViewModel : BindableBase
{
    private readonly ApplicationSettings _settings;

    public PreferencesViewModel(ApplicationSettings settings)
    {
        _settings = settings;
        ImageResultSize = _settings.ImageResultSize;
        Rating = _settings.Rating;
    }

    private ResultSize _imageResultSize;
    public ResultSize ImageResultSize
    {
        get { return _imageResultSize; }
        set
        {
            if (value != ResultSize.Empty)
            {
                base.SetProperty(ref _imageResultSize, value);
                _settings.ImageResultSize = value;
            }
        }
    }

    private Rating _rating;
    public Rating Rating
    {
        get { return _rating; }
        set
        {
            if (value != Rating.Empty)
            {
                base.SetProperty(ref _rating, value);
                _settings.Rating = value;
            }
        }
    }
}

Now that a rough idea of the application architecture, it’s time to start hooking into the operating system features. The next chapter focuses on all the powerful features within Windows 8 and how they fit into the application design.