Migrating apps from Windows Phone to Windows 8 - Channel 9

Features and Contracts in Windows Store Apps

Brian Peek, Rick Barraza — Wed, 26 Sep 2012 19:53:32 GMT

While the goal of these quickstarts is to discuss the issues and solutions involved in porting our Windows Phone 7 app to a Windows Store app, there are some features and requirements in Windows 8 we wanted to address: snapping and appcontracts.

Windows 8 Contracts provide OS level functionality and can significantly extend the power of your app when implemented properly. In this video, we will look at two contracts we implemented, the Search Contract and the Share Contract. But first, let us look at how snapping is handled in a Windows Store app.

Handling Window Snapping

As we discussed in the last Quickstart, snapping can have a significant impact on how you choose to present your app interface. In a typical template project page, we will find a GridView and ListView element both positioned in Grid.Row="1" under the navigation and page header row of our root grid.

It is the VisualStateManager that controls the visibility of these elements. Since PageHub.xaml inherits from Common\LayoutAwarePage.cs, we already have the orientation and positioning handlers taken care of. When the app is "snapped" to the screen and has its visual footprint significantly reduced, the VisualStateManager will toggle the visibility of the main GridView to Collapsed while making the thinner ListView based interface visible as shown below:

One other thing to note in this discussion is that while the ListView and GridView are both showing the same data, they would most likely need to reference different data templates and styles.

In the Khan Academy app, the ListView control that handles the snapped layout shares the same CollectionViewSource as the larger GridView control, but points to its own ItemTemplateSelector so that it will pull in the snapped styles accordingly.

The Search Contract

The Search Contract allows your app to register with the operating system as being searchable from the Windows 8 Search charm.

To set this up, we need to add some code to the LaunchApp() method in App.xaml.cs as shown below:

App.xaml.cs

