Upgrading Radial Gauge from UWP to WinUI 3

In this article we describe the process of migrating a user control from UWP to WinUI 3. The subject is the Radial Gauge that we wrote many years ago and is currently part of Windows Community Toolkit. For its UI the radial gauge uses XAML as well as the Composition API. To successfully migrate the control from UWP to WinUI3

• we had to remove some UWP calls that don’t exist in WinUI 3,
• we replaced some UWP calls by their WinUI 3 counterpart, and
• we decided to give the control a more rounded Windows 11 look-and-feel.

Setting up the environment

When we started this journey, the most recent version of Windows App SDK was the experimental preview of v1.0, so the list of required NuGet packages looked like this:

We installed the new Visual Studio templates:

After the upgrade to the official Windows App SDK 1.0 release, the dependencies list conveniently shrunk to this:

We created a sample app wherein all relevant UWP Radial Gauge source files from Windows Community Toolkit were copy-pasted.

Here’s the taxonomy of the current Windows 8 -style Radial Gauge control:

There was no need to change these properties, just as there was no need to change the control’s XAML template:

<ControlTemplate TargetType="local:RadialGauge">
    <Viewbox>
        <Grid x:Name="PART_Container"
              Width="200"
              Height="200">
 
            <!--  Scale  -->
            <Path Name="PART_Scale" />

            <!--  Trail  -->
            <Path Name="PART_Trail" />

            <!--  Value and Unit  -->
            <StackPanel HorizontalAlignment="Center"
                        VerticalAlignment="Bottom">
                <TextBlock Name="PART_ValueText" />
            </StackPanel>
        </Grid>
    </Viewbox>
</ControlTemplate>

The scale and trail of the gauge are Path elements, and then there are text boxes for value and unit. The rest of the UI parts -needle, ticks, and scale ticks- are drawn by the Composition API.

Goodbye Windows.UI namespace

The first step in migrating a code base from UWP to WinUI would be changing the namespace from Windows.UI.* to Microsoft.UI.* in a zillion places. All compiled well after this change…

Goodbye UI Events

… but at runtime the Toolkit’s ThemeListener crashed the app. It’s a known issue and the reason is that UWP’s UISettings.ColorValuesChanged Event and AccessibilitySettings.HighContrastChanged Event are no longer supported in desktop apps. Unlike UWP apps, WinUI 3 desktop apps are not notified when the user changes the theme, the contrast color, or high contrast mode. This is not a showstopper – as long as you stick to ThemeResources in your XAML. Since theming support is a popular feature these days, we assume that the majority of recent UWP apps is already using theme resource dictionaries. Make sure you don’t forget one for HighContrast. You don’t really need a notification when the theme changes at runtime: all XAML and Composition elements that get their color from a ThemeResource will immediately and automatically change color.

Here’s how we configured the Radial Gauge instances on the Home page of the sample app:

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="HighContrast">
        <!-- This makes the background disappear in High Contrast mode -->
        <x:Double x:Key="BackgroundOpacity">0</x:Double>
        <SolidColorBrush x:Key="TenPercentContrastBrush"
             Color="{ThemeResource SystemColorWindowTextColor}" />
        <SolidColorBrush x:Key="SystemAccentColorBrush"
             Color="{StaticResource SystemAccentColor}" />
        <SolidColorBrush x:Key="AppNeedleBrush"
             Color="{ThemeResource SystemAccentColor}" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
        <x:Double x:Key="BackgroundOpacity">.075</x:Double>
        <SolidColorBrush x:Key="TenPercentContrastBrush"
             Color="White"
             Opacity=".1" />
        <Color x:Key="SystemAccentColor">CadetBlue</Color>
        <SolidColorBrush x:Key="SystemAccentColorBrush"
             Color="{StaticResource SystemAccentColor}"
             Opacity=".5" />
        <SolidColorBrush x:Key="AppNeedleBrush"
             Color="OrangeRed" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="Light">
        <x:Double x:Key="BackgroundOpacity">.15</x:Double>
        <SolidColorBrush x:Key="TenPercentContrastBrush"
             Color="Black"
             Opacity=".1" />
        <Color x:Key="SystemAccentColor">CadetBlue</Color>
        <SolidColorBrush x:Key="SystemAccentColorBrush"
             Color="{StaticResource SystemAccentColor}"
             Opacity=".5" />
        <SolidColorBrush x:Key="AppNeedleBrush"
             Color="OrangeRed" />
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

Here’s that page in Light, Dark, and HighContrast theme:

As it turned out that all the Toolkit’s ThemeListener related code in the Radial Gauge is actually obsolete in a WinUI 3 desktop context, we removed that code.

Goodbye CoreWindow

Radial Gauge supports keyboard input. The Value property can be changed via the arrow keys, with the CTRL key to manage the change interval. To detect the virtual key press Radial Gauge was using CoreWindow.GetKeyState():

var ctrl = Window.Current.CoreWindow.GetKeyState(VirtualKey.Control);
if (ctrl.HasFlag(CoreVirtualKeyStates.Down))
{
    step = LargeChange;
}

Since UWP’s CoreWindow is not available in WinUI 3 desktop apps, we had to look for another way to detect key presses. We found it in the appropriately named KeyboardInput class. Here’s the new code:

if (KeyboardInput.GetKeyStateForCurrentThread(VirtualKey.Control) == CoreVirtualKeyStates.Down)
{
    step = LargeChange;
};

Goodbye KeyboardInput

Just a few days after that last modification, we upgraded the project to Windows App SDK v1.0 only to observe that the KeyboardInput class was not there anymore. We abandoned the keyboard events and went for Keyboard Accelerators. In hindsight that would always have been the proper approach. We created an extension method to facilitate the declaration:

public static void AddKeyboardAccelerator(this UIElement element,
  VirtualKeyModifiers keyModifiers,
  VirtualKey key,
  TypedEventHandler<KeyboardAccelerator, KeyboardAcceleratorInvokedEventArgs> handler)
{
    var accelerator =
      new KeyboardAccelerator()
      {
          Modifiers = keyModifiers,
          Key = key
      };
    accelerator.Invoked += handler;
    element.KeyboardAccelerators.Add(accelerator);
}

Then we replaced the keypress event handler by eight keyboard accelerators (one for each arrow key, with and without CTRL). Here are two of those:

this.AddKeyboardAccelerator(
    VirtualKeyModifiers.Control,
    VirtualKey.Left,
    (ka, kaea) =>
    {
        Value = Math.Max(Minimum, Value - LargeChange);
        kaea.Handled = true;
    });
this.AddKeyboardAccelerator(
    VirtualKeyModifiers.None,
    VirtualKey.Left,
    (ka, kaea) =>
    {
        Value = Math.Max(Minimum, Value - SmallChange);
        kaea.Handled = true;
    });

Goodbye DesignMode

One of the major differences between UWP and Win32 Desktop is the application model. Unsurprisingly the Windows.ApplicationModel namespace did not survive into Windows App SDK v1.0. As a result, the DesignMode to detect whether the control is hosted by a Visual Designer is not available anymore. It is used in the Toolkit’s DesignTimeHelper class. There seem to be no plans for a WinUI 3 Desktop XAML Designer, and with features like XAML Live Preview and XAML Hot Reload there’s no urgent need for one. Again, we happily removed another part of the Radial Gauge code.

Goodbye Windows 8 style

The original looks of the Radial Gauge were a product of the Windows 8 design style: sharp (“rounded corners, shadows, and gradients are bad for battery life”) and plump (“touch first: designed for fingers”). We decided it was time for a make-over to bring the UI closer to Windows 11 design. We made another copy of the control (“RadialGauge2”) where we

• decreased the default scale width,
• rounded the Scale and Trail shapes by changing their PenLineCaps in the XAML template,
• rounded the Tick, ScaleTick and Needle elements, and
• provided support for Opacity in these elements.

Rounding the shapes was not a trivial job, since we were relying on SpriteVisual instances – unrounded rectangles filled with a non-transparent CompositionColorBrush. Here’s the old code for the ticks:

SpriteVisual tick;
for (double i = radialGauge.Minimum; i <= radialGauge.Maximum; i += radialGauge.TickSpacing)
{
    tick = radialGauge._compositor.CreateSpriteVisual();
    tick.Size = new Vector2((float)radialGauge.TickWidth, (float)radialGauge.TickLength);
    tick.Brush = radialGauge._compositor.CreateColorBrush(radialGauge.TickBrush.Color);
    tick.Offset = new Vector3(100 - ((float)radialGauge.TickWidth / 2), 0.0f, 0);
    tick.CenterPoint = new Vector3((float)radialGauge.TickWidth / 2, 100.0f, 0);
    tick.RotationAngleInDegrees = (float)radialGauge.ValueToAngle(i);
    radialGauge._root.Children.InsertAtTop(tick);
}

The new Radial Gauge uses a CompositionRoundedRectangleGeometry to fill a CompositionSpriteShape for each tick, and then groups all the ticks into a single ShapeVisual. Transparent brushes are not possible in this part of the API (well, at least not in a simple way). As a work-around we applied the opacity of the source brush to the Opacity of the Visual. Here’s the -much longer- new code:

var ticks = radialGauge._compositor.CreateShapeVisual();
ticks.Size = new Vector2((float)radialGauge.Height, (float)radialGauge.Width);
ticks.BorderMode = CompositionBorderMode.Soft;
ticks.Opacity = (float)radialGauge.TickBrush.Opacity;
 
var roundedTickRectangle = radialGauge._compositor.CreateRoundedRectangleGeometry();
roundedTickRectangle.Size = new Vector2((float)radialGauge.TickWidth, (float)radialGauge.TickLength);
roundedTickRectangle.CornerRadius = new Vector2((float)radialGauge.TickWidth / 2, (float)radialGauge.TickWidth / 2);
 
var tssFillBrush = radialGauge._compositor.CreateColorBrush(radialGauge.TickBrush.Color);
var tssOffset = new Vector2(100 - ((float)radialGauge.TickWidth / 2), 0.0f);
var tssCenterPoint = new Vector2((float)radialGauge.TickWidth / 2, 100.0f);
 
for (double i = radialGauge.Minimum; i <= radialGauge.Maximum; i += radialGauge.TickSpacing)
{
    var tickSpriteShape = radialGauge._compositor.CreateSpriteShape(roundedTickRectangle);
    tickSpriteShape.FillBrush = tssFillBrush;
    tickSpriteShape.Offset = tssOffset;
    tickSpriteShape.CenterPoint = tssCenterPoint;
    tickSpriteShape.RotationAngleInDegrees = (float)radialGauge.ValueToAngle(i);
 
    ticks.Shapes.Add(tickSpriteShape);
}
 
radialGauge._root.Children.InsertAtTop(ticks);

The Home page of our sample app compares the new look to the original one:

The Gallery page displays two sets of controls: the top row has some gauge configurations using the old style, the second row has the same gauges but is using the new style:

We believe that the second row looks better in any configuration.

Here’s how it looks like with the official v1.0.0. of Windows App SDK, bringing the Windows 11 style into the equation:

Here’s how the upgraded Radial Gauge looks like in a candidate production app that is in the middle of its migration to WinUI 3:

For the sake of completion: that other control in the screenshot is a Radial Range Indicator.

The Verdict

Migrating controls and apps from UWP to WinUI 3 involves more than a namespace change, and we’re OK with that. Some API’s have disappeared, but none of these was crucial – not to this user control and not to the apps we’re currently migrating.

We are happy with the result: Radial Gauge now has better looks and less source code to maintain.

The sample app lives here on GitHub.

Enjoy!

Pagination with Entity Framework Core and Microsoft MVVM in WinUI 3

In this article we present a LINQ-based pagination solution for list controls as well as a pager user interface, all in a WinUI 3 application. We use SQLite as data provider and a Windows Community Toolkit DataGrid as host control, but the solution applies to any Entity Framework Core (EF Core) store and any WinUI 3 ItemsControl. For the implementation of the MVVM pattern, we chose the usual suspect: Microsoft MVVM Toolkit.

Here’s how the sample page looks like:

This is a new XAML page that we added to the sample app for our previous article on using the DataGrid in WinUI 3.

The heart of our pagination infrastructure is PaginatedList<T> – a subclass of List<T>.

It holds a specific page from a query result as a list of items can be bound to any ItemsControl as ItemsSource. A PaginatedList<T> instance not only embeds the (partial) result of the query but it also exposes the current page number, and the total number of pages for the whole query (quite convenient for a pager UI). The page size (number of records wanted) is not a property but is provided to the constructor.

Here’s how the class definition looks like:

public class PaginatedList<T> : List<T>
{
    public int PageIndex { get; private set; }

    public int PageCount { get; private set; }

    private PaginatedList(List<T> items, int count, int pageIndex, int pageSize)
    {
        PageIndex = pageIndex;
        PageCount = (int)Math.Ceiling(count / (double)pageSize);
        AddRange(items);
    }

    public static async Task<PaginatedList<T>> CreateAsync(
	IQueryable<T> source, 
	int pageIndex, 
	int pageSize)
    {
        int count = await source.CountAsync();
        List<T> items = await source
	.Skip((pageIndex - 1) * pageSize)
	.Take(pageSize)
	.ToListAsync();

        return new PaginatedList<T>(items, count, pageIndex, pageSize);
    }
}

We’re using some of the asynchronous EF Core IQueryable Extensions here, but feel free to add a synchronous version if that better fits your use case.

The PaginatedList is used inside the XAML page’s ViewModel (a Microsoft MVVM Toolkit’s ObservableObject) to produce a List<Mountain> to which the DataGrid is bound. The ViewModel also exposes the current page number and the total number of pages. These are used by the pager on top. Here’s the ViewModel’s code:

public class PaginationPageViewModel : ObservableObject
{
    private int _pageSize = 10;
    private int _pageNumber;
    private int _pageCount;
    private List<Mountain> _mountains;

    public int PageNumber
    {
        get => _pageNumber;
        private set => SetProperty(ref _pageNumber, value);
    }

    public int PageCount
    {
        get => _pageCount;
        private set => SetProperty(ref _pageCount, value);
    }

    public List<Mountain> Mountains
    {
        get => _mountains;
        private set => SetProperty(ref _mountains, value);
    }

    private async Task GetMountains(int pageIndex, int pageSize)
    {
        using MountainDbContext dbContext = new();
        PaginatedList<Mountain> pagedMountains = await PaginatedList<Mountain>.CreateAsync(
            dbContext.Mountains
                .OrderBy(m => m.Rank),
            pageIndex,
            pageSize);
        PageNumber = pagedMountains.PageIndex;
        PageCount = pagedMountains.PageCount;
        Mountains = pagedMountains;
    }
}

Here’s how the ‘current page of Mountains’ is bound to the DataGrid:

<ctWinUI:DataGrid x:Name="DataGrid"
                    ItemsSource="{x:Bind ViewModel.Mountains, Mode=OneWay}"
                    AutoGenerateColumns="False"
                    CanUserSortColumns="False"
                    SelectionMode="Single"
                    IsReadOnly="True"
                    RowDetailsVisibilityMode="Collapsed">
    <ctWinUI:DataGrid.Columns>
        <ctWinUI:DataGridTextColumn Header="Rank"
                                    Binding="{Binding Rank}" />
        <ctWinUI:DataGridComboBoxColumn Header="Mountain"
                                        Binding="{Binding Name}" />
        <!-- More columns -->
    </ctWinUI:DataGrid.Columns>
</ctWinUI:DataGrid>

The ViewModel also exposes 4 commands -implementors of IAsyncRelayCommand– to allow refreshing the DataGrid with a new logical page:

public IAsyncRelayCommand FirstAsyncCommand { get; }

public IAsyncRelayCommand PreviousAsyncCommand { get; }

public IAsyncRelayCommand NextAsyncCommand { get; }

public IAsyncRelayCommand LastAsyncCommand { get; }

We would have loved to use one of the new WinUI Pager controls for user interface, but tody these are available in WinUI 2 only. Therefor we brewed our own CommandBar-based pagination control with the canonical navigation buttons to the first, previous, next, and last pages:

