Dan Crevier's Blog : DM-V-VM

DataModel-View-ViewModel pattern series

dancre — Thu, 12 Oct 2006 05:00:51 GMT

I thought I should add a post with the full list of posts in the D-V-VM pattern. They are:

DataModel-View-ViewModel pattern: 1 (overview)

DataModel-View-ViewModel pattern: 2 (first implementation of DataModel class)

DM-V-VM part 3: A sample DataModel

DM-V-VM part 4: Unit testing the DataModel

DM-V-VM part 5: Commands

DM-V-VM part 6: Revisiting the data model

DM-V-VM part 7: Encapsulating commands

DM-V-VM part 8: View Models

dancre — Mon, 18 Sep 2006 06:01:00 GMT

Ok, time to wrap this up :-)

Now, we'll finally build what I'm calling a view model for managing a portfolio of stocks (building on the StockModel example from previous posts). A view model is a class that will be used as the DataContext for a data template that will be used to provide the UI for the model. Ideally, there is no code behind required for the UI. In practice, some glue code is often required, but in this example, I won't need any.

First, let's come up with the model. Unlike the data model, there is no base class we'll use here. We just need to provide properties, events, etc. that the UI can bind to. In this example, none of our properties will ever change value, so we don't need to implement INotifyPropertyChanged, but often you will need to. Our UI is going to be pretty simple. We'll provide a list of StockModels for the UI to bind to and provide CommandModels to add and remove stocks. Let's start with the constructor where we set up some fields and some accessors:

        public PortfolioViewModel(IStockQuoteProvider quoteProvider)
        {
            _quoteProvider = quoteProvider;
            _stockModels = new ObservableCollection<StockModel>();
            _stockModels.Add(new StockModel("MSFT", _quoteProvider));
 
            _addCommand = new AddCommand(this);
            _removeCommand = new RemoveCommand(this);
        }
 
        public ObservableCollection<StockModel> Stocks
        {
            get { return _stockModels; }
        }
 
        public CommandModel AddCommandModel
        {
            get { return _addCommand; }
        }
 
        public CommandModel RemoveCommandModel
        {
            get { return _removeCommand; }
        }
 
        private ObservableCollection<StockModel> _stockModels;
        private CommandModel _addCommand;
        private CommandModel _removeCommand;
        private IStockQuoteProvider _quoteProvider;

The quote provider lets us pass in any quote provider and makes it really easy to unit test the class. We populate the stock list with MSFT, but a real implementation may read it from some saved settings or something.

Next, let's define AddCommand. It will take the stock to add as its parameter:

        private class AddCommand : CommandModel
        {
            public AddCommand(PortfolioViewModel viewModel)
            {
                _viewModel = viewModel;
            }
 
            public override void OnQueryEnabled(object sender, CanExecuteRoutedEventArgs e)
            {
                string symbol = e.Parameter as string;
                e.CanExecute = (!string.IsNullOrEmpty(symbol));
                e.Handled = true;
            }
 
            public override void OnExecute(object sender, ExecutedRoutedEventArgs e)
            {
                string symbol = e.Parameter as string;
                _viewModel._stockModels.Add(new StockModel(symbol, _viewModel._quoteProvider));    
            }
 
            private PortfolioViewModel _viewModel;
        }

And, RemoveCommand, which will take a StockModel as its parameter:

        private class RemoveCommand : CommandModel
        {
            public RemoveCommand(PortfolioViewModel viewModel)
            {
                _viewModel = viewModel;
            }
 
            public override void OnQueryEnabled(object sender, CanExecuteRoutedEventArgs e)
            {
                e.CanExecute = e.Parameter is StockModel;
                e.Handled = true;
            }
 
            public override void OnExecute(object sender, ExecutedRoutedEventArgs e)
            {
                _viewModel._stockModels.Remove(e.Parameter as StockModel);
            }
 
            private PortfolioViewModel _viewModel;
        }

Now, how do we use this? Well, if we define a data template for the PortfolioViewModel, then we can put a PortfolioViewModel in any ContentControl. We could even have a list of them in an ItemsControl! We can put the data template in App.xaml and it can be used anywhere in the application. Here's an ugly, but functional template on top of the view model:

    <DataTemplate DataType="{x:Type local:PortfolioViewModel}">
      <DockPanel LastChildFill="True">
        <TextBlock DockPanel.Dock="Top" TextAlignment="Center">Portfolio View</TextBlock>
        <StackPanel DockPanel.Dock="Top" Orientation="Horizontal">
          <TextBox Name="AddSymbol" Width="100" />
          <Button Command="{Binding AddCommandModel.Command}"
                  CommandParameter="{Binding Path=Text,ElementName=AddSymbol}"
                  local:CreateCommandBinding.Command="{Binding AddCommandModel}"
                  >
            Add
            </Button>
          <Button Margin="50,0,0,0"
                  Command="{Binding RemoveCommandModel.Command}"
                  CommandParameter="{Binding Path=SelectedItem,ElementName=StockList}"
                  local:CreateCommandBinding.Command="{Binding RemoveCommandModel}"
                  >
            Remove
          </Button>
        </StackPanel>
        <ListBox Name="StockList" ItemsSource="{Binding Stocks}" />
      </DockPanel>
    </DataTemplate>

