1. Prism
2. Prism.Composition (New)
3. Prism.Interactivity (New)
4. Prism.Mvvm (New)
5. Prism.MefExtensions
6. Prism.UnityExtensions

We’ve updated Prism 4.1 with bug fixes and a few new features. We’ve removed Silverlight support. Windows Phone 8.1 will be supported in a future project. I hope you find this guidance and accompanying libraries helpful and useful.

Implementing this functionality was made much simpler in the AdventureWorks Shopper app with the AutoRotatingGridView control that automatically uses a horizontal scroll bar in landscape mode and a vertical scroll bar in portrait mode.

Let’s take a look at the AdventureWorks Shopper HubPage. To capture the AutoRotatingGridView’s scroll viewer’s scroll position we listen to the LayoutUpdated event.

void itemGridView_LayoutUpdated(object sender, object e)
{
    _scrollViewerOffsetProportion = 
         ScrollViewerUtilities.GetScrollViewerOffsetProportion(_itemsGridViewScrollViewer);
}

Notice that the LayoutUpdated event handler uses the itemGridView’s embedded ScrollViewer which is captured after the itemGridView is loaded.

void itemGridView_Loaded(object sender, RoutedEventArgs e)
{
    _itemsGridViewScrollViewer = VisualTreeUtilities.GetVisualChild<ScrollViewer>(itemGridView);
}

Here is the source for the GetVisualChild<T> method:

public static T GetVisualChild<T>(DependencyObject parent) where T : DependencyObject
{
    T child = default(T);
    int numVisuals = VisualTreeHelper.GetChildrenCount(parent);
    for (int i = 0; i < numVisuals; i++)
    {
        DependencyObject v = VisualTreeHelper.GetChild(parent, i);
        child = v as T;
        if (child == null)
            child = GetVisualChild<T>(v);
        if (child != null)
            break;
    }
    return child;
}
  

Here is the source for the GetScrollViewerOffsetProportion method:

public static double GetScrollViewerOffsetProportion(ScrollViewer scrollViewer)
{
    if (scrollViewer == null) return 0;

    var horizontalOffsetProportion = (scrollViewer.ScrollableWidth == 0) ? 0 
              : (scrollViewer.HorizontalOffset / scrollViewer.ScrollableWidth);
    var verticalOffsetProportion = (scrollViewer.ScrollableHeight == 0) ? 0 
              : (scrollViewer.VerticalOffset / scrollViewer.ScrollableHeight);

    var scrollViewerOffsetProportion = Math.Max(horizontalOffsetProportion, verticalOffsetProportion);
    return scrollViewerOffsetProportion;
}

Now that we’ve captured the scroll offset proportion (_scrollViewerOffsetProportion) after the user has scrolled, let’s use this value to scroll to the same approximate position when the user changes rotates their device or resizes the frame. When the page size changes we will check to see if the scroll viewer has finished resizing. We need to let the scroll viewer settle before we can change its scroll offset. One way we found to determine when the scroll viewer has stabilized is to examine the ComputedHorizontalScrollBarVisibility and ComputedVerticalScrollBarVisibility properties.

void Page_SizeChanged(object sender, SizeChangedEventArgs e)
{
    var scrollViewer = VisualTreeUtilities.GetVisualChild<ScrollViewer>(itemsGridView);

    if (scrollViewer != null)
    {
        if (scrollViewer.ComputedHorizontalScrollBarVisibility == Visibility.Visible 
             && scrollViewer.ComputedVerticalScrollBarVisibility == Visibility.Visible)
        {
            ScrollViewerUtilities.ScrollToProportion(scrollViewer, _scrollViewerOffsetProportion);
        }
        else
        {
            DependencyPropertyChangedHelper horizontalHelper = 
                new DependencyPropertyChangedHelper(scrollViewer, "ComputedHorizontalScrollBarVisibility");
            horizontalHelper.PropertyChanged += ScrollBarVisibilityChanged;

            DependencyPropertyChangedHelper verticalHelper = 
                new DependencyPropertyChangedHelper(scrollViewer, "ComputedVerticalScrollBarVisibility");
            verticalHelper.PropertyChanged += ScrollBarVisibilityChanged;
        }
    }
}

If these two properties equal Visibility.Visible then the scroll viewer is ready to be modified/scrolled. If not, then we use the DependencyPropertyChangedHelper to listen for changes in these two dependency properties.