<CommandBar DefaultLabelPosition="Right">
    <AppBarButton ToolTipService.ToolTip="First"
                    Icon="Previous"
                    Command="{x:Bind ViewModel.FirstAsyncCommand, Mode=OneWay}" />
    <AppBarButton ToolTipService.ToolTip="Previous"
                    Icon="Back"
                    Command="{x:Bind ViewModel.PreviousAsyncCommand, Mode=OneWay}" />
    <AppBarElementContainer>
        <TextBlock Text="Page" />
    </AppBarElementContainer>
    <AppBarElementContainer>
        <TextBlock Text="{x:Bind ViewModel.PageNumber, Mode=OneWay}" />
    </AppBarElementContainer>
    <! -- And so on ... -->

Here’s how the AsyncRelayCommands are initialized in the ViewModel with their respective Execute and CanExecute logic:

FirstAsyncCommand = new AsyncRelayCommand(
    async () => await GetMountains(1, _pageSize),
    () => _pageNumber != 1
);
PreviousAsyncCommand = new AsyncRelayCommand(
    async () => await GetMountains(_pageNumber - 1, _pageSize),
    () => _pageNumber > 1
);
NextAsyncCommand = new AsyncRelayCommand(
    async () => await GetMountains(_pageNumber + 1, _pageSize),
    () => _pageNumber < _pageCount
);
LastAsyncCommand = new AsyncRelayCommand(
    async () => await GetMountains(_pageCount, _pageSize),
    () => _pageNumber != _pageCount
);

Each time a new page is fetched and displayed, we need to tell the commands that their CanExecute property was updated so that the corresponding buttons in the pager will enable or disable themselves:

FirstAsyncCommand.NotifyCanExecuteChanged();
PreviousAsyncCommand.NotifyCanExecuteChanged();
// And so on ...

To improve the user experience, we enhanced PaginatedList<T> to implement some edge cases. When the result of the full query is empty (page count is zero), we set the current page number to zero:

int count = await source.CountAsync();
if (count == 0)
{
   // No results -> return page 0.
   return new PaginatedList<T>(new List<T>(), 0, 0, pageSize);
}

This is how the pager then looks like:

When the requested page is out of range (has no records) then PaginatedList<T> returns the last page:

List<T> items = await source.Skip((pageIndex - 1) * pageSize).Take(pageSize).ToListAsync();
if (items.Count == 0)
{
    // Requested page is out of range -> return last page.
    pageIndex = (int)Math.Ceiling(count / (double)pageSize);
    items = await source.Skip((pageIndex - 1) * pageSize).Take(pageSize).ToListAsync();
}

return new PaginatedList<T>(items, count, pageIndex, pageSize);

Here’s how the pager looks like when we try to navigate to page 1000:

Last but not least, we allow the user to change the page size. We first added the property and a list of possible values to the ViewModel:

public List<int> PageSizes => new() { 5, 10, 20, 50, 100 };

public int PageSize
{
    get => _pageSize;
    set
    {
        SetProperty(ref _pageSize, value);
        Refresh();
    }
}

Then we added a ComboBox and a TextBlock to the AppBar, via AppBarElementContainer instances:

<AppBarSeparator />
<AppBarElementContainer VerticalContentAlignment="Center">
    <ComboBox ItemsSource="{x:Bind ViewModel.PageSizes}"
                SelectedItem="{x:Bind ViewModel.PageSize, Mode=TwoWay}" />
</AppBarElementContainer>
<AppBarElementContainer VerticalContentAlignment="Center">
    <TextBlock Text="rows per page"
                Margin="8 0" />
</AppBarElementContainer>

Here’s how that part of the UI looks like:

Finally we implemented the Refresh() method – triggered by a change of the PageSize property. We simply navigate to the first page. Before that we make sure that the command can execute by setting the page number to zero:

private void Refresh()
{
    _pageNumber = 0;
    FirstAsyncCommand.Execute(null);
}

With a handful lines of code and a little help from our friends Microsoft MVVM Toolkit and EF Core we just implemented a WinUI 3 pagination use case. Our sample app lives here on GitHub.

Enjoy!

Using the Windows Community Toolkit DataGrid with WinUI 3 and Entity Framework Core

In this article we demonstrate the Windows Community Toolkit DataGrid in a desktop application powered by the Windows App SDK and a Sqlite relational database. We’ll cover

• populating the DataGrid,
• sorting rows via a click on a column header,
• filtering rows on predefined criteria,
• grouping rows,
• searching for rows,
• instant theme switching,
• …

Here’s how our sample app looks like on Windows 10:

 

Recently we started migrating some UWP apps to WinUI 3. Some of these apps have 3rd party DataGrid controls, and we wanted to know whether Community Toolkit DataGrid is a decent candidate to replace these – after all: it’s free. We had no idea how this DataGrid control would behave in a WinUI 3 desktop app, since there are no official samples yet: 

• the DataGrid sample page in Community Toolkit Sample app is UWP (and hence WinUI 2.*), while
• the DataGrid sample page in WinUI 3 Controls Gallery only has an … animated gif – and that’s not really reassuring at all:

On top of that the Community Toolkit DataGrid control is still in its first version which was a port from Silverlight to UWP. When you look at its source you’ll notice that a lot of the code is already 3 years old. Would it run on the brand new Windows App SDK?

For all these reasons we were a bit reluctant to immediately start using this DataGrid in a production WinUI 3 desktop application. So we decided to test drive it first in a more representative setting. This test drive became the sample app that we’re describing in this article.

Migrating the Community Toolkit Sample app

We started our adventure by migrating the UWP DataGrid sample page from the Community Toolkit Sample app to WinUI 3. It has all the functionality we need (filtering, grouping, sorting, theming) and more (editing), and it’s Open Sourced. Here’s how the original looks like:

The migration was easier than expected and basically boiled down to updating the “windows.ui.” namespace references to “microsoft.ui.” all over the place. We then applied some cosmetic changes, like adding transparency to the column header background and adding elegance to the CommandBar on top. We also couldn’t resist modernizing the C# syntax here and there.

The Home page of our sample app is the result of the migration from an UWP/WinRT XAML page to WinUI 3/.NET 5:

All features of the original Toolkit demo were successfully ported to our own sample app. You can for example apply a filter to the displayed records:

You can group records:

You can sort the records by clicking on a column header:

The icon in the top right corner op the page allows you to immediately switch between light and dark theme. As long as you stick to ‘lightweight styling’ (i.e. just overriding theme color resources) the following one-liner will do the trick:

Root.RequestedTheme = Root.RequestedTheme == ElementTheme.Light 
	? ElementTheme.Dark 
	: ElementTheme.Light;

From the moment you start to programmatically modify resources, or retemplate (parts of) a control, this instant theme-switching becomes problematic. Not only the control’s XAML but also the defined animations refer to expected colors, opacities, and more – and it’s super hard to override all of these. But let’s focus on DataGrid’s core features.

It takes some development and design effort to implement sorting, filtering, and especially grouping with the Community Toolkit DataGrid. In third party control toolkits such as the ones from DevExpress, Syncfusion, or Telerik [no ranking, just alphabetic order] such features can be configured declaratively and they come with a built-in UI. Nevertheless we were happy with the result of this first page, and decided to build a more modern/representative version of it by bringing some new components to the equation, like

• Microsoft MVVM Toolkit to replace the custom change propagation code in Models and ViewModels,
• a Sqlite relational database to replace the CSV file, and
• Entity Framework Core as an Object-Relational Mapper to run LINQ queries against the data.

Here’s an overview of the NuGet packages – ignore the version numbers, they were all upped multiple times since we made the screenshot:

We skipped editing and validation in our sample app, but still all Models and ViewModels were renamed and became children of MVVM Toolkit’s ObservableObject class:

public class Mountain : ObservableObject
{
    private uint _rank;
    private string _name;
    // more fields ...

    // Key

    [Key]
    public int Id { get; set; }

    // Fields

    public uint Rank
    {
        get => _rank;
        set => SetProperty(ref _rank, value);
    }

    // more properties ...

}

For more details on Microsoft MVVM Toolkit, check this introduction. In the rest of this article we’ll focus on Entity Framework (EF) Core, since that is most probably new to UWP developers who are migrating to Windows App SDK.

Configuring Entity Framework Core

For the enterprise sample we replaced the .csv file with a relational Sqlite database. An Entity Framework DbContext was defined to host a table with Mountain entities – a DbSet<Mountain>. Everything is persisted in the app’s local folder:

public class MountainDbContext : DbContext
{
    public DbSet<Mountain> Mountains { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        string path = Path.Combine(
	ApplicationData.Current.LocalFolder.Path, 
	"mountains.db");

        string connectionStringBuilder = new
            SqliteConnectionStringBuilder()
        {
            DataSource = path
        }
            .ToString();

        SqliteConnection connection = new SqliteConnection(connectionStringBuilder);
        optionsBuilder.UseSqlite(connection);
    }
}

Before accessing it, the ViewModel ensures that the database is created:

dbContext.Database.EnsureCreated();

This checks whether the database exists -it may of may not have been deployed with your app- and if not it creates an empty one. Our sample app then reads the original .CSV file and populates the Mountains table with it. Now we can write LINQ queries against the data, such as this one to get all of the Mountains:

public async Task<IEnumerable<Mountain>> AllMountainsAsync()
{
    using (MountainDbContext dbContext = new())
    {
        return await dbContext.Mountains
	.OrderBy(m => m.Rank)
	.AsNoTracking()
	.ToListAsync();
    }
}

Observe that EF Core comes with an asynchronous version of ToList(). When you’re not modifying the content, then it’s a good idea to disable EF change tracking, that’s what the AsNoTracking() does.

Making a read-only DataGrid

The DataGrid definition is similar to the one in the Home page, except that we made the grid read-only since we’re not huge fans of editable DataGrids:

<ctWinUI:DataGrid x:Name="DataGrid"
                    AutoGenerateColumns="False"
                    CanUserSortColumns="True"
                    Sorting="DataGrid_Sorting"
                    LoadingRowGroup="DataGrid_LoadingRowGroup"
                    SelectionMode="Single"
                    IsReadOnly="True">
    <ctWinUI:DataGrid.Columns>
        <ctWinUI:DataGridTextColumn Header="Rank"
                                    Binding="{Binding Rank}"
                                    Tag="Rank" />
        <ctWinUI:DataGridComboBoxColumn Header="Mountain"
                                        Binding="{Binding Name}"
                                        Tag="Name" />
        <!-- More columns ... -->
    </ctWinUI:DataGrid.Columns>
</ctWinUI:DataGrid>

It does not make sense to allow selecting individual cells, so we implemented “row-selection mode” by turning the focus brushes for individually selected cells transparent:

<SolidColorBrush x:Key="DataGridCellFocusVisualPrimaryBrush">Transparent</SolidColorBrush>
<SolidColorBrush x:Key="DataGridCellFocusVisualSecondaryBrush">Transparent</SolidColorBrush>

Be aware that Community Toolkit DataGrid does not support the {x:Bind} syntax for column property bindings, even when you provide bindings for DataContext and ItemsSource:

Drawing a Template Column

The apps that we’re migrating use templated columns, so we looked for an excuse to define a DataGridTemplateColumn in this sample app. We decided to display the height of the Mountain as a Slider. Here’s the template, observe that the use of {x:Bind} is supported, at least when you declare the DataType :

<ctWinUI:DataGridTemplateColumn Header="Height"
                                Tag="Height">
    <ctWinUI:DataGridTemplateColumn.CellTemplate>
        <DataTemplate x:DataType="models:Mountain">
            <Grid Background="Transparent"
                    ToolTipService.ToolTip="{x:Bind HeightDescription}">
                <Slider Minimum="7200"
                        Maximum="8848"
                        Value="{x:Bind Height}"
                        IsHitTestVisible="False"
                        IsTabStop="False" />
            </Grid>
        </DataTemplate>
    </ctWinUI:DataGridTemplateColumn.CellTemplate>
</ctWinUI:DataGridTemplateColumn>

Here’s how the page now looks like:

We kept IsEnabled to true to allow the Slider to keep its accent color instead of being grayed out, and set both IsHitTestVisible and IsTabStop to false to prevent user interaction.

Applying a Filter

Here are the LINQ queries that correspond to the filter options:

case FilterOptions.Rank_High:
    return await dbContext.Mountains
	.Where(m => m.Rank > 50)
	.OrderBy(m => m.Rank)
	.AsNoTracking()
	.ToListAsync();

case FilterOptions.Height_High:
    return await dbContext.Mountains
	.Where(m => m.Height > 8000)
	.OrderBy(m => m.Rank)
	.AsNoTracking()
	.ToListAsync();

As already mentioned, third party libraries have built-in UI to allow your end user to define and apply his own filters. Check this article for an example. Here’s how a filtered dataset looks like in our sample app – with less rows, and an extra indicator on the command button to notify the user that a filter is applied:

Sorting by clicking a column header

For the column sort feature, we wanted to avoid a huge switch statement with a different LINQ expression for each column – as in the original sample. We went for a solution that takes the name of the column and the sort direction as parameter:

public async Task<IEnumerable<Mountain>> SortedMountainsAsync(
	string sortBy, 
	bool ascending)
{
    using (MountainDbContext dbContext = new())
    {
        return await dbContext.Mountains
	.OrderBy(sortBy, !ascending)
	.AsNoTracking()
	.ToListAsync();
    }
}

The OrderBy() in the previous code is an -admittedly cryptic- extension method that builds the appropriate LINQ expression:

public static IOrderedQueryable<TEntity> OrderBy<TEntity>(
    this IQueryable<TEntity> source,
    string orderByProperty,
    bool desc)
{
    string command = desc ? "OrderByDescending" : "OrderBy";
    Type type = typeof(TEntity);
    PropertyInfo property = type.GetProperty(orderByProperty);
    ParameterExpression parameter = Expression.Parameter(
            type,
            "p");
    MemberExpression propertyAccess = Expression.MakeMemberAccess(
            parameter,
            property);
    LambdaExpression orderByExpression = Expression.Lambda(
            propertyAccess,
            parameter);
    MethodCallExpression resultExpression = Expression.Call(
            typeof(Queryable),
            command,
            new Type[] { type, property.PropertyType },
            source.Expression, Expression.Quote(orderByExpression));
    return (IOrderedQueryable<TEntity>)source
            .Provider
            .CreateQuery<TEntity>(resultExpression);
}

When working with EF or EF Core, it’s always good to have IQueryable extensions like this hanging around.

Implementing the Mode

Clicking on a column header (or on one of the command bar buttons) changes the ItemsSource of the DataGrid but also changes its UI (arrow indicators in the column header, and command bar decorators above the grid). You have to make sure that all ‘old’ arrow indicators are removed when you apply a filter -something that was overlooked in the official Toolkit Sample App.

We centralized the UI logic behind a “mode switch” in a PropertyChangedCallback for ItemsSourceProperty:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    _token = DataGrid.RegisterPropertyChangedCallback(
	ctWinUI.DataGrid.ItemsSourceProperty,
	DataGridItemsSourceChangedCallback);
    base.OnNavigatedTo(e);
}

protected override void OnNavigatedFrom(NavigationEventArgs e)
{
    DataGrid.UnregisterPropertyChangedCallback(
	ctWinUI.DataGrid.ItemsSourceProperty, 
	_token);
    base.OnNavigatedFrom(e);
}

private void DataGridItemsSourceChangedCallback(DependencyObject sender, DependencyProperty dp)
{
    // Remove Sort Indicators.
    if (dp == ctWinUI.DataGrid.ItemsSourceProperty)
    {
        foreach (var column in (sender as ctWinUI.DataGrid).Columns)
        {
            column.SortDirection = null;
        }
    }

    // Other display mode dependent UI logic
    // ...
}

Here’s how we implemented the button decorators in the command bar to indicate the active mode – as an Icon in an AppBarElementContainer that has a negative margin:

<CommandBar DefaultLabelPosition="Right"
            Background="Transparent"
            VerticalAlignment="Center">
    <AppBarButton Icon="Filter"
                    Label="Filter"
                    Width="80">
        <AppBarButton.Flyout>
            <MenuFlyout>
                <!-- Menu items -->
            </MenuFlyout>
        </AppBarButton.Flyout>
    </AppBarButton>
    <AppBarElementContainer x:Name="FilterIndicator"
                            Visibility="Collapsed"
                            Margin="-16 0 0 0">
        <FontIcon Glyph=""
                    FontSize="12"
                    Foreground="Coral"
                    VerticalAlignment="Top" />
    </AppBarElementContainer>

    <!-- More buttons and indicators -->

</CommandBar>