public async void LaunchApp(
    ApplicationExecutionState previousExecutionState)
{
    DataSource = new KhanDataSource();
    await DataSource.LoadAllData();
 
    SearchPane searchPane = SearchPane.GetForCurrentView();
    searchPane.PlaceholderText = “Search Khan Academy”;
    searchPane.QuerySubmitted +=
        (sender, queryArgs) =>
        {
            KhanAcademy.SearchResultsPage.Activate(
                queryArgs.QueryText, previousExecutionState);
        };
        […]

First, we get the SearchPane object for the current app. Once we have a handle to the instance of the pane, we can set some properties to make the search experience a bit more tailored to our app. Namely, we set the PlaceholderText property to the string “Search Khan Academy”. Finally, we hook the QuerySubmitted event off the SearchPane object, which will be called once the user presses the Enter key or clicks/taps the magnifying glass icon to the right of the search box. In the event handler, the SearchResultsPage is activated and displayed with the user’s query text passed to the page.

The Search pane can also handle real-time suggestions based on the query the user is typing. To do this, we just need to handle the SuggestionsRequested and ResultSuggestionChosen events as shown:

            searchPane.SuggestionsRequested += 
                (sender, suggestionArgs) =>
                {
                    var videos = App.DataSource.TopicGroups.SelectMany(g =>
                        g.Playlists.SelectMany(p => p.Videos.Where(v =>
                            Regex.IsMatch(v.Name ?? "", suggestionArgs.QueryText, RegexOptions.IgnoreCase) ||
                            Regex.IsMatch(v.Description ?? "", suggestionArgs.QueryText, RegexOptions.IgnoreCase))))
                            .Distinct(VideoItem.CreateComparer())
                            .Take(3);
                    foreach(VideoItem vi in videos)
                        suggestionArgs.Request.SearchSuggestionCollection.AppendQuerySuggestion(vi.Title);
                    var recommended = App.DataSource.TopicGroups.SelectMany(g =>
                        g.Playlists.SelectMany(p => p.Videos.Where(v =>
                            Regex.IsMatch(v.Name ?? "", suggestionArgs.QueryText, RegexOptions.IgnoreCase)))).FirstOrDefault();
                    if(recommended != null)
                    {
                        suggestionArgs.Request.SearchSuggestionCollection.AppendSearchSeparator("Recommended");
                        IRandomAccessStreamReference imgStream = RandomAccessStreamReference.CreateFromUri(recommended.ImagePath);
                        suggestionArgs.Request.SearchSuggestionCollection.AppendResultSuggestion(recommended.Title, recommended.Description, recommended.VideoPath.ToString(), imgStream, recommended.Title);
                    }
                };
            searchPane.ResultSuggestionChosen +=
                (sender, resultArgs) =>
                {
                    var recommended = App.DataSource.TopicGroups.SelectMany(g =>
                        g.Playlists.SelectMany(p => p.Videos.Where(v =>
                            Regex.IsMatch(v.VideoPath.ToString() ?? "", resultArgs.Tag, RegexOptions.IgnoreCase)))).FirstOrDefault();
                    Frame f = Window.Current.Content as Frame;
                    f.Navigate(typeof(VideoPage), JsonSerializer.Serialize(recommended));
                };

In the SuggestionRequested event handler, we use a LINQ query to find the first 3 results that match what the user is typing and add them to the suggestions list using the AppendQuerySuggestion method off the SearchSuggestionCollection object. In addition, we also use LINQ to find the closest match to what the user is typing to display and display that after a line separator.

The line gets added with the AppendSearchSeparator method, and the single result gets added with the AppendResultSuggestion method. The specific result suggestion can include an icon, and we get the stream for that icon using the CreateFromUri method off the RandomAccessStreamReference object, passing in the path to the image we want to use as the icon. This returns the IRandomAccessStreamReference required by the AppendResultSuggestion method.

In the ResultSuggestionChosen method, we determine which suggestion the user selected and then navigate to the VideoPage to show the video to the user.

The Share and Devices Contracts

The Share Contract allows the user to share a piece of data from the current app to another app which knows how to receive the data. For our app, we wanted to allow the user to share a link to the video they are watching to other apps. This works great with the Windows 8 mail app.

To accomplish this, we override the DataRequested method on the VideoPage class as shown:

VideoPage.xaml.cs

public sealed partial class VideoPage
    : KhanAcademy.Common.LayoutAwarePage
{
    private PlayToManager _playToManager = null;
    private CoreDispatcher _dispatcher = null;
    private DisplayRequest _displayRequest = null;
 
    public VideoPage()
    {
        this.InitializeComponent();
    }
    protected override void DataRequested(
        DataTransferManager sender,
        DataRequestedEventArgs args)
    {
        VideoItem vi = (this.DataContext as VideoItem);
        args.Request.Data.Properties.Title = vi.Name;
        args.Request.Data.Properties.Description = vi.Description;
        args.Request.Data.SetUri(vi.KhanPath);
    }

In this method, we get the VideoItem that is currently being played, and use its properties to fill out the Data object property of the Request object. The SetUri method is used to pass the actual Uri to the Khan Academy website.

Finally, we wanted to enable PlayTo functionality so the user can quickly and easily send the video output to a TV or other media device on the network. The user can choose to do this while watching the video by selecting the Devices charm. Any PlayTo-enabled devices on the network will show up in this device list.

In code, we handle this scenario in the OnNavigatedTo and OnNavigatedFrom overridden methods.

VideoPage.xaml.cs

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    _dispatcher = Window.Current.CoreWindow.Dispatcher;
    _playToManager = PlayToManager.GetForCurrentView();
    _playToManager.SourceRequested += playToManager_SourceRequested;
    if(_displayRequest == null)
        _displayRequest = new DisplayRequest();
    _displayRequest.RequestActive();
    base.OnNavigatedTo(e);
}
protected override void OnNavigatedFrom(NavigationEventArgs e)
{
    _playToManager.SourceRequested -= playToManager_SourceRequested;
    if(_displayRequest != null)
        _displayRequest.RequestRelease();
    base.OnNavigatedFrom(e);
}
void playToManager_SourceRequested(PlayToManager sender, PlayToSourceRequestedEventArgs args)
{
    var deferral = args.SourceRequest.GetDeferral();
    var handler = _dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        args.SourceRequest.SetSource(videoElement.PlayToSource);
        deferral.Complete();
    });
}

In the OnNavigatedTo method, we get an instance of the PlayToManager and hook the SourceRequested event. We also grab an instance of the current Dispatcher. In the SourceRequested event handler, we request a deferral. This tells the PlayTo manager to wait until we give it the PlayTo source so the request doesn’t time out. We then, using the dispatcher, set the source of the PlayTo request to the video player’s PlayToSource property, and then complete the deferral. At this point, the PlayTo request is sent and the media player talks to the OS to make the magic happen. Note that in the OnNavigatedFrom method we unhook the SourceRequested event handler since it is no longer needed once the user navigates away from this page.

So at this point, we have come up with a migration strategy for porting our Windows Phone 8 to Windows 8, handled changes to how we handle asynchronous data requests and have a well styled, data bound interface that leverages the newest features of Windows 8. From here, the next step would be submitting to the store for distribution.

Hopefully, this set of quickstarts has covered some key areas of interest in getting your app up and running on Windows 8.

I would like to extend a tremendous amount of gratitude for Joel Martinez and all his tireless work as well as opening up the Viewer for Khan Academy app to serve as a Coding4Fun Community project here on Channel 9.

The source code for the Windows 8 Khan Academy app is available for download:

If you have any questions, comments, or feedback feel free to join in the discussion.

Twitter: @rickbarraza, @joelmartinez

Custom Styling in Windows Store Apps

Rick Barraza — Wed, 26 Sep 2012 19:53:26 GMT

Now that we have the data properly formatted and bound to the controls, this video will focus on custom styling and interface elements in our app.

Setting up Custom Styles

As we've discussed in the previous Quickstarts, by basing our migration effort on one of the Windows 8 Templates in Visual Studio 2012, our project came with a Common and Data folder filled with classes and resources ready to use. The Common\StandardStyles.xaml file provides the default styling for all the elements in the template and is a great place to start when customizing your own interface.