private void ScrollBarVisibilityChanged(object sender, DependencyPropertyChangedEventArgs e)
{
    var helper = (DependencyPropertyChangedHelper)sender;

    var scrollViewer = VisualTreeUtilities.GetVisualChild<ScrollViewer>(itemsGridView);

    if (((Visibility)e.NewValue) == Visibility.Visible)
    {
        ScrollViewerUtilities.ScrollToProportion(scrollViewer, _scrollViewerOffsetProportion);
        helper.PropertyChanged -= ScrollBarVisibilityChanged;
    };

    if (_isPageLoading)
    {
        itemsGridView.LayoutUpdated += itemsGridView_LayoutUpdated;
        _isPageLoading = false;
    }
}

In the ScrollBarVisibilityChanged handler, we check to see if the dependency property has changed to Visible. If so, we update the scroll viewer by calling its ChangeView method.

public static void ScrollToProportion(ScrollViewer scrollViewer, double scrollViewerOffsetProportion)
{
    // Update the Horizontal and Vertical offset
    if (scrollViewer == null) return;
    var scrollViewerHorizontalOffset = scrollViewerOffsetProportion * scrollViewer.ScrollableWidth;
    var scrollViewerVerticalOffset = scrollViewerOffsetProportion * scrollViewer.ScrollableHeight;

    scrollViewer.ChangeView(scrollViewerHorizontalOffset, scrollViewerVerticalOffset, null);
}

To recap, we have:

1. Captured the AutoRotatingGridView’s scroll viewer’s offset value as a proportion to its total size.
2. After the user resizes the window either by rotating the device or changing the size of the frame, we apply the offset proportion value back to the AutoRotatingGridView.

Notice that if the user navigates to another page or the app is terminated, this offset proportion value is lost. In order to preserve this value, we utilize the SaveState and LoadState methods provided by the VisualStateAwarePage base class.

        protected override void SaveState(System.Collections.Generic.Dictionary<string, object> pageState)
        {
            if (pageState == null) return;

            base.SaveState(pageState);

            pageState["scrollViewerOffsetProportion"] = 
                ScrollViewerUtilities.GetScrollViewerOffsetProportion(_itemsGridViewScrollViewer);
        }

        protected override void LoadState(object navigationParameter, Dictionary<string, object> pageState)
        {
            if (pageState == null) return;

            base.LoadState(navigationParameter, pageState);

            if (pageState.ContainsKey("scrollViewerOffsetProportion"))
            {
                _scrollViewerOffsetProportion = 
                    double.Parse(pageState["scrollViewerOffsetProportion"].ToString());                
            }
        }

After the LoadState method populates the _scrollViewerOffsetProportion value, the Page_SizeChanged event handler mentioned above will update the scroll viewer to the appropriate scroll offset position.

I’ve tried to do this using separate GridView and ListView controls instead of a single AutoRotatingGridView control and the code is much more complicated and repetitive. You need to get the offset proportion from the GridView control and set it into the ListView control when the app goes from Landscape to Portrait, and vice versa when the app goes from Portrait to Landscape.

In the AdventureWorks app updated to 8.1, we considered using two separate controls as we had in the previous release, additionally using the ListView for Portrait mode. However the item data templates in Portrait mode were similar to the Landscape, not Minimal. There were also a few things about Portrait that were different from Minimal that made it hard to use the same ListView for both Portrait and Minimal visual states. Therefore, we were faced with having to use a GridView for Landscape, a ListView for Portrait and finally a separate ListView for Minimal. Yuck!

Enter the AutoRotatingGridView. This control is included in the AdventureWorks reference implementation updated to 8.1. This control listens to the its SizeChanged event and updates its layout between Landscape/Portrait/Minimal based on the windows size and shape. All you have to do is provide the appropriate values for:

1. Item data template
2. Items panel
3. Group style

A really nice feature of the AutoRotatingGridView is that if you don’t provide any of the above values for Portrait or Minimal modes, the control will fall back to the value defined for Landscape.

<awcontrols:AutoRotatingGridView
    ItemsSource="{Binding Items}"
    ItemTemplate="{StaticResource ProductTemplate}"
    MinimalItemTemplate="{StaticResource ProductTemplateMinimal}">
    <awcontrols:AutoRotatingGridView.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid Orientation="Vertical" />
        </ItemsPanelTemplate>
    </awcontrols:AutoRotatingGridView.ItemsPanel>
    <awcontrols:AutoRotatingGridView.PortraitItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid Orientation="Horizontal"/>
        </ItemsPanelTemplate>
    </awcontrols:AutoRotatingGridView.PortraitItemsPanel>
    <awcontrols:AutoRotatingGridView.MinimalItemsPanel>
        <ItemsPanelTemplate>
            <StackPanel HorizontalAlignment="Stretch" Margin="0,0,5,0"/>
        </ItemsPanelTemplate>
    </awcontrols:AutoRotatingGridView.MinimalItemsPanel>