In the future InfoBadge might be a nice alternative but that control is not yet pushed to WinUI 3.

Searching for records

Here’s our initial LINQ query behind the search feature:

return await dbContext.Mountains
            .Where(m => m.Name.Contains(queryText))
            .OrderBy(m => m.Rank)
            .AsNoTracking()
            .ToListAsync();

At first sight no surprises here, except that … it’s case sensitive:

The LINQ Provider for Sqlite (in contrast to the one for SQL Server) translates Contains() to a case sensitive comparison. The following modification to the query only makes things worse:

return await dbContext.Mountains
            .Where(m => m.Name.Contains(queryText, StringComparison.InvariantCulture)) // Crashes at runtime
            .OrderBy(m => m.Rank)
            .AsNoTracking()
            .ToListAsync();

It will crash at runtime since the LINQ Provider does not know how to translate this C# to its SQL syntax. Again you’ll find enough extension methods to solve this … but in this case EF Core itself has one: EF.Functions.Like(). Here’s how it’s used to generate a SQL LIKE:

return await dbContext.Mountains
            .Where(m => EF.Functions.Like(m.Name, $"%{queryText}%"))
            .OrderBy(m => m.Rank)
            .AsNoTracking()
            .ToListAsync();

Here’s how the result of the non-case-sensitive search looks like in the sample app:

Grouping rows

This is the first version of our LINQ query for the grouping feature:

IEnumerable<GroupInfoCollection<string, Mountain>> query = dbContext.Mountains
                .OrderBy(m => m.Range)
                .ThenBy(m => m.Rank)
                .AsNoTracking()
                .GroupBy(m => m.Range, (key, list) => new GroupInfoCollection<string, Mountain>(key, list));

Bad luck: the LINQ Provider for Sqlite does not know how to translate this C# into SQL syntax, and crashes at runtime:

We opted to bail out of the Sqlite Provider with a ToList() in the middle of the expression. The GroupBy() is then not applied to the query (an IQueryable) but to the result of the query (an IEnumerable). The responsibility was passed to the native .NET 5 LINQ provider, who knows how to handle this:

IEnumerable<GroupInfoCollection<string, Mountain>> query = dbContext.Mountains
                .OrderBy(m => m.Range)
                .ThenBy(m => m.Rank)
                .AsNoTracking()
                .ToList()
                .GroupBy(m => m.Range, (key, list) => new GroupInfoCollection<string, Mountain>(key, list));

Here’s how grouping looks like in our sample app:

Showing Row Details

The command bar has a button to reveal (or hide) the details of the selected row:

We prefer this pattern over the ‘every-click-opens-details-row’ that’s built into the DataGrid. Firstly because you cannot unselect a row – clicking on the selected row does not unselect it. The only way to close the details row is selecting another row – which then opens a new details row. Secondly we believe that in most cases it’s better to display the details not inside the DataGrid but in a separate place (navigate to another page, open a dialog, …).

Stability

Running V1 of a ported Silverlight control in an application ecosystem that’s only in v0.8: what could possibly go wrong?  

When browsing the open DataGrid related issues on GitHub, you encounter some stability issues. When we started building the sample app, we ran into some of these. When rapidly scrolling, switching mode, and clicking column headers, the DataGrid control gave up rather quickly. For the sake of completeness: with the same behavior we also managed to crash all of the 3rd party sample apps.

We were relieved to observe that most if not all of the performance and stability issues were solved with the release of Windows App SDK 0.8.2! From that release on the DataGrid is behaving as expected.

Conclusion

As far as we are concerned, Community Toolkit DataGrid on WinUI 3 has passed the tests, and is ready for prime time. Some of the features -like filtering and grouping- require more design and development effort than you would have with third party components. This is a challenge, but it’s also an opportunity for you to come up with a friendly non-technical user experience for these scenarios. Here are a couple of examples (NOT included in the sample app) of custom filtering and grouping that would even be hard with third party grids.

• Removing the Lagers from a list of beer styles. This is a filter on a substring in a hidden column:

• Grouping a list of hops by origin. This is a grouping on an n-to-n relation:

It’s great for the end user to see the most relevant filtering and groupings of the data and just select one from a menu.

Our sample app lives here on GitHub.

Enjoy!

Navigating in a WinUI 3 Desktop application

In this article we describe a minimal framework for a navigation service in a WinUI 3 Desktop application on top of a NavigationView control. We will cover

• navigating from a menu item to an application page,
• navigating to a menu item from code behind,
• retrieving the current menu item,
• hiding and showing menu items, and
• dynamically adding menu items.

Our purpose is to describe the interaction between some of the core classes and come up with a pattern that you can reuse in your own WinUI 3 apps. For that reason we deliberately stay away from MVVM and Dependency Injection libraries. We created a small sample app, here’s how it looks like:

The app is a WinUI 3 Desktop app built on top of the new Windows App SDK v0.8 (previously known as Project Reunion) with the regular Visual Studio 2019 (no preview stuff needed). From their own documentation, we learn that 

the Windows App SDK is a set of new developer components and tools that represent the next evolution in the Windows app development platform. The Windows App SDK provides a unified set of APIs and tools that can be used in a consistent way by any desktop app on Windows 11 and downlevel to Windows 10, version 1809,

and

Windows UI Library (WinUI) 3 is a native user experience (UX) framework for building modern Windows apps. It ships independently from the Windows operating system as a part of Project Reunion (now called the Windows App SDK). The 0.8 Preview release provides Visual Studio project templates to help you start building apps with a WinUI 3-based user interface.

Check this link on how to prepare your development environment for this. When all prerequisites are met, you should be able to create new WinUI 3 projects:

UWP developers will feel at home in a WinUI 3 Desktop application: it looks like UWP and it feels like UWP, except that

• the solution currently (and temporarily) comes with a separate MSIX installation project, and
• the main page (our Shell) is not a Page but a Window – one that supports both UWP and Win32 app models.

The main beef of our Shell Page Window is the WinUI 3 version of the NavigationView control. In the first releases of UWP we developers needed to create a navigation UI from scratch. In a couple of years modern XAML navigation UI evolved from DIY SplitView-based implementations (been there, done that) to simply putting a full fledged NavigationView control on the main page. NavigationView comes with different modes (left menu/top menu), built-in adaptive behavior, two-level hierarchical menu structure, footer menu items, back button support, animations, different icon types, … Apart from the menu, the control also comes with a Header, and a Frame to host the application pages.

Here’s the main structure of the Shell page in our sample app:

<NavigationView x:Name="NavigationView"
                Loaded="NavigationView_Loaded"
                SelectionChanged="NavigationView_SelectionChanged" 
                Header="WinUI 3 Navigation Sample"
                IsBackButtonVisible="Collapsed"
                IsSettingsVisible="False">
    <NavigationView.MenuItems>
        <NavigationViewItem Content="Home"
                            Tag="XamlBrewer.WinUI3.Navigation.Sample.Views.HomePage"
                            ToolTipService.ToolTip="Home">
            <NavigationViewItem.Icon>
                <BitmapIcon UriSource="/Assets/Home.png"
                            ShowAsMonochrome="False" />
            </NavigationViewItem.Icon>
        </NavigationViewItem>
        <!-- More items -->
    </NavigationView.MenuItems>
    <NavigationView.FooterMenuItems>
        <NavigationViewItem Content="About"
                            Tag="XamlBrewer.WinUI3.Navigation.Sample.Views.AboutPage">
            <NavigationViewItem.Icon>
                <BitmapIcon UriSource="/Assets/About.png"
                            ShowAsMonochrome="False" />
            </NavigationViewItem.Icon>
        </NavigationViewItem>
    </NavigationView.FooterMenuItems>
    <Frame x:Name="ContentFrame" />
</NavigationView>

The Festivals item demonstrates hierarchical navigation using nested menu items:

<NavigationViewItem Content="Festivals"
                    Tag="XamlBrewer.WinUI3.Navigation.Sample.Views.FestivalPage"
                    ToolTipService.ToolTip="Festivals">
    <NavigationViewItem.MenuItems>
        <NavigationViewItem Content="Tomorrowland"
                            Tag="XamlBrewer.WinUI3.Navigation.Sample.Views.FestivalDetailsPage"
                            ToolTipService.ToolTip="Tomorrowland" />
        <NavigationViewItem Content="Rock Werchter"
                            Tag="XamlBrewer.WinUI3.Navigation.Sample.Views.FestivalDetailsPage"
                            ToolTipService.ToolTip="Rock Werchter" />
    </NavigationViewItem.MenuItems>
</NavigationViewItem>

There’s much more on NavigationView than we cover in this article. For more details check these guidelines and play around with the WinUI 3 Controls Gallery app:

Basic Navigation

Our navigation pattern assumes/enforces that all navigation in the app is initiated by the NavigationView instance in the Shell window. We believe that this is applicable to a huge number of apps – at least to the ones that we are currently migrating from UWP. All navigation requests must refer to a NavigationViewItem instance that corresponds with an entry in the menu. The menu items define the target page in their Tag and Content fields, as you saw in the XAML snippets above. It’s the SelectionChanged event that triggers the navigation:

private void NavigationView_SelectionChanged(
	NavigationView sender, 
	NavigationViewSelectionChangedEventArgs args)
{
    SetCurrentNavigationViewItem(args.SelectedItemContainer as NavigationViewItem);
}

This first call into our micro-framework looked up the selected menu item and updated the content frame. Here’s how the code is structured:

1. All navigation-related code is implemented in a partial class of the Shell window,
2. encapsulated in an interface that is
3. exposed via the App instance to
4. the different XAML pages.

When a menu item is selected, we look up the target page information from that menu item, and pass it to Frame.Navigate(). We set the appropriate page header and update the menu’s SelectedItem. That last line is needed in case the navigation was triggered from code behind.

public void SetCurrentNavigationViewItem(
	NavigationViewItem item)
{
    if (item == null)
    {
        return;
    }

    if (item.Tag == null)
    {
        return;
    }

    ContentFrame.Navigate(
	Type.GetType(item.Tag.ToString()), 
	item.Content);
    NavigationView.Header = item.Content;
    NavigationView.SelectedItem = item;
}

Feel free add a test to prevent navigating to an invisible menu item and some exception handling, if you want.

To avoid showing an empty content frame, the app auto-navigates to the Home page when the app starts. The navigation logic is the same throughout all use cases in the app:

1. look up the menu item that corresponds to the target page, and
2. use it in the SetCurrentNavigationViewItem() call.

private void NavigationView_Loaded(
	object sender, 
	RoutedEventArgs e)
{
    // Navigates, but does not update the Menu.
    // ContentFrame.Navigate(typeof(HomePage));

    SetCurrentNavigationViewItem(GetNavigationViewItems(typeof(HomePage)).First());
}

Finding menu items

GetNavigationViewItems() retrieves a flattened list of all menu items of the NavigationView: the MenuItems, the FooterMenuItems, and their children. We added two overloads – one to filter on page type (e.g. to find all detail pages in a list) and another to filter on page type and title (to find a specific detail page):

public List<NavigationViewItem> GetNavigationViewItems()
{
    var result = new List<NavigationViewItem>();
    var items = NavigationView.MenuItems.Select(i => (NavigationViewItem)i).ToList();
    items.AddRange(NavigationView.FooterMenuItems.Select(i => (NavigationViewItem)i));
    result.AddRange(items);

    foreach (NavigationViewItem mainItem in items)
    {
        result.AddRange(mainItem.MenuItems.Select(i => (NavigationViewItem)i));
    }

    return result;
}

public List<NavigationViewItem> GetNavigationViewItems(
	Type type)
{
    return GetNavigationViewItems().Where(i => i.Tag.ToString() == type.FullName).ToList();
}

public List<NavigationViewItem> GetNavigationViewItems(
	Type type, 
	string title)
{
    return GetNavigationViewItems(type).Where(ni => ni.Content.ToString() == title).ToList();
}

Feel free to filter away NavigationViewItemHeader and NavigationViewItemSeparator instances from the flat list, if they’re in your way.

We also disclose the currently selected menu item:

public NavigationViewItem GetCurrentNavigationViewItem()
{
    return NavigationView.SelectedItem as NavigationViewItem;
}

Exposing the menu items

The previous methods were all implemented in the Shell Window. To make them available all over the app, we first defined them in an interface:

public interface INavigation
{
    NavigationViewItem GetCurrentNavigationViewItem();

    List<NavigationViewItem> GetNavigationViewItems();

    List<NavigationViewItem> GetNavigationViewItems(Type type);

    List<NavigationViewItem> GetNavigationViewItems(Type type, string title);

    void SetCurrentNavigationViewItem(NavigationViewItem item);
}

Then we exposed the implementation via the App instance – it knows the Shell because it creates it on start-up:

private Shell shell;

public INavigation Navigation => shell;
        
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    shell = new Shell();
    shell.Activate();
}

All parts of the code base can now easily access the lightweight Navigation Service:

(Application.Current as App).Navigation

Using the Navigation Service

Showing and hiding existing menu items

Our sample app has a ‘Beer’ page that only becomes visible when the user confirms she’s old enough to handle its content. The page is defined in the NavigationView menu, but is initially invisible. The Home page has a checkbox in the lower right corner:

When the box is checked, the hidden menu item appears:

Here’s the code in the Homepage. It looks up the BeerPage NavigationViewItem, and manipulates its Visibility:

private static NavigationViewItem BeerItem => 
	(Application.Current as App)
		.Navigation
		.GetNavigationViewItems(typeof(BeerPage))
		.First();

private void CheckBox_Checked(object sender, RoutedEventArgs e)
{
    BeerItem.Visibility = Visibility.Visible;
}

private void CheckBox_Unchecked(object sender, RoutedEventArgs e)
{
    BeerItem.Visibility = Visibility.Collapsed;
}

Programmatically navigating to an existing menu item

The FormulaOnePage in our sample app has a hyperlink to the FestivalPage:

The code behind that hyperlink looks up the target menu item using the GetNavigationViewItems overload with the page type, and then navigates to it – very straightforward:

private void Hyperlink_Click(
	Hyperlink sender, 
	HyperlinkClickEventArgs args)
{
    var navigation = (Application.Current as App).Navigation;
    var festivalItem = navigation.GetNavigationViewItems(typeof(FestivalPage)).First();
    navigation.SetCurrentNavigationViewItem(festivalItem);
}

There’s a similar hyperlink in the HomePage, to test whether we can reach footer menu items in the same way:

Under the Festival menu item, there is a list of FestivalDetails pages – all of the same type, but with a different topic of course. The hyperlinks on that Festival page use the GetNavigationViewItems overload with page type and content, and also ensure that the parent (Festival) menu item gets expanded:

private void Hyperlink_Click(
	Hyperlink sender, 
	HyperlinkClickEventArgs args)
{
    var navigation = (Application.Current as App).Navigation;
    navigation.GetCurrentNavigationViewItem().IsExpanded = true;
    var festivalItem = navigation.GetNavigationViewItems(
	typeof(FestivalDetailsPage), 
	"Rock Werchter").First();
    navigation.SetCurrentNavigationViewItem(festivalItem);
}

Here’s one of the detail pages:

Dynamically adding menu items

The BeerPage has a button to programmatically add BeerDetailPage items:

It looks up the parent, adds a menu item of the appropriate type and with its specific title, and makes sure that the parent is expanded:

private void Button_Click(
	object sender, 
	RoutedEventArgs e)
{
    var beerItem = (Application.Current as App)
	.Navigation
	.GetNavigationViewItems(this.GetType())
	.First();
    beerItem.MenuItems.Add(new NavigationViewItem
    {
        Content = $"Round {beerItem.MenuItems.Count + 1}",
        Tag = typeof(BeerDetailsPage).FullName
    });
    beerItem.IsExpanded = true;
}

Here’s such a detail page:

It has to buttons to iterate back and forth through its list of siblings. The ‘previous’ button navigates backwards through the list of all BeerDetailPage items in the menu. These may be spread over multiple parent items. The ‘next’ button shows how to limit the navigation to the parent of the detail page. This algorithm is a bit more cumbersome since child menu items don’t have a reference to their parent:

private void Button_Click(
	object sender, 
	RoutedEventArgs e)
{
    // Navigation through colleagues
    var navigation = (Application.Current as App).Navigation;
    var item = navigation.GetCurrentNavigationViewItem();
    var siblings = navigation.GetNavigationViewItems(this.GetType());
    var index = siblings.IndexOf(item);
    if (index > 0)
    {
        navigation.SetCurrentNavigationViewItem(siblings[index - 1]);
    }
}

