WPF: Loading Generalized DataTemplates in Code

I've been working WPF quite a bit recently and am discovering the ins and outs of this beast. It's nothing if not ambitious.

I personally like it. A lot. I worked with .NET Forms previously and Win32, and Java Swing before that, and this is far and away the most sophisticated UI framework I have ever seen. However, it's still relatively new and documentation (as well as good examples) can be scarce.

One thing that I've noticed when browsing examples online is that most people present ideas through trivial examples - in fact, they repeat the same information through repeated trivial exercises that can be found on other sites. I'll try to avoid doing that, but that also means that I'm going to assume that you know what you're doing. I'm not going to post tutorials or explain basic WPF concepts that are covered in the all the main WPF resources (see another post in the future.) I'm going to post annoying factoids that have halted progress for me personally at work, and hopefully this will help someone out there.

Let's jump in and take a look at generalized DataTemplates in WPF. By generalized, I'm talking about the DataTemplates that set their type via the DataType property. Sampled from MSDN:

<DataTemplate
  DataType="{x:Type c:GreekGod}">
   <TextBlock Text="{Binding Path=Name}" Foreground="Gold"/>
</DataTemplate>

Like the Style element, DataTemplate uses the DataType property as a way of hooking itself into the general scope of your application. Style's version of this is TargetType.

Now, here's the problem: Where do you specify this DataTemplate? Where does it go in the project? No one seems to make this clear, or provides a satisfactory answer. The real answer is that this DataTemplate needs to exist in a loaded Resources dictionary somewhere up the logical chain of elements where you expect it to be used.

Everyone assumes a trivial layout for a project. "If you need to create a DataTemplate, then just add it to the Window.Resources element, dumbass." However, this is not very helpful, for anyone who is working outside the standard layout conventions (for instance if you're developing WPF controls for a mixed managed application, and blending them into a Win32 frame.) Sometimes, you don't have the benefit of simply adding the template to a higher level component because, wait for it, the XAML might actually be dynamic. Maybe your application reads in XAML to construct a class at runtime. Maybe popping in a DataTemplate definition here is not such a good idea.

So now I'm scratching my head and going back to the root of the problem - how does WPF know about this template in the first place? If I put it in a loose XAML file in my project, and have it compiled, shouldn't the template be properly registered at runtime? Turns out that that isn't the case. Loose XAML does not a loaded component make, which I thought was interesting, and actually makes a lot of sense. This is something that may not be clear from MSDN: Just because you put a DataType property on a DataTemplate in a ResourceDictionary element without a x:Key in a XAML file that is compiled into your project, doesn't mean that it's actually registered with WPF at runtime. It needs to be loaded into the logical chain somewhere.

XAML is cool, but it's still a static definition of components. If you're going to need to sew anything in, you're best bet is to go back to code.

In my case, the answer lay in dynamically loading the XAML and adding it to my root control's MergedDictionaries set (no handy top-level Window, sorry), in the root control's constructor.

To do this, you create a Uri object that points to your project XAML resource (compiled BAML, actually), and use the Application.LoadComponent() static method to load and create the root node of the XAML. If you store your DataTemplate in a ResourceDictionary, the code might look something like this:

public RootControl() {
 InitializeComponent();
 Uri uri = new Uri("MyAssembly;component/Templates.xaml", System.UriKind.Relative);
 Resources.MergedDictionaries.Add((ResourceDictionary) Application.LoadComponent(uri);
 
 // ... continue initialization
}

Take a look at the MSDN Uri class definition for details as to why this syntax works. The above code is written for an assembly called "MyAssembly.dll", and with a XAML file called Templates.xaml in the root of the project. If you place your loose XAML files in subfolders, add the path after "component" in the Uri. "component" is really just the root of your project.

MergedDictionaries is a handy way of importing and aggregating resources from different definitions into a single Resources object. By loading the XAML into the root component's merged dictionary, you are indirectly registering the DataTemplate into the current logical scope, meaning it will be applied to your instantiated data.

A note concerning Merged Dictionaries and performance. If you have many resources and they are merged into a control that instantiated many times over, be aware that each Merged Dictionary is created once per component - you may want to look into ways of statically organizing your resources. I'll probably be looking at this on my side and will share any advice concerning this in future posts.

Of course, if your root class has a XAML definition, then go ahead and use this simpler notation:

<RootControl x:Class="UserControl"
 xmlns="..."
 xmlns:x="..." >
<RootControl.Resources>
 <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
       <ResourceDictionary Source="Templates.xaml"/>
    </ResourceDictionary.MergedDictionaries>
 </ResourceDictionary>
 </RootControl.Resources>
</RootControl>

And that's that. Hopefully this post manages not only to convey how to load templates via code, but also provides a bit of insight into how WPF does things under the hood.