Shawn Burke's Blog

Using AgFx with OAuth

Shawn Burke - MSFT — Tue, 26 Apr 2011 16:49:00 GMT

New Release

First, if you wander on over to the AgFx CodePlex site, you'll see that there is a new release up. There's some new things in this new release such as some statistics about the performance of your application, the ability to specify exact cache expiration, and some bug fixes. The majority of feedback that I have gotten has been feature requests or "how do I?", and few in the way of bug reports. So it's working well for most people, hopefully that continues. Please file bugs if you find them!

All of the below references the code sample that you can find in the CodePlex source tree at AgFx\Samples\Facebook.Auth.Sample.

OAuth with Facebook and AgFx on Windows Phone 7

Something applications commonly want to do is to use Facebook as their credentials system instead of hand-rolling one. For many types of applications this makes good sense, but it turns out that integrating a Windows Phone 7 application with Facebook can be a bit challenging.

So with this release, you'll see a new sample called Facebook.Auth.Sample that gives you a template to start from that will hopefully make your life easier.

In case you're new to OAuth, it's basically a way to establish credentials without allowing the calling application to ever see a username or password. So instead of some kind of a web service call like service.login(username, password), instead you have a bit of a round-about pattern that looks like the following:

The calling application directs a web browser to an auth url. Imagine something like http://www.somesite.com/oauth?appid=12345&redirect_uri=http://www.myapplication.com/authcomplete
The user enters the SomeSite credentials into the web page and submits.
If the credentials are correct, SomeSite issues a redirect to something like http://www.myapplication.com/authcomplete#access_token=ABCD1234&expires_in=3600.
For mobile appliacations "authcomplete" may be a dummy URL, it's just there as away to get the values. So the application traps the Navigating event on the browser, sees the token, grabs it off of the URL, and ends the process. What the application really cares about is access_token. In the case of Facebook, they have a landing page called login_success.html that we can use without having to set up a server.

Because there isn't a direct service call here, AgFx isn't set up to really handle this process. It wants a URL to call and a response to parse. We can't do that, but it's still nice to use the caching and databinding-friendly features of AgFx, so we can craft a hybrid solution.

The strategy is basically as follows:

Complete the process above for Facebook
Once we have a token and expiration time, stash it on a LoadContext for our FacebookLoginModel (derives from LoginModel)
Have AgFx kick off a Load for that load context.
Instead of returning a WebLoadRequest, which fetches a URL, we create a custom LoadRequest (FacebookLoadRequest) that just serializes the token/expiration into a Stream and returns that.
The result of that load will be an instance of FacebookLoginModel with the Token available for us to call, and now AgFx has data that it can manage via the regular caching mechanism.

With that in hand, we're in good shape, and we can start making other calls out to Facebook. It is a little goofy that we take data that we have in hand, write it to a stream, and just read it back out again. But OAuth itself is a bit odd compared to the rest of the direct call APIs out there. So this is the price we pay. It's a small one.

Take a look at FacebookLoginModel for details of how this dance works.

Login UI with PhoneApplicationFrameEx

PhoneApplicationFrameEx has a property on it called "PopupContent". This content will be shown over the top of the UI (e.g. over the current Page) whenever IsPopupContentVisible is set to true.

We can use this to make the login UI show automatically whenever the user is not logged in, and disappear automatically when a login succeeds. If you look in the samples App.xaml.cs, you'll see the following:

// Here we set up the frame binding.

//

// the below says:

//      "When the FacebookLoginModel.Current.IsLoggedIn property is FALSE, 

//       set the PhoneApplicationFrameEx.IsPopupVisible to true.  Or vice-versa."

//

RootFrame.PopupContent = loginView;

Binding b = new Binding("IsLoggedIn");

b.Source = FacebookLoginModel.Current;

b.Converter = new NotConverter();

RootFrame.SetBinding(PhoneApplicationFrameEx.IsPopupVisibleProperty, b);

Which basically takes the FacebookLoginModel.IsLoggedIn property and binds it's opposite to the IsPopupVisible property on the Frame. So, when the app starts for the first time, no cached creds will be available, and the login UI will show.

In the sample, the login UI is pretty much just the WebBrowser control, but I added an overlay that updates status when navigations and processing is happening.

See FacebookLoginView in the sample:

Upon logging in, the app fetches the full name of the user that logged in.

Making Service Calls

Once we are logged in, making service calls is easy. In the case of the sample, there is a very basic ViewModel called FacebookUser. By default, I just call the "me" user, which returns the information for the logged in user. It works like a standard AgFx model, and here's an example of it's GetLoadRequst:

public LoadRequest GetLoadRequest(LoadContext loadContext, Type objectType) {



    // abort if we don't have a token.

    //

    if (!FacebookLoginModel.Current.IsLoggedIn) {

        return null;

    }



    // build the "me" url including the auth token.

    //

    string meUri = String.Format("https://graph.facebook.com/{0}?access_token={1}", loadContext.Identity, FacebookLoginModel.Current.Token);



    return new WebLoadRequest(loadContext, new Uri(meUri));

}

And in Deserialize, you'd typically want to use a JSON parser to pick out the data, which comes back from Facebook as JSON. For brevity in the sample, I'm using a Regex, which is not an industrial strength solution! In this case, the only value we grab is the user's full name, which then ends up bound into the UIs.

All calls you make should access the FacebookLoginModel.Current.Token property to access the access_token, and a good pattern to handle log outs and other errors is to create a base DataLoader (like FacebookDataLoaderBase, for example), that has unified handling for errors and scenarios where the token has expired. If that's the case, you have one place to go clear the login state. Which, if you may have guessed, will automatically pop the login UI. Then derive your model DataLoaders from that type and do your model-specific processing.

Challenges Along the Way

Getting this to work was a bit harder than I expected, so I'm glad I took the time to work through the scenario.

There were three issues:

On a redirect, the Windows Phone 7 WebBrowser control has a bug that strips everything after the #. If you'll look up at the OAuth process, you'll see that there's a hash at step 3. This is a big problem because we lose the exact information we need. There is a workaround, but involves an extra redirect, and worse than that, involves needing to have the app's secret embedded in the code. I'm making sure this gets fixed for the next phone release.
Logging out of Facebook turns out to be challenging. If you search the web for "Facebook OAuth logout", you'll find lots of long, complicated threads of people trying to solve this problem. The issue is that there isn't a clean way of killing an access_token. So what happens is that you tell AgFx to logout and clear the LoginModel state, then redirect the web browser to the oauth page, and it just logs you right back in again because of a browser cookie that's hard to get to. After a fair amount or wrestling, I managed to detect this case and then redirect to http://www.facebook.com/logout.php, wait for that to complete, then to back to the auth page. That seems to work, but I'm not in love with the solution.
There are hiccups in the Facebook OAuth process. For example, if the user is logging in from a device for the first time, they will be directed to the Facebook page that lets you name the device. Unfortunately this doesn't perisist the redirect so the process dies. With some more code you could work around this, but if you don't, the user ends up on their home page.

The sample project handles both of these cases so you can use it as a template for your own Facebook or other OAuth integrations. I believe that Facebook uses standard OAuth, so it should port to another service cleanly, but I have not verified this. The pattern should be about the same.

AgFx now on CodePlex

Shawn Burke - MSFT — Fri, 01 Apr 2011 22:33:00 GMT

Today, the CodePlex AgFx site went live, with a new updated release.

Quite a few folks are now building Windows Phone 7 apps on AgFx and are having good luck with it.

I’ve written a few more walkthroughs and detail pages on the documentation tab, and the release now includes a help CHM file.

Along with some bug fixes the Release on CodePlex adds:

The ability to manually push items into the cache with the DataManager.Current.Save method
Helper classes for handling login and credentials management with AgFx (AgFx.Controls.Phone.Authentication)
A derived PhoneApplicaitonFrame type (creatively named PhoneApplicationFrameEx) that gives support for
- An app-wide header area for something like a loading progress bar
- A PopupContent property that makes it easy to pop UI over the current page for things like login or “Loading…” UI.
A CachePolicy of CachePolicy.Forever that keeps things in the cache indefinitely.

There are some additional features in the tree that didn’t make it into the initial release as well:

The ability for model items to specify their cache duration. Before this had to be statically declared as part of the CachePolicyAttribute. Now an object can override that and provide an exact time for it’s cache to expire. If CachePolicy.AutoRefresh is specified, a reload will happen automatically at that time.
AgFx knows a lot about what your app is up to, so I added some functionality to keep some statistics around that info. AgFx will build a report on this data for you on-demand, and it gives you a lot of insight into what your apps is up to:

To enable this, I just need to write the following code at startup.

DataManager.ShouldCollectStatistics = true;

And everything happens automatically. I can fetch the data as follows:

StringWriter writer = new StringWriter();
AgFx.DataManager.Current.GetStatisticsReport(writer, false);
writer.Flush();
string output = writer.ToString();

Here is an example of the output for the sample NWS weather application. In this case, I started the app, requested weather for a few different zip codes, closed the app, then did a few more request, some new, some repeated.

As you can see I get a lot of data about my network requests (called “fetch”) below, my deserialization, and how many objects of each type I was managing.

Totals:
    Total Instances: 6
    Total Requests: 10
    Total Fetches: 5
    Total Fetch Failures: 0
    Total Deserialization Failures: 0
    Cache Hit Rate: 0.50
    Average Fetch Time: 546.1ms
    Maximum Fetch Time: 2780.0ms (Object Type=WeatherForecastVm, ID=98109)
    Average Deserialize Time: 19.8ms
    Maximum Deserialize Time: 84.0ms (Object Type=WeatherForecastVm, ID=98112)
    Average Deserialize Size: 7287.5 bytes
    Maximum Deserialize Size: 14437 bytes (Object Type=WeatherForecastVm, ID=98033)
Statistics for NWSWeather.Sample.ViewModels.WeatherForecastVm:
    Total Instances: 3
    Total Requests: 4
    Total Fetches: 3
    Total Fetch Failures: 0
    Total Deserialization Failures: 0
    Cache Hit Rate: 0.33
    Average Fetch Time: 997.5ms
    Maximum Fetch Time: 2780.0ms (Object Type=WeatherForecastVm, ID=98109)
    Average Deserialize Time: 29.7ms
    Maximum Deserialize Time: 84.0ms (Object Type=WeatherForecastVm, ID=98112)
    Average Deserialize Size: 14351.7 bytes
    Maximum Deserialize Size: 14437 bytes (Object Type=WeatherForecastVm, ID=98033)
Statistics for NWSWeather.Sample.ViewModels.ZipCodeVm:
    Total Instances: 3
    Total Requests: 6
    Total Fetches: 2
    Total Fetch Failures: 0
    Total Deserialization Failures: 0
    Cache Hit Rate: 0.67
    Average Fetch Time: 94.7ms
    Maximum Fetch Time: 195.0ms (Object Type=ZipCodeVm, ID=98109)
    Average Deserialize Time: 10.0ms
    Maximum Deserialize Time: 29.0ms (Object Type=ZipCodeVm, ID=98112)
    Average Deserialize Size: 223.3 bytes
    Maximum Deserialize Size: 224 bytes (Object Type=ZipCodeVm, ID=98033)

Notice how much faster the Zip Code service is that the Weather Service! Of course, it’s a lot less data.

Enjoy!

My Visual Studio snippets

Shawn Burke - MSFT — Tue, 29 Mar 2011 22:58:00 GMT

One of the great features of Visual Studio, that’s been around for a while is snippets. Frankly, I should build more of these because I use them *so* often.

I find them so useful I thought I’d share them here, either for you to use or to template into ones of your own.

Firs t,when building templated controls I write this a lot:

[TemplatePart(Name = ElementContent, Type = typeof(FrameworkElement))]

And it’s not just that, I then have to create a constant to define “ElementContent” and then usually load that value into a member variable as part of OnApplyTemplate.

So I built a snippet that builds this stuff out for me, resulting in this:

    [TemplatePart(Name = ElementContent, Type = typeof(FrameworkElement))]
    //private const string ElementContent = "Content_FrameworkElement";
    //private FrameworkElement _Content;
    //_Content = (FrameworkElement)GetTemplatePart(ElementContent);