The add button functionality is much like the way we dealt with commands in part 7. The remove button's command parameter is bound to the selected item in the list box - pretty cool, huh? It will be disabled if nothing is selected and use the selected StockModel if one is selected. The ListBox is bound to the list of StockModels. To make each item display correctly, we need a data template for StockModels. Here's a simple implementation:

    <DataTemplate DataType="{x:Type local:StockModel}">
      <StackPanel Orientation="Horizontal" local:ActivateModel.Model="{Binding}">
        <TextBlock Text="{Binding Symbol}" Width="100"/>
        <TextBlock Text="{Binding Quote}" />
      </StackPanel>
    </DataTemplate>

Now, we need to put a Portfolio view into our window. We can do so by using the following XAML:

<Window x:Class="ModelSample.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="ModelSample" Height="300" Width="300"
    >
    <Grid>
      <ContentControl x:Name="_content" />
    </Grid>
</Window>

and, the following code behind:

    public partial class Window1 : Window
    {
 
        public Window1()
        {
            InitializeComponent();
 
            _content.Content = new PortfolioViewModel(new MockQuoteProvider());
        }
 
    }

The end result looks something like:

Ok, it's not very pretty, but the visuals are all in Xaml and a designer can use Expression or the raw HTML to improve the look. Meanwhile, the behavior is all in PortfolioViewModel, which is easily unit testable because it doesn't depend on any UI.

This example is slightly idealized. I was able to use the attached property tricks to completely eliminate the code behind, but that's not always possible. Sometimes you are left with some glue code that may or may not be easily unit testable. And, I've found in practice that deisgners often need behavior tweaks to implement the UI they want. For example, they may need events to trigger animations. But, I hope I've given the general idea in this series of posts.

I'm including a sample project with demonstrates this all. Unfortunately, I never got around to updating the unit tests after adding the activation stuff to the DataModel class, so there are no unit tests. If there is enough interest, I'll add unit tests. I hope it's easy to see how they would be written.

DM-V-VM part 7: Encapsulating commands

dancre — Fri, 15 Sep 2006 18:56:00 GMT

In part 5, I talked about commands and how they are used for behavior. Now, I want to talk about a better way to encapsulate them. First, I'll create a CommandModel class that encapsulates the RoutedCommand and the enabled/execute code. This is all pretty straightforward:

    public abstract class CommandModel
    {
        public CommandModel()
        {
            _routedCommand = new RoutedCommand();
        }
 
        /// <summary>
        /// Routed command associated with the model.
        /// </summary>
        public RoutedCommand Command
        {
            get { return _routedCommand; }
        }
 
        /// <summary>
        /// Determines if a command is enabled. Override to provide custom behavior. Do not call the
        /// base version when overriding.
        /// </summary>
        public virtual void OnQueryEnabled(object sender, CanExecuteRoutedEventArgs e)
        {
            e.CanExecute = true;
            e.Handled = true;
        }
 
        /// <summary>
        /// Function to execute the command.
        /// </summary>
        public abstract void OnExecute(object sender, ExecutedRoutedEventArgs e);
 
        private RoutedCommand _routedCommand;
    }

Subclasses could add more properties to the RoutedCommand if need be. You could also imagine adding more properties to CommandModel for things like an icon to display in the UI. For example, in Max, our toolbars are ItemsControls bound to a list of CommandModels with a data template for each command model that shows the icon and name of the command.

Now, we can wrap our simple command from part 5 into a class:

    class MyCommand : CommandModel
    {
        public override void OnQueryEnabled(object sender, CanExecuteRoutedEventArgs e)
        {
            e.CanExecute = !string.IsNullOrEmpty(e.Parameter as string);
            e.Handled = true;
        }
 
        public override void OnExecute(object sender, ExecutedRoutedEventArgs e)
        {
            string text = e.Parameter as string;
 
            // Do something with text
        }
    }

We can now remove all of the command related code from the window class. We're still stuck setting up the binding in the UI class. But, we can use the attached property trick to get rid of this, similar to how we did the activation in part 6. We'll create a property that you can attach to a UI element like

local:CreateCommandBinding.Command="{Binding MyCommand}"