private void Button_Click_1(
	object sender, 
	RoutedEventArgs e)
{
    // Navigation within parent
    var navigation = (Application.Current as App).Navigation;
    var item = navigation.GetCurrentNavigationViewItem();
    var mainItems = navigation.GetNavigationViewItems();
    foreach (var mainItem in mainItems)
    {
        // Find the parent
        if (mainItem.MenuItems.Contains(item))
        {
            var siblings = mainItem.MenuItems;
            var index = siblings.IndexOf(item);
            if (index < siblings.Count - 1)
            {
                navigation.SetCurrentNavigationViewItem((NavigationViewItem)siblings[index + 1]);
            }
        }
    }
}

It’s a wrap

There is definitely room for extra helper methods and a higher abstraction level, but in just a handful lines of C# we created the core of a service that covers most of the navigation requirements for an WinUI 3 app that uses a NavigationView control.

Our sample app lives here on GitHub.

Enjoy!

Data Validation with the Microsoft MVVM Toolkit

In this article we will walk through a handful of scenarios and techniques for input validation with the ObservableValidator class of Microsoft MVVM Toolkit. We will cover

• canonical property validation,
• comparing two (or more) properties,
• comparing the new value of a property to its previous one,
• delaying the validation, and
• preventing to assign an invalid value to a property.

We created a sample app in UWP, it looks like this:

Input Validation in UWP

The System.Component.DataAnnotations is almost as old as the .NET Framework itself. It contains attribute classes to decorate ViewModels and Models with metadata for validation purposes – among other. These attributes describe property validation rules. When the rules are broken, the instance exposes its validation errors via its INotifyDataError members. This validation technique is intensively used in several ASP.NET frameworks and also made its way to Silverlight and WPF. Until very recently, data validation in UWP did not get much attention from Microsoft. Most development teams embedded third-party solutions such as Prism, Template10, or Calcium into their UWP apps, or rolled their own custom solution.

With Microsoft MVVM toolkit there now is a Microsoft provided alternative, and it’s even ready for Reunion. Now that we’re talking about the future: WinUI 3 controls will come with templates that react upon the INotifyDataErrorInfo status of the (View)Model that they are bound to. There is currently a bug that inhibits a deeper dive into this. Nevertheless, the WinUI3 Controls Gallery app already contains a sample page. It’s currently broken, but it reveals a glimpse of the near future of input validation in WinUI:

That’s not a spectacular screenshot, so for reference here’s an example of similar control templates in WPF:

While the UI parts of UWP Data Validation are not yet ready for prime time, the supporting Microsoft MVVM Toolkit is fully operational. Welcome to ObservableValidator.

ObservableValidator

The great official documentation teaches us that

‘The ObservableValidator is a base class implementing the INotifyDataErrorInfo interface, providing support for validating properties exposed to other application modules. It also inherits from ObservableObject, so it implements INotifyPropertyChanged and INotifyPropertyChanging as well. It can be used as a starting point for all kinds of objects that need to support both property change notifications and property validation.’.

Microsoft MVVM Toolkit is fully developed in the open, the source code for ObservableValidator is right here. Models and ViewModels that require validation just need to inherit from it, like this:

public class Suspect : ObservableValidator
{
    private string _name;
    private string _socialSecurityNumber;

    // ... there's more
}

The instance will expose its error status through its INotifyDataErrorInfo members. The Views in our sample app have bindings to ErrorsChanged and HasErrors. Check our previous blog post to see how this was done. Were’ reusing its ‘error popup’ approach. Here’s its XAML definition:

<SymbolIcon Symbol="ReportHacked"
            Foreground="Red"
            Visibility="{x:Bind ViewModel.Suspect.HasErrors, Mode=OneWay}">
    <ToolTipService.ToolTip>
        <TextBlock Text="{x:Bind ViewModel.Suspect.Errors, Mode=OneWay}"
                    Foreground="Red" />
    </ToolTipService.ToolTip>
</SymbolIcon>

Using existing Validation Attributes

The System.Component.DataAnnotations namespace hosts a huge list of attributes available for the validation of individual properties: required, minimum and maximum length, range, Enum, Regex … These cover most of the usual suspects. There are not too much XAML examples on the market, so when you search for sample code, you’ll probably end up in ASP.NET MVC projects. Don’t worry about that: MVC Models are very similar to MVVM ViewModels.

To implement validation in a class, it suffices to decorate its properties with one or more of these validation attributes and call one of its SetProperty() overloads with true as the third parameter in the property setter. Here’s how our sample app evaluates whether Keyser Söze has a required Name of minimum length and has his SocialSecurityNumber checked against a regular expression:

[Required(
	ErrorMessage = "Name is Required")]
[MinLength(
	2, 
	ErrorMessage = "Name should be longer than one character")]
public string Name
{
    get => _name;
    set => SetProperty(ref _name, value, true);
}

[RegularExpression(
	@"^(?!000)(?!666)(?!9)\d{3}([- ]?)(?!00)\d{2}\1(?!0000)\d{4}$", 
	ErrorMessage = "Invalid Social Security Number.")]
public string SocialSecurityNumber
{
    get => _socialSecurityNumber;
    set => SetProperty(ref _socialSecurityNumber, value, true);
}

The validation is triggered whenever the property gets a new value. All we need in the View is a two-way binding to the property:

<TextBox Text="{x:Bind ViewModel.Suspect.Name, Mode=TwoWay}"
            PlaceholderText="Name" />
<TextBox Text="{x:Bind ViewModel.Suspect.SocialSecurityNumber, Mode=TwoWay}"
            PlaceholderText="Social Security Number" />

Here’s how our sample app reacts to an evil social security number:

The regular expression correctly refuses a number that starts with 666.

Rolling your own Validation Attributes

It’s easy to roll your own reusable validation attribute: inherit from ValidationAttribute and provide your own implementation of the IsValid() method. The method gets the ValidationContext injected as a parameter, exposing the whole instance that is being validated, not only the decorated property. This allows you to write validation rules over more than one property, like:

• property a should be less than property b, or
• if property a has a value, then property b becomes required.

Allow us to mention that there already *is* a validation attribute that compares two properties -the CompareAttribute– but it only checks for equality. It’s used in the confirmation fields for email addresses and passwords (and probably nowhere else)

Our sample app contains a validation rule to compare two dates. It is used in the common ‘if the EndDate is filled out it then should come after StartDate’ scenario.

Let’s first show how the GreaterThan attribute is applied in the ViewModel class:

[GreaterThan (
	nameof(StartDate), 
	"End date should come after start date.")]
public DateTime? EndDate
{
    get => _endDate;
    set { 
        SetProperty(ref _endDate, value, true);
    }
}

Here’s the implementation of the validation attribute itself. It can be reused across applications:

public sealed class GreaterThanAttribute : ValidationAttribute
{
    private string _errorMessage;

    public GreaterThanAttribute(string propertyName, string errorMessage)
    {
        PropertyName = propertyName;
        _errorMessage = errorMessage;
    }

    public string PropertyName { get; }

    protected override ValidationResult IsValid(object value, ValidationContext validationContext)
    {
        if (value == null)
        {
            return ValidationResult.Success;
        }

        var instance = validationContext.ObjectInstance;
        var otherValue = instance.GetType().GetProperty(PropertyName).GetValue(instance);

        if (((IComparable)value).CompareTo(otherValue) > 0)
        {
            return ValidationResult.Success;
        }

        return new ValidationResult(_errorMessage);
    }
}

Since we’ve created a dependency between the values of Start- and EndDate in the ViewModel, we need to make sure that the validation is triggered by both properties’ changes. That’s why we make a call to ValidateProperty() in the setter of StartDate:

public DateTime? StartDate
{
    get => _startDate;
    set { SetProperty(ref _startDate, value, true);
        ValidateProperty(EndDate, nameof(EndDate));
    }
}

In the View, we bound both properties to a Date in a CalendarDatePicker:

<CalendarDatePicker Date="{x:Bind ViewModel.NoDelorean.GetStartDate(), BindBack=ViewModel.NoDelorean.SetStartDate, Mode=TwoWay}"
                    PlaceholderText="Start Date" />
<CalendarDatePicker Date="{x:Bind ViewModel.NoDelorean.GetEndDate(), BindBack=ViewModel.NoDelorean.SetEndDate, Mode=TwoWay}"
                    PlaceholderText="End Date" />

[We used {x:Bind} with function bindings to plug in a transformation between the DateTime of the properties and the DateTimeOffset values of the controls.]

Here’s how an invalid instance looks like in the sample app:

Also, please note that this rule does not apply to all ViewModels. Sometimes it should be possible to go back in time:

Using a CustomValidation method

Not every validation rule should be cast in a universally reusable validation attribute class. For a local rule, you can get away with writing a static validation method and applying it to a property via a CustomValidation attribute. Our sample app uses this technique to compare a new value of a property to its old value. The ViewModel represents a CountDown class – the validation rule ensures that we don’t ‘count up’.

The values to compare must have their own fields:

private int _value = 10;
private int _previousValue;

We created a static method that takes the property’s type (int in our Counter case) and a ValidationContext, and returns the result of the validation as a ValidationResult:

public static ValidationResult ValidateValue(
	int value, 
	ValidationContext context)
{
    var instance = (Countdown)context.ObjectInstance;
    var isValid = value < instance._previousValue;

    if (isValid)
    {
        return ValidationResult.Success;
    }

    return new ValidationResult("We're not supposed to count up.");
}

Again the validation context gives us access to the instance being validated, so it allows us to compare the new counter value to the old. Here’s how the rule is applied to the Value property:

[CustomValidation(typeof(Countdown), nameof(ValidateValue))]
public int Value
{
    get => _value;
    set
    {
        _previousValue = _value;
        SetProperty(ref _value, value, true);
    }
}

And this is how violating the counter rule looks like in the sample app:

Delaying Validation

Up until now, we always triggered the validation on the assignment of the property. This is not needed or wanted in every scenario or for every property. The third parameter in the SetProperty() call was always set to true in the previous examples. In our next sample, the validation will be triggered by a button click, so we start with a false in the property setter:

[Required(
	ErrorMessage = "Name is Required")]
[MinLength(
	2, 
	ErrorMessage = "Name should be longer than one character")]
public string Name
{
    get => _name;
    set => SetProperty(ref _name, value, false);
}

[RegularExpression(
	@"^(?!000)(?!666)(?!9)\d{3}([- ]?)(?!00)\d{2}\1(?!0000)\d{4}$", 
	ErrorMessage = "Invalid Social Security Number.")]
public string SocialSecurityNumber
{
    get => _socialSecurityNumber;
    set => SetProperty(ref _socialSecurityNumber, value, false);
}

For the sake of simplicity we validate all properties together – there’s a call for this: ValidateAllProperties(). The call is hooked to the button with an instance of MVVM Toolkit’s RelayCommand:

public ICommand ValidateCommand => 
	new RelayCommand(() => ValidateAllProperties());

Here’s the binding:

<Button Content="Validate"
        Command="{x:Bind ViewModel.SuspectWithDelayedValidation.ValidateCommand, Mode=OneWay}" />

And this is how the result looks like in the app:

There is a Try

In the previous examples we started the validation after the assignment of a property. We were continuously breaking an ancient object oriented programming principle:

it should not be possible to bring a properly encapsulated object into an invalid state via the public interface.

In some scenarios or parts of your app (e.g. in the Models) you should indeed prevent the assignment of invalid values to properties. Fortunately Microsoft MVVM Toolkit comes with TrySetProperty() … there *is* a Try.

TrySetProperty inspects the new value that you (try to) assign, and only succeeds when that value is a valid one. On the upside you’ll never have instances in an invalid state, on the downside you need to provide you own Errors store – instances will never have ‘official’ errors in their INotifyDataErrorInfo members.

In our sample app we decorated the ViewModel with alternative members – a list of ValidationResult instances to store the errors per property and a Boolean that returns whether that list has members:

public class NotYoda : ObservableValidator
{
    private List<ValidationResult> _errors = new List<ValidationResult>();

    public string Errors => string.Join(Environment.NewLine, from ValidationResult e in _errors select e.ErrorMessage);

    // Since HasErrors is not virtual:
    public bool ErrorsHaveI => Errors.Length > 0;

    // More, there is...
}

In the property setters we first clean up the previous messages for the property, then call the TrySetProperty, use its output parameter to update our custom error list, and then notify the custom error property changes:

[Required(
	ErrorMessage = "Name is Required")]
[MinLength(
	2, 
	ErrorMessage = "Name should be longer than one character")]
public string Name
{
    get => _name;
    set
    {
        _errors.RemoveAll(v => v.MemberNames.Contains(nameof(Name)));

        TrySetProperty(ref _name, value, out IReadOnlyCollection<ValidationResult> errors);

        _errors.AddRange(errors);
        OnPropertyChanged(nameof(Errors));
        OnPropertyChanged(nameof(ErrorsHaveI));
    }
}

[RegularExpression(
	@"^(?!000)(?!666)(?!9)\d{3}([- ]?)(?!00)\d{2}\1(?!0000)\d{4}$", 
	ErrorMessage = "Invalid Social Security Number.")]
public string SocialSecurityNumber
{
    get => _socialSecurityNumber;
    set
    {
        _errors.RemoveAll(v => v.MemberNames.Contains(nameof(SocialSecurityNumber)));

        TrySetProperty(ref _socialSecurityNumber, value, out IReadOnlyCollection<ValidationResult> errors);

        _errors.AddRange(errors);
        OnPropertyChanged(nameof(Errors));
        OnPropertyChanged(nameof(ErrorsHaveI));
    }
}

In the View, the bindings for the properties are not different from the other samples:

<TextBox Text="{x:Bind ViewModel.NotYoda.SocialSecurityNumber, Mode=TwoWay}"
            PlaceholderText="Social Security Number" />
<TextBlock Text="{x:Bind ViewModel.NotYoda.SocialSecurityNumber, Mode=TwoWay}" />

The error icon is of course bound to the custom error properties:

<SymbolIcon Symbol="ReportHacked"
            Foreground="Red"
            Visibility="{x:Bind ViewModel.NotYoda.ErrorsHaveI, Mode=OneWay}"
            HorizontalAlignment="Right">
    <ToolTipService.ToolTip>
        <TextBlock Text="{x:Bind ViewModel.NotYoda.Errors, Mode=OneWay}"
                    Foreground="Red" />
    </ToolTipService.ToolTip>
</SymbolIcon>

Our sample app displays the current (valid) value next to the input boxes:

The shape of things to come

If you compare the different ViewModels in our sample app, you’ll definitely observe the copy/paste patterns around most of the calls to SetProperty() and OnPropertyChanged(). In a future version, MVVM Toolkit will be enhanced with property attributes that will generate the source code for these – as illustrated in this tweet from the author:

We’ll keep you informed on this. In mean time, our sample app lives here on GitHub.

Enjoy!

Introducing the WinUI 2.6 Pager Controls

In this article we walk through a UWP app that demonstrates two new pagination controls that ship with the upcoming WinUI 2.6. The Windows UI 2.x Library is a project that’s factoring out the XAML UWP controls from the operating system into a NuGet package. New XAML controls and styles as well as backward compatible updates on existing native controls are rolled out via WinUI 2. This happens at a much higher pace than with the Windows 10 SDKs. WinUI 2 is allowing UWP developers to build and deploy apps that behave better on target platforms with different Windows 10 versions.

The next iteration of WinUI 2 will bring two new pagination controls: a traditional Pager control and a visual PipsPager control. The need for such a family of XAML pagination controls was raised in 2018, and today they are ready to use … well almost. WinUI v2.6. is currently in still prerelease. Make sure to check ‘include prerelease’ when looking for the NuGet package:

Pagination controls make the most sense when they’re connected to large DataGrids. For the sake of simplicity our sample app just uses a FlipView with some images.

Pager Control

From the specifications we learn that the last official pagination control in XAML was the DataPager in … Silverlight. It’s good to see that this gap will finally be closed with a new XAML Pager control. Here’s the new Pager control in its simplest form – with its default display mode, and NumberOfPages and SelectedPageIndex bound to its associated FlipView:

