Category Archives: prism

WPF Prism concepts: regions

If you are a developer in the Microsoft environment and if you’re developing desktop apps, it’s likely that you’ve read something about Prism.  If you don’t then this is what Prism is about:

Prism is a framework for building loosely coupled, maintainable, and testable XAML applications in WPF, Windows 10 UWP, and Xamarin Forms. (from the Prism’s Official GitHub description)

The Prism documentation is very detailed but with this blog post we are more practical and examples-driven. If you want to dive into the details of Prism the official documentation is the best place.

Definition

A region is a placeholder in the shell of a Prism application for content that will be loaded at runtime. Regions are defined as UI elements like ContentControl, ItemsControl, TabControl or a custom control.

The content of a region is a view. We can access regions in a decoupled way by their name and they support dynamically adding or removing views.

Example with view discovery

So now it’s coding time!

The first thing we need is to setup our app to be a Prism-app. At this point we have a clean Prism-App.

Then, we create a region in our MainWindow. This is the XAML code.

<Window x:Class="XXXXX.Views.MainWindow"         xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"         xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"          xmlns:prism="http://prismlibrary.com/"                Title="MainWindow" Height="300" Width="300">
    <Grid>
        <ContentControl prism:RegionManager.RegionName="RegionA" />
    </Grid>
</Window>

We can see that the regions are defined as XAML attached properties. In the code above our region is called RegionA.

Now we have our region defined but no content to load into. We create a new user control in the Views subfolder and name it ViewA.xaml.

Immagine

In this class in the XAML part we write:

<UserControl x:Class="XXXXX.Views.ViewA"              xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"              >
    <Grid>
        <TextBlock Text="View A" FontSize="38" />
    </Grid>
</UserControl>

That’s good! We have our region and a view. Now it’s time to tell Prism that RegionA is the target where to load the ViewA view. In the code-behind of the MainWindows.xaml we write:

using Prism.Regions;
using System;
using System.Windows;

namespace XXXXX.Views
{

    public partial class MainWindow : Window
    {
        public MainWindow(IRegionManager regionManager)
        {
            InitializeComponent();

            if (regionManager == null)
            {
                throw new ArgumentNullException(nameof(regionManager));
            }
            regionManager.RegisterViewWithRegion("RegionA", typeof(ViewA));
        }
    }
}

With the above code for the constructor we are registering that RegionA has to be populated with an instance of ViewA view. The region manager is passed as a parameter by the DI container (in our case Unity). This technique is called View Discovery. The result is:

Screenshot_1

Example with View Injection

Now we explore the View Injection technique that enables us to load and unload the content of a region dynamically at runtime.

We create a new view, ViewB, like we did for ViewA under the Views folder.

<UserControl x:Class="XXXXX.Views.ViewB"              xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"            >
    <Grid>
        <TextBlock Text="View B" FontSize="38" Foreground="#FF0023FF" />
    </Grid>
</UserControl>

We edit the MainWindow to add another region and a button to fire our code:

<Window x:Class="XXXXX.Views.MainWindow"         xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"         xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"          xmlns:prism="http://prismlibrary.com/"                Title="MainWindow" Height="300" Width="300">
    <StackPanel>
        <ContentControl prism:RegionManager.RegionName="RegionA" />
  <Button Click="Button_Click" >Load region B</Button>
<Button Click="Button_Clear_Click" >Clear region B</Button>
<ContentControl prism:RegionManager.RegionName="RegionB" />
    </StackPanel>
</Window>

And the code behind

public partial class MainWindow : Window
    {

        private readonly IRegionManager _regionManager;
        private readonly IUnityContainer _container;

        public MainWindow(IRegionManager regionManager, IUnityContainer container)
        {
            InitializeComponent();
            //view discovery
            if (regionManager == null)
            {
                throw new ArgumentNullException(nameof(regionManager));
            }

            if (container == null)
            {
                throw new ArgumentNullException(nameof(container));
            }

            _regionManager = regionManager;
            _container = container;

            _regionManager.RegisterViewWithRegion(RegionNames.RegionA, typeof(ViewA));

        }

        private void Button_Click(object sender, RoutedEventArgs e)
        {
            //We get from the container an instance of ViewB.
            var view = _container.Resolve<ViewB>();

            //We get from the region manager our target region.
            IRegion region = _regionManager.Regions["RegionB"];

            //We inject the view into the region.
            region.Add(view);
        }

  private void Button_Clear_Click(object sender, RoutedEventArgs e)
        {
            //We get from the region manager our target region.
            IRegion region = _regionManager.Regions["RegionB"];

            //Clears the content.
            region.RemoveAll();
        }

    }