To create a command binding for a given command model. First we just need the standard attached property definition, set up to call OnCommandInvalidated when the property changes:

    public static class CreateCommandBinding
    {
        public static readonly DependencyProperty CommandProperty
           = DependencyProperty.RegisterAttached("Command", typeof(CommandModel), typeof(CreateCommandBinding),
                new PropertyMetadata(new PropertyChangedCallback(OnCommandInvalidated)));
 
        public static CommandModel GetCommand(DependencyObject sender)
        {
            return (CommandModel)sender.GetValue(CommandProperty);
        }
 
        public static void SetCommand(DependencyObject sender, CommandModel command)
        {
            sender.SetValue(CommandProperty, command);
        }

And, OnCommandInvalidated will set up the binding when the command is changed.

        private static void OnCommandInvalidated(DependencyObject dependencyObject, DependencyPropertyChangedEventArgs e)
        {
            // Clear the exisiting bindings on the element we are attached to.
            UIElement element = (UIElement)dependencyObject;
            element.CommandBindings.Clear();
 
            // If we're given a command model, set up a binding
            CommandModel commandModel = e.NewValue as CommandModel;
            if (commandModel != null)
            {
                element.CommandBindings.Add(new CommandBinding(commandModel.Command, commandModel.OnExecute, commandModel.OnQueryEnabled));
            }
 
            // Suggest to WPF to refresh commands
            CommandManager.InvalidateRequerySuggested();
        }

Note: I was a little lazy implementing the clearing code. You can't have multiple bindings on element you put this on. A more general implementation would be to clear the specific binding for e.OldValue.

Putting it together, the Xaml for the window now looks like:

<Window x:Class="CommandDemo.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="clr-namespace:CommandDemo" 
    Title="CommandDemo" Height="300" Width="300"
    DataContext="{Binding RelativeSource={RelativeSource Self}}"
    >
    <StackPanel>
      <TextBox Name="_textBox"/>
      <Button Name="_button"
              local:CreateCommandBinding.Command="{Binding MyCommand}" 
              Command="{Binding MyCommand.Command}"
              CommandParameter="{Binding Text, ElementName=_textBox}">
        Do something
      </Button>
    </StackPanel>
</Window>

The only difference is the CreateCommandBinding property. And, the code behind looks like:

    public partial class Window1 : Window
    {
        public Window1()
        {
            InitializeComponent();
        }
 
        public CommandModel MyCommand
        {
            get { return _myCommand; }
        }
 
        CommandModel _myCommand = new MyCommand();
    }

So, we've extracted almost all of the behavior out of the Window's code behind. The command code is nicely encapsulated into a class with no coupling to the UI, so it can be easily reused and unit tested.

The way things are now, the window is setting itself as its DataContext and exposing the behavior of the windows through bindings via that DataContext. As a preview of what's coming next, we'll move that behavior out to a separate class (which I'm calling a ViewModel) and set the DataContext of the window to the view model instead of itself. We'll be left with no code behind (except InitializeComponent) and clean separation between the style and the behavior.

DM-V-VM part 6: Revisiting the data model

dancre — Sat, 26 Aug 2006 06:58:37 GMT

Sorry it's taking me so long to get the posts out. The series turned out to be a little longer than I anticipated :-) I got a lot of good feedback on the Data Model stuff.

First off, I want to mention layering. The DataModel typically is a layer on top of some other lower level data model that's not optimized to WPF. This might be something specific to the database technology you are using. Or, it could wrap some native object that's accessed via interop (I've run into a couple of examples of people doing this recently).

Also, I made some simplifications in the first post that made them much less interesting. The big simplification was that the models only fetched their data once and weren't live. Things get a lot more interesting when the models keep their data up to date.

Once you make them live, you run into a life time issue. If you have a large set of items, you only want to keep the visible items live. We'll do this by giving models Activate and Deactivate functions that control when it is live. Let's start with the DataModel changes. I'm not going to list the full class here, just the modifications. I'll post the entire sample soon when I finish up the series. If you have any question about how to apply these changes, let me know.

First, an IsActive property, which is implemented much like the State property. We could make it settable to activate and deactivate the model, but I like to think of those as methods rather than a property change:

        public bool IsActive
        {
            get
            {
                VerifyCalledOnUIThread();
                return _isActive;
            }

            private set
            {
                VerifyCalledOnUIThread();
                if (value != _isActive)
                {
                    _isActive = value;
                    SendPropertyChanged("IsActive");
                }
            }
        }

And, the Activate/Deactivate methods:

        public void Activate()
        {
            VerifyCalledOnUIThread();

            if (!_isActive)
            {
                this.IsActive = true;
                OnActivated();
            }
        }

        public void Deactivate()
        {
            VerifyCalledOnUIThread();

            if (_isActive)
            {
                this.IsActive = false;
                OnDeactivated();
            }
        }

And, some simple overridable stubs:

        protected virtual void OnActivated()
        {
        }

        protected virtual void OnDeactivated()
        {
        }

This is all pretty simple, we can just activate it and deactivate it. Subclasses can override the behavior when activated and deactivated.

Now, let's modify the StockModel to be live while activated. We'll use a DispatcherTimer to update on an interval. We'll start the timer and do the first update when activated:

        protected override void OnActivated()
        {
            VerifyCalledOnUIThread();

            base.OnActivated();

            _timer = new DispatcherTimer(DispatcherPriority.Background);
            _timer.Interval = TimeSpan.FromMinutes(5);
            _timer.Tick += delegate { ScheduleUpdate(); };
            _timer.Start();

            ScheduleUpdate();
        }

And, we'll stop the timer when deactivated:

        protected override void OnDeactivated()
        {
            VerifyCalledOnUIThread();

            base.OnDeactivated();

            _timer.Stop();
            _timer = null;
        }

When we're ready to do an update, we'll use a background thread as before:

        private void ScheduleUpdate()
        {
            VerifyCalledOnUIThread();

            // Queue a work item to fetch the quote
            if (ThreadPool.QueueUserWorkItem(new WaitCallback(FetchQuoteCallback)))
            {
                this.State = ModelState.Fetching;
            }
        }

Note: We could have used a System.Threading.Timer to do the updates where we'd be called on a background thread directly, but then we couldn't set the model state to fetching. We'd have to send that back to the UI thread.

Ok, now we've made it so you can activate it and deactivate it, but when do we do so? Let's say we've got thousands of our models in a ListBox. It's only going to only show a few of them on the screen at a time and we only want the ones on screen to be active. We'll use the attached property trick to do this without having to write custom code each time we want to activate and deactivate models. The basic idea is that we're going to display our model in a DataTemplate and we want to activate the model when FrameworkElements in the UI are loaded, and deactivate the model when they are unloaded. With the attached property trick, our DataTemplate Xaml just has to be:

    <DataTemplate DataType="{x:Type local:StockModel}">
      <StackPanel Orientation="Horizontal" local:ActivateModel.Model="{Binding}">
        <TextBlock Text="{Binding Symbol}" Width="100"/>
        <TextBlock Text="{Binding Quote}" />
      </StackPanel>
    </DataTemplate>

Note the local:ActivateModel.Model={Binding}. Now, here's how we implement that magic property! First, we need define the DependencyProperty and the accessor functions:

    public static class ActivateModel
    {
        public static readonly DependencyProperty ModelProperty
           = DependencyProperty.RegisterAttached("Model", typeof(DataModel), typeof(ActivateModel),
                new PropertyMetadata(new PropertyChangedCallback(OnModelInvalidated)));

        public static DataModel GetModel(DependencyObject sender)
        {
            return (DataModel)sender.GetValue(ModelProperty);
        }

        public static void SetModel(DependencyObject sender, DataModel model)
        {
            sender.SetValue(ModelProperty, model);
        }

We've registered a PropertyChangedCallback on the property, so any time it is changed (including when it's initially set), OnModelInvalidated is going to be called. In OnModelInvalidated, we're going to register for Loaded and Unloaded events on the the FrameworkElement we are attached to. We also have to do a bit of bookkeeping to clean up if we were previously pointing to a different model.

        private static void OnModelInvalidated(DependencyObject dependencyObject, DependencyPropertyChangedEventArgs e)
        {
            FrameworkElement element = (FrameworkElement)dependencyObject;

            // Add handlers if necessary
            if (e.OldValue == null && e.NewValue != null)
            {
                element.Loaded += OnElementLoaded;
                element.Unloaded += OnElementUnloaded;
            }

            // Or, remove if necessary
            if (e.OldValue != null && e.NewValue == null)
            {
                element.Loaded -= OnElementLoaded;
                element.Unloaded -= OnElementUnloaded;
            }

            // If loaded, deactivate old model and activate new one
            if (element.IsLoaded)
            {
                if (e.OldValue != null)
                {
                    ((DataModel)e.OldValue).Deactivate();
                }

                if (e.NewValue != null)
                {
                    ((DataModel)e.NewValue).Activate();
                }
            }
        }

And, here are the Loaded/Unloaded handlers.

        static void OnElementLoaded(object sender, RoutedEventArgs e)
        {
            FrameworkElement element = (FrameworkElement)sender;
            DataModel model = GetModel(element);
            model.Activate();
        }

        static void OnElementUnloaded(object sender, RoutedEventArgs e)
        {
            FrameworkElement element = (FrameworkElement)sender;
            DataModel model = GetModel(element);
            model.Deactivate();
        }

Pretty neat trick, isn't it? This means it's really easy for us to activate models when they are visible in the UI by simply adding the ActivateModel.Model property to the UI element. Since we know all FrameworkElements will get unloaded when they go away, we know we won't have to worry about leaking anything. It doesn't require any custom activate/deactivate code per view!

We get a form of data virtualization out of this trick. If the data is very expensive, the models can act as a relatively cheap shell. When you go to view a a large collection of items, you just need to provide a collection of the data models instead of the full items. The expensive data can then be accessed only when the UI for the data is visible on the screen and then thrown out when the data goes offscreen.

I'll confess, I've made another simplification from what we've done in Max. The lifetime management of a lot of our models is slightly more complex. And, as much as we hated to do so, we ended up adding a reference counting to our models. So we keep track of multiple levels of activation and a model is live as long as that count is greater than zero. To get something a bit like smart pointers, we have Activate return an IDisposable which we call an "activation cookie". Disposing of the activation cookie decrements the activation count. The cookie is the only way to decrement the count, there's no public method on the model. It's smart enough to not let you decrement multiple times. And, in debug builds, we have a finalizer on the cookie that asserts if Dispose wasn't called, to help catch leaks. We were quite happy to leaving reference counting when moving to managed code, so it hurt a bit to bring it back :-)

Ok, I think I'm just a couple of posts from wrapping this up!

DM-V-VM part 5: Commands

dancre — Sat, 05 Aug 2006 18:49:40 GMT

In the previous posts, I've covered data models and how to make data easily consumable by Avalon. Now, I want to start getting into the view model side of things because I don't think it's clear what I mean by them and I'm working up to an example.

I want to start by talking about handling behavior in the UI. Let's take a simple example. Say you have some UI that has a TextBox and a Button that does some operation on that text. The standard way you might do something like this with Xaml and code behind is something like:

<Window x:Class="CommandDemo.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="CommandDemo" Height="300" Width="300"
    >
    <StackPanel>
      <TextBox Name="_textBox"/>
      <Button Name="_button" Click="OnButtonClick">Do something</Button>
    </StackPanel>
</Window>

and the code behind:

namespace CommandDemo
{
    public partial class Window1 : Window
    {
 
        public Window1()
        {
            InitializeComponent();
        }
 
        private void OnButtonClick(object sender, RoutedEventArgs e)
        {
            string text = _textBox.Text;
 
            // Do something with text
        }
 
    }
}

The Xaml specifies the function that should be called on click and the code behind goes directly to the text box to get the text. So, there's a fair amount of coupling between the Xaml and the code behind. Now let's say you want the button to be disabled when the TextBox is empty. You might have code behind that watches for the text changing and enables/disables the button. That leads to more coupling. Or, you could write a ValueConverter and bind the enabled state to the text box text passed through the value converter.

But, I want to get the behavior side of things out of the code behind to clearly separate the behavior aspects from the styling. This will make the behavior more unit testable and makes it easier for designers to own the Xaml and developers to own the behavior.

Let's start with a quick example of how to do this with RoutedCommands. A button can be bound to an ICommand. ICommand lets the button know when to be enabled and what to do when it's clicked. RoutedCommand is an ICommand implementation that fires a routed event looking for a CommandBinding definied on an element that handles that command. One other thing that commands support is a command parameter. Here's an example of how we can use a RoutedCommand to handle the scenario above.

First, the code behind:

    public partial class Window1 : Window
    {
        public Window1()
        {
            InitializeComponent();
 
            this.CommandBindings.Add(new CommandBinding(this.MyCommand, OnExecute,
                   OnQueryCommandEnabled));
        }
 
        public RoutedCommand MyCommand
        {
            get { return _myCommand; }
        }
 
        private void OnQueryCommandEnabled(object sender, CanExecuteRoutedEventArgs e)
        {
            e.CanExecute = !string.IsNullOrEmpty(e.Parameter as string);
            e.Handled = true;
        }
 
        private void OnExecute(object sender, ExecutedRoutedEventArgs e)
        {
            string text = e.Parameter as string;
 
            // Do something with text
        }
 
        RoutedCommand _myCommand = new RoutedCommand();
    }

Note: We've removed any reference to specific UI elements from the code behind! We set up a RoutedCommand and make it available through a property. And, we've set up a binding pointing to query enabled and execute functions. These functions get the string to operate on through the command parameter.

Now, here's the Xaml:

<Window x:Class="CommandDemo.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="CommandDemo" Height="300" Width="300"
    DataContext="{Binding RelativeSource={RelativeSource Self}}"
    >
    <StackPanel>
      <TextBox Name="_textBox"/>
      <Button Name="_button"
              Command="{Binding MyCommand}"
              CommandParameter="{Binding Text, ElementName=_textBox}">
        Do something
      </Button>
    </StackPanel>
</Window>

One key thing I've done here is to set the DataContext of the window to itself. That's what lets Command="{Binding MyCommand}" work in the button. That binding is relative to the DataContext. It sets up the command parameter by binding to the text in the text box.

With this version, the button's enabled state will change when the text field changes. How does that work exactly? Well, ICommand has a CanExecuteChanged event that the button registers for and requeries the enabled state each time it fires. But, when does it fire? With a RoutedCommand, it will fire on any input event. You can also suggest that commands update by calling CommandManager.InvalidateRequerySuggested. So, after each key press or other input event, WPF will call OnQueryCommandEnabled.

So, where are we? We've really cleaned things up from the original version. The code behind no longer knows about any of the UI elements in the Xaml. But, we can go further and completely remove the command behavior from the code behind. That'll be my next post!

DM-V-VM part 4: Unit testing the DataModel

dancre — Thu, 27 Jul 2006 08:27:29 GMT

In part 3, I showed code for StockModel, a DataModel for stocks. On the Max team, we are big believers in extensive unit testing of our code. It took some time to learn the best way to test some of the WPF related stuff. In this post, I intend to demonstrate how to unit test code that involves a Dispatcher.

We use the unit testing framework built into at least certain flavors of VS 2005, but I think other frameworks like NUnit are pretty similar.

The first thing we'll define inside our class is a mock IStockQuoteProvider that returns a known value and tracks what symbol it was called with:

    [TestClass]
    public class StockModelTests
    {
        /// <summary>
        /// IStockQuoteProvider that returns 100
        /// </summary>
        private class TestQuoteProvider : IStockQuoteProvider
        {
            public bool TryGetQuote(string symbol, out double quote)
            {
                _lastSymbol = symbol;
                quote = 100.0;
 
                return true;
            }
 
            public string LastSymbol
            { get { return _lastSymbol; } }
 
            private string _lastSymbol = "";
        }

Now, I'll walk through the test method a piece at a time. First, we'll create a StockModel and check the initial state:

        [TestMethod]
        public void TestStockModelProviderGetsValue()
        {
            TestQuoteProvider testQuoteProvider = new TestQuoteProvider();
 
            StockModel stockModel = new StockModel("MSFT", testQuoteProvider);
 
            // Verify the initial model state
            Assert.AreEqual("MSFT", stockModel.Symbol);
            Assert.AreEqual(0.0, stockModel.Quote);
            Assert.AreEqual(DataModel.ModelState.Fectching, stockModel.State);
 

At this point, the StockModel has queued the work item to fetch the state, and it may have even executed it. It may seem like there's a race condition here where the quote would be updated, but there isn't. The background work item uses Dispatcher.BeginInvoke to change the state and/or quote. All this does is put something in the dispatcher queue. But, that won't get executed because the dispatcher isn't processing messages.

The way we'll get the get the dispatcher to run is with a DispatcherFrame. The basics of the DispatcherFrame is that when you call Dispatcher.PushFrame(), it will process messages in the dispatcher until DispatcherFrame.Cotinue is set to false. At that point Dispatcher.PushFrame() will return.

What we'll do is add a property changed handler that sets DispatcherFrame.Continue false when the model's state changes from fetching. I like to use an anonymous delegate for this because I find it readable and it gives easy access to the local variables we need.

            DispatcherFrame frame = new DispatcherFrame();
 
            PropertyChangedEventHandler waitForModelHandler = new PropertyChangedEventHandler(
                delegate(object sender, PropertyChangedEventArgs e)
                {
                    if (e.PropertyName == "State" && stockModel.State !=
                        DataModel.ModelState.Fectching)
                    {
                        frame.Continue = false;
                    }
                });
            stockModel.PropertyChanged += waitForModelHandler;
 

            Dispatcher.PushFrame(frame);

When Dispatcher.PushFrame returns, it means that we've hit the property changed handler and the model is up to date. Now, we can verify the final state:

            Assert.AreEqual(DataModel.ModelState.Active, stockModel.State);
            Assert.AreEqual(100.0, stockModel.Quote);
            Assert.AreEqual("MSFT", testQuoteProvider.LastSymbol);
    }

That's the test. This has tested the code path where the provider returns a quote. Another test is to use an IStockQuoteProvider that returns false and makes sure the state is set to invalid. I'm not including that code in this post because it's pretty obvious from the code above, but I'll include it in the full sample at the end.

I want to point out a couple of limitations with this approach...

The first is that if the property changed handler isn't called because of a bug in the code, the test will just hang. One solution to this is to use a DispatcherTimer that sets a failure flag and sets frame.Continue to false. If the failure flag is set when PushFrame returns, it means the property changed handler wasn't hit. If it was hit, you just need to reset the DispatcherTimer.

Another limitation is that if you have a bunch of tests run in a row using this approach, it's possible that things left in the dispatcher in one test will cause failures in a future test. This can be solved by running the test on its own thread with a private dispatcher.

Solving these limitations is left as an exercise for the reader :-) If you have questions, let me know.

DM-V-VM part 3: A sample DataModel

dancre — Thu, 27 Jul 2006 08:01:15 GMT

In part 2, I showed a base class for DataModels. In this post, I will describe a sample implementation. For this sample, I'll use a DataModel that represents a stock. The model will be in charge of asynchronously fetching the stock quote and making it's value available.

As part of making this class more testable, we first define an interface for retrieving stock quotes:

    public interface IStockQuoteProvider
    {
        /// <summary>
        /// Get a quote. This function may block on slow operations like hitting the network.
        /// </summary>
        /// <param name="symbol">The stock symbol.</param>
        /// <param name="quote">The quote.</param>
        /// <returns>Whether we were able to get a quote.</returns>
        bool TryGetQuote(string symbol, out double quote);
    }

This will let us plug in mock providers for unit testing. Let's walk through the model implementation. First the class declaration and constructor:

    public class StockModel : DataModel
    {
        public StockModel(string symbol, IStockQuoteProvider quoteProvider)
        {
            _symbol = symbol;
            _quoteProvider = quoteProvider;
 
            this.State = ModelState.Fectching;
 
            // Queue a work item to fetch the quote
            if (!ThreadPool.QueueUserWorkItem(new WaitCallback(FetchQuoteCallback)))
            {
                this.State = ModelState.Invalid;
            }
        }

The constructor takes the stock symbol and the quote provider. It sets the initial model state to fetching and queues a work item to be called on a background thread. Don't forget to check the return result of QueueUserWorkItem! If it fails, the model will be put in the invalid state.

Next, the symbol property. This one is simple!

        public string Symbol
        {
            get { return _symbol; }
        }

For the quote property, we'll have a private setter that will send the property changed event:

        public double Quote
        {
            get
            {
                VerifyCalledOnUIThread();
 
                return _quote;
            }
 
            private set
            {
                VerifyCalledOnUIThread();
 
                if (_quote != value)
                {
                    _quote = value;
                    SendPropertyChanged("Quote");
                }
            }
        }

Now, here's the callback to fetch the quote. Remember, this will be called on a background thread where it's okay for us to do expensive operations like hitting a web service to get a quote.

        private void FetchQuoteCallback(object state)
        {
            double fetchedQuote;
            if (_quoteProvider.TryGetQuote(_symbol, out fetchedQuote))
            {
                this.Dispatcher.BeginInvoke(DispatcherPriority.ApplicationIdle,
                    new ThreadStart(delegate
                    {
                        this.Quote = fetchedQuote;
                        this.State = ModelState.Active;
                    }));
            }
            else
            {
                this.Dispatcher.BeginInvoke(DispatcherPriority.ApplicationIdle,
                    new ThreadStart(delegate
                    { this.State = ModelState.Invalid; }));
            }
        }

We need to dispatch back to the UI thread to set the properties. This avoids any complex locking logic and makes sure that all of the property changed events come from the UI thread.

Finally, we just have the fields:

        private string _symbol;
        private double _quote;
        private IStockQuoteProvider _quoteProvider;
    }

So, that's it! What we've got is a class that's perfectly suited to being displayed in a WPF DataTemplate. It's got the symbol and quote available for binding. And, the state can be used in a trigger to change the look while it's fetching or if there's an error. The UI thread will never be blocked on slow operations.

Next up, I'll show some unit tests for this class, which will show you how to unit test code that uses a dispatcher.

DataModel-View-ViewModel pattern: 2

dancre — Mon, 24 Jul 2006 06:51:56 GMT

In part 1, I gave an overview of a pattern we use in the UI development of Max. In this post, I plan to talk about DataModels. In part 1, I wrote:

DataModel

DataModel is responsible for exposing data in a way that is easily consumable by WPF. All of its public APIs must be called on the UI thread only. It must implement INotifyPropertyChanged and/or INotifyCollectionChanged as appropriate. When data is expensive to fetch, it abstracts away the expensive operations, never blocking the UI thread (that is evil!). It also keeps the data "live". These sorts of classes are fairly straightforward to unit test.

I want to talk a bit about the threading model. Making all public APIs single threaded on a DataModel may seem like overkill. It's certainly possible to make some methods thread safe. And, you might know that WPF data binding will actually handle property changed events from other threads. But, in my experience, making the APIs of DataModel single thread significantly simplifies the models and eliminates many possible bugs. The rules become very simple. Of course, DataModels usually need to do operations on background threads, but they can use the Dispatcher to dispatch the results back to the UI thread.

Let's go through a possible DataModel base class. I will use it in the sample moving forward.

First, the defition and constructor:

    public class DataModel : INotifyPropertyChanged
    {
        public DataModel()
        {
            _dispatcher = Dispatcher.CurrentDispatcher;
        }

We grab the current Dispatcher in the constructor. We now have it available for any background operations that need to be dispatch results to the UI thread.

Now, here's the definition of the possible states of the model:

        public enum ModelState
        {
            Fectching,  // The model is fetching data
            Invalid,    // The model is in an invalid state
            Active      // The model has fetched its data
        }

I think these are pretty self explanatory. Basically, the model will be in a fetching state if it's fetching data asynchronously. Otherwise, it will be in the invalid or activate state. The state is made available through the following property:

        public ModelState State
        {
            get
            {
                VerifyCalledOnUIThread();
                return _state;
            }
 
            set
            {
                VerifyCalledOnUIThread();
                if (value != _state)
                {
                    _state = value;
                    SendPropertyChanged("State");
                }
            }
        }

This is the basic pattern we'll use for most model properties. When getting the value, we verify that we're on the UI thread and just return the cached value. When setting the property, we also verify that we're on the UI thread. And, if the value changed, we send the event that it changed. Let me fill in a couple of the utility functions now. The first is VerifyCalledOnUIThread():

        [Conditional("Debug")]
        protected void VerifyCalledOnUIThread()
        {
            Debug.Assert(Dispatcher.CurrentDispatcher == this.Dispatcher,
                "Call must be made on UI thread.");
        }

Basically, we make sure that we're on the right thread by checking the current dispatcher. The Conditional attribute makes it so this code isn't executed in retail bits. Sprinkling asserts in the code like this makes it easy to catch these violations early. Otherwise, you might end up tracing down hard to reproduce race conditions.

Next, here's our NotifyPropertyChanged event. We define our own add/remove handlers so we can verify that things are called on the UI thread. If handlers were added/removed from another thread, we'd run into threading issues.

        public event PropertyChangedEventHandler PropertyChanged
        {
            add
            {
                VerifyCalledOnUIThread();
                _propertyChangedEvent += value;
            }
            remove
            {
                VerifyCalledOnUIThread();
                _propertyChangedEvent -= value;
            }
        }

And, SendPropertyChanged is a helper function that notifies listeners that the named property changed:

        protected void SendPropertyChanged(string propertyName)
        {
            VerifyCalledOnUIThread();
            if (_propertyChangedEvent != null)
            {
                _propertyChangedEvent(this, new PropertyChangedEventArgs(propertyName));
            }
        }

That just leaves the fields:

        private ModelState _state;
        private Dispatcher _dispatcher;
        private PropertyChangedEventHandler _propertyChangedEvent;
    }

I'll be using this base class in my sample moving forward. If anyone's interested, I could make the source code available, but it's all here and I plan to make the full version with comments available when I get further along in the sample.

This class is missing one major feature that I plan to talk more about later. But, I think I need a disclaimer here in case anyone starts any of their own code based on this. As mentioned above, one of the roles of a DataModel is to keep its data "live". This can lead to memory leaks. To keep data live, the model will need to register for change notifications from some other source, or maybe set up a timer. This will keep the DataModel object alive. If there's a DataTemplate pointing to the DataModel with data binding set up, it will have registered for property changed notifications from the DataModel, so the DataModel will be keeping the UI in the DataTemplate alive, even after it's been unloaded from the UI. The solution we use is to have a reference counted activate/deactivate pattern in our DataModel classes where a model is only live while active. We activate the model when the UI pointing to it is Loaded, and deactivate when Unloaded. I'll blog about this more in the future...

DataModel-View-ViewModel pattern: 1

dancre — Mon, 24 Jul 2006 06:14:33 GMT

John Gossman has blogged several times about the M-V-VM pattern for developing WPF applications. We've been using a similar pattern on the Max team, with slightly different terminology (DataModel instead of ViewModel). I thought I'd do a series of posts about some of our learnings here. With this pattern, you can make a well componentized application that cleanly separates the visual style from the behavior and makes the behavior code highly testable.

I know this post will probably bring in some comments about terminology. I'm just using the terminology we use on our team and it works well for us. Use whatever you like!

The elements of this pattern are as follows:

DataModel

DataModel is responsible for exposing data in a way that is easily consumable by WPF. All of its public APIs must be called on the UI thread only. It must implement INotifyPropertyChanged and/or INotifyCollectionChanged as appropriate. When data is expensive to fetch, it abstracts away the expensive operations, never blocking the UI thread (that is evil!). It also keeps the data "live" and can be used to combine data from multiple sources. These sorts of classes are fairly straightforward to unit test.

ViewModel

A ViewModel is a model for a view in the application (duh!). It exposes data relevant to the view and exposes the behaviors for the views, usually with Commands. The model is fairly specific to a view in the application, but does not subclass from any WPF classes or make assumptions about the UI that will be bound to it. Since they are separate from the actual UI, these classes are also relatively straightforward to unit test.

View

A View is the actual UI behind a view in the application. The pattern we use is to set the DataContext of a view to its ViewModel. This makes it easy to get to the ViewModel through binding. It also matches the DataTemplate/Data pattern of WPF. Ideally, the view can be implemented purely as Xaml with no code behind. The attached property trick comes in very handy for this.

The lines between DataModels and ViewModels can be blurry. DataModels are often shown in the UI with some DataTemplate, which isn't really so different than the way we use ViewModels. However, the distinction usually makes sense in practice. I also want to point out that there's often composition at many layers. ViewModels may compose other ViewModels and DataModels. And, DataModels may be composed of other DataModels.

Next, I plan to work my way up to a sample that includes all of these layers. I also plan to include some examples of unit testing including some issues like dealing with Dispatchers.

Part 2: A DataModel base class