<FlipView x:Name="ImageRepeater"
          ItemsSource="{x:Bind Pictures}" />
<!-- Default Display Mode -->
<winui:PagerControl NumberOfPages="{x:Bind Pictures.Count}"
                    SelectedPageIndex="{x:Bind ImageRepeater.SelectedIndex, Mode=TwoWay}" />

Here’s how it looks like – no surprises here:

By changing the DisplayMode to NumberBox you can trade the DropDown page selector for an editable NumberBox, more convenient when there are a lot of pages:

The third DisplayMode is named ButtonPanel and displays page numbers as a hyperlink, and an ellipsis if there are too many. Here’s the XAML:

<winui:PagerControl NumberOfPages="{x:Bind Pictures.Count}"
                    SelectedPageIndex="{x:Bind ImageRepeater.SelectedIndex, Mode=TwoWay}"
                    FirstButtonVisibility="Hidden"
                    LastButtonVisibility="Hidden"
                    NextButtonVisibility="Hidden"
                    PreviousButtonVisibility="Hidden"
                    DisplayMode="ButtonPanel" />

Here’s how this looks like:

In this configuration the Pager always displays a page number hyperlink to the previous, next, first, and last pages. It would be nice to hide the obsolete default arrow buttons for this. The API supports this, but unfortunately there’s this bug that prevents hide these buttons. The fix is not yet released.

The synchronization between the pagination control and the host of the pages can be configured via binding to (or programmatically updating) properties -like we did on this page- or by implementing event handlers on the button clicks – what we will do in the PipsPager sample.

WinUI is developed in the open, you find the (technical) documentation and C++ source code for the Pager control right here. The new Pager looks and feels totally as expected.

FlipView companion

The specifications for a glyph-based pagination control were issued long before the first implementation of the PipsPager. The description reminded us of a similar control that we wrote (many) years ago in the Windows 8 age: the FlipViewIndicator, a companion pagination control for … the FlipView. The control -basically a templated ListBox- ended up in Tim Heuer’s Callisto framework. For old times sake we dug up the source code and pasted it in the sample app. Here’s how the result looks like:

We’re glad to see it still works nicely. Here’s how to use it in an app:

<FlipView x:Name="ImageRepeater"
            ItemsSource="{x:Bind Pictures}" />
<controls:FlipViewIndicator FlipView="{Binding ElementName=ImageRepeater}" /> />

For more details on its implementation, check this antique blog post.

PipsPager

Most web based image carousels use a pagination control made of dots, like this:

Pips are small but easily countable items, such as the dots on dominoes and dice, and that’s were PipsPager got its name from. It’s a row (or column) of dots -optionally extended with arrow buttons- that allows you to paginate. You find the full specs here.

Here’s its default look and feel in our sample app:

In an attempt to stretch the new control, we implemented a circular carousel: when the user reaches the end, the first item will reappear on the next navigation. To achieve this, we needed to override (or rather bypass) some of the PipsPager’s default behaviors. By default, the PipsPager

• disables its ‘Previous’ button when the pip that corresponds to the first page is displayed,
• does not react on clicking on the pip that corresponds to the displayed page, and
• disables its ‘Next’ button when the pip that corresponds to the last page is displayed.

Instead, we built a carousel that

• always keeps the pip for the selected page in the middle,
• uses all other pips to navigate (slower with the more central pips, faster with the peripheral ones), and
• implements circular (endless) navigation.

Here’s how it looks like:

PipsPager supports this scenario: it allows setting NumberOfPages to a negative number to indicate an undefined or unknown number of pages, and it can hide its ‘Previous’ and ‘Next’ buttons. For the interaction, we’re using SelectedIndexChanged:

Here’s the XAML for our carousel PipsPager:

<FlipView x:Name="ImageRepeater"
            ItemsSource="{x:Bind Pictures}"
            SelectionChanged="ImageRepeater_SelectionChanged" />
<winui:PipsPager x:Name="Pager"
                    NumberOfPages="-1"
                    NextButtonVisibility="Collapsed"
                    PreviousButtonVisibility="Collapsed"
                    SelectedIndexChanged="Pager_SelectedIndexChanged"
                    MaxVisiblePips="5" />

To make sure that the pip for the first page never appears (it would not respond to clicking hence block the circular navigation) we decided to make the control not rotate between pages 1 and n (the number of images) but instead to make it rotate between n and 2n. So the PipsPager always believes he’s somewhere in the middle of the page collection.

Here’s the initialization:

Pager.SelectedPageIndex = Pictures.Count;

And here are the event handlers that implement change selection in the pager but also in its host. FlipView has its built-in navigation support, so it can change the selected item by itself, in which case we need to update the pager:

private void ImageRepeater_SelectionChanged(
	object sender, 
	SelectionChangedEventArgs e)
{
    // Keeps the selection in the middle of the pager.
    Pager.SelectedPageIndex = ImageRepeater.SelectedIndex;
}

private void Pager_SelectedIndexChanged(
	WinUI.PipsPager sender, 
	WinUI.PipsPagerSelectedIndexChangedEventArgs args)
{
    // Good that this doesn't create an infinite loop.
    Pager.SelectedPageIndex = Pager.SelectedPageIndex % Pictures.Count + Pictures.Count;
    ImageRepeater.SelectedIndex = Pager.SelectedPageIndex % Pictures.Count;
}

Just like the regular Pager this new PipsPager looks and feels as expected. There’s still some room to fix bugs and improve these controls: the official release of WinUI 2.6 is scheduled for next month. We’re happy with these two new pagination controls. It’s great to see the UWP ecosystem extended with good-working and good-looking essential controls.

Our sample app lives here on GitHub.

Enjoy!

Introducing the WinUI InfoBar control

According to its roadmap WinUI 3.0 is currently focusing on Win32 desktop applications and .NET 5. In mean time WinUI 2.x keeps on evolving, bringing XAML features and controls for UWP. One of these new controls is the InfoBar control which was released as a component of WinUI 2.5.

In its original proposal we read that Microsoft was looking for a uniform way to display “long-lived app-wide status messages for scenarios such as updates available or errors that may occur which prevent the user from experiencing an app or its features working as intended“.

Here’s an example of such an ‘update available’ message in Office:

Here’s another example of the type of message that InfoBar is designed to display: the ‘we are recording this session’ message in Teams. This is clearly more than just a notification, hence the control needs to be explicitly closed by the user:

Unlike similar controls (notifications, teaching tip) the InfoBar is not a member of the Flyout family, so you should adapt your layout for it.

We made a little UWP sample app to play with this newcomer – and stretch it a little bit. Here’s how this app looks like, it demonstrates some typical usages of InfoBar:

The InfoBar API

Here’s an overview of InfoBar’s public interface:

The InfoBar controls displays a Message with a Title and an Icon (with background color and icon adapting to the Severity) and an optional ActionButton. You can take a look at its documentation here and its source code right here – it’s spread over a remarkably huge number of files.

Here’s an example of a XAML declaration in its simplest form – a warning without action button that displays a validation message of a text box:

<!-- Validation Panel -->
<winui:InfoBar Title="Not amused"
                Message="I think we need a recount ..."
                Severity="Warning"
                IsOpen="True" />

Here are some samples of typical declarations of an informational wide horizontal InfoBar at the top, with an action button (regular button or hyperlink):

<!-- Office 365 Status Bar -->
<winui:InfoBar Title="UPDATES ARE AVAILABLE"
                Message="Do you want to update this app right now? It will close and reopen."
                Severity="Informational"
                IsOpen="True">
    <winui:InfoBar.ActionButton>
        <Button Content="Update" />
    </winui:InfoBar.ActionButton>
</winui:InfoBar>

<!-- Visual Studio Status Bar -->
<winui:InfoBar Title="Performance report"
                Message="There's this weird extension slowing down the startup."
                Severity="Informational"
                IsOpen="True">
    <winui:InfoBar.ActionButton>
        <HyperlinkButton Content="Tell me more about this" />
    </winui:InfoBar.ActionButton>
</winui:InfoBar>

Here’s the Live Visual Tree for all these controls. Notice that all InfoBar instances live inside the XAML page. This means you need to preserve space for them:

We also created an InfoBar with a WinUI DropDownButton as its ActionButton and IsClosable to false to force the user to select an option in the dropdown if she wants to close the message. Here’s the XAML:

<!-- One that Edge and Outlook should have -->
<winui:InfoBar x:Name="PreferencesInfoBar"
                Title="Preferences updated"
                Message="We changed your user preferences, you like it?"
                Severity="Informational"
                IsOpen="True"
                IsClosable="False">
    <winui:InfoBar.ActionButton>
        <winui:DropDownButton>
            <TextBlock FontFamily="Segoe MDL2 Assets"
                        FontSize="14"
                        Text="" />
            <winui:DropDownButton.Flyout>
                <MenuFlyout Placement="BottomEdgeAlignedLeft">
                    <MenuFlyoutItem Icon="Emoji2"
                                    Text="Keep"
                                    Click="MenuFlyoutItem_Click" />
                    <MenuFlyoutItem Text="Revert"
                                    Click="MenuFlyoutItem_Click">
                        <MenuFlyoutItem.Icon>
                            <FontIcon Glyph="" />
                        </MenuFlyoutItem.Icon>
                    </MenuFlyoutItem>
                    <MenuFlyoutItem Icon="Emoji"
                                    Text="Revert and never touch my preferences again"
                                    Click="MenuFlyoutItem_Click" />
                </MenuFlyout>
            </winui:DropDownButton.Flyout>
        </winui:DropDownButton>
    </winui:InfoBar.ActionButton>
</winui:InfoBar>

All menu items in the sample are hooked to the same handler that closes the InfoBar by setting the IsOpen property:

private void MenuFlyoutItem_Click(object sender, RoutedEventArgs e)
{
    PreferencesInfoBar.IsOpen = false;
}

Here’s how it looks like in the sample app. Notice how the Live Visual Tree indicates that the menu flyout is hovering over the other controls – you don’t need to preserve space for these:

Here’s yet another typical example, but this time we created it programmatically. It’s an error message at the bottom of the page, much like the old WinForms StatusStrip:

var infoBar = new WinUI.InfoBar
{
    Title = "OOPS",
    Message = "Division by zero. Dude, I told you so ...",
    Severity = WinUI.InfoBarSeverity.Error,
    IsOpen = true,
    VerticalAlignment = VerticalAlignment.Bottom,
    Margin = new Thickness(0, 0, 0, 80)
};

RootGrid.Children.Add(infoBar);

The last of the ‘classical’ examples is an informational message at the right side of the page. We’re pretty close to a notification scenario here – except that the control still requires manual closing:

<!-- Toast (with ignored customizations) -->
<winui:InfoBar Title="WOOHOO"
                Message="Data has been saved properly."
                Severity="Success"
                IsOpen="True"
                CornerRadius="8"
                VerticalAlignment="Center"
                HorizontalAlignment="Right"
                Height="120">
    <winui:InfoBar.Content>
        <TextBlock Text="Keep up the good work ..."
                    Foreground="DimGray"
                    Padding="0 0 0 12" />
    </winui:InfoBar.Content>
</winui:InfoBar>

In the previous InfoBar instance, we tried to apply some customizations such as a specific Height and CornerRadius. The current control template just ignores these. That’s largely understandable, since the purpose of this new control is to bring a common look-and-feel for this type of scenario and steer away of custom solutions.

Customizing the InfoBar

On one hand it’s good to finally have a standard control for error and warning messages with a default look (size, color, icon) and a default behavior (requires explicit closing). We strongly believe that we should try to stick to this standard. On the other hand our customers very often require corporate UI and UX patterns that may deviate from the defaults.

Adapting the Template

It’s almost never a good idea to entirely re-template a control, especially since WinUI targets support across all Windows 10 versions. Hence its control templates may contain multiple IsApiContractPresent conditions so you’ll have to test your retemplated control for each and every version – and then you’re still not future-proof. On top of that you also have to consider accessibility when customizing controls.

There’s nothing wrong with lightweight styling (i.e. overriding some system brushes to sync the color scheme to your corporate style). WinUI controls facilitate this by making maximum use of XAML Theme Resources – you can check the ones that are used by the InfoBar right here. In the sample app we went a little bit further. We couldn’t resist to create a template for the InfoBar’s originally proposed look and feel:

we started with right-clicking on an instance in the Visual Studio designer, to create a copy of the current template:

You find the latest version of this template right here. It wouldn’t add value to post the source code of our template here, so we won’t. We’re happy with the outcome of this little exercise.

Adding Auto-Closing Behavior

The documentation is pretty clear on on where InfoBar should be used and where not. The control should e.g. NOT be used for just confirming an action, and in several GitHub issues –such as this one– it is stated that the control is NOT meant to be auto-closed. These are of course just recommendations, and we developers and our customers have been known to bypass recommendations sometimes, no?

In a lot of apps user interface consistency is –rightly- more important than following recommendations. Here’s an example of such consistency in Visual Studio. When you’re checking in code into a source control system (Azure DevOps, Git, whatever), the VS Team Explorer window displays an warning InfoBar as long as the action is busy, and an error InfoBar when something went wrong. After a successful check-in, the same UI is used for displaying the result:

Most of us will agree that this behavior makes sense, but this last message is far from  “long-lived app-wide status messages for scenarios such as updates available or errors that may occur which prevent the user from experiencing an app or its features working as intended“.

It’s good to reuse the InfoBar default look here, but we believe that this last message deserves a different behavior: it should auto-close after a few seconds. That’s just what we did in the sample app. We created an InfoBar subclass with an extra public AutoCloseInterval and some private methods to implement the behavior (feel free to add a fancy Community Toolkit fade animation yourself). Here’s the class diagram for the control:

 

Since the API of InfoBar is similar to the TeachingTip control, we were able to reuse the code for our own AutoClosingTeachingTip. The child class registers a notification function to listen for changes in the IsOpen property:

this.RegisterPropertyChangedCallback(IsOpenProperty, IsOpenChanged);

A timer is started:

private void Open()
{
    _timer = new DispatcherTimer();
    _timer.Tick += Timer_Tick;
    _timer.Interval = TimeSpan.FromMilliseconds(AutoCloseInterval);
    _timer.Start();
}

After the interval, the control is closed:

private void Timer_Tick(object sender, object e)
{
    this.IsOpen = false;
}

Allow us to repeat that with InfoBar it’s good to finally have a standard control for error and warning messages with a default look and a default behavior. We welcome this new member of the WinUI control family.

Our sample app lives here on GitHub.

Enjoy!

A lap around the Microsoft MVVM Toolkit

In this article we’ll walk through a UWP sample app to experiment with the features of the new Microsoft.Toolkit.Mvvm package that is part of the Microsoft Community Toolkit.

MVVM

MVVM is a software architectural pattern introduced by Microsoft in 2005 to support the development of XAML apps, originally in WPF and later on in Silverlight. MVVM stays relevant to the more recent XAML environments such as UWP, Xamarin (MAUI), the Uno platform, and WinUI.

In a nutshell MVVM allows you to separate UI logic from business logic by dividing your code into

• Models that represent data or information – think ‘domain objects’ or ‘entities’,
• Views that represent the structure and layout that the user interacts with – think ‘pages’ and ‘controls’, and
• ViewModels that express Model data and business logic through methods, properties and commands that are accessible to the Views,  preferably via declarative data-binding.

MVVM requires the strong data-binding capabilities that we see in XAML through its {Binding} and {x:Bind} markup extensions. The pattern was also implemented in other technology stacks such as AngularJS/Angular.io, Ext JS and Vue.js.

Microsoft started recommending MVVM for XAML 15 years ago and they still do. Oddly enough, they only provided ‘bindable controls’ and never came up with official helper classes (like base classes that implement INotifyPropertyChanged or ICommand) or an MVVM development framework (with event aggregation, messaging, or viewmodel location). The only exception is the Composite Application Library, which later grew into Prism. Regarding MVVM, Microsoft developers always had to rely on (Open Source) third parties, of which the most popular (in alphabetical order) are/were Caliburn, MVVM Light, and Prism.

We had great experiences with each of these frameworks. However -except for Prism- none of them are still actively maintained. We assume that the ecosystem for XAML apps is evolving too rapidly for the maintainers of larger Open Source libraries. Indeed none of the existing MVVM frameworks was ever designed with .NET Core, Uno, MAUI or WinUI 3 in mind…