</awcontrols:AutoRotatingGridView>

The above XAML defines an AutoRotatingGridView with an ItemTemplate, for Landscape mode, and a MinimalItemTemplate. When the control is in Portrait mode, the “ProductTemplate” ItemTemplate will be used since there is no PortraitItemTemplate specified. When the control is in Minimal, the control will use the “ProductTemplateMinimal” as specified by the MinimalItemTemplate property.

One feature that is missing from Windows Store app sdk is control support for user input validation. In WPF and Silverlight, you would expect to implement INotifyDataErrorInfo/IDataErrorInfo and controls such as TextBox and ComboBox would show an error state when appropriate. Unfortunately, these controls do not support these interfaces in the current release of .NET for Windows Store apps and Windows Runtime.

What is provided is support for DataAnnotations attributes. The Prism.StoreApps library provides some assistance in validating model objects that leverage these DataAnnotationson attributes. You will need to provide your own attached properties to appropriately style input controls. You can find an example error highlighting attached property in the AdventureWorks reference implementation (HighlightFormFieldOnErrors.PropertyErrors).

You can get the latest source on CodePlex.

Let’s take a look at how you can use the Microsoft.Practices.Prism.StoreApps library to validate user input.

1. Complete the Creating a basic implementation of the MVVM pattern walk through from the previous post.
2. Add a model class to the project: Add a class named Credential.
3. Use ValidatableBindableBase as the base class for the Credential class.
4. Add two string properties to the Credential class: Username and Password.
   Make sure to use a backing field and the SetProperty method provided by ValidatableBindableBase. The SetProperty method not only checks that the new value is different from the existing value before raising the PropertyChanged event, it also runs the validation logic.

   private string _username;
   private string _password;
   
   public string Username
   {
       get { return _username; }
       set { SetProperty(ref _username, value); }
   }
   
   public string Password
   {
       get { return _password; }
       set { SetProperty(ref _password, value); }
   }
       

5. Add “Required” and “StringLength” DataAnnotations attributes to each property.

   [Required]
   [StringLength(10)]
   public string Username
   {
       get { return _username; }
       set { SetProperty(ref _username, value); }
   }
   
   [Required]
   [StringLength(20)]
   public string Password
   {
       get { return _password; }
       set { SetProperty(ref _password, value); }
   }

6. The model class is ready so let’s expose an instance of it on the SignInFlyoutViewModel.
7. Add a class named SignInFlyoutViewModel to the ViewModels folder.
8. Add a property to the SignInFlyoutViewModel that exposes the Credential model.    

   public class SignInFlyoutViewModel
   {
       public SignInFlyoutViewModel()
       {
           UserCredential = new Credential();
       }
       public Credential UserCredential { get; set; }
   }

9. Use the ViewModelLocator.AutoWireViewModel=”True” attached property on the SignInFlyout page to associate this page (view) with the SignInFlyoutViewModel.
10. Next, let’s add some controls to the view to bind to the Username and Password properties of the view model’s Credential property. We’ll also add some TextBlocks that will bind to any validation error messages.    

    <TextBox Text="{Binding UserCredential.Username, Mode=TwoWay}" 
             BorderBrush="Black" />
    <TextBlock Text="{Binding UserCredential.Errors[Username], 
                        Converter={StaticResource FirstErrorConverter}}" 
             Foreground="Red" />
    <TextBox Text="{Binding UserCredential.Password, Mode=TwoWay}" 
             BorderBrush="Black" />
    <TextBlock Text="{Binding UserCredential.Errors[Password], 
                        Converter={StaticResource FirstErrorConverter}}" 
             Foreground="Red"/>

