Merged Dictionaries In Xamarin.Forms

Placing styles and other resources in your ResourceDictionary is a great way to reuse these elements through your page or application. However, up until now, you could only merge with one external resource dictionary, using MergedWith. With MergedDictionaries, you can now separate out your styles into multiple files, and merge them as desired on each page.

Note: I personally wrote this feature in Xamarin.Forms. My PR 1138 has been merged, with many thanks to Stephane for the code review. It is currently unknown which version, of Xamarin.Forms this feature will appear in. I will update here when I find out.

How To Use

Create a new XAML file, and create your resource dictionary, as below.  I called the my new file, MyResourceDictionary.

<?xml version="1.0" encoding="utf-8" ?>
<ResourceDictionary xmlns="http://xamarin.com/schemas/2014/forms"
                   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                   x:Class="Mobile.Style.MyResourceDictionary"> 
    <Style TargetType="Button"> 
        <Setter Property="TextColor" Value="White" /> 
    </Style>
</ResourceDictionary>

Then, in your ContentPage, do the following.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:theme="clr-namespace:Mobile.Style"
             x:Class="Mobile.MainPage">
    <ContentPage.Resources>
        <ResourceDictionary.MergedDictionaries>
            <theme:MyResourceDictionary />
            <!-- Add as many as you want here -->
        </ResourceDictionary.MergedDictionaries>
    </ContentPage.Resources>
</ContentPage>

Or, you can even do this, if you want to get creative, but I recommend the first approach.

<ContentPage.Resources>
    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary MergedWith="theme:MyResourceDictionary">
            <Style TargetType="Button"> 
                <Setter Property="TextColor" Value="White" /> 
            </Style>
        </ResourceDictionary>
    </ResourceDictionary.MergedDictionaries>
</ContentPage.Resources>

Searching

A ResourceDictionary, could have the same key as a dictionary that is merged via MergedWith or MergedDictionaries. When the page is trying to find a key, it uses this search method.

  1. Check in page’s local keys
  2. Check MergedWith ResourceDictionary
  3. Check each MergedDictionaries, in the order they are listed

The first place it finds the key, it uses that key. Hence the priority is set based on the list above.

If a merged dictionary, then has another MergedWith or MergedDictionaries, attached, it follows the same search pattern, again.

Performance Considerations

Searching resource dictionaries, involves checking every key, until it finds something suitable. If you have a large amount of keys, and the key you are looking for is right at the end, and you use this key multiple times, it may impact performance. It is best to ensure you only place the appropriate resource dictionaries in your page, to avoid unnecessary searching.

Why MergedWith and not Source

UWP and WPF use Source as their property name, not MergedWith. Currently, the resource dictionary has the MergedWith tag to merge one Resource Dictionary, with another. It is planned that the Source attribute will be used in the future, but will also support finding dictionaries based on URI as well. Once this occurs, it is expected that MergedWith, will be deprecated.

Microsoft MVP | Xamarin MVP | Xamarin Certified Developer |
Exrin MVVM Framework | Xamarin Forms Developer | Melbourne, Australia


XAMARIN.FORMS MONTHLY NEWSLETTER

JOIN 1,000+ SUBSCRIBERS

  1. Don't miss out on updates
  2. The latest info from this site, Xamarin and the community
  3. Unsubscribe at any time*

* We use MailChimp, with double opt-in, and instant unsubscribe

Related Posts

Tagged:Tags:

3 Comments

  1. Brian

    This is awesome, thanks Adam! Merged resource dictionaries is something I’ve missed coming from WPF and SL background

Leave A Comment?