Maybe it’s time for a new wind to blow.

Enter Windows MVVM Toolkit

The Microsoft.Toolkit.Mvvm package is a modern, fast, and modular MVVM library that is part of the Windows Community Toolkit (WCT). The package targets .NET Standard 2.* so it can be used on

• any .NET app platform: UWP, WinForms, WPF, Xamarin, Uno, WinUI and more, and on
• any .NET runtime: .NET Native, .NET Core, .NET Framework, or Mono.

Its API surface is the same in all environments, making it perfect for building shared libraries.

The object model and terminology are definitely inspired by MVVM Light and the development team is aiming to provide a smooth migration path from MVVM Light to the new toolkit. Apart from functionality WCT Toolkit also pays high attention to performance. Many benchmarks like this one (on the Messenger class) are continuously run during the development:

The package comes with documentation and a nice sample app. WCT MVVM is currently in ‘preview 4’ so everything is still work in progress.

A UWP Sample App

A few months ago this GitHub issue revealed the initial feature set of Microsoft MVVM Toolkit, preliminary documentation, and even an operational preview package. We decided to create a little UWP app to test that package. Here’s how the home page looks like – standard clean WinUI 2.5:

We’ll use this app throughout this article to explore the features of the new MVVM Toolkit in town.

Core classes

The Building Blocks page of the sample app illustrates the core classes for data binding and commanding:

ObservableObject

ObservableObject provides a base class for types to implement INotifyPropertyChanged and INotifyPropertyChanging – typically Models and ViewModels. You may have encountered similar helpers in other frameworks under the name ObservableBase, BindableBase, or NotifyPropertyChanged. Typically such a class comes with an easy way to raise the PropertyChanged event in property Setters, and that’s exactly what SetProperty() does.

Here’s what it looks like in one of our Model classes:

public class SuperHero : ObservableObject
{
    private string _name;

    public string Name
    {
        get => _name;
        set => SetProperty(ref _name, value);
    }

    // ...
}

Here’s another example from the sample app, this time for a ViewModel – the one that is bound to the BuildingBlocksPage View:

public class BuildingBlocksPageViewModel : ObservableObject
{
    private SuperHero _superHero;

    public SuperHero SuperHero
    {
        get => _superHero;
        set => SetProperty(ref _superHero, value);
    }

    // ...

}

Here’s how the ViewModel is declaratively bound to the View as its DataContext:

<Page.DataContext>
    <viewModels:BuildingBlocksPageViewModel x:Name="ViewModel" />
</Page.DataContext>

When we change a property on the SuperHero, the UI will update:

ViewModel.SuperHero.Nemesis = _nemeses[rnd.Next(0, 5)];

When the property that you want to monitor is a Task<T>, then you can use SetPropertyAndNotifyOnCompletion() instead of SetProperty(). It wil set the property but with the help of an internal TaskNotifier<T> it will delay the notification to when the task was completed:

private TaskNotifier<string> _saveTheUniverseTask;

public Task<string> SaveTheUniverseTask
{
    get => _saveTheUniverseTask;
    private set
    {
        SetPropertyAndNotifyOnCompletion(ref _saveTheUniverseTask, value);
    }
}

There’s even an overload that allows you to register a callback for when the task finishes. Here’s the ViewModel code triggered by the save button on the sample page. It assigns a new value to the task, and then starts it:

public async Task SaveTheUniverse()
{
    SaveTheUniverseTask = new Task<string>(
        () =>
        {
            Task.Delay(2000).Wait();

            if (rnd.Next(2) > 0)
            {
                return $"We're doomed, I lost my {SuperHero.Tool}.";
            }

            return "We're saved ... this time.";
        }
    );

    _saveTheUniverseTask.Start();
}

The task was made observable, so you can monitor its status and result. A simple binding suffices to follow up on the Status [note: The sample app has some extra code to reveal more statuses than ‘initial’ and ‘completed’.]:

<Run Text="{x:Bind ViewModel.SaveTheUniverseTask.Status, Mode=OneWay}" />

We needed to add some extra code to bind to the Result of the task, since UWP XAML does not allow you to bind to a generic. Here’s a ‘wrapper’ property for the result:

public string SaveTheUniverseTaskResult => 
	_saveTheUniverseTask.Status == TaskStatus.RanToCompletion 
	? _saveTheUniverseTask.Result 
	: "(hold your breath)";

And again, the declarative binding:

<Run Text="{x:Bind ViewModel.SaveTheUniverseTaskResult, Mode=OneWay}" />

RelayCommand

The RelayCommand class – a.k.a. DelegateCommand in some frameworks- and its generic and asynchronous siblings provide a default implementation of the ICommand interface. It’s used to declaratively bind events in UI controls to methods in the viewmodel. In the sample app the BuildingBlocksPageViewModel has the following method to toggle its data provider:

private void SwitchDataProvider()
{
    if (_dataProvider is RedDataProvider)
    {
        DataProvider = new BlueDataProvider();
    }
    else
    {
        DataProvider = new RedDataProvider();
    }

    SuperHero = _dataProvider.SuperHero();
}

To trigger this method from a button, we declare a property of the ICommand type:

public ICommand SwitchDataProviderCommand { get; }

Then we let a RelayCommand refer to it:

SwitchDataProviderCommand = new RelayCommand(SwitchDataProvider);

In the view we can now bind the button’s Command property to the ViewModel’s property of type ICommand:

<Button Command="{x:Bind ViewModel.SwitchDataProviderCommand}" />

AsyncRelayCommand extends the ICommand behavior with support for asynchronous operations. Here’s an example of an asynchronous data provider switch:

private async Task SwitchDataProviderAsync()
{
    await Task.Delay(1000);

    SwitchDataProvider();
}

The corresponding property is defined as IAsyncRelayCommand:

public IAsyncRelayCommand SwitchDataProviderAsyncCommand { get; }

And assigned to an AsyncRelayCommand instance:

SwitchDataProviderAsyncCommand = new AsyncRelayCommand(SwitchDataProviderAsync);

IAsyncRelayCommand inherits from ICommand, so you can bind it to a Button’s Command:

<Button Command="{x:Bind ViewModel.SwitchDataProviderAsyncCommand}" />

The ExecutionTask property gives you access to the underlying Task, so you can monitor it. There’s also a convenient IsRunning property that indicates when the task is … running. You can use this to display a busy indicator, such as a ProgressRing. Here’s how such binding looks like:

<winui:ProgressRing
   IsActive="{x:Bind 
	ViewModel.SwitchDataProviderAsyncCommand.IsRunning, 
	FallbackValue=False, 
	Mode=OneWay}" />

ObservableValidator

ObservableValidator is an ObservableObject that hosts a default implementation of INotifyDataErrorInfo. This enables Models and ViewModels to implement validation rules and expose validation results. INotifyDataErrorInfo used to be an important interface some years ago, when all out-of-the-box controls in e.g. Windows Forms, ASP.NET Forms, and WPF came with error templates that implemented the UI part of this interface. It looks like the built-in class comments in the validation annotation attributes are still living in that era – not really reassuring for today’s .NET Client developers:

In the modern XAML stacks you need to do all of the control templating manually or rely on a third-party control library. But here’s the good news: rumor has it that WinUI 3 will bring back error templates for XAML controls, so we welcome this WCT MVVM Toolkit’s ObservableValidator very much.

The ObservableValidator class comes with

• members that implement the INotifyDataErrorInfo interface (HasErrors, GetErrors(), ErrorsChanged, …), 
• overloads of SetProperty() that allow you to specify whether or not validation should run on the assignment of a new property value,
• a TrySetProperty() that does not assign the value if it induces validation errors, and 
• support for all kinds of validation attributes from the System.Component.DataAnnotations namespace.

Here’s the StudyGroup class from our sample app. Its properties are decorated with validation rules on requirement, length, numerical range, and regular expression pattern:

public class StudyGroup : ObservableValidator
{
    [Required(ErrorMessage = "Topic is Required")]
    [MinLength(2, ErrorMessage = "Topic should be longer than one character")]
    public string Topic
    {
        get => _topic;
        set => SetProperty(ref _topic, value, true);
    }

    [Range(2009, 2015, ErrorMessage = "Class should be from 2009 to 2015")]
    public int Class
    {
        get => _class;
        set => SetProperty(ref _class, value, true);
    }

    [RegularExpression(@".*[pP]aintball.*", ErrorMessage = "Hobbies should contain 'Paintball'.")]
    public string Hobbies
    {
        get => _hobbies;
        set => SetProperty(ref _hobbies, value, true);
    }

    // ...
}

Many more validation attributes exist. Some allow you to compare the new value of a property to the old one, or compare the value of two properties within the instance. It’s also very easy to roll your own custom validation attribute.

Using the INotifyDataErrorInfo members a View can react appropriately to the the validation state of its ViewModels. In our sample app we decided to let StudyGroup expose an Errors string with the concatenated list of validation errors. A symbol icon with a tooltip displays the messages:

<SymbolIcon Symbol="ReportHacked"
            Foreground="Red"
            Visibility="{x:Bind ViewModel.StudyGroup.HasErrors, Mode=OneWay}"
            HorizontalAlignment="Right"
            Margin="0 4">
    <ToolTipService.ToolTip>
        <TextBlock Text="{x:Bind ViewModel.StudyGroup.Errors, Mode=OneWay}"
                    Foreground="Red" />
    </ToolTipService.ToolTip>
</SymbolIcon>

Here’s how it looks like in action:

Messaging

In an MVVM application, ViewModels as well as other components may need to communicate with each other in a loosely coupled way. Most MVVM libraries have a Messenger infrastructure for this purpose.

Microsoft MVVM Toolkit’s messaging API allows independent modules to exchange information via messages through a publish/subscribe mechanism. Our sample app hosts two scenario’s. Both scenario’s have different View/ViewModel pairs (a.k.a. “Modules”) on the same page. They are unaware of each other, but need to exchange information about the current ‘theme’.

Here’s the first messaging scenario:

• the ViewModel of the Shell hosts the current ‘Theme’ (just a color),
• when the sample page opens, all modules request the current theme and adapt their UI,
• a ‘Theme Module’ allows to update this current theme through a ToggleSwitch,
• the other modules update their UI immediately, and
• the ‘Theme’ is not a global variable (and neither is the ShellViewModel).

Here’s how the page looks like:

Messages

In this scenario we use two of the message base classes that come with MVVM Toolkit. Here’s the definition of the message that is sent by the theme module when the theme changed, a ValueChangedMessage<T>:

public class ThemeChangedMessage : ValueChangedMessage<Theme>
{
    public ThemeChangedMessage(Theme value) : base(value)
    {
    }
}

Here’s the definition of the message that all modules use to get the current theme, a RequestMessage<T>:

public class ThemeRequestMessage : RequestMessage<Theme>
{
}

ObservableRecipient and Messenger

All ViewModels in this scenario inherit from ObservableRecipient  (which was called ViewModelBase in Preview 1) to get access to an IMessenger instance via the Messenger property.

Here’s the ShellViewModel from our sample app. It switches to the default theme, and starts listening for the ThemeRequestMessage (which it answers with the theme) and the ThemeChangedMessage (which updates the theme). In a production app, the theme would probably be persisted in the Settings.

Here’s the definition of the ShellViewModel:

public class ShellViewModel : ObservableRecipient
{
    private Theme _theme = Theme.Default;

    public ShellViewModel()
    {
        Messenger.Register<ThemeRequestMessage>(this, m =>
        {
            m.Reply(_theme); 
        });

        Messenger.Register<ThemeChangedMessage>(this, m =>
        {
            _theme = m.Value;
        });
    }
}

Here’s the call that the theme-aware modules make to fetch the current theme when they are displayed:

_theme = Messenger.Send<ThemeRequestMessage>();

Just like the ShellViewModel they also subscribe to the ThemeChangedMessage to update:

Messenger.Register<ThemeChangedMessage>(this, m =>
   {
      // ...
   }

Sending a message is as easy as calling Send() on the Messenger:

Messenger.Send(new ThemeChangedMessage(_theme));

Under the hood, the messaging infrastructure is using classic .NET Events and Delegates. It’s important that ViewModels unsubscribe their callbacks when they stop listening for messages. The IMessenger interface comes with several Unregister() members, of which this one is the most radical:

Messenger.UnregisterAll(this);

Generally a ViewModel should only send messages and respond to messages when it is in an operational state – i.e. when it is bound to a loaded View. This operational state can be defined with the IsActive property. When the property becomes true, the OnActivated() method is called, so that’s the appropriate place to register your callbacks:

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

    Messenger.Register<ThemeChangedMessage>(this, m =>
    {
        // ...
    });
}

When IsActive becomes false, OnDeactivated() is called. Its default implementation unregisters all callbacks, so in most cases you need to do … nothing.

Here’s how a View in the sample app marks out the operational state of its ViewModel:

private void ColorModule_Loaded(object sender, RoutedEventArgs e)
{
    _colorModuleViewModel.IsActive = true;
}

private void ColorModule_Unloaded(object sender, RoutedEventArgs e)
{
    _colorModuleViewModel.IsActive = false;
}

The default Messenger in the current version of WCT MVVM uses WeakReferences under the hood, so dangling ViewModels with non-unregistered callbacks will eventually be cleaned up by the Garbage Collector. If you’re sure that your app nicely unregisters all messaging handlers, then you may switch to the original (faster!) Messenger that relies on strong references. Here’s how to do this:

public class ShellViewModel : ObservableRecipient
{
    public ShellViewModel() : base(StrongReferenceMessenger.Default)
    {}

    // ...

}

Message Tokens

Some apps may host groups of modules that listen to different variations of messages. Message tokens can be very useful to reduce the communication overhead. Here’s a screenshot of our sample app – the page is based of a real-life scenario and shows four modules:

• one that broadcasts all pillow-and-blanket war casualties,
• one that is only interested in pillow victims,
• one that is only interested in blanket victims, and
• one that is interested in all casualty messages.

The message itself is empty – it’s good to see that no specific base class is needed:

public class CasualtyMessage // No specific base class needed.
{
}

When a casualty is reported, the broadcast module sends the message, and uses the victim’s party (pillow or blanket) as token:

Messenger.Default.Send<CasualtyMessage, string>(new CasualtyMessage(), "pillow");
// OR
Messenger.Default.Send<CasualtyMessage, string>(new CasualtyMessage(), "blanket");

The next to modules register a callback for CasualtyMessage, but only for their own token:

Messenger.Register<CasualtyMessage, string>(this, "blanket", m => { OnCasualtyMessageReceived(); });

The fourth module registers twice, once for each token. It’s impossible to receive tokenized messages without tokenized registration. So in out sample app, the following will not receive a single message:

// Does not see the messages with a token.
Messenger.Register<CasualtyMessage>(this, m => { OnCasualtyMessageReceived(); });

In our sample app –and many other- Enumations would make an ideal candidate for tokens. After all: the use of hardcoded strings is risky business. Unfortunately token classes are required to implement IEquatable<T> as you see in the definition:

void Register<TMessage, TToken>(object recipient, TToken token, Action<TMessage> action)
            where TMessage : class
            where TToken : IEquatable<TToken>;

This constraint rules out the use of Enumerations. So we created the Party class that looks and feels like an Enum, but implements the interface:

public sealed class Party : IEquatable<Party>
{
    public static readonly Party Pillow = new Party(1, nameof(Pillow));
    public static readonly Party Blanket = new Party(2, nameof(Blanket));

    public string Name { get; private set; }

    public int Id { get; private set; }

    private Party(int id, string name)
    {
        Id = id;
        Name = name;
    }

    public bool Equals(Party other)
    {
        return Id == other.Id;
    }
}

The class can be used as token, instead of String, and we ended up with a much better maintainable code:

Messenger.Register<CasualtyMessage, Party>(this, Party.Blanket, m => { OnCasualtyMessageReceived(); });

Messenger.Default.Send<CasualtyMessage, Party>(new CasualtyMessage(), Party.Pillow);

Dependency Injection

In an MVVM architecture your code base is divided into Views, ViewModels, and Models. Any other reusable code should be grouped into Services. There should be a way to locate and call these services from any component.

ServiceLocator and DependencyInjection are two (related) common patterns to implement this. These patterns are independent from MVVM, but having a service container available in an MVVM app is useful/required in many cases, like