11. Note that the TextBlock controls bind to the Errors property of the UserCredential on the view model. The Errors property is provided by ValidatableBindableBase and is populated when a property fails validation. Since The Errors property returns a collection of string error messages for a given property name, we will use a value converter to show only the first message. Here is the source code for the FirstErrorConverter:
    

    public sealed class FirstErrorConverter : IValueConverter
    {
        public object Convert(object value, 
                              Type targetType, 
                              object parameter, 
                              string language)
        {
            ICollection<string> errors = value as ICollection<string>;
            return errors != null && errors.Count > 0 ? errors.ElementAt(0):null;
        }
    
        public object ConvertBack(object value, 
                                  Type targetType, 
                                  object parameter, 
                                  string language)
        {
            throw new NotImplementedException();
        }
    }

12. To use this value converter as a static resource, remember to reference it in App.xaml:

    <ResourceDictionary>
        ...
        <converters:FirstErrorConverter x:Key="FirstErrorConverter" />
    </ResourceDictionary>

13. Run the app and tap the “ShowFlyout” button. Enter some values in the two textboxes on the SignInFlyout. If you enter a string value that is too long for the field, or you remove the contents of either field, you will see the appropriate message in the TextBlocks.
14. Next, add a button that calls UserCredential.ValidateProperties() that validates all properties of the model object instance.

    public SignInFlyoutViewModel()
    {
        UserCredential = new Credential();
        ValidateAll = 
            new DelegateCommand(() => UserCredential.ValidateProperties());
    }
    public Credential UserCredential { get; set; }
    
    public ICommand ValidateAll { get; set; }

15. Add a button to the view that binds to the ValidateAll command. Remember that the background of the flyout is white according to the UI Guidelines so you will need to style your controls accordingly.

    <Button Command="{Binding ValidateAll}" 
            Content="Validate All" 
            Foreground="Black"/>

You can get the latest source on CodePlex.

The following procedure shows how to integrate a dependency injection container into a Windows Store app that leverages MvvmAppBase from the Microsoft.Practices.Prism.StoreApps library.