However, to keep things organized, we created a new file and also placed it in the Common folder called CustomStyles.xaml. By using inheritance, we are able to keep most of our custom edits in CustomStyles.xaml and leave StandardStyles.xaml relatively unchanged.

It may be designer preference, but one exception to this separation between CustomStyles.xaml and StandardStyles.xaml was the inclusion of custom of global colors, which we put at the very top of the StandardStyles.xaml file since we would want them to affect all subsequent styles, including the defaults.

StandardStyles.xaml

http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:vsm="using:Windows.UI.Xaml"
    >

However, all other custom style definitions are kept grouped together in a single file called CustomStyles.xaml which in turn references StandardStyles.xaml as a merged dictionary:

CustomStyles.xaml

http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:vsm="using:Windows.UI.Xaml"
    xmlns:local="using:KhanAcademy.Common">

In this way, custom styles we define in CustomStyles.xaml can be BasedOn template styles already defined in StandardStyles.xaml with only minimal change, if we only intend to customize a few properties of an existing template:

CustomStyles.xaml

Of course, we don't need to base our new elements on existing elements. We can always create new styles and templates from scratch as needed:

CustomStyles.xaml

Notice that the DataTemplate shown above is assuming bindable properties of the elements it will be formatting, which we already reviewed in the Data Binding Quickstart.

Since CustomStyles.xaml is already merging in StandardStyles.xaml as a Resource Dictionary, we only need to reference CustomStyles.xaml directly in App.xaml to get access to the entire collection of custom and standard styles.

App.xaml


    
        
            
        
        KhanAcademy

Working with Template Selectors

As discussed in our Data Binding Quickstart, we wanted to implement a Hub type experience for the Khan Academy landing page. This meant that the interface would be displaying both collections of Playlists and individual playlist collections of Videos. These two types of objects would look different from each other, since Videos have a thumbnail graphic and Playlists only display their title and description.

The challenge was that our single Grid View would need to display both types of objects, but using different styling for each.So we needed a solution to switch templates based on object type.

If we look at the way the default Grid View Template Project works, we see that its ItemTemplate property references a specific StaticResource. In this case, the Standard250x250ItemTemplate description found in Common\StandardStyles.xaml:

GroupedItemsPage.xaml

That is the way it often works. You use a specific, StaticResource reference on the ItemTemplate property of the container you have bound to your data.

But in the Khan Academy project, if you look at the GridView setup on Hub.xaml, you'll see that we are not using a StaticResource on the ItemTemplate property, but setting a value for the GridView’s ItemTemplateSelector property instead:

HubPage.xaml

ItemTemplateSelector is referencing a local resource we added to the page resources:

HubPage.xaml

Based on the return type of HubItemSelector, this ItemTemplateSelector will redirect the template to whatever template you define in the look up. So what does the class HubItemSelector actually look like?

HubItemSelector.cs

public class HubItemSelector : DataTemplateSelector
    {
        public DataTemplate Video { get; set; }
        public DataTemplate Playlist { get; set; }
        public DataTemplate Topic { get; set; }
        protected override DataTemplate SelectTemplateCore(object item, DependencyObject container)
        {
            DataItem dataItem = item as DataItem;
            if (dataItem.GetType() == typeof(VideoItem))
            {
                return Playlist;
            }
            else
            {
                return Topic;
            }
        }
    }

This technique can definitely come in handy if you are experimenting with Hub style interfaces and find yourself in a similar situation with your own app.

Semantic Zoom

Like Windows Phone, modern Window 8 apps are Touch ready. As such, Semantic Zoom is a powerful new control we can leverage in our apps. Semantic Zoom allows the user to switch views on a large body of data with a simple pinch gesture.

This gives us a great high level, low level metaphor we can leverage in our apps, and is very effective when we want to provide the experience of "zooming out" on a data set and simplifying or aggregating the smaller pieces of content. Here is how it works.

If we look at the default landing page of a Grid App template project, we see the following structure:

After the Page is declared and has its Resources defined, the LayoutRootStyle grid is created with two main rows: a row for the header that meets the Windows 8 app styling guidelines, and a row for our content.

The template defines two elements that want to occupy Grid.Row="1". A GridView that is visible when the app is at normal size, and a ListView that is visible when the app is snapped. We will look at snapping in the next quickstart, but for now just realize that this collapsing of visibility is taken care of by the VisualStateManager also on the page.

If we look at HubPage.xaml in the Khan Academy app, though, we can see where SemanticZoom fits into the entire page structure.

With this change, we make SemanticZoom is the primary element in Grid.Row="1" as long as the app isn't snapped. The GridView element that used to be there can now be nested under the SemanticZoom.ZoomedInView property and will appear as expected. However, you now have a SemanticZoom.ZoomedOutView element you can fill with whatever you want.

The control is setup to support gestures automatically. By pinching the screen closed, the user will zoom out and the control will transition between the two containers automatically. While in a zoomed out state, if the user pinches outward, they will return to the default Zoomed In view.