• when you want to cache expensive ViewModels instead of recreating them every time a View is instantiated, or
• when you want to access the messenging infrastructure from a non-ObservableRecipient (like a View).

WCT MVVM comes with an Ioc helper class around the IServiceProvider interface. It supports creating and using a service container, but does not come itself with another service provider. This allows you to stick to your favorite dependency injection framework: Autofac, Ninject, Castle Windsor, Microsoft.Extensions.DependencyInjection or any other. Our sample app uses that last one – very popular in ASP.NET Core:

Here’s a screenshot of the test page, it demonstrates fetching services from the container, and constructor injection:

When the app starts up, it registers its services in the container (the Messenger instance, an expensive ViewModel, a service for Logging, and one for Dialogs) and builds the provider:

Ioc.Default.ConfigureServices
        (new ServiceCollection()
            .AddSingleton<IMessenger>(WeakReferenceMessenger.Default)
            .AddSingleton<ILoggingService, DebugLoggingService>()
            .AddSingleton<ColorModuleViewModel>()
            .AddSingleton<ModalView>()
            .BuildServiceProvider()
        );

At runtime, the app can now pull services out of the container with a call to one of the GetService() family members. Here’s how the expensive ViewModel is fetched by a View:

var viewModel = Ioc.Default.GetService<ColorModuleViewModel>();

And here’s a View getting a reference to the Messenger to send a message:

Ioc.Default.GetService<IMessenger>()
	.Send<CasualtyMessage, Party>(new CasualtyMessage(), Party.Pillow);

For the sake of completeness (and unrelated to MVVM) the sample app also demonstrates constructor injection. Here’s how a ViewModel fetches the Logging and the Dialog services when it’s instantiated:

public ColorModuleViewModel(ILoggingService loggingService, ModalView modalView)
{
    // ...
}

Wait, there’s more!

The new WCT MVVM library is familiar, fast, and flexible. But there’s more coming your way than just the NuGet package. In the near future you may also expect:

• interactive sample apps for all target platforms,
• documentation and Best Practices guidance,
• migration guides from other frameworks such as this one for MVVMLight and this one for Windows Template Studio Basic MVVM, and
• support in Windows Template Studio.

In mean time our sample UWP app lives here on Github.

Enjoy!

A WinUI 2 Reference App

In this article we’ll walk through a UWP app that heavily relies on WinUI 2. WinUI 2.x (currently version 2.4) is the production-ready predecessor of the ambitious WinUI 3 platform. Version 3.x aims to become -in a not too distant future- the native runtime UI library for all apps that run on Windows – think Win32, UWP, Xamarin, Uno, and React Native.

To prepare ourselves for this WinUI 3.x we created a small but –hopefully- representative UWP app using WinUI 2.4. It fetches and displays live financial data (stock prices and news) from IEX Cloud. Here’s how the app looks like:

The app

• makes maximum use of WinUI controls,
  • ItemsRepeater
  • NavigationView
  • TabView
  • TeachingTip
  • ProgressRing
• applies some Fluent techniques,
  • Acrylic brushes
  • ThemeShadow
  • Implicit Animations
• and relies on 3rd party libraries
  • Telerik UI for UWP (by Progress)
  • IEXSharp (by Victor Lee)

It is our intention to upgrade this app with every new version of one of the underlying dependencies (specifically WinUI). This will give us an idea on how hard or easy it is to upgrade existing UWP apps to the new platform. In the mean time this reference app may also help you getting started with WinUI in UWP.

The app displays stock market data that is returned from services by IEXCloud, a company that publishes (and we quote from their home page) “institutional grade data, including fundamentals, ownership, international equities, mutual funds, options, real-time data, and alternative data – all in one API“. The data is exposed for free (if you stay below 50.000 core calls per month) but you need to register an account. The app’s Settings page allows you to enter the access keys that come with that account.

To become familiar with the financials API, we started to play around with IEXSharp – an Open Source C# IEXCloud client. We rapidly decided to continue to use the client: it’s complete, easy to work with, and regularly updated.

Here’s the full list of the app’s dependencies, with WinUI v2.5.0 already lurking as a preview:

Let’s dive into the source code.

The Shell Page

The root page of the app hosts the navigation infrastructure and shared UI assets such as the background image. Due to our long history as Prism framework user, we keep calling this type of page the Shell.

Look and feel

The main control in the Shell page is a NavigationView. We’ll use ‘winui’ as namespace alias for the WinUI-specific controls:

xmlns:winui="using:Microsoft.UI.Xaml.Controls"

Here’s the XAML declaration of a NavigationView with its menu on the left, a page header and no back button:

<winui:NavigationView 
	x:Name="NavigationView"
	Header="My stocks"
	IsBackButtonVisible="Collapsed">
	<winui:NavigationView.MenuItems>
		<!-- menu items -->
	</winui:NavigationView.MenuItems>
</winui:NavigationView>

The menu is a list of NavigationViewItem instances. You can nest these to obtain hierarchical navigation. Here’s the XAML definition of the History menu item, demonstrating not only a hierarchical construct but also three types of icons to use (symbol, SVG path, and multicolor bitmap):

<winui:NavigationViewItem Content="History">
    <winui:NavigationViewItem.Icon>
        <FontIcon Glyph="" />
    </winui:NavigationViewItem.Icon>
    <winui:NavigationViewItem.MenuItems>
        <winui:NavigationViewItem Content="AAPL">
            <winui:NavigationViewItem.Icon>
                <PathIcon Data="M32.295, etcetera ..." />
            </winui:NavigationViewItem.Icon>
        </winui:NavigationViewItem>
        <winui:NavigationViewItem Content="MSFT">
            <winui:NavigationViewItem.Icon>
                <BitmapIcon UriSource="/Assets/microsoft.png"
                            ShowAsMonochrome="False" />
            </winui:NavigationViewItem.Icon>
        </winui:NavigationViewItem>
    </winui:NavigationViewItem.MenuItems>
</winui:NavigationViewItem>

Here’s how the Shell page looks like. The Fluent reveal highlight effect is by default enabled in the control, as well as the acrylic background (we did override the BackgroundSource however):

The emptiness on the right of the menu is a Frame control to host the different user pages.

Navigation

Navigation is very straightforward: each NavigationViewItem keeps the class name of the target content page in its Tag property:

<winui:NavigationViewItem 
	Content="Watchlist"
        Tag="XamlBrewer.UWP.IEXCloud.Sample.Views.WatchListPage" />

The menu conveniently responds to ItemInvoked (click) as well as SelectionChanged (click on a unselected item). Here’s how we Navigate the Frame to the selected content page, and update the Header with the text of the (root node of the) selected item:

private void NavigationView_SelectionChanged(
	WinUI.NavigationView sender, 
	WinUI.NavigationViewSelectionChangedEventArgs args)
{
    if (args.IsSettingsSelected)
    {
        ContentFrame.Navigate(typeof(SettingsPage));
        NavigationView.Header = "Settings";
        return;
    }

    var item = args.SelectedItemContainer as WinUI.NavigationViewItem;

    if (item.Tag != null)
    {
        ContentFrame.Navigate(Type.GetType(item.Tag.ToString()), item.Content);
        NavigationView.Header = sender.SelectedItemsPath().First().Content;
    }
}

The NavigationView makes a distinction between the Settings menu item and the others, in case you would want to open a settings dialog or ye olde Windows 8 SettingsPane. The current guidelines for app settings however specify that “the app settings window should open full-screen and fill the whole window”. Here’s the corresponding from the (by the way excellent) docs:

It looks like we’re supposed to treat the Settings page not different from the other pages. If that’s the case for all devices, then API members such as IsSettingsSelected are actually obsolete.

NavigationView 2.4 supports a hierarchical menu but is missing a SelectedItems property – representing the path from the root menu to the selected leaf menu. This would be extremely helpful in some common scenario’s, e.g. when

• you want to display a bread crumb, or
• your navigation logic requires information from different levels.

In our sample app, the root menu defines the target class for navigation while the leaf menu provides the stock symbol to show. We created a SelectedItemsPath extension method that goes recursively through the selected menu items and returns the full path as a list:

public static List<WinUI.NavigationViewItem> SelectedItemsPath(
	this WinUI.NavigationView navigationView)
{
    var result = new List<WinUI.NavigationViewItem>();
    GetSelectedItems(navigationView.MenuItems, ref result);

    return result;
}

private static void GetSelectedItems(
	IList<object> items, 
	ref List<WinUI.NavigationViewItem> result)
{
    foreach (WinUI.NavigationViewItem item in items)
    {
        if (item.IsSelected)
        {
            result.Insert(0, item);
        }
        else
        {
            if (item.MenuItems?.Count > 0)
            {
                var count = result.Count;
                GetSelectedItems(item.MenuItems, ref result);
                if (result.Count > count)
                {
                    result.Insert(0, item);
                }
            }
        }
    }
}

Teaching tip

All of the content pages visualize stock related data from the IEXCloud services. This requires a (free) account. The Shell page hosts a TeachingTip control to inform you of this:

<winui:TeachingTip 
	x:Name="SettingsTip"
	Title="IEX Cloud Account Required"
	CloseButtonClick="SettingsTip_CloseButtonClick"
	IsOpen="False">
   <winui:TeachingTip.Content>
      <!-- ... -->
   </winui:TeachingTip.Content>
</winui:TeachingTip>

Here’s how it looks like:

The TeachingTip is only opened when the required tokens are not found in the settings, and its arrow points to the center of the Settings menu item:

private void Shell_Loaded(
	object sender, 
	RoutedEventArgs e)
{
    var settings = new Settings();
    if (String.IsNullOrEmpty(settings.PublishableKey) && 
	String.IsNullOrEmpty(settings.PublishableSandBoxKey))
    {
        SettingsTip.Target = NavigationView.SettingsItem as FrameworkElement;
        SettingsTip.PreferredPlacement = WinUI.TeachingTipPlacementMode.TopLeft;
        SettingsTip.IsOpen = true;
    }
}

When the teaching tip is closed, the app autonavigates to the Settings page.

The Settings page

In the Settings page the user can enter (and test) the different tokens that are required to call the IEXCloud services, and also choose between ‘production’ mode (limited number of calls, but real data) and ‘sandbox’ mode (unlimited calls, but fake data). During development and testing it definitely made sense to activate ‘sandbox’ mode – some of the diagrams eat a lot of data.

Using Observable Settings

A while ago we came across this very elegant ObservableSettings base class for bindable settings in UWP. Here are the settings for our WinUI reference app – two pairs of token keys, and an indicator for sandbox mode:

public class Settings : ObservableSettings
{
    public static Settings Default { get; } = new Settings();

    public Settings()
        : base(ApplicationData.Current.LocalSettings)
    {}

    public string PublishableKey
    {
        get { return Get<string>(); }
        set { Set(value); }
    }

    public string SecretKey
    {
        get { return Get<string>(); }
        set { Set(value); }
    }

    // Similar code for sandbox keys.
   // ...

    [DefaultSettingValue(Value = true)]
    public bool UseSandBox
    {
        get { return Get<bool>(); }
        set { Set(value); }
    }
}

All you need to do is create a Settings instance …

private Settings Settings => new Settings();

… and bind its properties it to the corresponding UI elements:

<TextBox Header="Publishable key"
            Text="{x:Bind Settings.PublishableKey, Mode=TwoWay}" />
<PasswordBox Header="Secret key"
                Password="{x:Bind Settings.SecretKey, Mode=TwoWay}" />

Changes are automatically saved to local settings. How convenient!

Here’s how the Settings page looks like:

Applying ThemeShadow

The panels in the Settings page have shadow around them. ThemeShadow is defined as a shared resource and then applied to each panel:

<Grid Background="Transparent">
    <Grid.Resources>
        <ThemeShadow x:Name="SharedShadow" />
    </Grid.Resources>
    <Grid x:Name="ShadowCatcher"
            Margin="-8" />
    <VariableSizedWrapGrid x:Name="SettingsGrid"
                            Orientation="Horizontal">
        <StackPanel x:Name="ContentGrid"
                    Shadow="{StaticResource SharedShadow}">
            <!-- Production Content -->
        </StackPanel>
        <!-- Gets the animation -->
        <Grid>
            <!-- Casts the shadow -->
            <StackPanel x:Name="SandboxContentGrid"
                        Shadow="{StaticResource SharedShadow}">
                <!-- Sandbox Content -->
            </StackPanel>
        </Grid>
    </VariableSizedWrapGrid>
</Grid>

When the app starts, the panels are lifted by a Translation on the z-axis:

public SettingsPage()
{
    this.InitializeComponent();
    ContentGrid.Translation += new Vector3(0, 0, 6);
    // ...
}

The control underneath the WrapGrid is added to the shadow’s Receivers:

private void SettingsPage_Loaded(object sender, RoutedEventArgs e)
{
    SharedShadow.Receivers.Add(ShadowCatcher);
}

Applying Implicit Transformations

Since smooth transition is not (yet) the default, we let the different panels in the Settings page fluently respond to changes in window size via implicit animations:

We had to add an extra Grid in the panel template to make this happen: adding ThemeShadow and implicit animations to the same control did not work …

Let’s dive into the real content pages now.

The Watchlist page

The Watchlist page hosts a list of high level properties of some stocks. We admit that the current Telerik Rad Datagrid would have been an ideal container for this collection, but we wanted to get some more experience with the WinUI ItemsRepeater. Here’s the XAML structure of the Watchlist page:

<winui:ItemsRepeater x:Name="Quotes">
    <winui:ItemsRepeater.Layout>
        <winui:StackLayout 
	Orientation="Vertical"
	Spacing="20" />
    </winui:ItemsRepeater.Layout>
    <winui:ItemsRepeater.ItemTemplate>
        <DataTemplate x:DataType="response:Quote">
            <!-- template content -->
        </DataTemplate>
    </winui:ItemsRepeater.ItemTemplate>
</winui:ItemsRepeater>

Here’s what the page looks like:

There’s nothing more to report on this page, except that –after all those years- we learned that you can format positive, negative, and zero values with a single expression:

<TextBlock Text="{x:Bind sys:String.Format('{0:+0.00%;-0.00%;0%}', changePercent)}" />

And again, we’re using an items repeater to mimic a data grid here. As soon as this app will make the move to WinUI 3, this page will become an ideal host for testing the upcoming Telerik WinUI 3 Data Grid.

The News page

The News page displays the latest news for a stock symbol in an ItemsRepeater. The symbol is taken from the Content of the hierarchical menu item and passed via the navigation logic:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    base.OnNavigatedTo(e);

    _symbol = e.Parameter.ToString();
}

Here’s how the page looks like:

We observed that the RelativePanel is the best host for data templates that contain images with different source sizes.

The History page

The main beef of the History page is a Telerik RadCartesianChart that displays stock price history with

• the closing price as a LineSeries,
• a graphical representation of the OHLC (open-high-low-close) data as a CandleStickSeries, and
• a customized ChartTrackBall that reveals the OHLC data when hovering over the chart with the mouse.

Here’s how the History page looks like:

The focus of the reference app –and this article- is not on the charts but on WinUI 2, so let’s take a look on the TabView on top of the page. It starts with TabItems for the two predefined stock symbols from the menu (AAPL and MSPF). It also allows to add (removable) custom tabs, and it comes with a TabStripFooter with a (not-yet-implemented) Save button.

Here’s its XAML definition:

<winui:TabView 
	x:Name="SymbolsTab"
	SelectionChanged="SymbolsTab_SelectionChanged"
	AddTabButtonClick="SymbolsTab_AddTabButtonClick"
	TabCloseRequested="SymbolsTab_TabCloseRequested">
    <winui:TabViewItem Header="AAPL"
                        IsClosable="False" />
    <winui:TabViewItem Header="MSFT"
                        IsClosable="False" />
    <winui:TabView.TabStripFooter>
        <!-- Save Button -->
    </winui:TabView.TabStripFooter>
</winui:TabView>

When we navigate to the History page, we pick up the stock symbol – just like in the News page- and then use it to select the appropriate Tab item:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    base.OnNavigatedTo(e);

    _symbol = e.Parameter.ToString();

    try
    {
        // Synchronize menu to tab.
        SymbolsTab.SelectedItem = SymbolsTab
                                    .TabItems
                                    .Where(ti => (ti as WinUI.TabViewItem).Header.ToString() == _symbol)
                                    .First();
    }
    catch (Exception)
    {
        // Synchronization failed.
        SymbolsTab.SelectedIndex = 0;
    }
}