1. Add a reference to a Dependency Injection Container library. This walk through will use the Unity v3 container which is available via nugget (https://www.nuget.org/packages/Unity/).
2. Add a private member varliable to the App class that will hold the container.

   private UnityContainer _container = new UnityContainer();

3. Override the Resolve method on the App class so that it uses the container to resolve object instances from a type.

   protected override object Resolve(Type type)
   {
       return _container.Resolve(type);
   }

4. You can now remove the call to ViewModelLocator.Register in App.OnInitialize because the ViewModelLocator can use the container to resolve view model types. Register into the container any services that will need to be provided to view models via constructor injection. The StartPageViewModel needs an instance of IFlyoutService. The following code registers the three services provided by the MvvmAppBase.

   protected override void OnInitialize(IActivatedEventArgs args)
   {
       _container.RegisterInstance(NavigationService);
       _container.RegisterInstance(FlyoutService);
       _container.RegisterInstance(SessionStateService);
   }

5. Run the app. Notice that the button still causes the FlyoutService to show the SignInFlyout.

You can get the latest source on CodePlex.

The following procedure shows how to create and show a Flyout by using the Microsoft.Practices.Prism.StoreApps library. You will discover how to use the FlyoutService class within a view model to show the Flyout, and how to add a SettingsCommand that will launch the Flyout from the Settings pane.

1. Complete the Creating a basic implementation of the MVVM pattern walk through from the previous post.
2. First let’s create a Flyout. Add a blank page named SignInFlyout to the Views folder.
   The FlyoutService will use a default convention to look for Flyouts in the Views namespace where the name of the Flyout ends in “Flyout”.
3. Add a TextBlock to the Grid control in the SignInFlyout page.

   <Grid Background="White">
       <TextBlock Text="Sign In!!!" Foreground="Black" />
   </Grid>
       

4. Change the SignInFlyout class to derive from the FlyoutView base class in the Microsoft.Practices.Prism.StoreApps library. Also, specify the width in the constructor. The StandardFlyoutSize class is defined in the Microsoft.Practices.Prism.StoreApps library.

   public sealed partial class SignInFlyout : FlyoutView
   {
       public SignInFlyout() : base(StandardFlyoutSize.Narrow)
       {
           this.InitializeComponent();
       }
   }

5. Update the SignInFlyout.xaml file so that the SignInFlyout view extends the FlyoutView base class in the Microsoft.Practices.Prism.StoreApps library.

6.  <Infrastructure:FlyoutView
        xmlns:Infrastructure="using:Microsoft.Practices.Prism.StoreApps"
        ...
    </Infrastructure:FlyoutView>
       

7. Next, let’s update the StartPage to show the SignInFlyout. Import the interfaces from the Microsoft.Practices.Prism.StoreApps namespace into the StartPageViewModel class.

   using Microsoft.Practices.Prism.StoreApps.Interfaces;

8. Add a constructor to the StartPageViewModel class that takes a parameter of type IFlyoutService.

   public StartPageViewModel(IFlyoutService flyoutService)
   {
   }

9. Notice that the StartPageViewModel class does not have a default constructor.
10. Run the app.
    You will receive a MissingMethodException that indicates that there isn't a parameterless constructor defined for the StartPageViewModel object. This occurs because the ViewModelLocator uses its default convention to locate the StartPageViewModel. The ViewModelLocator then used its default view model factory (Activator.CreateInstance) to construct an instance of the view model. In order for this to work, the type being constructed must possess a default constructor.
11. Let’s provide the ViewModelLocator with a factory to create view model instances for the StartPage. Override the OnInitialize method in the App class to train the ViewModelLocator how to construct the StartPageViewModel instance.

    protected override void OnInitialize(IActivatedEventArgs args)
    {
        ViewModelLocator.Register(typeof(StartPage).ToString(), 
                () => new StartPageViewModel(FlyoutService));
    }

12. The Register method takes a string representation of the view type, and a delegate that returns the view model. You will see that the StartPageViewModel instance is created with the FlyoutService property of the MvvmAppBase class being passed to its constructor. Now that the ViewModelLocator knows how to construct the view model for the StartPage, it will not follow its convention for the StartPage.
13. Add a Button to the StackPanel in StartPage that will show the SignInFlyout.

    <StackPanel>
        <TextBlock Text="Hello World!!!" />
        <TextBox Text="{Binding FirstName, Mode=TwoWay}" />
        <Button Content="ShowFlyout"
                Command="{Binding SignInCommand}" />
    </StackPanel>
        

14. Notice that the Button's Command property will be bound to a SignInCommand in the StartPageViewModel class.
15. Import the System.Windows.Input namespace into the StartPageViewModel class.

    using System.Windows.Input;

16. Add the SignInCommand property to the StartPageViewModel class.

    public ICommand SignInCommand { get; private set; }

17. The property has a private setter because it will only be set internally.
18. Set the SignInCommand property to an instance of a DelegateCommand that invokes the FlyoutService.

    public StartPageViewModel(IFlyoutService flyoutService)
    {
         SignInCommand = new DelegateCommand(() => flyoutService.ShowFlyout("SignIn"));
    }

19. The DelegateCommand class, provided by the Microsoft.Practices.Prism.StoreApps library, is constructed with a delegate that will be invoked when the command is executed. Here, a lambda expression is specified that calls the ShowFlyout method of the FlyoutService class, passing the name of the Flyout.
20. Run the app.
21. Select the SignIn Button.
    The SignInFlyout appears. Yeah!
22. Next, let’s add an item to the Settings pane that will also show the SignInFlyout. Stop the app and override the GetSettingsCharmActionItems method in the App class. This method will be called when the CommandsRequested event of the SettingsPane class is raised. Add a SettingsCharmActionItem to the Settings pane that will open the SignInFlyout.

    protected override IList<SettingsCharmActionItem> GetSettingsCharmActionItems()
    {
        return new List<SettingsCharmActionItem>{ new SettingsCharmActionItem("Sign In", 
            () => FlyoutService.ShowFlyout("SignIn"))};
    }

23. The SettingsCharmActionItem class, provided by the Microsoft.Practices.Prism.StoreApps library, takes two constructor parameters. The first is a string title that will be displayed in the Settings pane. The second is an Action delegate that will be invoked when the user selects the “Sign In” item in the Settings pane.
24. Run the app. Invoke the charms menu by making a horizontal edge gesture, swiping left with a finger or pointing device from the right of the screen.
25. Select the Settings charm to display the Settings pane.
26. Select the “Sign In” item.
    The SignInFlyout appears.
    

Next let’s integrate a dependency injection container into the app.

You can get the latest source on CodePlex.

The following procedure shows how to create a basic implementation of the MVVM pattern by using the Microsoft.Practices.Prism.StoreApps library. You will also discover how view model instances can save their state to survive app termination.

1. Complete the Creating a Hello World app walk through from the previous post.
2. Add a folder named ViewModels to the root folder of the Windows Store app project.
3. Add a new class to the ViewModels folder named StartPageViewModel.
4. Make the StartPageViewModel class public.
5. Add a FirstName property and backing field to the StartPageViewModel class.

   private string _firstName;
   public string FirstName
   {
       get { return _firstName; }
       set { _firstName = value; }
   }

6. Import the types from the Microsoft.Practices.Prism.StoreApps library into the StartPageViewModel class.

7. using Microsoft.Practices.Prism.StoreApps;

8. Update the StartPageViewModel class so that it derives from the ViewModel base class in the Microsoft.Practices.Prism.StoreApps library.

   public class StartPageViewModel : ViewModel

9. By deriving the StartPageViewModel class from the ViewModel base class we can use the ViewModel class's implementation of INotifyPropertyChanged.
10. Update the FirstName property to use the SetProperty method, from the Microsoft.Practices.Prism.StoreApps library, in the property setter.

    public string FirstName
    {
        get { return _firstName; }
        set { SetProperty(ref _firstName, value); }
    }

11. The SetProperty method first checks to see if the new property value is identical to the old value. If the new value is different, the backing field is updated and the PropertyChanged event is raised with the property name as the event argument.
12. Replace the contents of the Grid control in the StartPage view with a TextBox that will bind to the FirstName property of the StartPageViewModel class.

    <StackPanel>
        <TextBlock Text="Hello World!!!"
                   Style="{StaticResource HeaderTextStyle}" />
        <TextBox Text="{Binding FirstName, Mode=TwoWay}" />
    </StackPanel>

13. The TextBox control will allow you to enter data. Since the Text property of the TextBox is bound to the FirstName property of the StartPageViewModel class with a TwoWay binding, updating the text in the TextBox control will update FirstName property and vice versa.
14. Add the ViewModelLocator.AutoWireViewModel attached property to the Page control for the StartPage.

    <Page xmlns:Infrastructure="using:Microsoft.Practices.Prism.StoreApps"
          Infrastructure:ViewModelLocator.AutoWireViewModel="True"
          ... >
        ...
    </Page>

15. The AutoWireViewModel attached property tells the ViewModelLocator object to create an instance of the view model that corresponds to this view and set it into the view's DataContext property. The ViewModelLocator object uses a default convention where it looks in the "ViewModels" namespace for a type whose name starts with the name of the view and ends with "ViewModel".
16. Run the app. Enter a value in the TextBox. The FirstName property of the StartPageViewModel instance will be updated.
17. With the app running select the Suspend and shutdown menu option from the Debug Location toolbar in Visual Studio.
    This feature is used to ensure that your app behaves as expected when Windows suspends or resumes it, or activates it after a suspend and shutdown sequence.
18. Run the app.
    Notice that the value you previously entered into the TextBox is no longer present.
19. Stop the app and update the StartPageViewModel class so that the FirstName property is annotated with the [RestorableState] attribute.

    [RestorableState]
    public string FirstName
    {
        get { return _firstName; }
        set { SetProperty(ref _firstName, value); }
    }

20. Properties annotated with the [RestorableState] custom attribute will have their values saved when the app suspends, and will have their values restored when the app reactivates following termination.
21. Run the app. With the app running select the Suspend and shutdown menu option from the Debug Location toolbar in Visual Studio.
22. Run the app again. Notice that the value you previously entered into the TextBox survived termination.

Next let’s take a look at how to create a Flyout and show it using the FlyoutService.

Basically, if you are interested in improving the quality and maintainability of your Windows Store apps, I recommend taking a look at this guidance.

You can get the latest source on CodePlex.

This post is part 1 of a series that walks you through how to use the Prism for Windows Runtime library to create a Windows Store app. The Prism library will not only make your apps more testable and maintainable, I believe it will also make it easier to create Windows Store apps.

Creating a Hello World app using Prism for Windows Runtime

1. Create a new C#-based Windows Store app named HelloWorld using the Blank App (XAML) Visual Studio project template.
2. Add a reference to the Microsoft.Practices.Prism.StoreApps library.
3. Add a folder named “Views” to the root folder of the Windows Store app project.
   This app will use the FrameNavigationService class, provided by the Microsoft.Practices.Prism.StoreApps library, to navigate. The FrameNavigationService class's default convention is to locate pages in the "Views" namespace of the Windows Store app project. When the Navigate method of the FrameNavigationService class is called with a page token parameter, "Page" is appended to the page token. For example, if the Navigate method was called with "Customer" as the page token, the FrameNavigationService would look for a page named "CustomerPage" in the "Views" namespace.
4. Add a new Blank Page named “StartPage” to the Views folder.
5. Add a TextBlock control to the page's Grid control.    

   <TextBlock Text="Hello World!!!" Style="{StaticResource HeaderTextStyle}" />

6. Delete all of the contents of the App.xaml.cs file. This boilerplate functionality is now provided by the MvvmAppBase class.
7. Add the following code to the App.xaml.cs file.

   using Microsoft.Practices.Prism.StoreApps;
   
   sealed partial class App : MvvmAppBase
   {
       public App()
       {
           this.InitializeComponent();
       }
   }

8. Update the App.xaml file so that the App class derives from the MvvmAppBase class rather than the Application class.

   <Infrastructure:MvvmAppBase xmlns:Infrastructure="using:Microsoft.Practices.Prism.StoreApps">
      ...
   </Infrastructure:MvvmAppBase>
   

9. Add code to the App class to navigate to the StartPage.
   The MvvmAppBase class provides several virtual methods that you can override to customize its behavior. However, MvvmAppBase provides the OnLaunchApplication abstract method for which you must provide an override. This method specifies what your app will do when it's launched.

   protected override void OnLaunchApplication(LaunchActivatedEventArgs args)
   {
       NavigationService.Navigate("Start", null);
   }
   
   The MvvmAppBase has a NavigationService property that exposes the FrameNavigationService.

10. Run the app. When the app runs you will see the StartPage with the “Hello World!!!” TextBlock.

Next let’s take a look at how to associate a view model to the StartPage view in my next post: Creating a basic implementation of the MVVM pattern.

We split up our guidance into three parts:

1. Developing a Windows Phone Application using the MVVM Pattern
   This guidance walks you through building a simple Windows Phone application using CodeBehind files. The guidance then shows you how the same app can be much more unit testable when built using the MVVM pattern.
2. A Case Study for Building Advanced Windows Phone Applications
   This guidance takes an in-depth look at how to write an advanced Windows Phone application, using many features of Mango. Unit testability was an important factor that guided the design of this application.
3. Building Testable Windows Phone Applications
   Taking the work on unit testability from the above guidance, this guidance provides shorter samples of how to build unit testable Windows Phone applications.

Please take a look and send me your feedback.

I’ve seen several blog posts on this topic but none that gave me an end to end solution. Armed with the latest Mango bits and the CoreCon 10 WP7 API, this task was easier than I thought. Here’s how it works…

1. Capture the unit test run with custom LogProvider that writes the test run messages to a file in isolated storage.
2. Custom MSBuild task that deploys test xap file to emulator, installs the application, runs the application, waits for a configured number of seconds and harvests the results of item #1 above.

Let’s start with the custom LogProvider:

public class FileLogProvider : LogProvider
{
    public const string TESTRESULTFILENAME = @"TestResults\testresults.txt";
    protected override void ProcessRemainder(LogMessage message)
    {
        base.ProcessRemainder(message);
        AppendToFile(message);
    }

    public override void Process(LogMessage logMessage)
    {
        AppendToFile(logMessage);
    }

    private void AppendToFile(LogMessage logMessage)
    {
        UTF8Encoding encoding = new UTF8Encoding();
        var carriageReturnBytes = encoding.GetBytes(new[] { '\r', '\n' });

        using (IsolatedStorageFile store = IsolatedStorageFile.GetUserStoreForApplication())
        {
            if (!store.DirectoryExists("TestResults"))
            {
                store.CreateDirectory("TestResults");
            }
            using (IsolatedStorageFileStream isoStream =
                store.OpenFile(TESTRESULTFILENAME, FileMode.Append))
            {
                var byteArray = encoding.GetBytes(logMessage.Message);
                isoStream.Write(byteArray, 0, byteArray.Length);
                isoStream.Write(carriageReturnBytes, 0, carriageReturnBytes.Length);
            }
        }
    }
}

public partial class MainPage : PhoneApplicationPage
{
    // Constructor
    public MainPage()
    {
        this.InitializeComponent();
        LogProvider fileLogProvider = new FileLogProvider();
        var settings = UnitTestSystem.CreateDefaultSettings();
        settings.LogProviders.Add(fileLogProvider);

        Content = UnitTestSystem.CreateTestPage(settings);
        BackKeyPress += (x, xe) => xe.Cancel = (Content as IMobileTestPage).NavigateBack();
    }
}

Great! Now that we’ve captured the test run results on the phone, how do we get it to the server? I’ve heard people use web services but I found using the CoreCon API worked fine.

My custom MSBuild task does the following:

1. Connects to the emulator
2. Installs/Reinstalls the application
3. Launches the application
4. Waits a specified number of seconds for the application to finish running tests.
5. Pulls the TestResults\testresults.txt file from the application’s isolated storage and copies it locally.
6. Examines the contents of the test results for failing unit test.

Here is the source for my custom MSBuild task:

namespace MSBuildTasks
{
    public class RunWP7UnitTestsInEmulator : Task
    {
        private int defaultNumberOfMiliSecondsToProcess = 50000;

        [Required]
        public string PathToUnitTestXapFile { get; set; }

        [Required]
        public string ProductGuid { get; set; }

        public int NumberOfMilliSecondsToProcess { get; set; }

        public override bool Execute()
        {
            if (NumberOfMilliSecondsToProcess == 0)
            {
                Log.LogMessage(string.Format("Using default processing time: {0}", defaultNumberOfMiliSecondsToProcess));
                NumberOfMilliSecondsToProcess = defaultNumberOfMiliSecondsToProcess;
            }

            Log.LogMessage(string.Format("NumberOfMilliSecondsToProcess: {0}", NumberOfMilliSecondsToProcess));

            Log.LogMessage("Running tests in XAP: " + PathToUnitTestXapFile);
            var productGuid = new Guid(ProductGuid);

            var emulator = GetWP7Emulator();
            Log.LogMessage("Connecting to Emulator.");
            emulator.Connect();
            Log.LogMessage("After call to Connect().");

            //Deploy application
            if (emulator.IsApplicationInstalled(productGuid))
            {
                emulator.GetApplication(productGuid).Uninstall();
            }

            emulator.InstallApplication(productGuid, productGuid, "NormalApp", null, PathToUnitTestXapFile);

            //Run application
            var application = emulator.GetApplication(productGuid);
            application.Launch();


 
            Thread.Sleep(NumberOfMilliSecondsToProcess);

            //Get Results from Isolated Store on device
            var isostorefile = application.GetIsolatedStore();
            var localTestResultFileName = "EmulatorTestResults-" + productGuid + ".txt";
            isostorefile.ReceiveFile(@"\TestResults\testresults.txt", localTestResultFileName, true);

            var testResults = File.ReadAllText(localTestResultFileName);

            if (testResults.Contains("Exception:"))
            {
                Log.LogError("Failing test found. Look for exception in: " + localTestResultFileName);
                return false;
            }

            Log.LogMessage("All tests passed.");

            emulator.Disconnect();

            return true;
        }

        private Device GetWP7Emulator()
        {
            var manager = new DatastoreManager(CultureInfo.CurrentUICulture.LCID);
            var wp7Platform = manager.GetPlatforms().Single(platform => platform.Name == "Windows Phone 7");
            return wp7Platform.GetDevices().Single(device => device.Name == "Windows Phone Emulator");
        }
    }
}

<Project DefaultTargets="Test" xmlns="https://schemas.microsoft.com/developer/msbuild/2003" >
    <UsingTask TaskName="MSBuildTasks.RunWP7UnitTestsInEmulator" 
        AssemblyFile="MSBuildTasks.dll"/>

    <PropertyGroup>
        <SourceFilesPath>$(MSBuildProjectDirectory)\..\Source\</SourceFilesPath>

    </PropertyGroup>

    <ItemGroup>
        <SolutionItemsToBuild Include="$(SourceFilesPath)\**\*.sln" />
    </ItemGroup>

    <Target Name="Build">
        <MSBuild Projects="%(SolutionItemsToBuild.Identity)" Targets="Build"/>
    </Target>

    <Target Name="Test" DependsOnTargets="Build">
        <RunWP7UnitTestsInEmulator NumberOfMilliSecondsToProcess="50000" 
            PathToUnitTestXapFile="$(SourceFilesPath)\MyWP7Project.Tests\Bin\Debug\MyWP7Project.Tests.xap" 
            ProductGuid="MyWP7ProjectProductGuid" />
    </Target>
</Project>

You’ll need to replace the PathToUnitTexstXapFile and ProductGuid, but this proj file should build all solutions in the “Source” folder and then test the Windows Phone unit tests specified in the Test target.

I’ve had this integrated into my continuous integration server and it works great. I need to run the CI server in interactive mode because launching the emulator on my server box always pops a dialog complaining about the graphics processing unit configuration. I just keep an emulator instance open to avoid this popup.