Which gives me some extra code commented below that I can just copy down into the class. Nice!

Building snippets is easy, it’s just an XML format. It works great, just add the folder to VS via the Snippet Manager (Tools –> Code Snippets Manager).

In my case, I have a snippets folder on Live Mesh that gets replicated to all the places I write code, so I always have my snippets.

For the snippet above, the xml looks like this:

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets  xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>Template Part Declaration</Title>
      <Shortcut>template_part</Shortcut>
      <Description>Template Part Decl</Description>
      <Author>Shawn Burke</Author>
      <SnippetTypes>
        <SnippetType>Expansion</SnippetType>
      </SnippetTypes>
    </Header>
    <Snippet>
      <Declarations>
        <Literal>
          <ID>name</ID>
          <ToolTip>Template Part Name</ToolTip>
          <Default>PartName</Default>
        </Literal>
        <Literal>
          <ID>type</ID>
          <ToolTip>Element Type</ToolTip>
          <Default>type</Default>
        </Literal>
      </Declarations>
      <Code Language="csharp">
        <![CDATA[
 
        
        [TemplatePart(Name = Element$name$, Type = typeof($type$))]
        //private const string Element$name$ = "$name$_$type$";
        //private $type$ _$name$;
        //_$name$ = ($type$)GetTemplatePart(Element$name$);
 
 
$end$]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

It’s pretty simple, I’ve highlighted the interesting parts. There are much fancier things you can do with snippets which I should probably learn.

Here’s a list of the ones I use regularly, and a zip of all of them attached to this post.

Create an INotifyPropertyChanged class implementation – inpc_impl
Create a property that raises a INotifyPropertyChange.PropertyChanged event – inpc_prop (I probably use this one the most)
Create a Silverlight/Phone formatted Dependency Property with a change handler – propdpsl
Create a template part attiibute (above) – template_part
Create a template visual state attribute – template_visualstate
Create a wrapper for an async call to an Service Reference proxy – svca

The last one generates this code, for a method called GetComments, which gives me nice lambda handlers for success and error cases, which is the pattern I use for most calls to a generated proxy.

    public void GetComments(string postId, Action<IEnumerable<Comment>> success, Action<Exception> error) {
            var ws = new BlogServiceClient();

            ws.GetCommentsCompleted += (s, a) =>
            {

                if (a.Error != null) {
                    if (error != null) {
                        error(a.Error);
                    }
                    else {
                        HandleError(ws, "GetComments", a.Error);
                    }
                }
                else {
                    if (success != null) {
                        success(a.Result);
                    }
                }
                ws.Close();
            };
            ws.GetCommentsAsync(postId);
        }

The highlighted parts are template parameters.

Tutorial: Building a connected phone app with AgFx

Shawn Burke - MSFT — Thu, 17 Mar 2011 21:39:00 GMT

Earlier this week I wrote a post detailing the application framework that I’ve been working on, which I’m calling AgFx. I wanted that post to be a bit of an introductory overview,. Now I’m going to dig into detail a bit more, as well as show a bit about how you can use the free Windows Phone 7 Developer tools to quickly create a great application. AgFx does a lot, and one of the apps I used to generate requirements and testing, is Jeff Wilcox’s gorgeous new foursquare™ client: 4th & Mayor, which is built on AgFx.

Jeff and I, along with some others, have written several apps on top of AgFx over the last few months, and have really sharpened it to be exactly what you need when building a connected phone application. And the steps that you use to do it are almost always the same, and I’ll detail them here.

If you’re thinking about writing an app that talks to a web service of any kind, go ahead and follow along with that example in your head.

Below is pretty long and comprehensive, but it is not only a basic tutorial, it is also a summary of some of the broader set of features in AgFx. So it may give you some ideas about how to use AgFx for your next Phone application, or even your current one! We have moved several existing data-connected applications to AgFx and in every case the code becomes smaller, simpler, and better performing.

Step 1: Figure out what data you’ll be using

The first step is to go take a look at the data that the web service offers and how you can process it. In this example case we’ll be using the NOAA National Weather Service REST Web Service.

So we go to the website above an look at what the web service offers. Looking through at their service operations, I see this one:

Summarized Data for One or More Zipcodes

Which sounds about right. Give it a zip code, get back weather data. And there is an example for a query there as well:

http://www.weather.gov/forecasts/xml/sample_products/browser_interface/ndfdBrowserClientByDay.php?zipCodeList=98052&format=12+hourly&numDays=7

We like things that we can easily build a query string from. AgFx supports more complex operations, but these GET queries are a slam dunk. If you click on that link, you’ll get a bunch of XML data. It’s a little hairy, but the data is there so all we need to do is parse it, which is easy enough. OK, weather data: check.

One thing it does not give us, though, is the name of the city for the zip code. It gives us the latitude and longitude, but that’s not that helpful really. We want to be able to display the name of the city for a given zip code, and we can get that from WebServiceX.NET, here.

WebServiceX.net provides an API for converting a zip code into a city and state name.

Basically we call this: http://www.webservicex.net/uszip.asmx/GetInfoByZIP?USZip=98052, and we get this:

<?xml version="1.0" encoding="utf-8"?>
<NewDataSet>
  <Table>
    <CITY>Redmond</CITY>
    <STATE>WA</STATE>
    <ZIP>98052</ZIP>
    <AREA_CODE>425</AREA_CODE>
    <TIME_ZONE>P</TIME_ZONE>
  </Table>
</NewDataSet>

Perfect! City name: check.

Step 2: Define your identifiers and LoadContexts

Now it’s time to start writing the code to talk to the service.

The first thing to think about is the shape of the objects coming back from the service, and what is their unique identifier. In database terms, this would be the primary key. Given that key, I expect to get the correct data back, and that data should be discreet from calls using different keys.

In the weather case, the weather data is basically a set of weather forecast objects. They always come together as a group and this app will never talk to them individually – it’s the collection of objects that makes up the data we care about. We don’t care about addressing the individual forecasts, so the zip code works great as the identifier for our forecast.

For the zip code information, it’s even easier, the data is tied directly to the zip code, so that’s also the unique identifier here.

Before we go on, let’s think of some other examples.

Imagine you were talking to the Flickr service. Flickr has identifiers on almost every object. For example the identifier for my user profile on Flickr is “78467353@N00”. If I was to write a model for my Flickr user profile, I’d use that as my identifier. The same goes for a model that represents my PhotoStream, because that’s tied to my user account. But a model for an individual album or photo would use the id associated with that item. And so on.

This identifer is how you’ll ask for data from AgFx, so that’s why it’s important, we’ll see more about this later:

DataManager.Current.Load<ZipCodeVm>(txtZipCode.Text);

So, back to LoadContext what’s going on with that guy? Good question.

The LoadContext is where I store data that will be used to make a request for my data. For example, if I want to request a photos on Flickr from a photo album, I may want to pass in paging information, or information about how many items to return. The LoadContext is where I would put that information, the reason why will be clear later. LoadContext really exists for more sophisticated cases and in the case of simple requests, like those for the weather app, you won’t need to bother with it much. But you’ll see it in the API so you should understand what it’s for.

Even in simple cases, it also gives you a chance to make things strongly typed.

If you look at the base LoadContext:

  public class LoadContext {
 
        public object Identity { get; }
        public string UniqueKey {get;}
        public LoadContext(object identity) {}       
        
        // .. other stuff
    }

you’ll see the Identity property there is of type object. So in this case, we’re just going to derive and give ourselves a nice strongly-typed property and constructor:

     public class ZipCodeLoadContext : LoadContext {
        public string ZipCode {
            get {
                return (string)Identity;
            }            
        }
 
        public ZipCodeLoadContext(string zipcode)
            : base(zipcode) {
 
        }
    }

One important thing to note here is that the parameter on the constructor should match the type of object you’ll be passing in. In this case, the zip is going to be a string, so there should be a 1-parameter ctor that takes a string. AgFx will look for this to automatically create the LoadContext.

We can reuse this LoadContext for the zip code service as well. Handy!

Step 3: Define your ViewModel object (or model, if you want to do it that way…)

Now that we’ve got the LoadContext, we can create our ViewModel. ViewModels should derive from ModelItemBase<T>, which you’ll want to be familiar with. So let’s look at some of the members you’ll be using:

ModelItemBase.LastUpdated – this property tells you the last time an object’s data was fetched. It will be the same even after the data is loaded from the cache, it only updates when new data is loaded. This property is data-bindable, so you can bind it to a field in your UI to show the user when the data for this particular object was last loaded.
ModelItemBase.IsUpdating - This property is also data-bindable, and flips to true whenever AgFx is loading new data for your object. It doesn’t flip to true for cache loads (those should be fast!), just when it’s loading new data, usually from the network. You can bind this to an “Updating” UI item that you want to be enabled (like a progress bar) or visible only when an update is occuring.
ModelItemBase.Refresh() – This method allows you to refresh any loaded item with new data, at any time before or after it’s expiration date. You can call this in the click handler for a link or a button to cause a data refresh to happen (which, will cause IsUpdating to be true, and then LastUpdated to be changed as part of that process).

ModelItemBase derives from NotifyPropertyChangedBase, which is a default implementation of INotifyPropertyChanged and also adds some helpful functions:

NotifyPropertyChangedBase.RaisePropertyChanged – helper for firing INotifyPropertyChanged.PropertyChanged
NotifyPropertyChangedBase.AddDependentProperty – if you have properties that are dependent on one another, it can be annoying to have to notify property changes from a bunch of different places. This allows you, in the object’s ctor, to declare properties that are dependent on each other. So imagine your ViewModel has a Price property and a Discount property. The price is dependent on the discount, so if Discount changes, then Price will have new value. You want any UI bound to Price to automatically change, so you’d just do this: AddDependentProperty(“Discount”, “Price”), which says that when Discount changes, fire a PropertyChanged notification for Price.
NotifyPropertyChangedBase.NotificationContext – if you have done any work off of the UI thread, you know that you can’t change the properties of UI objects from other threads. Likewise, if you make property changes to an object that is databound to UI, then you also can’t fire change notifications off thread. This property allows the thread switch to happen automatically. Just initialize this property with the SynchronizationContext from the desired thread (typically you just pass DispatcherSynchronizationContext.Current) and you’re done.

Okay, that’s it for ModelItemBase. Let’s create our ViewModel for the weather forecast:

First, let’s create the constructors:

public class WeatherForecastVm : ModelItemBase<ZipCodeLoadContext>   {

 public WeatherForecastVm()  {  }
        
 public WeatherForecastVm(string zipcode): 
        base(new ZipCodeLoadContext(zipcode))   {     }

//...
}

This is pretty simple, but it’s important to note two things:

You must have a default constructor
You should have a constructor that takes your identifier and creates a LoadContext for it. It’s not critical, but you’ll find it helpful.

Okay, now we add some properties to the ViewModel.

Most properties look like this:

private string _city;
public string City
{
    get
    {
        return _city;
    }
    set
    {
        if (_city != value)
        {
            _city = value;
            RaisePropertyChanged("City");
        }
    }
}

Note the “RaisePropertyChanged” call at the bottom, which calls down to NotifyPropertyChangedBase declared above. This let’s the UI know that it should update this value.

For collection properties, things are just a little bit different. When you databind to collection properties, you typically use an ObservableCollection<T> so that any databound UI will automatically update when you make changes to your items. That still works fine here, too, but with a small tweak

For collection properties in your ViewModel, that you should do the following:

Make your collection property read/write. These properties are often just read only but for AgFx it’s much simpler if they are read write.
Don’t replace the value of the collection in the setter, clear your collection, then copy the items over from the new value.

The reason for this is because AgFx knows which instance of your object is bound to your UI, and always updates that instance (it uses the same instance across your application). So when an update happens, it “copies” the property values from the fresh instance into the one currently held by the system. Rather than doing this automatically, because you may want to manage how the copying happens, you’ll typically just do this:

private ObservableCollection<WeatherPeriod> _wp = new ObservableCollection<WeatherPeriod>();
public ObservableCollection<WeatherPeriod> WeatherPeriods {
    get {
        return _wp;
    }
    public set {

        if (value == null) throw new ArgumentNullException();
        if (_wp != null) {
            _wp.Clear();

            foreach (var wp in value) {
               _wp.Add(wp);
            }
            
        }
       
        RaisePropertyChanged("WeatherPeriods");
    }
}

So now you can add all of your properties to fill out the shape of your ViewModel.

Step 4: Define your caching policy

When you fetch data from your service, how long is it good for? AgFx defines a very simple way to define how long data should be cached for in your object.

The way this is done is with the CachePolicyAttribute. The constructor for CachePolicyAttribute takes two parameters:

The CachePolicy itself. CachePolicy can be one of the following values
1. CachePolicy.NoCache – this object should not be cached. Each time an application asks for this object, fetch an updated value. This won’t be used very often, but hey, it could happen.
2. CachePolicy.ValidCacheOnly – in this case, the data will only be returned from AgFx if it’s valid. In other words, AgFx will check the cache, and return that value if it’s within it’s expiration time. If not, new data will be fetched and returned when it is available. In our sample here, the Weather data is set as ValidCacheOnly. No use in showing weather data from last week!
3. CachePolicy.CacheThenRefresh – this is likely the most commonly used policy. What this means is that AgFx should go ahead look for a cached value, and if it finds one, regardless of it’s expiration date it should return that value to the caller. At that point, if the data is expired, automatically kick off a refresh. Imagine a Facebook application. When the user starts the app, imagine the app shows the user’s News Feed. The app could either always just show a blank News Feed with “Updating…” and then go get new data (this would be the ValidCacheOnly behavior). Or it could show the feed in the last state that it was in, and then update that with any new items since the last check. Most apps chose the latter, and this setting does exactly that. If you were to be databound to a “NewsVeedVm”, the feed would load from the cache then automatically update when new data was available. No code necessary, AgFx does this for you.
4. CachePolicy.AutoRefresh – This goes one step further and automatically kicks off a refresh of the data when the data reaches the end of it’s designated lifespan.
A cache time (in seconds). This defines how long your data should be cached for. For something like weather data, this might be 15 minutes (60 * 15), and for ZipCode data it’s basically forever, so you can just put a really long cache period in there.

So we just apply this to our ViewModels as in the following:

[CachePolicy(CachePolicy.ValidCacheOnly, 60 * 15)] 
    public class WeatherForecastVm : ModelItemBase<ZipCodeLoadContext>{…}

// this basically never changes, but we'll say 
// it's valid for a year.
[CachePolicy(CachePolicy.CacheThenRefresh, 3600 * 24 * 365)] 
    public class ZipCodeVm : ModelItemBase<ZipCodeLoadContext>{…}

That’s it.

Step 5: Defining your DataLoader

Okay, now is when the real party starts. The DataLoader is the beating heart of your ViewModel objects.

The DataLoader has two primary jobs:

Configure a request for data to populate the object
Take the raw data and create a model or ViewModel object out of it

Fortunately both of these are pretty easy.

Your DataLoader is an object that implements IDataLoader<T> where T is your LoadContext type from earlier. Your DataLoader should be a public nested type in your view model. This isn’t strictly necessary (see AgFx.DataLoaderAttribute) but I haven’t yet found a case where I need to do it otherwise. If it’s a nested type, AgFx will automatically find and instantiate it.

IDataLoader<T> It has two methods:

IDataLoader.GetLoadRequest – this returns an object that describes how to fetch data for your ViewModel. In the vast majority of cases this will just be a URI, and there is a special class called WebLoadRequest for that. GetLoadRequest actually returns an object of the abstract type LoadRequest, so you can do fancy stuff here if you need to. At the end of the day, this takes information from your LoadContext (basically whatever you need to build the URI in most cases) and then tells AgFx how to convert this into a Stream. Usually this means just doing a web request and returning the ResponseStream.
IDataLoader.Deserialize – given the Stream from (1) above, Deserialize is responsible for turning that into an object of the type that AgFx is asking for (in other words, your view Model type).

Implementing these is also simple. Here’s how GetLoadRequest usually looks:

private const string ZipCodeUriFormat = "http://www.webservicex.net/uszip.asmx/GetInfoByZIP?USZip={0}";

public LoadRequest GetLoadRequest(ZipCodeLoadContext loadContext, Type objectType)
{
    // build the URI, return a WebLoadRequest.
    string uri = String.Format(ZipCodeUriFormat, loadContext.ZipCode);
    return new WebLoadRequest(loadContext, new Uri(uri));
}

Make sense? It’s pretty simple. If you needed more parameters on the request, then you’d add more properties to your LoadContext and then use that to build out the URI.

AgFx will take that object and it will result in a network request. When that network request returns, the stream that it provided will be passed along back to the DataLoader for processing.

Processing the network data is typically straight-forward. I’m doing manual XML walking here. If your web service exposes a WSDL that the Windows Phone Developer Tools can handle, you can use that to make parsing a snap, usually using DataContractSerializer,, but for clarity I’ll just do the brute force method below.

public object Deserialize(ZipCodeLoadContext loadContext, Type objectType, System.IO.Stream stream)
{

    // the XML will look like the following, so we parse it.

    //<?xml version="1.0" encoding="utf-8"?>
    //<NewDataSet>
    //  <Table>
    //    <CITY>Kirkland</CITY>
    //    <STATE>WA</STATE>
    //    <ZIP>98033</ZIP>
    //    <AREA_CODE>425</AREA_CODE>
    //    <TIME_ZONE>P</TIME_ZONE>
    //  </Table>
    //</NewDataSet>                

    var xml = XElement.Load(stream);


    var table = (
                from t in xml.Elements("Table")
                select t).FirstOrDefault();

    if (table == null) {
        throw new ArgumentException("Unknown zipcode " + loadContext.ZipCode);
    }

    ZipCodeVm vm = new ZipCodeVm(loadContext.ZipCode);
    vm.City = table.Element("CITY").Value;
    vm.State = table.Element("STATE").Value;
    vm.AreaCode = table.Element("AREA_CODE").Value;
    vm.TimeZone = table.Element("TIME_ZONE").Value;
    return vm;
}

So what we do here is get into the XML stream with XLINQ, then just create a new ViewModel object (of type ZipCodeVm) and populate it’s properties with the values that we got out of XML.

Note the objectType property. The returned object MUST be an instance of this type (derived types are OK). AgFx will enforce this. You can take a look at the Deserialize method in the WeatherForecastVm as well, it’s pretty much the same, but it handles much more complex XML from the NOAA service via a helper class.

Now we just compile to make sure it’s all building.

Step 6: Bind to your UI with Expression Blend

Believe it or not, our application is just about done. Using the great sample data features of Expression Blend, it’s really easy to create our UI.

We’ll walk through a simple case of just the zip code information that we deserialized above. To make this easy to understand, what we want to do is create a UserControl that shows the city and state, along with the LastUpdated date. For the whole weather application, it’s the same process with a little more detail.

For this, I add a new Windows Phone User Control to my project, right click on the XAML file in Solution Explorer and choose “Open in Expression Blend…”.

Once Blend opens with the UserControl showing on the design surface, the first thing we’ll do is create sample data for our ViewModel:

Now we choose “Create Sample Data From Class”:

This will show us the public types in our project assemblies. We’re looking for “ZipCodeVm”, which is one of the VM objects we created up in step 3.

Hit OK, and now just drag the ZipCodeVm item onto the design surface:

Now we just build out our UI like so by dragging on some TextBlock objects from the Blend toolbar:

Now, for each of the items that says “TextBlock” we can just databind to our data fields by dragging them onto the object on the design surface, as demonstrated by the red arrow below. We’ll see sample (bogus) data that lets us just visualize how the UI will look at runtime.

Remember, it’s bogus sample data., it just allows us to see the layout. This prevents the tweak-F5-tweak-F5 method that many of use are used to.

After a little cleanup, here is what the XAML looks like. Notice the Binding statements to the properties we added in our ViewModel.

<StackPanel>
    <StackPanel Orientation="Horizontal">
        <TextBlock Text="{Binding City}" FontWeight="Bold"/>
        <TextBlock Text=", "/>
        <TextBlock Text="{Binding State}" />
    </StackPanel>
    <StackPanel Orientation="Horizontal">
        <TextBlock Text="Updated: " />
        <TextBlock Text="{Binding LastUpdated}" />
    </StackPanel>
</StackPanel>

Step 7: Load your object data into your UI

Okay now we’ve got our View Models built, our data processing done, and our databinding done. Now we just have to load the data.

The primary object for data access and management in AgFx is DataManager. DataManager is a singleton class that is accessed via the DataManager.Current property.

DataManager only exposes a few operations, but they really are key to tying the whole thing together.

As a starter example, we’d load data into the UserControl that we built above as follows:

zipCodeUserControl1.DataContext =
          DataManager.Current.Load<ZipCodeVm>("98052");

Which gives us this at runtime:

Notice we are passing the zip code as a string. Remember form our ZipCodeLoadContext, that we added a constructor with just a single string parameter. AgFx will take that “98052” and automatically pass it to that constructor. Also notice that we don’t have to do anything to manage caching or networking here. AgFx figures out if the value is already available in the cache, if the cache is valid, or if it needs to be refreshed from the network.

It’s important to keep in mind that the instance returned from the Load call will be the same instance that is returned from any future Load or Refresh calls. This identity-tracking is one of the key features of AgFx. What this means, is that once I’ve databound to a value in my UI, future calls to Refresh or Load will update this same instance.

In other words, if in a button click you simply do this:

private void btnRefreshZipcode_Click(object sender, RoutedEventArgs e) {
     DataManager.Current.Refresh<ZipCodeVm>("98052");
}

then the UI above will update. Note we never touch the user control or it’s DataContext. It just works.

DataManager gives you a broad set of operations to interact with your data.

Remember these are all accessed via DataManager.Current:

DataManager.Load<> as noted above takes either the shortcut value or an actual LoadContext object that you construct yourself. You would construct a LoadContext if you needed to set additional parameters, like a page number or result set size. Load executes asynchronously except in the case that there is already a value in memory, in which case that value is returned immediately. If that value has expired, a reload is kicked off, and the current value is returned and will be updated when the load completes.
DataManager.Refresh<>, which reloads the data for the given item, as if the value has expired. It otherwise works in the same way as Load<>.
DataManager.LoadFromCache<> works also similarly to Load<>, but it will only load from the cache and is synchronous. This is generally used in app startup as a way to load things up before the UI kicks off, for a example credentials and whatnot. You probably won’t use it often.
DataManager.Clear<> – clears the given object out of the DataManager’s data structures. Calling Load again will create a new instance, reload it’s live data, etc.
DataManager.RegisterProxy<> – this exists for some advanced scenarios that I won’t cover here, but basically this allows you to register other objects that you would like to be updated in addition to the main instance that DataManager is managing.
DataManager.UnhandledError (event) – this allows you to catch any unhandled errors that occur within a DataLoader’s code and potentially handle them before they bubble up to the app.
DataManager.IsLoading – this property is set to true whenever any object’s loader is currently fetching new data. DataManager implements INotifyPropertyChanged, so you can bind this property to UI that runs a ProgressBar or something if you want to show UI whenever network activity is occurring. This will not be set to true for cache loads, only for live loads (just like the ModelItemBase.IsUpdating property).

For Load and Refresh, there are overloads that allow you to get handle both completion and error scenarios in code. The signatures look like this:

public T Load<T>(object id, Action<T> completed, Action<Exception> error) ;

which allows you to pass in a lambda that will be called when the operation completes or fails, like so:

this.DataContext = DataManager.Current.Load<WeatherForecastVm>(txtZipCode.Text,
        (vm) =>
        {
            // upon a succesful load, show the info panel.
            // this is a bit of a hack, but we can't databind against
            // a non-existant data context...
            info.Visibility = Visibility.Visible;
        },
        (ex) =>
        {
            MessageBox.Show("Error: " + ex.Message);
        });

Note that if you pass in a handler for error, then the DataManager.UnhandledError event will not be invoked, regardless of what happens in the handler. You either handle via the lambda, or the global event, not both.

The “vm” parameter in the success handler will be the same instance as the object returned from the Load<> function as well, so any operations on this object will also be reflected in the UI. These handlers will invoke on the UI thread.

Finally, as I’ve mentioned before, it’s best to let DataManager do all the instance management for you. It does a lot of caching so don’t cache instances yourself unless you have to. For ViewModels that have properties that are other ViewModels (a pattern I really like because it encourages on-demand network activity as a user moves through an app), use this pattern:

/// <summary>
/// ZipCode info is the name of the city for the zipcode.  This is a separate 
/// service lookup, so we treat it separately.
/// </summary>
public ZipCodeVm ZipCodeInfo
{
    get
    {                
        return DataManager.Current.Load<ZipCodeVm>(LoadContext.ZipCode);
    }
}

Just use the Load method to return the right value.

So back to our weather example, here is the parts of the UI that are serviced by the various objects we’ve been discussing:

Step 8: Debugging

If you build a debug version of AgFx, you’ll find some useful debugging output that will help you determine what AgFx is up to. In the case of a first-time run of the weather application, here’s the output you’ll seee:

No cache found for NWSWeather.Sample.ViewModels.WeatherForecastVm (1)
3/17/2011 2:22:35 PM: Queuing load for WeatherForecastVm (2)
No cache found for NWSWeather.Sample.ViewModels.ZipCodeVm
3/17/2011 2:22:35 PM: Queuing load for ZipCodeVm
3/17/2011 2:22:35 PM: Checking cache for ZipCodeVm
3/17/2011 2:22:37 PM: Deserializing live data for NWSWeather.Sample.ViewModels.WeatherForecastVm (3)
Writing cache for WeatherForecastVm, IsOptimized=False, Will expire 3/17/2011 2:37:37 PM (4)
3/17/2011 2:23:43 PM: Deserializing live data for NWSWeather.Sample.ViewModels.ZipCodeVm
Writing cache for ZipCodeVm, IsOptimized=False, Will expire 3/16/2012 2:23:43 PM

Because these operations all happen off of the UI thread, you get interleaving between the call to the weather service and the zip code service. That’s good!

I’ve added the numbers in (bold) to the right to describe that this output means:

When the Load<WeatherForecastVm>(“98052”) call was made, the cache was checked and no value existed.
Because no cache existed a load (network) was queued for this item
The load completed and asked the DataLoader to deserialize the value
The deserialize completed, so the stream is being written to the cache with the specified expiration date.

If you’re writing an app and it’s not doing what you think it should, this output will really help you understand what the problem might be. If you see a lot of this output when you don’t expect to, that means something is going on that may be resulting in extra data loads that you don’t need. So you can use this as a perf tuning input as well.

As a comparison, here’s the output from a second run, after the app has been exited and restarted a few minutes later. Note there are no “queuing load” or “writing cache” entries. This shows that cached data is actually being loaded, when it was last updated, and when it will expire.

3/17/2011 2:35:12 PM: Checking cache for WeatherForecastVm
3/17/2011 2:35:12 PM: Checking cache for ZipCodeVm
3/17/2011 2:35:12 PM: Loading cached data for ZipCodeVm, Last Updated=3/17/2011 2:23:43 PM, Expiration=3/16/2012 2:23:43 PM
3/17/2011 2:35:12 PM: Deserializing cached data for NWSWeather.Sample.ViewModels.ZipCodeVm, IsOptimized=False
3/17/2011 2:35:12 PM: Loading cached data for WeatherForecastVm, Last Updated=3/17/2011 2:22:37 PM, Expiration=3/17/2011 2:37:37 PM
3/17/2011 2:35:12 PM: Deserializing cached data for NWSWeather.Sample.ViewModels.WeatherForecastVm, IsOptimized=False

Wrap up

Phew, that’s a lot of stuff! Believe it or not, there’s more but I’ll leave it at that for now. I’ve had a lot of fun putting this framework together, with help from Jeff among others. And I’ve had even more fun writing apps on top of it. Hopefully you will too, please let me know how it goes!

Download AgFx with the NOAA Weather sample here. Note when you open this project, you'll get a few warnings about Silverlight project. These are expected and harmless because the base code is an Silverlight class library (so it can be used on Silverlight too). Just hit OK.

Shawn

Build great Windows Phone applications the easy way!

Shawn Burke - MSFT — Sat, 12 Mar 2011 02:15:00 GMT

Introducing AgFx

One of the things we’ve spent a fair amount of time on is working with various application writers, helping them build great Windows Phone 7 applications. Many of the top applications that you’ll find on Windows Phone 7 devices today spent some time in a debugger on my desktop, or Jeff’s, or another one of the folks around here.

In doing this process, we saw a lot of common trouble spots for developers looking to write Windows Phone 7 applications and as I started to think more about the problem.

I thought the same thing I always think: “hmmmm, how can I build a framework that will make these things easy for the developer so they can worry about other stuff!”

And so it was born, and I’m currently calling it AgFx. Fortunately I’m a lot better at building frameworks than I am at naming things, so I’ll leave it at that. But if you’re wondering what the “Ag” is about, “Ag” is the symbol for Silver, and this framework happens to work on desktop Silverlight as well, so you can use it to build the guts of applications that are shareable across phone and desktop.

AgFx is available via CodePlex here.

What does it do?

AgFx provides a set of base class helpers and a data management engine that allow you to write your View Models (or just models, if you’re so inclined) in a very simple and consistent way. It contains some other helpful stuff too, but the data management engine is the heart of it, which I’ll introduce in this post.

Most applications do some variant of the following sequence:

Fetch data off of Internet
Process said data into some data structures
Bind said structures to some UI
Cache structures on disk
Next time a request comes in (say after tombstoning), check the cache
1. If cache is valid, goto 2
2. If cache is not valid, goto 1
Repeat

And while the above sounds simple, it turns out it’s not. In fact, it’s a lot of work to get it right AND even when it works you have lots of opportunities to cause performance problems or other things that you’ll have to go out and figure out later.

But fortunately the patterns are consistent enough that we can build an infrastructure to automate most of the above. If you are thinking of writing an application that’s similar to the above pattern, this will make it MUCH easier.

When thinking about most data-connected applications, it turns out there are only two key pieces of information required from the developer. Consider a stock quote from a web service. In order to display that stock quote in an application, we need to know:

How to go fetch the data. In this hypothetical case, it’s the URL to some service: http://www.contoso.com/services/stockquotes?symbol=msft
How to process the data into an object that is consumable by my application. Typically it means parsing JSON or XML that comes back from the request.

Everything else can be managed by the system, off of the UI thread in most cases:

Checking for cached data and/or requesting new data
Processing/Parsing the data
Creating objects from the data
Caching the data back to disk
Handling data updates (these must be on the UI thread)

And it turns out that this is exactly what AgFx does. It manages all of the above so you don’t have to.

Eh…code please.

Okay, let’s use a concrete example. The app that I’ll be including with the bits here is a simple app that goes against the NOAA XML web services for weather reports. Basically they take a US zip code and return a weather forecast.

Oh, the joys of winter in Seattle….

Anyway, as mentioned above, we need two pieces of information from the developer: how to go find the data, and how to deserlialize it. AgFx handles the rest. The vast majority of your code when writing with AgFx is building these view model objects and deserializing data into them.

Let’s start with some examples. First, AgFx view models usually look something like this:

    [CachePolicy(CachePolicy.ValidCacheOnly, 60 * 15)] 
    public class WeatherForecastVm : ModelItemBase<ZipCodeLoadContext>
    {
        public WeatherForecastVm()
        {
        }
        
        public WeatherForecastVm(string zipcode):

		base(new ZipCodeLoadContext(zipcode))
        {
        }
    
       //...properties, methods
     }

A few things to note there. First is the CachePolicyAttribute at the top. This tells the system how to handle the caching for this object type. “60 * 15” is 15 minutes – meaning these values are valid for 15 minutes. CachePolicy.ValidCacheOnly means that the system should only return cached values that are within that cache time window, otherwise, it should go fetch an updated version.

Now, you’ll notice that the above is a generic type, deriving from ModelItemBase<T>, and is referencing something called a “ZipCodeLoadContext”. Any object that AgFx is handling needs to have a LoadContext which is essentially the identifier for an instance of an item, as well as the place where you set extra state needed for loading. It will become clear why it’s called a LoadContext shortly. But the identifier should be unique for that type of item. On many services it might be the user id (for users) or the item id (for some data item). In this case the identifier is a zip code because zip codes map 1:1 with weather forecasts. Given a zip code, we’ll always get the right forecast data (we all know we might not get the right forecast!).

In this case, the ZipCodeLoadContext looks like the following:

 public class ZipCodeLoadContext : LoadContext {
        public string ZipCode {
            get {
                return (string)Identity;
            }            
        }

        public ZipCodeLoadContext(string zipcode)
            : base(zipcode) {

        }
    }

Given that this is a simple case, you’re just wrapping the zipcode string, really. The framework allows you to shortcut that if that’s the case, but I am including it here for completeness and so we get a nice strongly typed “ZipCode” property.

Now to the important part. The final piece is the DataLoader which is what holds this all together. Here’s the DataLoader for the WeatherForecastVm, as a nested class inside the WeatherForecastVm class itself:

public class WeatherForecastVm : ModelItemBase<ZipCodeLoadContext>
    {
       // ... VM Body removed

        /// <summary>
        /// Our loader, which knows how to do two things:
        /// 1. Build the URI for requesting data for a given zipcode
        /// 2. Parse the return value from that URI
        /// </summary>
        public class WeatherForecastVmLoader : IDataLoader<ZipCodeLoadContext>
        {
            const string NWS_Rest_Format = "http://www.weather.gov/forecasts/xml/sample_products/browser_interface/ndfdBrowserClientByDay.php?zipCodeList={0}&format=12+hourly&startDate={1:yyyy-MM-dd}";
            
            /// <summary>
            /// Build a LoadRequest that knows how to fetch new data for our object.
            /// In this case, it's just a URL so we construct the URL and then pass it to the
            /// default WebLoadRequest object, along with our LoadContext
            /// </summary>
            public LoadRequest GetLoadRequest(ZipCodeLoadContext lc, Type objectType)
            {
                string uri = String.Format(NWS_Rest_Format, lc.ZipCode, DateTime.Now.Date);
                return new WebLoadRequest(lc, new Uri(uri));
            }

            /// <summary>
            /// Once our LoadRequest has executed, we'll be handed back a stream containing the response from the 
            /// above URI, which we'll parse.
            /// 
            /// Note this will execute in two cases:
            /// 1. When we fetch fresh data from the Internet
            /// 2. When we are deserializing cached data off the disk.

	    /// The operation is equivelent at this point.
            /// </summary>
            public object Deserialize(ZipCodeLoadContext lc,

					Type objectType,

					System.IO.Stream stream)
            {
                // Parse the XML out of the stream.
                var locs = NWSParser.ParseWeatherXml(

				new string[] { lc.ZipCode }, stream);

                // make sure we got the right data
                var loc = locs.FirstOrDefault();

                if (loc == null)
                {
                    throw new FormatException("Didn't get any weather data.");
                }

                // Create our VM.  Note this is the same type as our containing object
                var vm = new WeatherForecastVm(lc.ZipCode);                

                // push in the weather periods
                foreach (var wp in loc.WeatherPeriods)
                {
                    vm.WeatherPeriods.Add(wp);
                }

                return vm;

            }
        }

    }

Again, the loader does two things, loads the new value (GetLoadRequest) and then parses it (Deserialize). Note we never have to write any serialization code for caching, just deserialize and AgFx does the rest.

Using your data

All of your view models will follow the same pattern above – you’ll define the type, define it’s LoadContext (if necessary), then define it’s DataLoader. At that point, you’re pretty much done.

The way that all of these objects (viewmodels or strict models) are accessed is the same in AgFx, and that’s with the DataManager.

So, what’s the code to use the data in this application? It’s just this:

private void btnAddZipCode_Click(object sender, RoutedEventArgs e)
{
  // Load up a new ViewModel based on the zip.
  // This will either fetch new data from the Internet, or load the cached data off disk
  // as appropriate.
  //
  this.DataContext = DataManager.Current.Load<WeatherForecastVm>(txtZipCode.Text);
}

That’s really it. The rest of the code is databindings in the XAML, and some other code to save the zip code so it automatically loads again the next time.

What we are doing here is asking the DataManager to load an object of type WeatherForecastVm, with the given zip code as the identifier. The framework takes care of the rest.

So, again, what are the steps that happen for me automatically upon calling that one line of code?

Look in the cache for data that a WeatherForecastVm can load, with the unique identifier of the specified zip code.
If the data is there, check it’s “expiration date”, if it’s not expired, return the data.
If it is expired, go get new data from the web, then save it to disk
Deserialize data from (2) or (3)
Create a WeatherForecastVm object and populate it from the deserialized data
Return the WeatherForecastVm instance so it can be used for databinding.

Almost all of this happens off of the UI thread (basically everything up to step 6).

Furthermore, the DataManager tracks instances, so the instance that’s returned from the Load call will *always* be the same (for the given identity value) for your entire application. This means that as long as you use this Load call, and databind to that object, any future refreshes of that data will automatically be reflected in your UI, regardless of where it is in your application. You don’t need to worry about any of this, it just works. More on this below. AgFx does the caching and fast lookup for you, so don’t hold references to these values if you don’t absolutely have to.

Loading On Demand

Using DataManager.Load<> allows the framework to control when and where items are loaded. This also allows your app to do work only as it’s needed to populate your UI. And once you break up the work into discreet view model objects, you can also control their caching policy independently. If you look at the WeatherForecastVm in the sample, you’ll see the following property:

 /// <summary>
 /// ZipCode info is the name of the city for the zipcode.  This is a sepearate 
 /// service lookup, so we treat it seperately.
 /// </summary>
 public ZipCodeVm ZipCodeInfo
 {
    get
    {                
      return DataManager.Current.Load<ZipCodeVm>(LoadContext.ZipCode);
    }
 }

Note that this property results in a call to another VM class – “ZipCodeVm”. If you look at the image up above, you’ll see that the name “Redmond” is shown under the 98052 zip code. This information didn’t come down with the weather data, I had to fetch it from another service. But since it’s based off the same identifier (“98052”) as the weather forecast, we just pass that along.

When I want my UI to show the city, as above, I’ll databind a TextBlock like so:

<TextBlock Text="{Binding ZipCodeInfo.City}" FontWeight="Bold"/>

To which the databinding engine does the following steps:

On the current DataContext, look for a property called “ZipCodeInfo”
Fetch that value, and then (if not null) look for a property called “City”
Fetch that value and set it as the Text property

So, back to our WeatherForecastVm object, when the databinding engine asks for the ZipCodeInfo property value,that request will be kicked off. But here’s the trick. It’s kicked off asynchronously. Execution won’t be held up while that value is fetched. So what does it return?

I mentioned above that the instance returned from then Load call will always been the same for a given instance*. So here’s what happens:

The Load<> call is made
A default instance of ZipCodeVm is created and returned. The UI will databind against this instance
AgFx does the off-thread work of getting the value from the web service, deserializing it into a ZipCodeVm object, and caching it on disk.
AgFx then takes and copies the updated values into the properties of the instance that was created. Since it is this instance that is being databound against, the UI will automatically update with these new values.
Any future Load calls, if new data is fetched, will also update this instance.

The net result is that UI anywhere in the application that is bound to a value retrieved via the Load<> method will always be kept up to date. No code wiring needed.

Finally, another upside to breaking up object like this is that you can specify a different cache policy. If you remember, the WeatherForecastVm policy was ValidOnly, for 15 minutes.

Zip codes don’t change much so we’re doing this instead:

// this basically never changes, but we'll say it's valid for a year.
[CachePolicy(CachePolicy.CacheThenRefresh, 3600 * 24 * 365)] 
public class ZipCodeVm : ModelItemBase<ZipCodeLoadContext>{...}

CacheThenRefresh means that if a request is made and there is a cached value that has expired, go ahead and return that cached value and automatically kick off a refresh. Just as in the case above, the refresh will update the instance that was created out of the cache and your UI will update when the refresh happens. A common case for this is an app that shows a Twitter feed. When you launch Twitter, you may want to see the feed as it was last time you opened the app, then have the new posts show as they come in off the network.

* this isn’t strictly true – if no one is holding the value, it can be garbage collected so it’s not using memory, and then a new instance will be created on demand at the next request. But since it’s not being held in memory, your code will never know that.

Take a look

That’s a quick introduction to AgFx, and there is a LOT more. We’ve been writing apps internally on top of it for a while now and we’re having great success and there are a bunch of more features that allow you to handle things your app might need to do quickly and efficiently. So for now, grab the code and run the app and get a feel for the framework. Ask questions in the comments and I’ll start digging into more advanced features in posts I’ll do shortly.

AgFx is available via CodePlex here.

Using ObservableCollection with the Portable Library Tools CTP

Shawn Burke - MSFT — Thu, 03 Feb 2011 19:50:00 GMT

One of the main goals of the Portable Library Tools is to be able to implement your ViewModel in the Portable Library such that you can share it between your UI in your Silverlight, Windows Phone, or even WPF project. Unfortunately, this is a bit of a challenge with the Portable Library Tools CTP, because it does not include ObservableCollection<T> or INotifyCollectionChanged.

The reason for this is simple. The CTP doesn’t have references for System.Windows, and both ObservableCollection<T> and INotifyCollectionChanged are defined in System.Windows. That they are defined in this assembly isn’t the best in terms of layering, and we have been discussing what to do about that. But they are there, and we’re looking to address this issue in a future release of the Portable Library Tools. But that doesn’t help you now, does it?

In fact, ObservableCollection is one of a few common classes that you may find you would like to be able to address from your portable code. The other one that I’ve run into is HttpUtility.UrlEncode/UrlDecode, so I’ll handle that here as well.

There are two ways to handle this, in general:

If you have a common class or interface that is available to all callers, you can key off of you can use a service locator pattern or some kind of dependency injection (ISomething impl = Factory.GetInstance<ISomething>();)
If you don’t have a common class or interface, you can create a class that allows you to define the specific operations you’re interested in

In the case of ObservableCollection, we have case (2). Because ObservableCollection/INotifyCollectionChanged aren’t available as part of the Portable Library Tools references. So there is no way to do the following:

 public class MyViewModel {
        private ObservableCollection<string> _strings = new ObservableCollection<string>();
        public ObservableCollection<string> Strings {
            get {
                return _strings;
            }
        }
    }

This is an interesting case where a Dependency Injection strategy won’t work.

However, if we look closer at ObservableCollection, we see that it derives from IList, which has the methods that we care about (Add, Remove, etc.). But what we really care about this is consumers of our ViewModel – specifically Silverlight’s databinding engine. Fortunately, the databinding engine uses reflection to check for INotifyCollectionChanged on the collection itself rather than the object being used as the DataContext. So it doesn’t matter what the type is on our ViewModel, it matters what type that object actually is.

With this knowledge in hand, our strategy is simple, and we implement it as follows.

First, we type our ViewModel collection property as IList:

 public class PortableViewModel : INotifyPropertyChanged {
        private IList<string> _stringList;
        public IList<string> Strings {
            get {                
                return _stringList;
            }
        }
}

Now, we define a class that is abstract in our Portable Library, but will be implemented in the application projects. The idea is to keep this as simple as possible:

    public abstract class PortabilityFactory {
        private static PortabilityFactory _factory;

        public static PortabilityFactory Current {
            get {
                if (_factory == null) {
                    throw new InvalidOperationException();
                }
                return _factory;
            }
            set {
                _factory = value;
            }
        }

        protected PortabilityFactory() {
           // note we auto-set current here,
           // which saves an extra step for the caller
            Current = this;            
        }

        public virtual IList<T> CreateList<T>() {
            return new List<T>();
        }

        public abstract string UrlEncode(string url);
        public abstract string UrlDecode(string url);
    }

We go back to our ViewModel, and specify the right call:

 public IList<string> Strings {
       get {
           if (_stringList == null) {
               _stringList = PortabilityFactory.Current.CreateList<string>();
           }
           return _stringList;
        }
}

Now, we go to our project and implement. Here’s the Phone example, and the Silverlight example, respectively. The best place to create this is in App.xaml.cs so it happens at app start up.

namespace WindowsPhoneApplication1 {
    public partial class App : Application {

        private PortabilityFactory _pf = new PhonePortabilityFactory();

        private class PhonePortabilityFactory : PortabilityFactory {
            public override IList<T> CreateList<T>() {
                return new ObservableCollection<T>();
            }

            public override string UrlDecode(string url) {
                return System.Net.HttpUtility.UrlDecode(url);
            }

            public override string UrlEncode(string url) {
                return System.Net.HttpUtility.UrlEncode(url);
            } 
}

namespace SilverlightApplication1
{
    public partial class App : Application
    {
        private PortabilityFactory _pf = new SilverlightPortabilityFactory();

        private class SilverlightPortabilityFactory : PortabilityFactory {
            public override IList<T> CreateList<T>() {
                return new ObservableCollection<T>();
            }

            public override string UrlDecode(string url) {
                return System.Windows.Browser.HttpUtility.UrlDecode(url);
            }

            public override string UrlEncode(string url) {
                return System.Windows.Browser.HttpUtility.UrlEncode(url);
            }
        }
}

Now you’ve done all you need to, and the rest of the system will work properly, and you can use the ViewModel directly as a datacontext:

public MainPage()
{
      InitializeComponent();
      this._vm = new PortableObservableCollection.PortableViewModel();
      this.DataContext = _vm;
}

Even when Portable Library Tools reaches it’s version 1, there will still be things that aren’t in the portable subset. You can use variations of the above techniques to handle those types as well. For some more complex features, you can use more of a Service Locator or Dependency Injection pattern. An example of this in the CTP is IsolatedStorage, which is not currently in the subset. For this you can imagine creating an IFileStorage interface and having it’s implementation plumb through to the Isolated Storage APIs, but use it generically in your portable library code. We are looking to minimize these situations as time goes on.

I’ve attached the project from which the code snippets came. Note you’ll need to install the Visual Studio 2010 SP1 Beta, and the Portable Library Tools CTP.

3-Screen Coding Is Here: Portable Library Tools allow you to target multiple .NET platforms with one binary!

Shawn Burke - MSFT — Sun, 23 Jan 2011 02:07:46 GMT

Earlier this week, we released the Portable Library Tools CTP. You’ll need to install the VS 2010 SP1 Beta first, then it’s a quick install on top of that.

What is it?

Back at PDC in October, I did a PDC talk called 3-Screen Coding: Sharing Code Between Windows Phone, Silverlight, and .NET. If you want to spend some time to get the full scoop on what the Portable Library Tools are all about, you watch it online by clicking here.

But if you don’t have time for that, the basic idea is as follows:

A Portable Library is a DLL that will run compatibly across a set of .NET platforms. The set of platforms currently supported for this CTP are .NET 4, Windows Phone 7, Silverlight 4, and XNA Framework 4.0 for XBox 360.

The Portable Library Tools CTP introduces a new project type called the Portable Class Library, which does two things:

Allows you to pick which of the supported platforms you’d wish to target, and
Gives you a “view” (Intellisense, Object Browser, Compiler, etc.) of the APIs that are command and compatible among those platforms

So essentially what this does is guide you in building code that you can trust will behave the same way on a set of platforms. And, naturally, if you choose all the platforms, you get a smaller “view” of the world than if you choose a set of similar platforms. This is because, as soon as one platform doesn’t have a given API, it can’t be in the widest set.

You can build portable libraries with VB or C#. The project type is currently under the “Windows” node in the Add New Project dialog. For more details, check out Justin’s post on the CLR team blog.

Why is a given API in (or not in) the subset?

When you start building a portable library, you’ll notice that the list of APIs available is smaller than you’re used to, but we think it’s still big enough to get things done.

How did we decide what to put in there and what not to?

Well, the process was pretty straight forward. First we thought about what would be necessary to build reasonably sophisticated code that one would want to share among different platforms – the minimum useful subset. We thought it was something like core BCL, plus basic networking, plus basic XML handling. As we went through scenarios and writing test projects, we verified that that was the minimum set of things you needed to write useful code, at least for the scenarios we tried.

So we then took and converted that into the set of assemblies that contain such functionality:

mscorlib
system
system.core
system.net
system.xml

We mapped out all of their types, properties, methods, and events for all of the platforms, then took the intersection of that list. This gave us the list of API signatures that were present in on all platforms. We went through this list and discovered some things that should have been on a given platform but weren’t, and we filed work items to get those added.

Second, we walked through that intersection and tried to remove obsolete and duplicate ways of doing things. For example, we did not include the old type-unsafe collection types, such as ArrayList. We removed many of the formatting methods that did not take an IFormatProvider parameter, because supplying that has been a clear best practice. And so on.

As this is a CTP, this is an ongoing process and open to feedback from you. We’ll be repeating the process with some of the platform subsets, so you’ll get a larger set of APIs if you only want to target Silverlight 4 and Windows Phone 7, for example.

So if you find an API that you think should be in the subset, ensure that it’s actually available on all of the platforms (it has to be the exact same signature), and then see the above caveats. I’m sure we missed some things, so let us know in the comments if there’s something you really think should be there and we’ll look at it!

As it currently is, here’s what’s where:

Feature	Assemblies	.NET Framework 4	Silverlight 4	Windows Phone 7	Xbox 360
Core BCL	mscorlib.dll System.dll System.Core.dll	X	X	X	X
Core XML	System.Xml.dll	X	X	X	X
Core HTTP	System.Net.dll	X	X	X	-
WCF Client	System.ServiceModel.dll	X	X	X	-
XML Serialization	System.Xml.Serialization.dll	X	X	X	-
MEF	System.ComponentModel.Composition.dll	X	X	-	-

Note the inclusion of an assembly in this list does not mean all of it’s functionality is supported, only the functionality that is common between the platforms that it exists on.

How to use the Portable Library Tools to build an application

If you are careful in how you design your application, you’ll find that you can build a large part of it as a portable library. The basic pattern is to put all of the code that you want to be portable into the portable library, and then have all the code that references a specific platform into a platform project.

So you could imagine your solution looks like the following:

Where you have one portable library that defines the service access, business logic, and view models for both a Silverlight 4 and a Window Phone 7 application.

What about UI?

When I first started working on the Window Phone 7 project in July of 2009, there was quite a bit of talk about what the right application model was between Silverlight and the phone. Should I just be able to run Silverlight applications straight away on the phone? Should all the XAML be portable? Should VS have a mode where you can select your platform and modify your project for either Silverlight or for the Phone and then somehow automatically switch between the “right” code at runtime? Should there be some kind of a importer thing that magically reformats your Silverlight app into a phone application? The point is, there were no shortage of creative ideas on this topic. But most of them seemed (at best) complex or error-prone.

One of the challenges to application portability – meaning the exact same application just runs on platform A and B – is that there are often different or missing facilities. Consider the functionality that’s in System.Windows.Browser in Silverlight, which is primarily focused on accessing the DOM of the browser that Silverlight (if in-browser) is hosted in. This has no clear analogue on Windows Phone, where Silverlight is natively hosted as a full screen application. So such functionality is either going to missing (meaning your app crashes at runtime) or stubbed out (meaning your app probably crashes at runtime!). There are a wide range of these types of differences and it’s not easy to deal with them in a consistent way. To do is a lot of extra work devoted to things that most developers won’t ever try to use in their platform-specific applications anyway.

More importantly, is that for an app to be really useful, it needs to conform to the UI paradigms and input methods of the target platform. Consider the DataGrid control in Silverlight, and how it is used. This is a control that’s really designed to be used with a mouse and keyboard.

I spent some time writing applications for Silverlight and then writing them for the phone, and as I did so it became clear that sharing UI wasn’t as great as it sounded. In fact, with well written ViewModels, it was much, much easier to craft nice, specific XAML for each platform and then just quickly use Blend or Visual Studio to wire it up and take advantage of the powerful, flexible databinding system that the Silverlight runtime provides. Creating the UI specifically for each platform is critical to delivering applications with a great user experience.

The Portable Library Tools CTP doesn’t yet allow you to reference System.Windows.dll, functionality, but that is planned for a future release. This gives you access to the Silverlight UI types like Button, Grid, UIElement, and Storyboard. So while sharing UI isn’t that useful, being able to write sharable components that reference or modify UI can be. For example, it’s nice to be able to share things like value converters.

What’s missing?

Our goal for this CTP was to get something usable out there and see what people were able to do with it, and then let feedback drive what we focus on. Many things we know about and are working to get them added, but there are probably some important small things that we missed.

For things that can’t be in the portable subset because they are different across each platform, there are ways of dealing with this cleanly (okay, fairly cleanly) within your application. I’ll cover that in an upcoming post.

iPhone SDK vs. Windows Phone 7 Series SDK Challenge, Part 2: MoveMe

Shawn Burke - MSFT — Sat, 27 Mar 2010 01:42:00 GMT

In this series, I will be taking sample applications from the iPhone SDK and implementing them on Windows Phone 7 Series. My goal is to do as much of an “apples-to-apples” comparison as I can. This series will be written to not only compare and contrast how easy or difficult it is to complete tasks on either platform, how many lines of code, etc., but I’d also like it to be a way for iPhone developers to either get started on Windows Phone 7 Series development, or for developers in general to learn the platform.

Here’s my methodology:

Run the iPhone SDK app in the iPhone Simulator to get a feel for what it does and how it works, without looking at the implementation
Implement the equivalent functionality on Windows Phone 7 Series using Silverlight.
Compare the two implementations based on complexity, functionality, lines of code, number of files, etc.
Add some functionality to the Windows Phone 7 Series app that shows off a way to make the scenario more interesting or leverages an aspect of the platform, or uses a better design pattern to implement the functionality.

You can download Microsoft Visual Studio 2010 Express for Windows Phone CTP here, and the Expression Blend 4 Beta here.

If you’re seeing this series for the first time, check out Part 1: Hello World.

A note on methodology…in the prior post there was some feedback about lines of code not being a very good metric for this exercise. I don’t really disagree, there’s a lot more to this than lines of code but I believe that is a relevant metric, even if it’s not the ultimate one. And there’s no perfect answer here. So I am going to continue to report the number of lines of code that I, as a developer would need to write in these apps as a data point, and I’ll leave it up to the reader to determine how that fits in with overall complexity, etc. The first example was so basic that I think it was difficult to talk about in real terms. I think that as these apps get more complex, the subjective differences in concept count and will be more important.

MoveMe

The MoveMe app is the main end-to-end app writing example in the iPhone SDK, called Creating an iPhone Application. This application demonstrates a few concepts, including handling touch input, how to do animations, and how to do some basic transforms.

The behavior of the application is pretty simple.

User touches the button: The button does a “throb” type animation where it scales up and then back down briefly.

User drags the button: After a touch begins, moving the touch point will drag the button around with the touch.

User lets go of the button: The button animates back to its original position, but does a few small bounces as it reaches it’s original point, which makes the app fun and gives it an extra bit of interactivity.

Now, how would I write an app that meets this spec for Windows Phone 7 Series, and how hard would it be? Let’s find out!

Implementing the UI

Okay, let’s build the UI for this application. In the HelloWorld example, we did all the UI design in Visual Studio and/or by hand in XAML.

In this example, we’re going to use the Expression Blend 4 Beta.

You might be wondering when to use Visual Studio, when to use Blend, and when to do XAML by hand. Different people will have different takes on this, but here’s mine:

XAML by hand – simple UI that doesn’t contain animations, gradients, etc., and or UI that I want to really optimize and craft when I know exactly what I want to do.
Visual Studio – Basic UI layout, property setting, data binding, etc.
Blend – Any serious design work needs to be done in Blend, including animations, handling states and transitions, styling and templating, editing resources.

As in Part 1, go ahead and fire up Visual Studio 2010 Express for Windows Phone (yes, soon it will take longer to say the name of our products than to start them up!), and create a new Windows Phone Application. As in Part 1, clear out the XAML from the designer. An easy way to do this is to just:

Click on the design surface
Hit Control+A
Hit Delete

There’s a little bit left over (the “Grid.RowDefinitions” element), just go ahead and delete that element so we’re starting with a clean state of only one outer Grid element.

To use Blend, we need to save this project. See, when you create a project with Visual Studio Express, it doesn’t commit it to the disk (well, in a place where you can find it, at least) until you actually save the project. This is handy if you’re doing some fooling around, because it doesn’t clutter your disk with WindowsPhoneApplication23-like directories. But it’s also kind of dangerous, since when you close VS, if you don’t save the project…it’s all gone. Yes, this has bitten me since I was saving files and didn’t remember that, so be careful to save the project/solution via “Save All”, at least once.

So, save and note the location on disk.

Start Expression Blend 4 Beta, and chose File –> Open Project/Solution, and load your project. You should see just about the same thing you saw over in VS: a blank, black designer surface.

Now, thinking about this application, we don’t really need a button, even though it looks like one. We never click it. So we’re just going to create a visual and use that. This is also true in the iPhone example above, where the visual is actually not a button either but a jpg image with a nice gradient and round edges. We’ll do something simple here that looks pretty good.

In Blend, look in the tool pane on the left for the icon that looks like the below (the highlighted one on the left), and hold it down to get the popout menu, and choose “Border”:

Okay, now draw out a box in the middle of the design surface of about 300x100. The Properties Pane to the left should show the properties for this item.

First, let’s make it more visible by giving it a border brush. Set the BorderBrush to white by clicking BorderBrush and dragging the color selector all the way to the upper right in the palette. Then, down a bit farther, make the BorderThickness 4 all the way around, and the CornerRadius set to 6.

In the Layout section, do the following to Width, Height, Horizontal and Vertical Alignment, and Margin (all 4 margin values):

You’ll see the outline now is in the middle of the design surface.

Now let’s give it a background color. Above “BorderBrush” select “Background”, and click the third tab over: Gradient Brush. You’ll see a gradient slider at the bottom, and if you click the markers, you can edit the gradient stops individually (or add more). In this case, you can select something you like, but where’s what I chose:

Left stop: #BFACCFE2 (I just picked a spot on the palette and set opacity to 75%, no magic here, feel free to fiddle these or just enter these numbers into the hex area and be done with it)

Right stop: #FF3E738F

Okay, looks pretty good. Finally set the name of the element in the “Name” field at the top of the Properties pane to “welcome”.

Now let’s add some text. Just hit “T” and it’ll select the TextBlock tool automatically:

Now draw out some are inside our “welcome” visual and type “Welcome!”, then click on the design surface (to exit text entry mode) and hit “V” to go back into selection mode (or the top item in the tool pane that looks like a mouse pointer).

Click on the text again to select it in the tool pane.

Just like the border, we want to center this. So set HorizontalAlignment and VerticalAlignment to “Center”, and clear the Margins:

That’s it for the UI. Here’s how it looks, on the design surface:

Not bad! Okay, now the fun part…

Adding Animations

Using Blend to build animations is a lot of fun, and it’s easy. In XAML, I can not only declare elements and visuals, but also I can declare animations that will affect those visuals. These are called Storyboards.

To recap, we’ll be doing two animations:

The “throb” animation when the element is touched
The “center” animation when the element is released after being dragged.

The throb animation is just a scale transform, so we’ll do that first.

In the Objects and Timeline Pane (left side, bottom half), click the little + icon to add a new Storyboard called “touchStoryboard”:

The timeline view will appear. In there, click a bit to the right of “0” to create a keyframe at .2 seconds:

Now, click on our “welcome” element (the Border, not the TextBlock in it), and scroll to the bottom of the Properties Pane. Open up Transform, click the third tab ("Scale”), and set X and Y to 1.2:

This all of this says that, at .2 seconds, I want the X and Y size of this element to scale to 1.2.

In fact you can see this happen. Push the “Play” arrow in the timeline view, and you’ll see the animation run!

Let’s make two tweaks. First, we want the animation to automatically reverse so it scales up then back down nicely.

Click in the dropdown that says “touchStoryboard” in Objects and Timeline, then in the Properties pane check “Auto Reverse”:

Now run it again, and you’ll see it go both ways. Let’s even make it nicer by adding an easing function.

First, click on the “Render Transform” item in the Objects tree, then, in the Property Pane, you’ll see a bunch of easing functions to choose from. Feel free to play with this, then seeing how each runs. I chose “Circle In”, but some other ones are fun. Try them out! Elastic In is kind of fun, but we’ll stick with Circle In.

That’s it for that animation.

Now, we also want an animation to move the Border back to it’s original position when the user ends the touch gesture. This is exactly the same process as above, but just targeting a different transform property.

Create a new animation called “releaseStoryboard”

Select a timeline point at 1.2 seconds.
Click on the “welcome” Border element again
Scroll to the “Transforms” panel at the bottom of the Properties Pane
Choose the first tab (“Translate”), which may already be selected
Set both X and Y values to 0.0 (we do this just to make the values stick, because the value is already 0 and we need Blend to know we want to save that value)
Click on “RenderTransform” in the Objects tree
In the properties pane, choose “Bounce Out”
Set “Bounces” to 6, and “Bounciness” to 4 (feel free to play with these as well)

Okay, we’re done.

Note, if you want to test this Storyboard, you have to do something a little tricky because the final value is the same as the initial value, so playing it does nothing. If you want to play with it, do the following:

Next to the selection dropdown, hit the little "x” (Close Storyboard)
Go to the Translate Transform value for “welcome”
Set X,Y to –50, –200, respectively (or whatever)
Select “releaseStoryboard” again from the dropdown
Hit play, see it run
Go into the object tree and select “RenderTransform” to change the easing function.
When you’re done, hit the Close Storyboard “x” again and set the values in Transform/Translate back to 0

Wiring Up the Animations

Okay, now go back to Visual Studio. You’ll get a prompt due to the modification of MainPage.xaml. Hit “Yes”.

In the designer, click on the “welcome” Border element. In the Property Browser, hit the “Events” button, then double click each of “ManipulationStarted”, “ManipulationDelta”, “ManipulationCompleted”. You’ll need to flip back to the designer from code, after each double click.

It’s code time. Here we go.

Here, three event handlers have been created for us:

welcome_ManipulationStarted: This will execute when a manipulation begins. Think of it as MouseDown.

welcome_ManipulationDelta: This executes each time a manipulation changes. Think MouseMove.

welcome_ManipulationCompleted: This will execute when the manipulation ends. Think MouseUp.

Now, in ManipuliationStarted, we want to kick off the “throb” animation that we called “touchAnimation”. That’s easy:

   1:  private void welcome_ManipulationStarted(object sender, ManipulationStartedEventArgs e)

   2:  {

   3:      touchStoryboard.Begin();

   4:  }

Likewise, when the manipulation completes, we want to re-center the welcome visual with our bounce animation:

   1:  private void welcome_ManipulationCompleted(object sender, ManipulationCompletedEventArgs e)

   2:  {

   3:      releaseStoryboard.Begin();

   4:  }

Note there is actually a way to kick off these animations from Blend directly via something called “Triggers”, but I think it’s clearer to show what’s going on like this. A Trigger basically allows you to say “When this event fires, trigger this Storyboard”, so it’s the exact same logical process as above, but without the code.

But how do we get the object to move? Well, for that we really don’t want an animation because we want it to respond immediately to user input.

We do this by directly modifying the transform to match the offset for the manipulation, and then we’ll let the animation bring it back to zero when the manipulation completes. The manipulation events do a great job of keeping track of all the stuff that you usually had to do yourself when doing drags: where you started from, how far you’ve moved, etc.

So we can easily modify the position as below:

   1:  private void welcome_ManipulationDelta(object sender, ManipulationDeltaEventArgs e)

   2:  {

   3:      CompositeTransform transform = (CompositeTransform)welcome.RenderTransform;

4:

   5:      transform.TranslateX = e.CumulativeManipulation.Translation.X;

   6:      transform.TranslateY = e.CumulativeManipulation.Translation.Y;

   7:  }

That’s it!

Go ahead and run the app in the emulator. I suggest running without the debugger, it’s a little faster (CTRL+F5). If you’ve got a machine that supports DirectX 10, you’ll see nice smooth GPU accelerated graphics, which also what it looks like on the phone, running at about 60 frames per second. If your machine does not support DX10 (like the laptop I’m writing this on!), it won’t be quite a smooth so you’ll have to take my word for it!

Comparing Against the iPhone

This is an example where the flexibility and power of XAML meets the tooling of Visual Studio and Blend, and the whole experience really shines.

So, for several things that are declarative and 100% toolable with the Windows Phone 7 Series, this example does them with code on the iPhone. In parens is the lines of code that I count to do these operations.

PlacardView.m: 19 total LOC
- Creating the view that hosts the button-like image and the text
- Drawing the image that is the background of the button
- Drawing the “Welcome” text over the image (I think you could technically do this step and/or the prior one using Interface Builder)
MoveMeView.m: 63 total LOC
- Constructing and running the scale (“throb”) animation (25)
- Constructing the path describing the animation back to center plus bounce effect (38)

Beyond the code count, yy experience with doing this kind of thing in code is that it’s VERY time intensive. When I was a developer back on Windows Forms, doing GDI+ drawing, we did this stuff a lot, and it took forever! You write some code and even once you get it basically working, you see it’s not quite right, you go back, tweak the interval, or the math a bit, run it again, etc. You can take a look at the iPhone code here to judge for yourself. Scroll down to “animatePlacardViewToCenter” toward the bottom. I don’t think this code is terribly complicated, but it’s not what I’d call simple and it’s not at all simple to get right.

And then there’s a few other lines of code running around for setting up the ViewController and the Views, about 15 lines between MoveMeAppDelegate, PlacardView, and MoveMeView, plus the assorted decls in the h files.

Adding those up, I conservatively get something like 100 lines of code (19+63+15+decls) on iPhone that I have to write, by hand, to make this project work.

The lines of code that I wrote in the examples above is 5 lines of code on Windows Phone 7 Series.

In terms of incremental concept counts beyond the HelloWorld app, here’s a shot at that:

iPhone:

Drawing Images
Drawing Text
Handling touch events
Creating animations
Scaling animations
Building a path and animating along that

Windows Phone 7 Series:

Laying out UI in Blend
Creating & testing basic animations in Blend
Handling touch events
Invoking animations from code

This was actually the first example I tried converting, even before I did the HelloWorld, and I was pretty surprised. Some of this is luck that this app happens to match up with the Windows Phone 7 Series platform just perfectly. In terms of time, I wrote the above application, from scratch, in about 10 minutes. I don’t know how long it would take a very skilled iPhone developer to write MoveMe on that iPhone from scratch, but if I was to write it on Silverlight in the same way (e.g. all via code), I think it would likely take me at least an hour or two to get it all working right, maybe more if I ended up picking the wrong strategy or couldn’t get the math right, etc.

Making Some Tweaks

Silverlight contains a feature called “Projections” to do a variety of 3D-like effects with a 2D surface.

So let’s play with that a bit.

Go back to Blend and select the “welcome” Border in the object tree. In it’s properties, scroll down to the bottom, open Transform, and see Projection at the bottom. Set X,Y,Z to 90. You’ll see the element kind of disappear, replaced by a thin blue line.

Now…

Create a new animation called “startupStoryboard”.
Set it’s key time to .5 seconds in the timeline view
Set the projection values above to 0 for X, Y, and Z.
Save
Go back to Visual Studio, and in the constructor, add the following bold code (lines 7-9 to the constructor:

   1:  public MainPage()

   2:  {

   3:      InitializeComponent();

4:

   5:      SupportedOrientations = SupportedPageOrientation.Portrait;

6:

   7:      this.Loaded += (s, e) =>

   8:      {

   9:          startupStoryboard.Begin();

  10:      };

  11:  }

If the code above looks funny, it’s using something called a lambda in C#, which is an inline anonymous method. It’s just a handy shorthand for creating a handler like the manipulation ones above.

So with this you’ll get a nice 3D looking fly in effect when the app starts up. Here it is, in flight:

Pretty cool!

iPhone SDK vs Windows Phone 7 Series SDK Challenge, Part 1: Hello World!

Shawn Burke - MSFT — Tue, 23 Mar 2010 14:00:00 GMT

Here’s my methodology:

Run the iPhone SDK app in the iPhone Simulator to get a feel for what it does and how it works, without looking at the implementation
Implement the equivalent functionality on Windows Phone 7 Series using Silverlight.
Compare the two implementations based on complexity, functionality, lines of code, number of files, etc.
Add some functionality to the Windows Phone 7 Series app that shows off a way to make the scenario more interesting or leverages an aspect of the platform, or uses a better design pattern to implement the functionality.

You can download Microsoft Visual Studio 2010 Express for Windows Phone CTP here, and the Expression Blend 4 Beta here.

Hello World!

Of course no first post would be allowed if it didn’t focus on the “hello world” scenario. The iPhone SDK follows that tradition with the Your First iPhone Application walkthrough. I will say that the developer documentation for iPhone is pretty good. There are plenty of walkthoughs and they break things down into nicely sized steps and do a good job of bringing the user along.

As expected, this application is quite simple. It comprises of a text box, a label, and a button. When you push the button, the label changes to “Hello” plus the word you typed into the text box. Makes perfect sense for a starter application.

There’s not much to this but it covers a few basic elements:

Laying out basic UI
Handling user input
Hooking up events
Formatting text

So, let’s get started building a similar app for Windows Phone 7 Series!

Implementing the UI:

UI in Silverlight (and therefore Windows Phone 7) is defined in XAML, which is a declarative XML language also used by WPF on the desktop. For anyone that’s familiar with similar types of markup, it’s relatively straightforward to learn, but has a lot of power in it once you get it figured out. We’ll talk more about that.

This UI is very simple. When I look at this, I note a couple of things:

Elements are arranged vertically
They are all centered

So, let’s create our Application and then start with the UI. Once you have the the VS 2010 Express for Windows Phone tool running, create a new Windows Phone Project, and call it Hello World:

Once created, you’ll see the designer on one side and your XAML on the other:

Now, we can create our UI in one of three ways:

Use the designer in Visual Studio to drag and drop the components
Use the designer in Expression Blend 4 to drag and drop the components
Enter the XAML by hand in either of the above

We’ll start with (1), then kind of move to (3) just for instructional value.

To develop this UI in the designer:

First, delete all of the markup between inside of the Grid element (LayoutRoot). You should be left with just this XAML for your MainPage.xaml (i shortened all the xmlns declarations below for brevity):

   1:  <phoneNavigation:PhoneApplicationPage

   2:      x:Class="HelloWorld.MainPage"

   3:     xmlns="...[snip]"

   4:      FontFamily="{StaticResource PhoneFontFamilyNormal}"

   5:      FontSize="{StaticResource PhoneFontSizeNormal}"

   6:      Foreground="{StaticResource PhoneForegroundBrush}">

7:

   8:      <Grid x:Name="LayoutRoot" Background="{StaticResource PhoneBackgroundBrush}">

9:

  10:      </Grid>

11:

  12:  </phoneNavigation:PhoneApplicationPage>

We’ll be adding XAML at line 9, so that’s the important part.

Now,

Click on the center area of the phone surface
Open the Toolbox and double click “StackPanel”
Double click “TextBox”
Double click “TextBlock”
Double click “Button”

That will create the necessary UI elements but they won’t be arranged quite right. We’ll fix it in a second.

Here’s the XAML that we end up with:

   1:  <StackPanel Height="100" HorizontalAlignment="Left" Margin="10,10,0,0" Name="stackPanel1" VerticalAlignment="Top" Width="200">

   2:           <TextBox Height="32" Name="textBox1" Text="TextBox" Width="100" />

   3:           <TextBlock Height="23" Name="textBlock1" Text="TextBlock" />

   4:           <Button Content="Button" Height="70" Name="button1" Width="160" />

   5:  </StackPanel>

The designer does it’s best at guessing what we want, but in this case we want things to be a bit simpler.

So we’ll just clean it up a bit. We want the items to be centered and we want them to have a little bit of a margin on either side, so here’s what we end up with. I’ve also made it match the values and style from the iPhone app:

   1:  <StackPanel Margin="10">

   2:      <TextBox Name="textBox1" HorizontalAlignment="Stretch" Text="You" TextAlignment="Center"/>

   3:      <TextBlock Name="textBlock1" HorizontalAlignment="Center" Margin="0,100,0,0" Text="Hello You!" />

   4:      <Button Name="button1" HorizontalAlignment="Center" Margin="0,150,0,0" Content="Hello"/>

   5:  </StackPanel>

Now let’s take a look at what we’ve done there.

Line 1: We removed all of the formatting from the StackPanel, except for Margin, as that’s all we need. Since our parent element is a Grid, by default the StackPanel will be sized to fit in that space. The Margin says that we want to reserve 10 pixels on each side of the StackPanel.
Line 2: We’ve set the HorizontalAlignment of the TextBox to “Stretch”, which says that it should fill it’s parent’s size horizontally. We want to do this so the TextBox is always full-width. We also set TextAlignment to Center, to center the text.
Line 3: In contrast to the TextBox above, we don’t care how wide the TextBlock is, just so long as it is big enough for it’s text. That’ll happen automatically, so we just set it’s Horizontal alignment to Center. We also set a Margin above the TextBlock of 100 pixels to bump it down a bit, per the iPhone UI.
Line 4: We do the same things here as in Line 3.

Here’s how the UI looks in the designer:

Believe it or not, we’re almost done!

Implementing the App Logic

Now, we want the TextBlock to change it’s text when the Button is clicked.

In the designer, double click the Button to be taken to the Event Handler for the Button’s Click event. In that event handler, we take the Text property from the TextBox, and format it into a string, then set it into the TextBlock. That’s it!

   1:  private void button1_Click(object sender, RoutedEventArgs e)

   2:  {

   3:      string name = textBox1.Text;

4:

   5:      // if there isn't a name set, just use "World"

   6:      if (String.IsNullOrEmpty(name))

   7:      {

   8:          name = "World";

   9:      }

10:

  11:      // set the value into the TextBlock

  12:      textBlock1.Text = String.Format("Hello {0}!", name);

13:

  14:  }

We use the String.Format() method to handle the formatting for us.

Now all that’s left is to test the app in the Windows Phone Emulator and verify it does what we think it does!

And it does!

Comparing against the iPhone

Looking at the iPhone example, there are basically three things that you have to touch as the developer:

1) The UI in the Nib file

2) The app delegate

3) The view controller

Counting lines is a bit tricky here, but to try to keep this even, I’m going to only count lines of code that I could not have (or would not have) generated with the tooling. Meaning, I’m not counting XAML and I’m not counting operations that happen in the Nib file with the XCode designer tool. So in the case of the above, even though I modified the XAML, I could have done all of those operations using the visual designer tool. And normally I would have, but the XAML is more instructive (and less steps!). I’m interested in things that I, as the developer have to figure out in code. I’m also not counting lines that just have a curly brace on them, or lines that are generated for me (e.g. method names that are generated for me when I make a connection, etc.)

So, by that count, here’s what I get from the code listing for the iPhone app found here:

HelloWorldAppDelegate.h: 6

HelloWorldAppDelegate.m: 12

MyViewController.h: 8

MyViewController.m: 18

Which gives me a grand total of about 44 lines of code on iPhone. I really do recommend looking at the iPhone code for a comparison to the above.

Now, for the Windows Phone 7 Series application, the only code I typed was in the event handler above

Main.Xaml.cs: 4

So a total of 4 lines of code on Windows Phone 7. And more importantly, the process is just A LOT simpler. For example, I was surprised that the User Interface Designer in XCode doesn’t automatically create instance variables for me and wire them up to the corresponding elements. I assumed I wouldn’t have to write this code myself (and risk getting it wrong!). I don’t need to worry about view controllers or anything. I just write my code. This blog post up to this point has covered almost every aspect of this app’s development in a few pages. The iPhone tutorial has 5 top level steps with 2-3 sub sections of each.

Now, it’s worth pointing out that the iPhone development model uses the Model View Controller (MVC) pattern, which is a very flexible and powerful pattern that enforces proper separation of concerns. But it’s fairly complex and difficult to understand when you first walk up to it. Here at Microsoft we’ve dabbled in MVC a bit, with frameworks like MFC on Visual C++ and with the ASP.NET MVC framework now. Both are very powerful frameworks. But one of the reasons we’ve stayed away from MVC with client UI frameworks is that it’s difficult to tool. We haven’t seen the type of value that beats “double click, write code!” for the broad set of scenarios.

Another thing to think about is “how many of those lines of code were focused on my app’s functionality?”. Or, the converse of “How many lines of code were boilerplate plumbing?” In both examples, the actual number of “functional” code lines is similar. I count most of them in MyViewController.m, in the changeGreeting method. It’s about 7 lines of code that do the work of taking the value from the TextBox and putting it into the label. Versus 4 on the Windows Phone 7 side. But, unfortunately, on iPhone I still have to write that other 37 lines of code, just to get there.

10% of the code, 1 file instead of 4, it’s just much simpler.

Making Some Tweaks

It turns out, I can actually do this application with ZERO lines of code, if I’m willing to change the spec a bit. The data binding functionality in Silverlight is incredibly powerful. And what I can do is databind the TextBox’s value directly to the TextBlock. Take some time looking at this XAML below. You’ll see that I have added another nested StackPanel and two more TextBlocks. Why? Because that’s how I build that string, and the nested StackPanel will lay things out Horizontally for me, as specified by the Orientation property.

   1:  <StackPanel Margin="10">

   2:      <TextBox Name="textBox1" HorizontalAlignment="Stretch" Text="You" TextAlignment="Center"/>

   3:      <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" Margin="0,100,0,0" >

   4:          <TextBlock Text="Hello " />

   5:          <TextBlock Name="textBlock1"  Text="{Binding ElementName=textBox1, Path=Text}"  />

   6:          <TextBlock Text="!" />

   7:      </StackPanel>

   8:      <Button Name="button1" HorizontalAlignment="Center" Margin="0,150,0,0" Content="Hello" Click="button1_Click" />

   9:  </StackPanel>

Now, the real action is there in the bolded TextBlock.Text property:

Text="{Binding ElementName=textBox1, Path=Text}"

That does all the heavy lifting. It sets up a databinding between the TextBox.Text property on textBox1 and the TextBlock.Text property on textBlock1. As I change the text of the TextBox, the label updates automatically.

In fact, I don’t even need the button any more, so I could get rid of that altogether. And no button means no event handler. No event handler means no C# code at all.

Want to see more? Check out Part Two.

Silverlight Toolkit March 2009 Release

Shawn Burke - MSFT — Sat, 21 Mar 2009 00:17:38 GMT

This week we released an updated Silverlight Toolkit - the Silverlight Toolkit March 2009 release. This release has some new components, but we spent a lot of time working to make sure that the Toolkit can be updated in an agile way, but still fits in nicely with other platform and tools releases.

Goals for the March 2009 Release

1. Align the Toolkit with the SDK

The main thing that we wanted to establish was a smooth flow of components from the Toolkit into the platform, in this case the SDK. Most Toolkit components are things that people will want to have in their default tooling experience, and one of our goals is to minimize the number of things that developers must download to get productive with the platform. So the first order of business was to setup the Toolkit to be primarily an incubation vehicle for SDK components. So most components start in the Toolkit, and end up eventually in the SDK that comes with Visual Studio or Expression Blend.

This also meant pulling the existing SDK controls into the Toolkit package. With the March 2009 release, you'll find the source code for all of the Silverlight 3 versions of the SDK controls - DataGrid, Calendar, TabControl, etc. As with the rest of the Toolkit, this code is licensed under MS-PL so you're free to modify it or use it in your application.

2. Do the work to support Silverlight 2 and Silverlight 3

With Silverlight 3 coming into the picture, we needed to structure the Toolkit project to be able to handle both versions. Our philosophy is to do as much work in the Silverlight 2 Toolkit as possible, then just do things in Silverlight 3 that have a dependency on the new runtime. We'll continue to support Silverlight 2 up through the release of Silverlight 3, then we'll focus on Silverlight 3 exclusively as customers upgrade. On the Release page you'll see a Silverlight 3 Beta and Silverlight 2 installer.

3. Fully support the Blend and Visual Studio development environments

I've always been a big believer in delivering great design-time experiences. We've done a lot of work with the tools teams to make sure that our components work well with the designers, including having items in the Toolbox and having the right properties show up in the tool. This turned out to be more work than we had anticipated and we're hopeful that any customers that are writing components can use what we've done as a good example of how to make all of this stuff work. We'll keep pushing on making this a great experience over time.

4. Address critical customer feedback

The biggest piece of feedback we've gotten is to have our Samples available in VB.NET as well as C#, so we did the work to make that happen.

In addition, we've fixed the highest-voted bugs in components across the Toolkit including Charting, AutoCompleteBox, and TreeView. Thanks to everyone that took the time to file issues or vote, that data is very helpful to us. One catch here is that some of our components (like TreeView) need to maintain API compat with WPF, so that limits the type of changes that we can make.

We also now have an MSI-based installer package that installs the Toolkit for you and gets the Toolkit control items into the Visual Studio Toolbox or Blend Asset Panel automatically. This helps with the discovery of components and makes them easier to add to your projects. It also sets up a nice Start Menu entry as well:

5. Add new controls

We've also added some new controls - Accordion, DomainUpDown, and TimePicker, all of which are in the Preview band for this release. Check them out!

Toolkit Namespace and Assembly Changes

If you're upgrading from a prior version of the Toolkit, you'll notice that the namespace names for most components have changed from Microsoft.* to System.*. So for this upgrade, you'll need to go through the process of updating your code, so sorry for that up front.

This was something we spent a *lot* of time talking through. The original reason for making the Toolkit components be in Microsoft was so that we could add components to the SDK or the Core and not have them conflict with Toolkit versions. We wanted there to be an opt-in change when developers moved from a Toolkit control to the platform version - we'd delay the need for the user to make a change until the very end. But the user would need to update source code. The more we thought about this, and talked to customers, the more it seemed like this wasn't the right thing to do since it means more-and-more code that you'll need to fix up if you wait longer. Instead, for the components we expected to make it into the platform, it was better to put them into their final namespace and then physically move them into the platform assembly when they were fully mature. This meant having a new Toolkit build with each platform release that has those types removed. But that's something we do anyway, and doing it this way means that customers only need to update their references and maybe their XAML xml namespace, and that's it. Code should continue to run. We decided that was a better model.

In conjunction with that, we needed to make sure that installing or using the Toolkit was something that didn't disturb the supported platform release. So that meant Toolkit assemblies had to be able to sit side-by-side with SDK assemblies. To accomplish that, we appended the word "Toolkit" to the Toolkit assemblies and that makes an easy mapping for where things are in the Toolkit to where they will end up in the SDK.

Here is an example:

Today, System.Windows.Controls.Accordion is in System.Windows.Controls.Layout.Toolkit.dll. Someday in the future, Accordion will reach the Mature Quality Band and then a platform release will happen and it will be moved into the SDK. When the next version of Silverlight ships, we will ship a corresponding Toolkit and SDK. The Accordion component will move into System.Windows.Controls.Layout.DLL (note no "Toolkit" in there), which is part of the SDK itself. Developers using this component will need to add a reference to that SDK assembly and (optionally) remove the reference to System.Windows.Controls.Layout.Toolkit.dll if it's not needed anymore. The developer would also need to update their XML namespace definition to point to the SDK version of the DLL so that the XAML parser knows where to find it. That should be it, and the project will now be using the SDK version of the component with no code changes.

What this unfortunately means is that we've got quite a few assemblies coming out of the Toolkit. We've tried to intelligently bucket the Toolkit controls into a few different assemblies so you don't have to pay to have a bunch of components in your XAP you're not using. We'll do the same thing for the SDK. But given the above, you get 2 assemblies for each bucket. Unfortunately, that's the simplest solution even if it's a little verbose.

Rebuilding SDK Components

As I mentioned above, the full source for the SDK components is now present in the Toolkit project. The Toolkit only includes source for these components, not the components themselves. Many parts of the system (for example Blend) are tested and built against the released version of the SDK components. We don't want the Toolkit updating these by default, but we do want to allow developers to make fixes to these components and deploy them with their applications if needed. In the Toolkit you'll find a Toolkit solution and an SDK solution so there is a nice separation there. If you do make a change to one of these components, you can just update the reference in your project to your rebuilt version and run against that.

Other Improvements

The Toolkit also includes two great new themes: Bubble Cream and Twilight Blue.

We've added AreaSeries in the Charts

Looking forward to hearing your feedback!