When the user selects another Tab –that’s a SelectionChanged– we fetch its symbol and refresh the page’s data:

private async void SymbolsTab_SelectionChanged(
	object sender, 
	SelectionChangedEventArgs e)
{
    if (!e.AddedItems.Any())
    {
        return;
    }

    _symbol = (e.AddedItems.First() as WinUI.TabViewItem).Header.ToString();

    // Here's where we should try to sync from tab to menu without starting a loop.
    // ...

    ProgressRing.IsActive = true;

    using (var iexCloudClient = IEXCloudService.GetClient())
    {
        try
        {
            var response = await iexCloudClient.StockPrices.HistoricalPriceAsync(_symbol);
            if (response.ErrorMessage != null)
            {
                HistoricPrices.ItemsSource = null;
                CandleSticks.ItemsSource = null;
            }
            else
            {
                HistoricPrices.ItemsSource = response.Data;
                CandleSticks.ItemsSource = response.Data;
            }
        }
        catch (Exception ex)
        {
            HistoricPrices.ItemsSource = null;
            CandleSticks.ItemsSource = null;
        }
    }

    ProgressRing.IsActive = false;
}

When the ‘plus’ button is hit, we open a small ContentDialog to request a new stock symbol:

When the user confirms the new stock symbol, we add a new TabViewItem and select it:

if (await dialog.ShowAsync() == ContentDialogResult.Primary)
{
    var newTab = new WinUI.TabViewItem();
    newTab.Header = textBox.Text;
    sender.TabItems.Add(newTab);
    sender.SelectedIndex = sender.TabItems.Count - 1;
}

Here’s another straightforward piece of code. When the user closes one of the custom tabs, we simply remove it:

private void SymbolsTab_TabCloseRequested(
	WinUI.TabView sender, 
	WinUI.TabViewTabCloseRequestedEventArgs args)
{
    sender.TabItems.Remove(args.Item);
}

The Portfolio page

All the controls and techniques that were used in the previous pages were just a warming-up for the Portfolio page. It displays a GridView with (fictional) stock positions: original value, current value, turnover, and a history sparkline (technicaly another Telerik RadChart, this time showing a SplineSeries). Here’s how the page looks like:

We’ll focus on the menu on top of the page. It allows to specify the time period for the sparklines. It is another NavigationView instance, this time demonstrating a NavigationViewItemHeader and a different PaneDisplayMode:

<winui:NavigationView 
	x:Name="TopNavigationView"
	PaneDisplayMode="Top"
	IsSettingsVisible="False"
	IsBackButtonVisible="Collapsed"
	SelectionChanged="TopNavigationView_SelectionChanged">
    <winui:NavigationView.MenuItems>
        <winui:NavigationViewItemHeader Content="  Chart period: " />
        <winui:NavigationViewItem Content="1 Month"
                                    Tag="OneMonth" />
        <winui:NavigationViewItem Content="3 Months"
                                    Tag="ThreeMonths"
                                    IsSelected="True" />
        <winui:NavigationViewItem Content="1 Year"
                                    Tag="OneYear" />
    </winui:NavigationView.MenuItems>
</winui:NavigationView>

A navigation view menu comes with its own styling – including a default acrylic background. We needed to override one of its many resources to make that background transparent to blend in the page:

<SolidColorBrush x:Key="NavigationViewTopPaneBackground"
                    Color="Transparent" />

Selecting a menu refreshes the query and the page, just like the tab in the History page.

For the sake of completeness, here’s how the implicit animations look like (this should be the default) on this page:

The Source

Our WinUI 2 reference app lives here on GitHub. You may expect regular updates to it.

Enoy!

Using LiteDB as a local NoSQL database in UWP

In this article we’ll show how to use a LiteDB database instance to hold local data in an UWP app. LiteDB is a NoSQL database with an API that is inspired by MongoDB. It focuses on storing ‘documents’: loosely typed nested key-value or key-array pairs similar to JSON objects.

Whenever you need to manipulate, query, and persist a collection of dynamic complex objects in your app, a NoSQL database is probably the better choice. A relational database such a SQLite would impose a less convenient, fixed, strongly-typed multi-table schema on your data.

We built a sample UWP app that locally stores some NetFlix series data. The app’s data layer covers

• creating the local database,
• running basic CRUD-queries,
• querying metadata,
• running advanced queries,
• handling foreign-key relationships, and
• dealing with images.

Here’s how that sample app looks like:

Configuring the app

In order to use LiteDB, your app needs a dll that has its source code in a very active GitHub repo and is distributed via NuGet:

Our sample UWP app also references Microsoft.UI.XAML a.k.a. WinUI. This is to ensure that we’re using the latest set of XAML controls and styles – it’s where the rounded corners come from.

When you open the app’s bin folder after adding the LiteDB NuGet package, you’ll notice that its dll takes less than half a megabyte – not bad for a whole database engine:

Creating the database instance

When creating an instance of a LiteDatabase you need to provide a connection string with at least the path to the file where it needs to be stored. For an UWP app, a file in ApplicationData.LocalFolder is an obvious choice:

private static LiteDatabase MyDatabase
{
    get
    {
        var databaseName = "MySeries";
        var filePath = Path.Combine(
            Windows.Storage.ApplicationData.Current.LocalFolder.Path, 
            databaseName);

        return new LiteDatabase(filePath);
    }
}

Here’s how the local data folder looks like after this code has run:

Creating Document Collections

The ‘complex dynamic objects’ that the sample app will store, represent NetFlix series with actors, and with seasons that have episodes. We defined these in POCO classes. LiteDB translates these to BsonDocuments (binary JSON) using its object mapping strategy. This strategy contains data type mapping and primary key generation/determination:

Here’s how the sample app’s entities class diagram looks like:

We’ll store these entities in two collections: one for the Series and one for the Actors. Observe that in a relational database the same schema would

• require at least five tables – one for each entity and one to hold the n-to-n relationship between Series and Actor, and
• leave no room for new or unexpected attributes.

Let’s focus on storing documents that represent Series. Here’s the code that

• (re)creates a LiteCollection to hold the Series instances using DropCollection() and GetCollection<T>(),
• places an index on it with EnsureIndex(), and
• populates it with sample data with some Insert() statements,
• in an Awaitable method:

public static Task Reset()
{
    return Task.Run(() =>
    {
        using (var db = MyDatabase)
        {
            // Remove collection.
            db.DropCollection("series");

            // Get a collection (create it if it doesn't exist)
            var seriesCollection = db.GetCollection("series");

            // Index on Name.
            seriesCollection.EnsureIndex(x => x.Name);

            // Populate.
            foreach (var series in Series.SampleData)
            {
                seriesCollection.Insert(series);
            }

            // ...
        }
    });
}

The database now knows its schema and is ready for some action.

Basic Queries

A call to FindAll() against a document collection returns all instances in it, sorted by their primary key – in our sample app this is the numeric Id field:

public static List SelectAll()
{
    using (var db = MyDatabase)
    {
        var col = db.GetCollection("series");
        return col.FindAll().ToList();
    }
}

A call to Query() returns an ILiteQueryable<T> which exposes LINQ capabilities. Here’s a query that returns all the Series in the database that have a season in a specific year, sorted by Name:

public static List SelectFromYear(int year)
{
    using (var db = MyDatabase)
    {
        var col = db.GetCollection("series");
        return col
            .Query()
            .Where(x => x.Seasons.Select(s => s.Year).Any(y => y == year))
            .OrderBy(x => x.Name)
            .ToList();
    }
}

The call to fetch a single document from a collection is conveniently called FindOne(). It takes a Lambda expression for predicate:

var ac = seriesCollection.FindOne(s => s.Name == "Altered Carbon");

The rest of the API for CRUD queries is also straightforward. Here are some samples of Insert(), Update() and Delete() statements. After each call, we pass back the last Actor in the collection, serialized into a JSON-string. Here’s the code:

public static IEnumerable Crud()
{
    using (var db = MyDatabase)
    {
        var actors = db.GetCollection("actors");
        var ws = new Actor { Name = "Will Smiff" };
        actors.Insert(ws);
        yield return BsonMapper.Global.Serialize(actors.FindAll().Last()).ToString();
        ws.Name = "Will Smith";
        actors.Update(ws);
        yield return BsonMapper.Global.Serialize(actors.FindAll().Last()).ToString();
        actors.Delete(ws.ActorId);
        yield return BsonMapper.Global.Serialize(actors.FindAll().Last()).ToString();
    }
}

Here’s how it looks like in the sample app:

Querying metadata

Just like in a relational database, you can use the API that queries user content to also fetch system metadata. The database itself is exposed as a collection named ‘$database’. Here’s how to enumerate all its properties – things like name, size, and configuration:

public static IEnumerable SelectDatabaseProperties()
{
    using (var db = MyDatabase)
    {
        var col = db.GetCollection("$database");
        var doc = col.FindAll().ToList().First();
        foreach (var item in doc.Keys)
        {
            yield return $"{item}: {doc[item]}";
        }
    }
}

Here’s how to get the list of all user collections in the database, using the expression-based syntax that we’ll cover shortly:

public static IEnumerable SelectUserCollections()
{
    using (var db = MyDatabase)
    {
        var col = db.GetCollection("$cols");
        //var cols = col.Find(BsonExpression.Create("$.type = 'user'")).ToList();
        var cols = col.Find("$.type = 'user'").ToList();
        var name = "name";
        foreach (var item in cols)
        {
            yield return $"{item[name]}";
        }
    }
}

Here’s the sample app displaying the results:

Advanced Queries

Next to its standard LINQ API LiteDB also supports a SQL syntax. Inside the statements you can use expressions that are based on JsonPath – a lightweight (but still powerful) JSON version of XPath.

Here are some sample queries and their corresponding expressions:

The titles of all episodes in a 2020 season	$.Seasons[@.Year = 2020].Episodes[*].Title
All season finales (last episode of each season)	$.Seasons[*].Episodes[-1]
All episodes with the text ‘fight’ in its description	$.Seasons[*].Episodes[@.Description LIKE ‘%fight%’]

Here’s how to write and execute these queries from C#. You Execute() a command and then Read() through its result set, pretty much like in the good old ADO.NET days:

public static IEnumerable Select2020Seasons()
{
    using (var db = MyDatabase)
    {
        // This year's episodes.
        var reader = db.Execute(
            "SELECT $.Name, $.Seasons[@.Year = 2020].Episodes[*].Title AS Episodes 
             FROM series");

        while (reader.Read())
        {
            yield return reader.Current.ToString();
        }
    }
}

public static IEnumerable SelectSeasonFinales()
{
    using (var db = MyDatabase)
    {
        // Season finales per season.
        var reader = db.Execute("
            SELECT $.Name, $.Seasons[*].Episodes[-1] AS SeasonFinales 
            FROM series");

        while (reader.Read())
        {
            yield return reader.Current.ToString();
        }
    }
}

public static IEnumerable SelectFightEpisodes()
{
    using (var db = MyDatabase)
    {
        // Episodes about fighting.
        var reader = db.Execute("
            SELECT $.Name, $.Seasons[*].Episodes[@.Description LIKE '%fight%'] AS Fights 
            FROM series");

        while (reader.Read())
        {
            yield return reader.Current.ToString();
        }
    }
}

Here’s how the results look like in the sample app:

Handling Foreign Key Relationships

Similar to foreign keys in a relational database, DBRef allows you to create references between collections – mainly to avoid duplication. In our sample entity model, each series has a cast of actors. We didn’t want to embed the actor’s details in the series document. While an actor may appear in multiple series, it makes sense to store properties like name and birthday and Academy Award nominations only once.

In the series entity we decorated the property holding the list of actors with a BsonRef attribute:

public class Series
{
    // ...

    [BsonRef("actors")]
    public Actor[] Cast { get; set; }

    // ...
}

The Cast now refers to Actor instances instead of embedding these. The Series instance will store only the identity of each Actor. The identity is the primary key property that you define by using naming conventions or applying the BsonId attribute (more details here):

public class Actor
{
    [BsonId]
    public int ActorId { get; set; }

    // ...
}

When adding actors to the cast of a series, make sure that the Actor documents are first added to the database – they need to have their identity. Then you can insert/update/upsert the Series:

var f1 = seriesCollection.FindOne(s => s.Name == "Formula1: Drive to survive");

var drivers = new List
{
    new Actor { Name = "Alex Albon" },
    new Actor { Name = "Carlos Sainz" },
    new Actor { Name = "Charles Leclerc" }
};
actorsCollection.Upsert(drivers);
f1.Cast = drivers.ToArray();
seriesCollection.Upsert(f1);

That same order applies to data modifications inside a transaction (yes, LiteDB supports transactions):

var rm = seriesCollection.FindOne(s => s.Name == "Rick and Morty");

var cartoons = new List
{
    new Actor { Name = "Rick Sanchez" },
    new Actor { Name = "Morty Smith" },
    new Actor { Name = "Mr. Meeseeks" }
};
rm.Cast = cartoons.ToArray();
db.BeginTrans();
actorsCollection.Upsert(cartoons); // Actors added.
seriesCollection.Upsert(rm);
// actorsCollection.Upsert(cartoons); // Actors not added - even inside a transaction the order is important.
db.Commit();

To join the Series with their Actors, just do the same as in Entity Framework and Include() the related entity. Here’s the LINQ query:

var col = db.GetCollection("series");
return col
    .Query()
    .Include(s => s.Cast)
    .OrderBy(x => x.Name)
    .ToList();

Here’s how the result looks like in the sample app:

Using FileStorage

LiteDB limits the maximum size for an individual document to 1 MB. For regular data types that should suffice. When you’re dealing with images and streams, you should store these in so-called FileStorage. When you start using the FileStorage feature, LiteDB creates two collections to store the metadata (‘_files’) and the content (‘_chunks’) of the files.

Here’s how to upload a local file (a poster image for a Series) together with its metadata –also a BsonDocument- into FileStorage:

public static string SaveFile(string fileId, string filePath, string series)
{
    using (var db = MyDatabase)
    {
        var fs = db.FileStorage;
        var fileInfo = fs.Upload(fileId, filePath);
        fs.SetMetadata(fileInfo.Id, new BsonDocument { ["series"] = series });

        return $"Imported {fileInfo.Filename} ({fileInfo.Length} bytes) as {fileInfo.Id}.";
    }
}

Here’s the call from the app to store the file:

fileInfo = DataLayer.SaveFile(
        @"$/series/rickandmorty.jpg", 
        path, 
        "Rick and Morty");

Observe that we apply a folder structure to the uploaded file(s), as if they’re saved in a ‘series’ folder.

Here’s how to use the resulting file Id to fetch the contents back:

public static Stream SelectFile(string fileId)
{
    using (var db = MyDatabase)
    {
        var stream = new MemoryStream();
        var fs = db.FileStorage;
        var fileInfo = fs.Download(fileId, stream);
        return stream;
    }
}

Here’s how to fetch all files from a virtual folder:

public static IEnumerable QueryFolder(string folder)
{
    using (var db = MyDatabase)
    {
        var fs = db.FileStorage;
        var infos = fs.Find("_id LIKE @0", folder + "%");
        if (infos != null)
        {
            foreach (var info in infos)
            {
                yield return info.Id;
            }
        }
    }
}

And the call from the client:

var files = DataLayer.QueryFolder(@"$/series/");

Here’s how to fetch files by their meta data:

public static Stream FindFileByMetadata(string series)
{
    using (var db = MyDatabase)
    {
        var stream = new MemoryStream();
        var fs = db.FileStorage;
        var fileInfo = fs.Find(x => x.Metadata["series"] == "Altered Carbon").FirstOrDefault();
        fs.Download(fileInfo.Id, stream);
        return stream;
    }
}

For the sake of completeness, here’s how to remove a file from FileStorage:

public static bool DeleteFile(string fileId)
{
    using (var db = MyDatabase)
    {
        var fs = db.FileStorage;
        return fs.Delete(fileId);
    }
}

Here’s the result from these queries in the sample app:

The Verdict

Whenever you need to manipulate, query, and locally persist collections of dynamic complex objects in a .NET based app, it’s worth considering LiteDB. It’s lightweight, it‘s easy to use, and it comes with rich capabilities. It’s also free of charge.

The Source

The sample app lives here on GitHub.

Enjoy and stay healthy!