What we’re doing here is to get our target region by using the RegionManager class.

The RegionManager class is responsible for creating and maintaining a collection of regions for the host controls. The RegionManager uses a control-specific adapter that associates a new region with the host control. The following illustration shows the relationship between the region, control, and adapter set up by the RegionManager. (Prism official docs)

When we have a reference of the region (RegionB in this case) we can add or remove content with the Add or the Remove/RemoveAll methods.

Screenshot_2

TL;DR

In this blog post we explored the concept of Region. Regions are useful conteiners to create our UI in a structured and dynamic way. We loaded content with the discovery and the injection technique.

In the next blog post we’ll study other Prism’s concepts.

Happy coding!

Reference

Prism official documentation (http://prismlibrary.readthedocs.io/en/latest/)
Prism Github page (https://github.com/PrismLibrary)

UWP Prism Unit Test

I’m sure we all hear about unit testing, test driven development and so on. These practices are useful and provide a long list of benefit like writing low-coupled and mantainable code to name a few.

We want to write unit test for our UWP Prism application and we’d like, for example, to put our ViewModels under tests to make sure the logic they implement is correct. Unit testing is possible only if we can get rid of all the dependencies in our class under test because we want to run our test every time we want (for exemple when the service library our teammate is writing is not yet finished) and as fast as we can.

Continue reading

Prism UWP for beginners: lifecycle

 

In this post we’ll explore the management of the lifecycle of a UWP app inside the OS.

Classic programs (Win32, for example) have two states: not running and running. When the typical desktop app is running it use all the RAM and CPU it needs, even when it is in the background. This is a problem in the world of universal apps because many types of device have very limited battery, CPU, and memory. So in this ecosystem we need to be green and free resources as soon as possible.

Windows comes to our help about power management but we need to know a few more things that we have to manage in our code. The OS can suspend our app when it wants in some cases and we need to give our useres the best user experience.

By default, apps that are not in the foreground are suspended which results in power savings and more resources available for the app currently in the foreground.

updated-lifecycle

In MSDN documentation we can find a detailed explanation of every status and the suggested action to take:

image

When a user leaves our application by switching to another one without terminating, he or she expects to find all the things in place when he/she’ll come back. The termination by the OS has to be transparent. So we need to save the state of the app and restore when the OS will restore the app.

Let’s do it!

Plain data

When we need to save simple data like boolean, strings, or numeric values we decorate with the RestorableState attribute in our viewmodel the properties that we need to save and restore. For example we have a TextBox binded to a string property:

  
        
        
  

And this is our code behind:


class RestoreStatePageViewModel : ViewModelBase
{
[RestorableState]
public string SimpleProperty
{
get { return _simpleProperty; }

set
{
_simpleProperty = value;

SetProperty(ref _simpleProperty, value);
}
}

public override void OnNavigatedTo(NavigatedToEventArgs e, Dictionary viewModelState)
{
base.OnNavigatedTo(e, viewModelState);
}

private ISessionStateService _sessionStateService;

private string _simpleProperty;
}

That’s it! Now: how to try? How can we force the OS to suspend our App? Visual Studio helps providing the Debug Location toolbar with the Lifecycle Events dropdown.

image

If this toolbar is not visible we find it by right-clicking in the white space of the main toolbar and select Debug Location.

image

Now we can launch our app and write something in the TextBox. Then we select Suspend and shutdown in the Lifecycle events dropdown. Visual studio will stop debugging and the app terminated. Now we hit F5 again to restart our app and we’ll find that the TextBox has the same value we writed before.

Complex data

Sometimes we have to save and restore complex or custom data. In this scenario we rely on the SessionStateService provided by Prism.

We register this service during the bootstrap in the App.xaml.cs code in the OnInitializeAsync method:

 protected override Task OnInitializeAsync(IActivatedEventArgs args)
        {

            Container.RegisterInstance(SessionStateService);

            return base.OnInitializeAsync(args);
        }

Let’s say we have a class that represents our Twitter Timeline. We need to decorate the class and the properties we want to save and restore with the DataContract and the DataMember attributes respectively.

This is because the Prism framework needs to serialize and deserialize our class and with UWP we don’t have the [Serializable] attribute we have in the standard .net environment.

using System.Collections.Generic;
using System.Runtime.Serialization;

namespace IC6.Buongiorno.Services.Twitter
{
    [DataContract]
    public class TwitterTimeline
    {
        [DataMember]
        public string Timeline { get; private set; }

        public TwitterTimeline(IEnumerable tweets)
        {
            Timeline = string.Join("\r\n\r\n\r\n", tweets);
        }
    }
}

We also need to configure Prism to serialize our custom class. We do this the App.xaml.cs code in the override of the OnRegisterKnownTypesForSerialization() method in which we have to register, in the SessionStateService, every custom class we’re going to use in the application, like in the following sample:

 protected override void OnRegisterKnownTypesForSerialization()
        {
            base.OnRegisterKnownTypesForSerialization();

            SessionStateService.RegisterKnownType(typeof(TwitterTimeline));
        }

Our class is now ready to be saved and restored.

In our viewmodel we need to save our timeline and we write:

public void SaveState()
{
if (_sessionStateService.SessionState.ContainsKey(SettingNames.Timeline.ToString()))
                {
                    _sessionStateService.SessionState.Remove(SettingNames.Timeline.ToString());
                }
                _sessionStateService.SessionState.Add(SettingNames.Timeline.ToString(), twitter);
}

To restore the state the best place is the OnNavigatedTo event.

 public override void OnNavigatedTo(NavigatedToEventArgs e, Dictionary viewModelState)
        {
            base.OnNavigatedTo(e, viewModelState);

                        if (_sessionStateService.SessionState.ContainsKey(SettingNames.Timeline.ToString()))
            {
                var twitter = _sessionStateService.SessionState[SettingNames.Timeline.ToString()] as TwitterTimeline;

                Timeline =  twitter.Timeline;
            }

                    }

We can test all this with the same procedure as before.

TL;DR

In this post we explored the concepts of lifecycle management and how to use Prism event to save and restore the state of our app to provide the best experience to our users.

If you want to learn more:

Prism UWP posts

Prism UWP for beginners: navigation

In this post we’ll talk about the navigation with Prism in UWP. With navigation I mean the technique to go from one page to another of your app. The operation in UWP/XAML is tipically performed with the Frame class that’s available only in the code-behind of a Page because it inherits from Frame. This way we do not respect the MVVM pattern. Prism comes in our help providing a wrapper to the Frame class accessible from the ViewModel: it’s the NavigationService. This isn’t a very new name to us because we found it in the bootstrapper.

protected override Task OnInitializeAsync(IActivatedEventArgs args)
{
//...
Container.RegisterInstance(NavigationService);
//...
}

We saw it at the end of the bootstrap procedure in the OnLaunchApplicationAsync method, too.

protected override Task OnLaunchApplicationAsync(LaunchActivatedEventArgs args)
{
NavigationService.Navigate(PageNames.Main.ToString(), null);
return Task.FromResult(true); //This is a little trick because this method returns a Task.
}

To try the navigation system we create a SettingsPage in the View folder and then we’ll navigate to that page with a button in the MainPage.

Immagine

To go to there we need a command in the MainPageViewModel class and bind it in the MainPage view.

public class MainPageViewModel : ViewModelBase
{
public DelegateCommand GoToSettings { get; private set; }

//...
}

In the constructor we initialize the GoToSettings property.

public MainPageViewModel(ITwitterService twitterService, IWeatherService weatherService, INavigationService navigationService)
{

_navigationService = navigationService;

GoToSettings = new DelegateCommand(() =&gt;
{
_navigationService.Navigate("Settings", null);
});
}

In the constructor we added a parameter: the INavigationService reference. This new dependency will be handled by Unity container when resolving an instance of MainPageViewModel. The GoToSettingsCommand is composed by a single line of code where we call the Navigate method with the first argument that is the name of the page where we want to go and the second argument is to add additional information: since we have no additional data we write null.

In this example the Settings page allows us to change the backgorund image of the main page. We notice that in the upper left corner of the application a back. This is handeld by the UWP framwork when detects a navigation.

This back button can be different based on the device where the app is running: phone, tablet or pc. For example in a tablet with tablet mode enabled it will appear on the navigation bar at the botton of the device. In the MSDN we can find al the details.

Screenshot_2.png

When we click the back button we go back to the main page.

When navigating in our view-model we can use two methods to detect when we land into a page or when we leave a page. OnNavigatedTo is callaed when navigation in performed to a page. OnNavigatingFrom is called when navigating away from the page.

   public override void OnNavigatedTo(NavigatedToEventArgs e, Dictionary viewModelState)
        {
            base.OnNavigatedTo(e, viewModelState);

//Loading state custom logic.
        }

        public override void OnNavigatingFrom(NavigatingFromEventArgs e, Dictionary viewModelState, bool suspending)
        {
            base.OnNavigatingFrom(e, viewModelState, suspending);
//Save state logic.
        }

TL;DR

In this post we explored the basic concept about navigating with Prism in UWP App with the Navigation Service and the events that Prism offers to detect the transition from one page to another.

If you want to learn more you can refer to the Prism official website and MSDN. Happy coding!

Prism UWP posts

Prism UWP for beginners: binding and commands

We setup the foundation of a Prism UWP app in the last post. Now we explore binding and commands.

Binding

Binding is the mechanism that connects the UI to the view-model properties to display data in the page and to receive input from the user (with two way binding). We can do binding by implementing the INotifyPropertyChanged interface in our view-model so the view is notified when a property in the view-model changes.

Prism helps us by providing classes that we can use to avoid reinventing the wheel and to start quickly with binding: VisualStateAwarePage and ViewModel.

We use VisualStateAwarePage instead of Page when we create a new view, for example:

<mvvm:SessionStateAwarePage
x:Class="IC6.Buongiorno.Views.MainPage"
mvvm:ViewModelLocator.AutoWireViewModel="True"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:IC6.Buongiorno.Views"
xmlns:mvvm="using:Prism.Windows.Mvvm" >
    <mvvm:SessionStateAwarePage.Background>
        <ImageBrush Stretch="Fill"
            ImageSource="ms-appx:///Assets/wallpaper.jpg" />
    </mvvm:SessionStateAwarePage.Background>

    <Grid Margin="50">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="1*" />
            <ColumnDefinition Width="10*" />
        </Grid.ColumnDefinitions>

        <StackPanel Grid.Column="0"  Margin="10">
            <Button Command="{Binding Update}" Foreground="White">Update
            </Button>
            <TextBlock Text="{Binding Timeline}" Foreground="White" TextWrapping="Wrap" />
        </StackPanel>
        <StackPanel Grid.Column="1"                     HorizontalAlignment="Right">
            <TextBlock Text="{Binding WeatherDescription}" FontSize="32" Foreground="White" />
            <TextBlock Text="{Binding WeatherTemperature}" FontSize="50" Foreground="White" />
        </StackPanel>
    </Grid>
</mvvm:SessionStateAwarePage>

We must replace the Page type in the code-behind, too.

using Prism.Windows.Mvvm;

// The Blank Page item template is documented at https://go.microsoft.com/fwlink/?LinkId=234238

namespace IC6.Buongiorno.Views
{
    ///
<summary>
    /// An empty page that can be used on its own or navigated to within a Frame.
    /// </summary>

    public sealed partial class MainPage : SessionStateAwarePage
    {
        public MainPage()
        {
            InitializeComponent();

        }

    }
}

We create a MainPageViewModel class in the ViewModels directory and inherit from ViewModel. ViewModel is class of Prism that provides several helpers. In this example we create 3 properties in the ViewModel: Timeline, WeatherDescription, WeatherTemperature. Timeline will expose our Twitter timeline to the UI, WeatherDescrption will expose a brief textual description of the current weather (like “sunny”, “heavy rain”) and WeatherTemperature will expose the current temperature. This is the full MainPageViewModel.

using IC6.Buongiorno.Services.Twitter;
using IC6.Buongiorno.Services.Weather;
using Prism.Commands;
using Prism.Windows.Mvvm;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace IC6.Buongiorno.ViewModels
{
    public class MainPageViewModel : ViewModelBase
    {
        ///<summary>
        /// Gets the command to Update Timeline and weather data.
        /// </summary>

        public DelegateCommand Update { get; private set; }

        ///<summary>
        /// Gets or sets the Twitter timeline.
        /// </summary>

        public string Timeline
        {
            get { return _timeline; }
            set { SetProperty(ref _timeline, value); }
        }

        ///<summary>
        /// Gets or sets the current weather description.
        /// </summary>

        public string WeatherDescription
        {
            get { return _weatherDescription; }
            set { SetProperty(ref _weatherDescription, value); }
        }

        ///<summary>
        /// Gets or sets the current weather temperature.s
        /// </summary>

        public string WeatherTemperature
        {
            get { return _weatherTemperature; }
            set { SetProperty(ref _weatherTemperature, value); }
        }

        ///<summary>
        /// Constructor with services.
        /// </summary>

        /// <param name="twitterService">The <see cref="ITwitterService"/> to access Twitter data.</param>
        /// <param name="weatherService">The <see cref="IWeatherService"/> to get current weather information.</param>
        public MainPageViewModel(ITwitterService twitterService, IWeatherService weatherService)
        {
            if (twitterService is null)
            {
                throw new ArgumentNullException(nameof(twitterService));
            }

            if (weatherService is null)
            {
                throw new ArgumentNullException(nameof(weatherService));
            }

            _twitterService = twitterService;

            _weatherService = weatherService;

            Update = new DelegateCommand(async () =>
            {
                Timeline = (await _twitterService.GetTimelineAsync()).Timeline;

                var weatherInfo = (await _weatherService.GetWeather());

                WeatherDescription = weatherInfo.Description;

                WeatherTemperature = $"{weatherInfo.Temperature} °C";
            });
        }

        private string _weatherTemperature;

        private string _weatherDescription;

        private readonly ITwitterService _twitterService;

        private readonly IWeatherService _weatherService;

        private string _timeline;
    }
}

In the code above the SetProperty method is provided by the ViewModel base class and with this we leverage the INotifyPropertyChanged interface to inform the UI that a property has updated its value.

In the constructor we have two dependencies: ITwitterService and IWeatherService. They are handled by the Unity container that we configured in the previuos post. When we’ll ask Unity to resolve an instance of MainPage it will automatically resolve ITwitterService and IWeatherService avoing to us all the heavylifting. This way our code remain clean and easier to read and mantain.

The view-model is automatically linked to the view by Prism beacuse in the page we declared mvvm:ViewModelLocator.AutoWireViewModel="True".

Commands

Commands are the mechanism to support the user interaction without using event handlers. In the Prism framework we find the DelegateCommand that implements the ICommand interface required by XAML.

The ICommand interface exposes a method called CanExecute that is very powerful. With a boolean condition we check if the command is enabled or not. In the MainPageViewModel class we declare an ICommand property and in the constructor we assign a DelegateCommand. In this example we’re getting the timeline from the Twitter service and the weather data from the weather service and assingn to the properties.

In the XAML code above we bind the button Update to this command with the standard binding syntax in the Command property of the Button.

TL;DR

In this post we explored the concepts of bindings and the commands to handle user input and display data retrieved with our services.

Cattura.PNG

Stay tuned for other Prims UWP posts.

Prism UWP posts

Prism UWP for beginners: setup

I want to learn Prism because it may be helpful in some future projects. To better understand how it works I need a target. I’d like to create a simple UWP app that displays my Twitter timeline and the local weather based on the GPS. Prism will help me to adopt the MVVM architeture and IoC/DI concepts. The MVVM and IoC/DI topics are out of the scope of this post.

Setup

I started a new UWP project with Visual Studio 2017 and then imported the Prism.Windows and Prims.Unity NuGet packages. Prism.Windows is the “core” library for the UWP techology and Prism.Unity is the IoC/DI container.

Screenshot_1.png

Conversion to Prism

I converted the Universal app to a Prism Universal app by configuring the bootstrapper. The bootstrapper is a required procedure by the Prism framework to properly initialize all the infrastructure. In vanilla UWP, the bootstrapper is the App class. I edited the App class so that it doesn’t inherit from the native Application class but from a Prism class called PrismUnityApplication.

This is the full App.xaml file.

<prismUnity:PrismUnityApplication x:Class="IC6.Buongiorno.App"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:prismUnity="using:Prism.Unity.Windows"
RequestedTheme="Light">

</prismUnity:PrismUnityApplication>

 

This is the full App.xaml.cs file.

using System.Threading.Tasks;
using Microsoft.Practices.Unity;
using Prism.Unity.Windows;
using Prism.Windows.AppModel;
using Windows.ApplicationModel.Activation;
using Windows.ApplicationModel.Resources;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using IC6.Buongiorno.Services.Twitter;
using IC6.Buongiorno.Services.Weather;

namespace IC6.Buongiorno
{
/// <summary>
/// Provides application-specific behavior to supplement the default Application class.
/// </summary>
public sealed partial class App : PrismUnityApplication
{

public App()
{
InitializeComponent();
}

protected override UIElement CreateShell(Frame rootFrame)
{
var shell = Container.Resolve<Shell>();
shell.SetContentFrame(rootFrame);
return shell;
}

/// <summary>
/// Logic of app initialization.
/// This is the best place to register the services in Unity container.
/// </summary>
/// <param name="args"></param>
/// <returns></returns>
protected override Task OnInitializeAsync(IActivatedEventArgs args)
{
System.Diagnostics.Debug.WriteLine(">>>>>>>>>>>>> OnInitializeAsync called.");

Container.RegisterInstance<ITwitterService>(new TwitterService());

Container.RegisterInstance<IWeatherService>(new WeatherService());

Container.RegisterInstance<IResourceLoader>(new ResourceLoaderAdapter(new ResourceLoader()));

Container.RegisterInstance(SessionStateService);

Container.RegisterInstance(NavigationService);

return base.OnInitializeAsync(args);
}

protected override Task OnLaunchApplicationAsync(LaunchActivatedEventArgs args)
{
NavigationService.Navigate(PageNames.Main.ToString(), null);

return Task.FromResult(true); //This is a little trick because this method returns a Task.
}
}
}

 

I created a Paged called Shell. The Prism definition of shell is:

The main window of an application where the primary UI content is contained.

Shell is called in the CreateShell method triggered by the Unity framework to create the main window of the application.

The OnInitializeAsync method is the place to initialize the Unity container. Here I registered my services. With registering I mean telling Unity that, for example, every time I need an ITwitterService it has to give me an instance of TwitterService. I also register the NavigationService and SessionStateService that I’ll explain in other posts.

I created the standard MVVM folders because Prism is convention based for some of its features.

image

I deleted the default MainPage.xaml file and created a new one in the Views directory as shown in the image above.

Inside OnLaunchApplicationAsync I called the NavigationService.Navigate method to navigate to the MainPage which accepts as first parameter the name of the page (the name of the View without the Page suffix): by passing as parameter the value “Main” Prism searches, in the Views folder, a page called MainPage.xaml. The second parameter is null because I didn’t have additional parameters to pass. The last statement is a little trick because this method returns a Task and I created a fake one with a constant true value.

TL;DR

I made my first steps with Prism in a UWP application: I created the shell and setup the bootstrapper.

Prism UWP posts