But what about all that business with snapping we quickly brushed over? Snapping and other OS features will be the subject of our next quickstart.

If you have any questions, comments, or feedback feel free to join in the discussion.

Twitter: @rickbarraza, @joelmartinez

Binding the Interface in Windows Store apps

Rick Barraza — Wed, 26 Sep 2012 19:52:54 GMT

In the previous Quickstarts, we have introduced the app and looked at handling data requests and formatting. In this next video, we will look at binding that data to the interface.

Binding and Windows 8 Templates

Data binding plays a central role in the Windows Store project templates available in Visual Studio 2012. For our project, we used the Grid App template available in Visual Studio 2012 as our base for the Khan Academy app. So let's see how this template is setup.

As we discussed in the first Quickstart of this series, creating a new project based on the Grid template will populate your project with sample pages and assets, a common folder of useful classes, and a data folder with a view model all ready to go. The default XAML pages such as GroupedItemsPage.xaml will also be wired up as they will inherit from LayoutAwarePage.cs in the Common folder to common system events of initialization, navigation and orientation.

But also notice the inclusion of a new class called BindableBase.cs in the Common folder. The default Data Model comes with every Template project inherits its collection elements from this class and by studying how the sample pages are wired up to the default Data Model is a great way to get up to speed quickly on Data Binding basics in Windows 8.

Let’s take a closer look at the Data Model for a Grid App Template project, DataModel\SampleDataSource.cs. This class has a collection of Groups in an ObservableCollection called AllGroups. Each group in AllGroups contains an ObservableCollection of DataItems. Both the SampleDataGroup and SampleDataItem inherit from the SampleDataCommon class.

The SampleDataCommon class, in turn, inherits from Common\BindableBase.cs, which we introduced above, and which allows all the objects to be bound by the UI controls.

SampleDataSource.cs

public abstract class SampleDataCommon : AppName.Common.BindableBase

In this Grid App Template, when the app first starts and App.xaml loads the landing page called GroupedItemsPage.xaml, the following code is run:

GroupedItemsPage.xaml.cs:

protected override void LoadState(
    Object navigationParameter,
    Dictionary pageState)
{
    var sampleDataGroups = SampleDataSource.GetGroups(
        (String)navigationParameter);
    this.DefaultViewModel["Groups"] = sampleDataGroups;
}

In this template sample, we create our Data Model by calling the SampleDataSource’s GetGroups() function, which returns an IEnumerable of SampleDataGroup values. This bindable collection of Groups is then assigned to the DefaultViewModel's Group element.

But what is a DefaultViewModel[“Groups”] element anyway? Remember, these UI Pages we are exploring in the Template project all inherit from Common\LayoutAwarePage.cs:

GroupedItemsPage.xaml.cs

public sealed partial class GroupedItemsPage
    : AppName.Common.LayoutAwarePage
{
    public GroupedItemsPage()
    {
        this.InitializeComponent();
    }
    […]

And here we see the true power of leveraging the Windows Store Project Templates as a basis for projects. LayoutAwarePage.cs is a robust implementation of a Windows 8 app page that provides several important conveniences: app view state to visual state mapping, page navigation event handlers and mouse and keyboard shortcuts, state management for navigation and process lifetime management, and most relevant to us right now, a default view model too:

public LayoutAwarePage()
{
    if (Windows.ApplicationModel.DesignMode.DesignModeEnabled)
        return;
 
    // Create an empty default view model
    this.DefaultViewModel =
        new ObservableDictionary();   
    […]

The last piece of the puzzle for binding is found in the resources of the page:

GroupedItemsPage.xaml

Here, a CollectionViewSource is being bound to the Groups element of the DefaultViewModel, which we just set to the response of SampleDataSource.GetGroups(). A CollectionViewSource allows you to sort, filter and group the underlying data without directly manipulating the data.

Finally, the control on the page that will display the information has its ItemsSource property bound to the groupedItemsViewSource, which is a CollectionViewSource.

XAML

Since there are no custom styles yet, the Item Template pulls from some standard templates also found in the Common folder to make everything work. If the CollectionViewSource has properly grouped data and the IsSourceGrouped property is set to true, the GridView takes care of the rest.

The Khan Academy View Model

In the Khan Academy app, we follow a very similar pattern with a couple of changes.

First, as we’ve seen in the previous two Quickstarts, we are instantiating our KhanDataSource View Model from App.xaml directly in it’s LaunchApp() handler and then passing it along when we navigate to our landing page of choice.

App.xaml.cs

public async void LaunchApp(
     ApplicationExecutionState previousExecutedState)
{
     DataSource = new KhanDataSource();
     await DataSource.LoadAllData();
     var rootFrame = new Frame();
[…]
     if ( rootFrame.Content == null)
     {
          if ( !rootFrame.Navigate(
               typeof(HubPage),
               JsonSerializer.Serialize(DataSource.TopicGroups)))
          {
               throw new Exception(“Failed to create initial page”);
          }
     }
     Window.Current.Content = rootFrame;
     Window.Current.Activate();
}

When HubPage.xaml.cs, receives our Data Model upon initialization in its LoadState() handler, it uses this Data Model for its own local binding as shown below:

HubPage.xaml.cs

protected override void LoadState(
     Object navigationParameter,
     Dictionary pageState)
{
     ObservableCollection items =
          JsonSerializer.Deserialize>(
               navigationParameter as string);
     this.DefaultViewModel[“Groups”] = items;
     this.groupGridView.ItemsSource = items;
}

Another difference between the KhanDataSource and the default SampleDataSource that comes with Template projects is an additional tier of data. Instead of having a simple collection of groups that contain items, the data returned from Khan Academy is organized by the app into top level Topics ( such as Math, Science, Hummanities, etc.), which each contain a collection of playlists ( Algebra, Arithmetic, Calculus, etc..). Each of these playlists is made up of a series of VideoItems that play the actual lessons.

To add an additional layer of complexity, to achieve a Hub experience in our welcoming page, we wanted to display multiple types of content to give the user a richer selection of items. However, having multiple types of content on the same container creates both a visual and navigational challenge.

For example, most of the groups displayed in HubPage.xaml are made up of playlist objects that have a title and description but no associated graphic.

Selecting a playlist object should take you to the ItemDetail.xaml page.

But we also wanted to feature at a top level videos from two specific playlists, New & Noteworthy and Talks & Interviews. These videoItems do have a associated thumbnail of the video they represent and clicking on these elements should take you to the VideoPage.xaml instead of the ItemDetail.xaml page.

We will discuss how we visually differentiate the styling of these two different types of objects in the next Quickstart. But for now, let us look at how we handle the Items being selected:

void ItemView_ItemClick(object sender, ItemClickEventArgs e)
{
    if ( e.ClickItem.GetType() == typeof(PlaylistItem))
    {
        this.Frame.Navigate(
            typeof(ItemDetailPage),
           JsonSerializer.Serialize(e.ClickedItem));
    }
    else if ( e.ClickedItem.GetType() == typeof(VideoItem))
    {
        this.Frame.Navigate(
            typeof(VideoPage),
            JsonSerializer.Serialize(e.ClickedItem));
    }
}

Since we are sharing a data binding between two different types of content, we query the type of the item and pass the clicked item to the appropriate page.

If the user selected a video, we would go to the video player page which uses the video player from the Microsoft.Metro.PlayerFramework referenced in the Project. Selecting a playlist, though, takes you to the ItemDetailPage.xaml to show you the list of videos in that list. The data binding on the ItemDetailPage.xaml page works the same way once it receives the serialized ClickedItem as a navigationParameter in its LoadState() method.

protected override void LoadState(
    Object navigationParameter,
    Dictionary pageState)
{
    PlaylistItem playlist =
        JsonSerializer.Deserialize(
            navigationParameter as string);
    this.DefaultViewModel[“Group”] = playlist;
    this.DefaultViewModel[“Items”] = playlist.Videos;
}

The other pages in the Khan Academy app follow the same pattern. An item is selected, the app's Frame then Navigates to the appropriate Page, passing the selected item as a parameter, and finally the loaded Page parses the passed in object, and populates its local View Model with the appropriate data.

Now that our components are displaying the appropriate data and navigating to the correct Pages, it's time to add visual identity. In the next Quickstart, we will look at custom styling.

If you have any questions, comments, or feedback feel free to join in the discussion.

Twitter: @rickbarraza, @joelmartinez

Handling Asynchronous Data in Windows Store Apps

Rick Barraza — Wed, 26 Sep 2012 19:52:40 GMT

This video covers the basics of working with data in the Windows 8 Khan Academy app. We go over the new asynchronous pattern in WinRT for handling requests to and from the server, as well as putting together the Data Model for our app.

If you have never worked with async patterns before, the following async overview may be helpful before proceeding with our Khan Academy samples.

An Overview of Async / Await

As referenced above, asynchronous APIs are found all over the Windows 8 runtime and they are a key concept in Windows 8 app development. We have already seen the async / await pattern in action in the first Quickstart of this series when discussing the LaunchApp() method on startup:

App.xaml.cs

public async void LaunchApp(
     ApplicationExecutionState previousExecutionState)
{
     DataSource = new KhanDataSource();
     await DataSource.LoadAllData();

Notice the use of the async keyword in the method’s declaration. Since this method is going to use an await operator for an asynchronous task, we need to use the async keyword in the declaration. In our case, we use await after we create our Data Model named DataSource and request it to populate itself by calling its LoadAllData() function. LoadAllData() handles both local and remote requests for Khan Academy video playlist data.

The Windows 8 Khan Academy video app ships with a cached snapshot of the entire playlist library stored locally. This keeps the UI fast and fluid since the app doesn’t need to request and parse the entire collection of videos from the internet before launching for the first time. Each time the app runs, though, the KhanDataSource.LoadAllData() function in our Data Model also makes a call to the Khan Academy server and updates the local cache with any updates behinds the scenes, before reloading the local data to update any bindings.

LoadRemoteData() is also implements the async/await pattern and is shown below:

private async void LoadRemoteData()
{
     HttpClient client = new HttpClient();
     client.MaxResponseContentBufferSize = Megabyte * 20;
     HttpResponseMessage response = await client.GetAsync(
          new Uri(“http://www.khanacademy.org/api/v1/topictree”));
     await WriteLocalCacheAsync(
          await response.Content.ReadAsStringAsync(),
          @”cache\topictree”);
     await LoadCachedData();
}

LoadRemoteData() first creates and qualifies an HttpClient object but then needs to await the asynchronous HttpResponseMessage from the server before continuing. So far, this is a straightforward async/await pattern.

But some tasks may require a nesting of await commands to complete the desired transaction. We can see this in the code once we want to write the response locally. In order to write to the local cache, which is itself an async operation, we first need to read the response as a string, which also requires an await command:

await WriteLocalCacheAsync(
     await response.Content.ReadAsStringAsync(),
     @”cache\topictree”);

Once the local cache has been updated with the most recent data retrieved from the Khan Academy web servers, we refresh the local Data Source from this updated cache.

In the Khan Academy Windows 8 app, the majority of code that handles the asynchronous data is contained in the KhanDataSource.cs file and follows the similar structure as shown above.

Handling the JSON Response

As we saw in the previous section, the Khan Academy app keeps the local cache of app data up to date by overwriting the local cache with updated JSON data from the Khan Academy servers.

With Windows 8, there are multiple ways of processing JSON data, based on your needs and situation. For our scenario, we knew the shape of the data being returned by Khan Academy, so we first created a custom class that would represent each logical node of the response:

[DataContract]
public class JsonNode
{
     [DataMember(Name = “children”)]
     public JsonNode[] Children { get; set; }
     [DataMember(Name = “kind”)]
     public string Kind { get; set; }
     [DataMember(Name = “ka_url”)]
     public string Url { get; set; }
     [DataMember(Name = “title”)]
     public JsonNode[] Title{ get; set; }
     [DataMember(Name = “description”)]
     public string Description { get; set; }
     […]
}

When it is time to read this locally cached JSON response, we invoke the following method and pass in our custom class type:

KhanDataSource.cs

private async Task LoadCachedData()
{
    JsonNode cached = await ReadLocalCacheAsync(
        @"cache\topictree.json",
        @"data\topictree.json");
    PopulateGroups(cached);
}
private static async Task ReadLocalCacheAsync(
    string filename,
    StorageFolder folder)
    where T : class
{
    try
    {
        var file = await folder.GetFileAsync(filename);
        string result = await FileIO.ReadTextAsync(file);
        var serializer = new DataContractJsonSerializer(typeof(T));
        var memStream = new MemoryStream(
            Encoding.UTF8.GetBytes(result));
        var serializedResult = serializer.ReadObject(memStream) as T;
        return serializedResult;
    }
    catch (FileNotFoundException)
    {
        return default(T);
    }
}

As you can see, ReadLocalCacheAsync creates a new DataContractJsonSerializer of the type specified. The string result of reading the local cache file is wrapped in a MemoryStream and passed to the JSON serializer. Once serialized, we have an object representation of the cached text data. The cached response is then sent to the PopulateGroups() function to update our Data Model.

If we look at the first part of the PopulateGroups() function, you'll see how we are using LINQ to pull out a properly formatted collection of elements for use in our Data Model.

private void PopulateGroups(JsonNode root)
{
    if (root == null) return;
    Func videoClause = v => v.Kind == "Video";
    Func topicClause = c => c.Kind == "Topic";
    var playlists = root.Children 
        .SelectMany(group => group.Children.Where(topicClause)
                        .Flatten(g => g.Children.Where(topicClause))
                        .Select(k => new PlaylistItem
                        {
                            Name = k.Title,
                            Description = k.Description,
                            Slug = group.Title,
                            SourceNode = k
                        })
                        .OrderBy(k => k.Slug));
    […]
}

Populating the Data Model

The Khan Academy API returns a series of playlists, made up of video items. However, the content of these playlists spans many different academic topics, so we want to make sure we further organize the playlists according to these topics. Here is a part of the Class Diagram to illustrate the relationship.

If we look at the last part of the PopulateGroups() method , the videos are subsequently organized under their individual playlists. This ungrouped collection of populated playlists is then sent to CreateGroups() which organizes them into their respective Topics. The relevant code looks like this:

private void PopulateGroups(JsonNode root)
{
    […]
    foreach (var playlist in playlists)
    {
        // now load all the videos
        var videos = playlist.SourceNode
            .Children
            .Flatten(v => v.Children);
        foreach (var video in videos.Where(videoClause).Select(
            v => new VideoItem
            {
                Name = v.Title,
                Description = v.Description,
                ImagePath = v.Downloads != null ?
                              new Uri(v.Downloads.Screenshot) : null,
                VideoPath = v.Downloads != null ?
                              new Uri(v.Downloads.Video) : null,
                KhanPath = new Uri(v.Url),
                Parent = playlist.Name,
                DateAdded = DateTime.Parse(v.DateAdded)
            }))
        {
            playlist.Videos.Add(video);
        }
    }
    if (playlists.Count() > 0)
    {
        SortGroups(
            TopicItem.CreateGroups(
                playlists.Where(p => p.Videos.Count > 0)));
    }
}
public static IEnumerable
CreateGroups(IEnumerable ungroupedPlaylists)
{
    var grouped = ungroupedPlaylists
        .GroupBy(i => i.GroupKey)
        .Select(g => new TopicItem(g.Key, g.Key + " description")
        {
            ListSetter = g
        });
    var res = grouped
        .OrderBy(i => i.Order)
        .ThenByDescending(i => i.Playlists.Count);
    return res;
}

In this way, we are able to get unsorted JSON data from Khan Academy and organize it into a series of classes that represent the actual videos, their topical playlist and their high level, academic grouping of topics. All this information is stored in ObservableCollections which we will bind to the UI in the next Quickstart.

If you have any questions, comments, or feedback feel free to join in the discussion.

Twitter: @rickbarraza, @joelmartinez

Setting Up Your Windows Store App Project

Rick Barraza — Wed, 26 Sep 2012 19:52:18 GMT

This video covers the basics of setting up a Windows Store app project in Visual Studio 2012 for the Windows Phone 7 app we are going to migrate. We also discuss the migration strategy, scoping the features within the port, and the advantages of using a Windows Store project template as our solution base. For more information on migration, please visit the Migrating a Windows Phone 7 app to a Windows Store app guidance.

The final source code for the WIndows Store App Viewer for Khan Academy is available for download.

Installing the Developer Tools

You can download and install everything necessary to follow along as we build the Windows Store project in this series. However, you must first install a copy of Windows 8. To view and build the project files, you will also need to download Microsoft Visual Studio Express 2012 for Windows 8.

The Khan Academy Phone App

To show the migration in action, we will use the open source Khan Academy Windows Phone 7 app, developed by Joel Martinez. This app retrieves a list of video playlists from the Khan Academy website and lets the user watch them. Our Windows 8 Store app will be called “Viewer for Khan Academy”.

If you’re not familiar with Khan Academy, they are a “not-for-profit organization with the goal of changing education for the better by providing a free world-class education for anyone anywhere.” Their website, www.khanacademy.com hosts thousands of videos over a wide collection of topics and are offered freely to anyone with an interest in learning. They support Open Source data and have a rich collection of APIs that expose their library to the developer community as well.

Joel Martinez is a mobile app developer who created a popular Windows Phone 7 app that accesses this rich collection of videos. By providing his original Windows Phone 7 viewer of Khan Academy app as an Open Source project and writing about the process extensively on his blog at http://www.codecube.net, he has helped developers learn the basics of Windows Phone 7 development leveraging public videos found online.

If you have a Windows Phone and want to try out the original Windows Phone 7 version, you can download it from the Windows Phone Store. The app's source code is also available for download.

The Windows Phone app was developed in Silverlight so uses XAML for its interface syntax with C# code behind. When the app is first run, it calls the public Khan Academy APIs which return a collection of video playlists. In the phone app, these playlists are not organized by topic:

Selecting a playlist brings up a collections of videos, which when clicked send the user to the video player on the phone to stream in the video content:

Joel Martinez developed the phone app with solid logical abstraction following an MVVM pattern. The Phone app also leverages both network calls to the Khan Academy APIs as well as local storage of retrieved data for improved responsiveness:

If requested data has not previously been retrieved and stored locally, the app makes a request to the cloud and stores the data in IsolatedStorage. Updating local storage data with cloud responses is done in the background.

Determining the Migration Strategy

When porting a Silverlight for Windows Phone 7 app to Windows 8, there are several considerations you should take into account. Do you want to migrate as quickly as possible, or do you want to invest more time in the new features Windows 8 makes available? Are you going to want to share as much reusable code as possible, or maintain different solutions per platform? How greatly will the User Interface be affected as you migrate from a smaller form factor to a larger tablet or desktop Interface?

In our case, the Windows Phone app relies heavily on hitting the Khan Academy servers and requesting data as discussed above. It also makes use of Windows Phone's IsolatedStorage. C# 5.0 introduced two new keywords async and await and this Async Pattern is used extensively in modern Windows 8 apps for handling I/O functions. Since our app uses these types of commands extensively, this would be a big change.

While it is possible to convert synchronous methods written in C# that do I/O internally to functions that return Task to a task continuation middle man, this method would be inherited more from the current .NET way of handling asynchronous tasks. We decided to invest in learning the modern asynchronous pattern implementations in WinRT for both handling server requests and storing app specific data. The Async / Await pattern is a significant addition to how all developers will be creating Windows 8 apps moving forward, so after our early explorations, we decided to create a fresh code base.

If your phone app does not use extensive I/O code that would benefit from the new Async / Await pattern, you may wish port primarily your models and view models, versus starting from scratch as outlined in such MSDN articles as http://msdn.microsoft.com/en-us/library/windows/apps/hh465136%28v=VS.85%29.aspx.

However, in either case, it is recommended that you don't try and bring over your XAML UI files directly. We discuss this further below.

Scoping the Solution

Once we determined a migration strategy for the existing Phone features, we wanted to see what benefits the new form factor and platform would afford. A core design principle for Windows 8 apps is “Winning as One”. This means that to the degree you app can leverage common features provided in the operating system and implemented consistently across apps, the greater the overall experience for the user will be. To that end, the Windows 8 operating system introduces Contracts and other features that apps can leverage to extend their functionality and provide a consistent, polished experience for their users.

While staying true to the functional goals of the phone app, there were three Contracts we wanted to leverage in the port to Windows 8. Since Khan Academy contains thousands of videos that cover a wide range of topics, exposing this data in our viewer through a Search Contract was essential. Once the app has loaded a video, the ability to send a link to a someone also made a lot of sense, so we would add this through the Sharing Contract. Since the primary content of the app are videos, leveraging the PlayTo Contract would allow the user to enjoy the experience on a larger screen if available.

Other than taking advantage of the Contracts made available through Windows 8, we wanted to keep the core functionality similar between phone and tablet. However, we decided to aggregate the information a little better in the Windows 8 version and group the playlists together by topic, something that is missing in the simple list interface of the Phone app.

Working with the Project Templates

To whatever degree you want to tweak versus rewrite your code, your XAML files are a different matter. The general advice is to start fresh, preferably from one of the new Windows 8 Project Templates found in Visual Studio, and then bring in the relevant UI elements under the root node. There are several reasons for this.

For one thing, the platform changes how navigation is handled. While on Windows Phone, navigation is usually handled with the NavigationService object, in Windows 8 it is primarily handled through Frames and Pages. Also, all the form factor considerations of Windows 8, including snapping, orientation and variable resolution support, require a common structure that doesn't exist in Windows Phone. If your existing phone app was designed with good view models and proper use of MVVM patterns, this UI migration will be much easier.

The best way to understand the differences between UI design from Windows Phone to Windows 8 is to open up the blank templates for Windows 8 Applications in Visual Studio 2012 and see how they work. We chose the Grid App template as the basis for our migration project.The Grid App template is a multi-page project that navigates among groups of items, so this template worked perfect for our list of Khan Academy videos.

There are several advantages of using a Windows Store Template as your starter project, instead of simply creating a “Blank Project” in Visual Studio. These include:

A Common Folder that comes packed with very usefull classes and assets to assist in Windows 8 app development, including BindableBase.cs.
Common\LayoutAwarePage.cs from which you can inherit your pages and have instant hooks into the system events when dealing with snapping, rotation and orientation.
Common\StandardStyles.xaml which gives you a default template on which to extend your app styles and templates.
A DataModel folder with provides a strong foundation for data binding and MVVM architecture for your app.

Unlike Windows Phone apps which handle navigation through a URI based navigation service, Windows 8 handles initialization and navigation through frames and container view models.

If you create open up a new Grid App Template, you will notice an App.xaml file. This is the first page loaded when a Windows 8 app stats. App.xaml.cs in turn calls its LaunchApp() function to direct the app to whatever startup page you wish to present.

We took this opportunity to create our data model for the app. With our KhanDataSource created, the common initialization practice is to create a Frame and use it to navigate to your startup page, passing along your Data Model if applicable. In our case, our startup page will be HubPage.xaml. Both the XAML elements of HubPage.xaml and the structure of our Data Model, KhanDataSource will be analyzed more in the next Quickstarts.

public async void LaunchApp(
     ApplicationExecutionState previousExecutedState)
{
     DataSource = new KhanDataSource();
     await DataSource.LoadAllData();
     var rootFrame = new Frame();
[…]
     if ( rootFrame.Content == null)
     {
          if ( !rootFrame.Navigate(
               typeof(HubPage),
               JsonSerializer.Serialize(DataSource.TopicGroups)))
          {
               throw new Exception(“Failed to create initial page”);
          }
     }
     Window.Current.Content = rootFrame;
     Window.Current.Activate();
}

All the C# templates and most apps will follow this same routine. When an app is launched, App.xaml fires its LaunchApp() event. If a Data Model is required, it may be created at this time and loaded from data either locally or from the cloud, and get passed into the startup page of your app for data binding to the UI. During the subsequent series of Quickstarts, we will look closely at each of these steps and how we implemented them in the Windows Store Khan Academy App.

There are also some great posts on Dev Center that dive deeper into general migration strategies if you want to research the specifics of this topic further:

In the next Quickstart, we'll jump straight into working with data and the new asynchronous pattern in Windows 8.

If you have any questions, comments, or feedback feel free to join in the discussion.

Twitter: @rickbarraza, @joelmartinez