Data See, Data Do : Xaml

A Custom Storyboard Component in Xaml

MikeHillberg — Fri, 20 Nov 2009 23:19:00 GMT

In WPF & Silverlight, a Storyboard is a collection of animations running in parallel. Not everyone likes the name “Storyboard” though. The idea behind the name was that that list of timelines running in parallel are like a list of plot lines in the plan for a movie.

In any case, just like you can package up a tree of elements into a re-usable UserControl component, it’s nice to be able to package up a tree of timelines into a re-usable Storyboard component. Here’s an approach to do just that, using Xaml, and made simpler by using a new Xaml feature in WPF4.

For example, here’s a Storyboard that puts three animations on a Rectangle:

<Grid>

    <Grid.Resources>
        <BackEase Amplitude="0.5" x:Key="backEase" />
    </Grid.Resources>

    <Grid.Triggers>
        <EventTrigger RoutedEvent="Grid.Loaded">
            <BeginStoryboard>
                <Storyboard TargetName="Rectangle1">
                    <DoubleAnimation Storyboard.TargetProperty="Width"
                                     From="0"
                                     EasingFunction="{StaticResource backEase}"
                                     Duration="0:0:1" />

                    <DoubleAnimation Storyboard.TargetProperty="Height"
                                     From="0"
                                     EasingFunction="{StaticResource backEase}"
                                     Duration="0:0:1" />

                    <ColorAnimation Storyboard.TargetProperty="Fill.Color"
                                    From="LightGray"
                                    Duration="0:0:1" />
                </Storyboard>

            </BeginStoryboard>
        </EventTrigger>
    </Grid.Triggers>

    <Rectangle Name="Rectangle1" Width="100" Height="100" Fill="Red" />

</Grid>

The goal is to package up this Storyboard into a re-usable component that I can use on any Rectangle that has a SolidColorBrush Fill. To do that, I’ll just move that <Storyboard> markup into a separate Xaml file and parameterize it.

Unfortunately there’s no single menu item for this e.g. in Visual Studio, but it’s not hard to do. What I do is right click on the project, “Add”, “User Control”, name it something like “MyRectangleStoryboard.xaml”, and get something like this:

<UserControl x:Class="CustomStoryboard.MyRectangleStoryboard"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >
    <Grid>
            
    </Grid>
</UserControl>

… and this:

public partial class MyRectangleStoryboard : UserControl
{
    public MyRectangleStoryboard()
    {
        InitializeComponent();
    }
}

Now, just change “UserControl” to “Storyboard (and remove the <Grid> from the Xaml), and you’re all set:

<Storyboard x:Class="CustomStoryboard2.MyRectangleStoryboard"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >
    
</Storyboard>

public partial class MyRectangleStoryboard : Storyboard
{
    public MyRectangleStoryboard()
    {
        InitializeComponent();
    }
}

The goal is to use this component instead of the storyboard/animation markup:

<Grid>
    <Grid.Resources>
        <BackEase Amplitude="0.5" x:Key="backEase" />
    </Grid.Resources>

    <Grid.Triggers>
        <EventTrigger RoutedEvent="Grid.Loaded">
            <BeginStoryboard>
                <l:MyRectangleStoryboard TargetName="Rectangle1" Duration="0:0:1" EasingFunction="{StaticResource backEase}"/>
            </BeginStoryboard>
        </EventTrigger>
    </Grid.Triggers>

    <Rectangle Name="Rectangle1" Width="100" Height="100" Fill="Red" />

</Grid>

As for the implementation of the MyRectangleStoryboard here’s the markup, which is cut/paste from the original with a couple of modifications for parameterization (which I’ll explain):

<Storyboard x:Class="CustomStoryboard.MyRectangleStoryboard"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:l="clr-namespace:CustomStoryboard" >

    <DoubleAnimation Storyboard.TargetProperty="Width"
                     From="0"
                     Duration="{Binding Duration, Source={l:XRoot}}"
                     EasingFunction="{Binding EasingFunction, Source={l:XRoot}}" />

    <DoubleAnimation Storyboard.TargetProperty="Height"
                     From="0"
                     Duration="{Binding Duration, Source={l:XRoot}}"
                     EasingFunction="{Binding EasingFunction, Source={l:XRoot}}" />

    <ColorAnimation Storyboard.TargetProperty="Fill.Color"
                    From="LightGray"
                    Duration="{Binding Duration, Source={l:XRoot}}" />

    
</Storyboard>

Notice that this custom storyboard is parameterized for the setting of the Duration and the EasingFunction properties on the animations. (Recall that these two properties were set when the MyRectangleStoryboard was used above).

Ordinarily, if you set the Duration on the storyboard it doesn’t inherit down to its children timelines, instead it clips its children timelines. But I want the MyRectangleStoryboard.Duration to actually be the Double/ColorAnimation.Duration, so I bound the Animation.Duration properties to the root’s Duration property.

The source of this binding is a custom “XRoot” markup extension that I wrote. You could equivalently establish this binding in code, and in fact you pretty much have to today. But in WPF4 (which is now in beta), you can write a custom MarkupExtension to access the root of a Xaml document, using the new IRootObjectProvider service. Here’s the implementation:

public class XRoot : MarkupExtension
{
    public override object ProvideValue(IServiceProvider serviceProvider)
    {
        var rootProvider = serviceProvider.GetService(typeof(IRootObjectProvider)) as IRootObjectProvider;
        if (rootProvider == null)
            return null;

        return rootProvider.RootObject;
    }
}

The other parameterization on this MyRectangleStoryboard component is the EasingFunction. This is a custom property on MyRectangleStoryboard so that I can set it any time I use it. The implementation is just a DependencyProperty:

public partial class MyRectangleStoryboard : Storyboard
{
    public MyRectangleStoryboard()
    {
        InitializeComponent();
    }

    public EasingFunctionBase EasingFunction
    {
        get { return (EasingFunctionBase)GetValue(EasingFunctionProperty); }
        set { SetValue(EasingFunctionProperty, value); }
    }

    public static readonly DependencyProperty EasingFunctionProperty =
        DependencyProperty.Register("EasingFunction", typeof(EasingFunctionBase), typeof(MyRectangleStoryboard));

}

So in the end there’s three takeaways from this:

You can create powerful custom animation sets by subclassing Storyboard.
Xaml is a useful component definition language, it’s not just for controls.
In WPF4, Xaml markup extensions can get explicit access to the lexical root of the Xaml document.

Simple way to create a gradient brush in Xaml

MikeHillberg — Fri, 25 Apr 2008 09:06:00 GMT

Rob, Nikhil & I were talking today about the early days of Xaml when you could create linear gradient brushes as an attribute value. E.g. (borrowing from Rob’s post on this subject) instead of creating a LinearGradientBrush for the fill of a rectangle with this Xaml:

<Rectangle.Fill>

</LinearGradientBrush>

</Rectangle.Fill>

</Rectangle>

… you could write:

<Rectangle Width="300" Height="200"

Fill="HorizontalGradient Blue White" >

</Rectangle>

The up side of the latter syntax obviously is that it’s terser. The drawback is that it’s difficult for a tool to understand it; it has no idea what “HorizontalGradient” means, nor that it has two arguments (nor how those arguments should be interpreted).

For that reason, we created the markup extension primitive for Xaml. A markup extension is any type that derives from MarkupExtension, and it can be specified in an attribute using “squiggle” syntax. The most common markup extension you see in Xaml is the binding extension, e.g.:

So we caution against “mini languages” in Xaml, such as the HorizontalGradient example above, because of the lack of toolability and compile-time validation, and we recommend markup extensions instead.

And so, here’s an example of a definition for such an extension, in this case to create a LinearGradientBrush:

[MarkupExtensionReturnType(typeof(LinearGradientBrush))]

public class LinearGradientBrushExtension : MarkupExtension

{

public LinearGradientBrushExtension()

{

StartColor = EndColor = Colors.White;

}

public LinearGradientBrushExtension( Color startColor, Color endColor, double angle)

{

StartColor = startColor;

EndColor = endColor;

Angle = angle;

}

public Color StartColor { get; set; }

public Color EndColor { get; set; }

public double Angle { get; set; }

public override object ProvideValue(IServiceProvider serviceProvider)

{

return new LinearGradientBrush(StartColor, EndColor, Angle);

}

… which can be used in Xaml like this:

<Rectangle Width="300" Height="200"

Fill="{helper:LinearGradientBrush StartColor=red, EndColor=blue, Angle=0}" />

… or, since the LinearGradientBrushExtension has a convenience constructor for setting the properties, the Xaml can simply be:

<Rectangle Width="300" Height="200"

Fill="{helper:LinearGradientBrush red, blue, 0}" />

Similarly, here’s a markup extension for a RadialGradientBrush:

[MarkupExtensionReturnType(typeof(RadialGradientBrush))]

public class RadialGradientBrushExtension : MarkupExtension

{

public RadialGradientBrushExtension()

{

StartColor = EndColor = Colors.White;

}

public RadialGradientBrushExtension( Color startColor, Color endColor )

{

StartColor = startColor;

EndColor = endColor;

}

public Color StartColor { get; set; }

public Color EndColor { get; set; }

public override object ProvideValue(IServiceProvider serviceProvider)

{

return new RadialGradientBrush(StartColor, EndColor);

}

… which enables this Xaml:

<Rectangle Width="300" Height="200"

Fill="{local:RadialGradientBrush red, blue}" />

Building read-only objects in Xaml

MikeHillberg — Mon, 02 Jul 2007 20:32:00 GMT

We often use Xaml to instantiate and initialize objects. For example, given “<Foo Bar=’1’/>”, a Xaml loader creates a Foo object, and sets the Bar property to 1. That works when the Bar property is settable, but what can you do if it isn’t?

An example of this scenario in .Net today shows up with strings; the String type is immutable, it doesn’t have any settable properties. But sometimes you want to build a string with formats, concatenation, etc. Thus the invention of the StringBuilder class, where the properties have setters (and the methods can mutate an instance).

You can follow the same idea in Xaml by creating builder types, using markup extensions.

Here’s an example of a type whose properties can’t be set except internally, since it has read-only properties:

<Assembly: XmlnsDefinition("http://blogs.msdn.com/mikehillberg/BuilderPattern", "PeopleNamespace")>

Namespace PeopleNamespace

Public Class Person

Private _name As String

Public ReadOnly Property Name() As String

Get

Return _name

End Get

End Property

Private _age As Integer

Public ReadOnly Property Age() As Integer

Get

Return _age

End Get

End Property

Public Shared Function Create(ByVal Name As String, ByVal Age As Integer) As Person

Dim person As New Person

person._name = Name

person._age = Age

Return person

End Function

End Class

End Namespace

(I’m using the XmlnsDefinition assembly attribute here so that I can have a normal-looking Uri in my Xaml, but you can also make references directly to an assembly using the “clr-namespace” syntax, as described here.)

For demonstration, also define a List(Of Person) named “People”:

Namespace PeopleNamespace

Public Class People

Inherits List(Of Person)

End Class

End Namespace

… and then, for example, you can’t load this Xaml, because of the read-only properties:

</People>

(This gives an error of “'Name' property is read-only and cannot be set from markup”).

But we can create a markup extension that follows the builder pattern to create the object.

First, define the markup extension, named PersonExtension. It looks just like the Person type, except it has setters for the properties, and overrides the ProvideValue function:

<Assembly: XmlnsDefinition("http://blogs.msdn.com/mikehillberg/BuilderPatternBuilder", "PeopleBuilderNamespace")>

Namespace PeopleBuilderNamespace

Public Class PersonExtension

Inherits MarkupExtension

Private _name As String

Public Property Name() As String

Get

Return _name

End Get

Set(ByVal value As String)

_name = value

End Set

End Property

Private _age As Integer

Public Property Age() As Integer

Get

Return _age

End Get

Set(ByVal value As Integer)

_age = value

End Set

End Property

Public Overrides Function ProvideValue(ByVal serviceProvider As IServiceProvider) As Object

Return Person.Create(Name, Age)

End Function

End Class

End Namespace

And now we can modify the markup slightly so that it successfully loads:

<People

xmlns="http://blogs.msdn.com/mikehillberg/BuilderPattern"

xmlns:builder="http://blogs.msdn.com/mikehillberg/BuilderPatternBuilder" >

<builder:Person Name='Mike' Age='5' />

<builder:Person Name='Dwayne' Age='7' />

</People>

To test it out, run this code:

Sub Main()

Dim people As People

people = XamlReader.Load(File.Open("..\..\Test.xaml", FileMode.Open))

For Each person As Person In people

Console.WriteLine("Name = " + person.Name + ", Age = " + person.Age.ToString())

End Sub

… and we get this output:

Name = Mike, Age = 5

Name = Dwayne, Age = 7

One last note about markup extensions … Notice that I named the builder class “PersonExtension”, but I referred to it from Xaml as “Person”. That’s possible because when Xaml doesn’t find “Person”, it automatically appends the “Extension” suffix, and looks for “PersonExtension”. If Person and PersonExtension had been in the same Clr namespace, that would have caused confusion, so I put them in different namespaces (“PeopleNamespace” and “PeopleBuilderNamespace”). Alternatively, I could have put them both in the “PeopleNamespace”, and used the specific <PersonExtension> tag (or maybe I would have named it “PersonBuilder”).

Namespaces in Xaml

MikeHillberg — Wed, 16 May 2007 19:51:00 GMT

If you’re really into Xml conformance, and you’ve really wondered how Xaml uses Xml namespaces, read on; I can cover the most relevant details in 1160 words or less …

Namespaces on tags

(I’m using the term “tag” here instead of the more correct term “element”, so that I don’t get confused with WPF element objects.)

In the W3C Namespaces for XML recommendation, it’s valid for a tag not to be in any namespace; to have no “namespace name”. In Xaml, it’s not. Or rather it’s mostly not; it’s OK if the XML is hiding in a CData section, or in an XData section such as:

<Page

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Page.DataContext>

<x:XData>

</BookList>

</x:XData>

</XmlDataProvider>

</Page.DataContext>

<ListBox.ItemTemplate>

</DataTemplate>

</ListBox.ItemTemplate>

</ListBox>

</Page>

... But generally tags must be in a namespace. That because, when Xaml is mapping tags to types, it needs to identify and locate the exact Type. There’s two ways this mapping is done. The really obvious way is for the namespace name URI to use the “clr-namespace” scheme. In this case, the CLR namespace and assembly of the type are specified in the Xaml, such as in the following mappings to the mscorlib.dll assembly for the System.String and System.Collections.ArrayList types:

<Page

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

xmlns:sys="clr-namespace:System;assembly=mscorlib"

xmlns:collections="clr-namespace:System.Collections;assembly=mscorlib" >

<Page.DataContext>

<collections:ArrayList>

<sys:String>Hello</sys:String>

<sys:String>World</sys:String>

</collections:ArrayList>

</Page.DataContext>

</Page>

The other way to map tags to types is to match up the namespace name with an assembly that has a corresponding [XmlnsDefinition] assembly attribute. For example, in another post, I put the XmlnsDefinition attribute in my code like this:

[assembly: System.Windows.Markup.XmlnsDefinition(

"http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx",

"EmployeeDatabase")]

namespace EmployeeDatabase

{

public class Employee

{

private AddressInformation _contactInformation;

public AddressInformation ContactInformation

{

get { return _contactInformation; }

set { _contactInformation = value; }

}

...

… and then I referenced that type by using the matching namespace name in my markup:

<Employee Name="Rob" Title="President"

xmlns="http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx">

<Employee.ContactInformation>

</Employee.ContactInformation>

...

Namespaces on other type references

More generally than just tags, anywhere in Xaml where a string refers to a type, it’s interpreted in the same way. Specifically, any value that references a Type is treated as a QName. A QName is a name that may or may not have a namespace prefix on it. If a QName doesn’t have a prefix, it’s usually interpreted to have the default namespace name. (If an attribute name doesn’t have a prefix it’s not in the default namespace, but more on that later.)

For example, in the following markup, the x:Static markup extension refers to a Class.Property value, so it interprets ‘SystemColors’ (the Class) to be in the default namespace:

<Page

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Button Background='{x:Static SystemColors.ControlBrush}'>Click</Button>

</Page>

Or, using a non-default namespace, you can have the equivalent:

<wpf:Page

xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<wpf:Button Background='{x:Static wpf:SystemColors.ControlBrush}'>Click</wpf:Button>

</wpf:Page>

Unprefixed attribute names

Attributes are a bit more interesting and non-obvious than tags or other QNames.

Whereas for tags, an unprefixed tag name is interpreted to be in the default namespace, unprefixed attributes are by definition not in any namespace. The first time I encountered that was when I was watching some XML get parsed by XmlReader. When an unprefixed attribute went by, the NamespaceURI property of the reader was null. I thought it was a bug. But it actually makes sense if you think about this example:

</RandomThings>

Here you have two unprefixed attributes named “State”, but they have different semantics, and more importantly they have distinct sets of valid values: one has to be either liquid, solid, or gas; the other has to be CA, WA, NY, MI, FL, OH, etc. So while the Molecule and Address tags both have the same namespace name (“http://blogs.msdn.com/mikehillberg/NamespacesInXaml”), it wouldn’t make sense to consider the two State attributes to be in the same namespace. And that’s why in the XML namespaces recommendation the State attributes have no namespace name; “interpretation of unprefixed attributes is determined by the element on which they appear”.

And when you think about Xaml being used to map XML to types and properties, that makes even more sense. That’s because you encounter the same rules in a class definition; two different classes can have properties with the same name that have different semantics and types. (A “Molecule” class and an “Address” class could both have un-related “State” properties.)

Thus in this example there’s no namespace prefix on the Background attribute, but we know it references the Button.Background property:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">

<wpf:Button Background='Red'>Click</wpf:Button>

</wpf:Page>

That’s a “standard” property, though. “Attached” properties are more interesting. For example, in the following, Canvas.Top is an attached property; it’s defined by Canvas, not by Button, despite being set on the Button tag:

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Button Canvas.Top='100'>Click</Button>

</Canvas>

</Page>

Since ‘Canvas’ is a reference to a type, it's expanded name uses the default namespace when no prefix is specified. Therefore in this case it has the default namespace name (“http://schemas.microsoft.com/winfx/2006/xaml/presentation”). Or, to make everything explicit again:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<wpf:Canvas>

<wpf:Button wpf:Canvas.Top='100' >Click</wpf:Button>

</wpf:Canvas>

</wpf:Page>

Prefixed attribute names

If you do put a prefix on an attribute for a standard property, and it maps to the same namespace name, then it behaves functionally equivalent to the attribute without the prefix. For example, this markup:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">

<wpf:Button Background='Red'>Click</wpf:Button>

</wpf:Page>

… is different only in syntax (not function) from this markup, where the Background attribute now has a prefix:

<wpf:Page xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">

<wpf:Button wpf:Background='Red'>Click</wpf:Button>

</wpf:Page>

You can even give the attribute a different prefix, as long as it has the same namespace name (the URI):

<wpf:Page

xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:wpf2="http://schemas.microsoft.com/winfx/2006/xaml/presentation" >

<wpf:Button wpf2:Background='Red'>Click</wpf:Button>

</wpf:Page>

… But if the namespace names are different, you’ll get an error:

<wpf:Page

xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:wpf2="SomethingElse" >

<wpf:Button wpf2:Background='Red'>Click</wpf:Button>

</wpf:Page>

For attached properties, as noted above, the class part of an attached property attribute name is interpreted as a QName, and so the prefix is used to determine the namespace name. The namespace name of the tag is irrelevant.

Built-in Xaml attributes

Finally, in Xaml there are a few built-in attributes: Key, Name, and Uid. For example, Key is used to provide the key for a dictionary item, such as the ‘myBrush’ here (Page.Resources is a dictionary):

<Page

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >

<Page.Resources>

</Page.Resources>

</Page>

These attributes are global and always must have a prefix. For example, if you modify that example so that ‘x:’ is now the default namespace name, the example becomes invalid:

<wpf:Page

xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml" >

<wpf:Page.Resources>

<wpf:SolidColorBrush Key='myBrush'>Red</wpf:SolidColorBrush>

</wpf:Page.Resources>

<wpf:Rectangle Width='100' Height='100' Fill='{wpf:StaticResource myBrush}' />

</wpf:Page>

… This is invalid because Key is an unprefixed attribute, so it’s interpreted to be a standard property on SolidColorBrush, rather than being interpreted as in the default namespace (and there is no SolidColorBrush.Key property).

One last thing

One last place where Xaml uses XML namespaces is in the Markup Compatibility feature. But this post is already long enough. See Rob’s blog or MSDN for interesting reading.

Expandos in xaml

MikeHillberg — Tue, 15 May 2007 03:36:00 GMT

This post has a couple of suggestions on ways to accomplish expandos in Xaml. First some background …

On an HTML page you can define your own new “expando” properties on the fly, such as in this example:

<HTML>

</BODY>

</HTML>

Here I invented a new property named ‘testing’. I can both set that property and get it (the two parts in yellow above).

That’s a good feature when you want it. It’s a frustrating feature when you don’t. For example, in the following markup, I misspelled the “bgcolor” attribute. I’d like to be told that this is invalid, but instead it’s assumed to simply be an expando property.

<HTML>

<P>Hello</P>

</BODY>

</HTML>

It’s for this reason that the Xaml language is strongly-typed. E.g. the following is a compile/load error (the “BGround” should be “Background”):

<TextBlock BGround='Red'>Hello</TextBlock>

But then if you do want an expando, how do you do it?

One way is to actually define the properties you want to use, as attached properties. For example, this markup uses the ‘MyProperties.Testing’ attached property to set a property onto an unsuspecting TextBlock:

<Window x:Class="WPFApplication1.Window1"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:local="clr-namespace:MyNamespace" >

<TextBlock local:MyProperties.Testing='1, 2, 3' >Hello</TextBlock>

</Window>

.. where the code for MyProperties looks like this:

namespace MyNamespace

{

public static class MyProperties

{

public static string GetTesting(FrameworkElement obj)

{

return (string)obj.GetValue(TestingProperty);

}

public static void SetTesting(FrameworkElement obj, string value)

{

obj.SetValue(TestingProperty, value);

}

// Using a DependencyProperty as the backing store for Testing. This enables animation, styling, binding, etc...

public static readonly DependencyProperty TestingProperty =

DependencyProperty.RegisterAttached("Testing", typeof(string), typeof(MyProperties) );

}

If you don’t want to write any code, you can do it all in markup, though it takes more markup than the HTML case.

First of all, recognize that expandos are really just a property bag of key/value pairs. So in the first HTML example above the P element has a dictionary item that maps the key “testing” to the value ”1,2,3”. In WPF you can get a real dictionary using the built-in Hashtable class. (You can’t use the Dictionary<K,T> class, because Generics aren’t supported in Xaml.) There’s also a Tag property on all elements to hold your random data. Put those two together and you can do something like the following:

<Page

xmlns='http://schemas.microsoft.com/winfx/2006/xaml/presentation'

xmlns:x='http://schemas.microsoft.com/winfx/2006/xaml'

xmlns:col='clr-namespace:System.Collections;assembly=mscorlib.dll'

xmlns:sys='clr-namespace:System;assembly=mscorlib'

Name='Page1' >

<Page.Tag>

<col:Hashtable>

<sys:String x:Key='testing'>1, 2, 3</sys:String>

<sys:String x:Key='anotherOne'>foo</sys:String>

<sys:String x:Key='yetAnotherOne'>bar</sys:String>

</col:Hashtable>

</Page.Tag>

<!-- This TextBlock.Text Binding queries a property out

of the dictionary -->

</Page>

Update: Another common use of expando properties is to “comment out” an attribute, since XML doesn’t provide a built-in means to do so. I was just reading an old post on Chuck’s blog, and he shows there a way to do this in Xaml by using the markup compatibility feature.

Tip: Using XamlWriter and XamlReader to clone an object

MikeHillberg — Tue, 01 May 2007 23:35:00 GMT

There are multiple ways to clone objects, and multiple definitions of what “clone” should even mean.

The main issue is usually about cloning “deep” vs. “shallow”. For example, if you have a Customer object that points to an Address object, and you clone the Customer object, does the Address object get cloned too (this would be a deep clone)? Or does the new Customer reference the original Address object (a shallow clone)?

Another issue is whether you clone just the properties of the object, or the fields instead. And do you clone event listeners?

Yet another issue is that you might clone a property value on the object that is supposed to be unique, such as the Name property on WPF elements.

Anyway, here’s a trick to clone an object by writing it out to Xaml then reading it back in. As such, the cloning rules it follows matches the Xaml serialization rules (see here for some more info). That primarily means that it only clones public properties – no fields or events – and it clones deep.

So here’s what the code might look like:

private Object CloneUsingXaml(Object o)

{

string xaml = XamlWriter.Save(o);

return XamlReader.Load(new XmlTextReader(new StringReader(xaml)));

}

(XamlReader.Load doesn’t have an overload that takes a string, so you need to convert the string into an XmlReader.)

Here’s an example. Take this app:

<Window x:Class="WPFApplication1.Window1"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

Title="Window1" Height="300" Width="300" Loaded='OnLoaded'>

<Grid.ColumnDefinitions>

</Grid.ColumnDefinitions>

</Grid>

</Window>

… and clone the Rectangle during load with:

private void OnLoaded(object sender, RoutedEventArgs args)

{

Rectangle rectangle2 = CloneUsingXaml(_rectangle1) as Rectangle;

rectangle2.Name = null;

Grid.SetColumn(rectangle2, 1);

Grid1.Children.Add(rectangle2);

}

… and you get a Window with two rectangles.

Here’s what the intermediate Xaml looks like:

<Rectangle

Fill="#FFFF0000"

Name="_rectangle1"

Width="20" Height="20"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" />

Note here that the Name property got cloned, which isn’t what we want, so I removed the Name after running the clone.

Limited generics support in Xaml

MikeHillberg — Fri, 06 Oct 2006 16:04:00 GMT

In a post to the WPF forum, Zhou Yong had the idea to use a MarkupExtension to make it possible to create a generic dictionary (Dictionary<K,V>) from Xaml. It’s a cool idea, so I played with it a bit, with the result shown below. The end result is that you can do the following, for example, where a ListBox is bound to a Collection<String>:

<ListBox.ItemsSource>

<generic:CollectionOfT TypeArgument="sys:String">

<sys:String>Hello</sys:String>

<sys:String>World</sys:String>

</generic:CollectionOfT>

</ListBox.ItemsSource>

</ListBox>

… or the following, where a MyGenericType<string, int> is instantiated:

<x:Type TypeName="sys:String" />

<x:Type TypeName="sys:Int32" />

</Generic>

But First, Some Background on Generics support in Xaml

For the most part, Xaml does not support generics. The one exception to that is that generics are supported on the root tag of your Xaml, if you’re compiling the Xaml. (Therefore, for example, it’s not supported if you’re loading Xaml directly into Internet Explorer.) Here’s an example of where a generic type is supported:

<PageFunction

x:Class="CSharp.MyPageFunction"

xmlns:sys="clr-namespace:System;assembly=mscorlib"

x:TypeArguments="sys:String"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

Title="VanillaPageFunction"

<Grid>

</Grid>

</PageFunction>

… where PageFunction is defined as:

public class PageFunction<T> : PageFunctionBase

Note that the x:TypeArguments attribute is how you specify type arguments to the generic type in Xaml. So that Xaml is equivalent to:

public partial class MyPageFunction : PageFunction<String>

{

public MyPageFunction()

{

...

}

...

}

A Helper To Create Collection<T> in Xaml

But working with Zhou’s approach of using markup extensions, here’s a markup extensions that helps with the case of a really common generic type: Collection<T> What we’ll end up with is a <CollectionOfT> markup extension.

First, here’s a base class that provides some common functionality (we’ll be using this again later for List<T>, etc.):

// MarkupExtension that is base for an extension that creates

// Collection<T>, List<T>, or Dictionary<T>.

// (CollectionType is either IList or IDictionary).

public abstract class CollectionOfTExtensionBase<CollectionType> : MarkupExtension

where CollectionType : class

{

public CollectionOfTExtensionBase(Type typeArgument)

{

_typeArgument = typeArgument;

}

// Default the collection to typeof(Object)

public CollectionOfTExtensionBase()

: this(typeof(Object))

{

}

// Items is the actual collection we'll return from ProvideValue.

protected CollectionType _items;

public CollectionType Items

{

get

{

if (_items == null)

{

Type collectionType = GetCollectionType(TypeArgument);

_items = Activator.CreateInstance(collectionType) as CollectionType;

}

return _items;

}

// TypeArgument is the "T" in e.g. Collection<T>

private Type _typeArgument;

public Type TypeArgument

{

get { return _typeArgument; }

set

{

_typeArgument = value;

// If the TypeArgument doesn't get set until after

// items have been added, we need to re-create items

// to be the right type.

if (_items != null)

{

object oldItems = _items;

_items = null;

CopyItems(oldItems);

}

// Default implementation of CopyItems that works for Collection/List

// (but not Dictionary).

protected virtual void CopyItems( object oldItems)

{

IList oldItemsAsList = oldItems as IList;

IList newItemsAsList = Items as IList;

for (int i = 0; i < oldItemsAsList.Count; i++)

{

newItemsAsList.Add(oldItemsAsList[i]);

}

// Get the generic type, e.g. typeof(Collection<>), aka Collection`1.

protected abstract Type GetCollectionType(Type typeArgument);

// Provide the collection instance.

public override object ProvideValue(IServiceProvider serviceProvider)

{

return _items;

}

With that base class in place, here’s the implementation of the CollectionOfT markup extension:

// MarkupExtension that creates a Collection<T>

[ContentProperty("Items")]

public class CollectionOfTExtension : CollectionOfTExtensionBase<IList>

{

protected override Type GetCollectionType(Type typeArgument)

{

return typeof(Collection<>).MakeGenericType(typeArgument);

}

And again, here’s that markup extension in action:

<generic:CollectionOfT TypeArgument="sys:String">

<sys:String>Hello</sys:String>

<sys:String>World</sys:String>

</generic:CollectionOfT>

A Helper to create List<T>, ObservableCollection<T> in Xaml

Similarly, here are ListOfT and ObservableCollectionOfT markup extensions for creating List<T> and ObservableCollection<T>:

// MarkupExtension that creates a List<T>

[ContentProperty("Items")]

public class ListOfTExtension : CollectionOfTExtensionBase<IList>

{

protected override Type GetCollectionType( Type typeArgument )

{

return typeof(List<>).MakeGenericType(typeArgument);

}

// MarkupExtension that creates an ObservableCollection<T>

[ContentProperty("Items")]

public class ObservableCollectionOfTExtension : CollectionOfTExtensionBase<IList>

{

protected override Type GetCollectionType(Type typeArgument)

{

return typeof(ObservableCollection<>).MakeGenericType(typeArgument);

}

A Helper to create Dictionary<T> in Xaml

Dictionary<K,V> is all that’s left to do. But Dictionary is a bit more complicated, because it has two type arguments, one for the key type and one for the value type. And there I cheated a little; I only put in support for the value type argument, and left the key type as always Object.

// MarkupExtension that creates an Dictionary<Object,T>

// (Items cannot be the [ContentProperty]).

public class DictionaryOfTExtension : CollectionOfTExtensionBase<IDictionary>

{

protected override Type GetCollectionType(Type typeArgument)

{

return typeof(Dictionary<,>).MakeGenericType(typeof(Object), typeArgument);

}

protected virtual void CopyItems(IDictionary oldItems)

{

IDictionary oldItemsAsDictionary = oldItems as IDictionary;

IDictionary newItemsAsDictionary = Items as IDictionary;

foreach( DictionaryEntry entry in oldItemsAsDictionary )

{

newItemsAsDictionary[entry.Key] = oldItemsAsDictionary[entry.Key];

}

The other complication with Dictionary is that the Items property can’t be the [ContentProperty]. So when you use it in Xaml, you have to specify the explicit <DictionaryOfT.Items> tag. So usage ends up looking like:

<generic:DictionaryOfT TypeArgument="sys:String">

<generic:DictionaryOfT.Items>

<sys:String x:Key="String1">Hello</sys:String>

<sys:String x:Key="String2">World</sys:String>

</generic:DictionaryOfT.Items>

</generic:DictionaryOfT>

A Helper to Create Other Generic Types

Finally, this is a more general extension, that can create any generic type. For example, given this class:

public class MyGenericClass<T1,T2>

{

private T1 _prop1;

public T1 Prop1

{

get { return _prop1; }

set { _prop1 = value; }

}

private T2 _prop2;

public T2 Prop2

{

get { return _prop2; }

set { _prop2 = value; }

}

… and this “Generic” markup extension:

// Markup extension that creates an object from a constructed generic type.

[ContentProperty("TypeArguments")]

public class GenericExtension : MarkupExtension

{

// The collection of type arguments for the generic type

private Collection<Type> _typeArguments = new Collection<Type>();

public Collection<Type> TypeArguments

{

get { return _typeArguments; }

}

// The generic type name (e.g. Dictionary, for the Dictionary<K,V> case)

private string _typeName;

public string TypeName

{

get { return _typeName; }

set { _typeName = value; }

}

// Constructors

public GenericExtension()

{

}

public GenericExtension(string typeName )

{

TypeName = typeName;

}

// ProvideValue, which returns an object instance of the constructed generic type

public override object ProvideValue(IServiceProvider serviceProvider)

{

IXamlTypeResolver xamlTypeResolver = serviceProvider.GetService(typeof(IXamlTypeResolver)) as IXamlTypeResolver;

if (xamlTypeResolver == null)

throw new Exception("The Generic markup extension requires an IXamlTypeResolver service provider");

// Get e.g. "Collection`1" type

Type genericType = xamlTypeResolver.Resolve(

_typeName + "`" + TypeArguments.Count.ToString() );

// Get an array of the type arguments

Type[] typeArgumentArray = new Type[ TypeArguments.Count ];

TypeArguments.CopyTo(typeArgumentArray, 0);

// Create the conrete type, e.g. Collection<String>

Type constructedType = genericType.MakeGenericType(typeArgumentArray);

// Create an instance of that type

return Activator.CreateInstance(constructedType);

}

... you can create an instance of MyGenericClass, such as MyGenericClass<string,int>, from Xaml with something like:

<generic:Generic TypeName="local:MyGenericClass" >

<x:Type TypeName="sys:String" />

<x:Type TypeName="sys:Int32" />

</generic:Generic>

Xaml Inspired Markup

MikeHillberg — Thu, 28 Sep 2006 04:16:00 GMT

A lot has been written about how Xaml maps tags and attributes to objects and properties. (Here’s a standard Xaml overview.) But it’s not necessary that Xaml actually be used to create .Net objects. For example, XPS is markup that can be treated like Xaml and used to create/initialize objects, but it can also be interpreted according to the definition of the markup, without creating any objects. For example, with this Xaml:

You could call XamlReader.Load to get a System.Windows.Shapes.Path object created (with its Data, Stroke, etc. properties initialized). Or you could interpret this directly according to the XPS specification and put ink on paper.

Along the same lines, Xaml defines some syntax conventions that you could apply most any time you’re defining a new Xml schema. Maybe you don’t plan to for your markup to be mapped to objects, at least not today. But if you already work with Xaml, following the same conventions for your other markup provides some nice consistency and readability, and a possible future path to intuitive code manipulation.

As a thought experiment, I tried this out on the document property format that Office 2007 uses to store the document’s title, subject, description, etc. Here’s an example of what that format looks like:

<cp:coreProperties xmlns:cp=

"http://schemas.openxmlformats.org/package/2006/metadata/core-properties"

xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/"

xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance">

<dc:title>The Onomonopia.Net Programming Language</dc:title>

<dc:subject> How to write code that does what it sounds like</dc:subject>

<dc:creator> Ima D. Veloper </dc:creator>

<cp:keywords></cp:keywords>

<dc:description></dc:description>

<cp:lastModifiedBy> </cp:lastModifiedBy>

<cp:revision>2</cp:revision>

<dcterms:created xsi:type="dcterms:W3CDTF">2006-05-03T01:13:00Z</dcterms:created>

<dcterms:modified xsi:type="dcterms:W3CDTF">2006-05-03T01:14:00Z</dcterms:modified>

</cp:coreProperties>

There’s good reason that this markup isn’t in a Xaml syntax, but this is easy markup to relate to, and just an experiment. So if I were approaching this problem from a code/Xaml point of view, and without this existing precedent (or the Dublin Core schema in use here), I might come up with a class implementation that looked like this:

public class CoreProperties

{

private string _title;

public string Title

{

get { return _title; }

set { _title = value; }

}

private string _subject;

public string Subject

{

get { return _subject; }

set { _subject = value; }

}

private string _description;

public string Description

{

get { return _description; }

set { _description = value; }

}

private DateTime _created;

public DateTime Created

{

get { return _created; }

set { _created = value; }

}

...

}

And the usage of this might look like:

<CoreProperties xmlns="" "http://schemas.openxmlformats.org/package/2006/metadata/core-properties"

Title="The Onomonopia.Net Programming Language"

Subject="How to write code that does what it sounds like"

Author="Ima D. Veloper"

... />

That’s an interesting experiment, but not really be-all-that-you-can-be interesting. Now let’s try something more illustrative, the classic <Employee> markup, and use it to suggest some general guidelines.

Of course the easiest way to define your markup schema in a Xaml-compatible way is to define classes first, like I did with CoreProperties above. But since this is all about Xaml-inspired markup that doesn’t necessarily have code backing it, and to make it more fun, I’ll try to do it without using the word “code” or any code concepts [oops, I said “code” already].

“Things” are tags, simple relationships are attributes

Xml markups tend to follow the guideline that nouns are tags, and adjectives are attributes. In code [doh!], classes and properties tend to be the same way. A little bit more generally, objects are tags, and attributes are relationships that map two objects. That is, the attribute name is a relationship that maps the tag object to the attribute value object.

So obviously our Employee is going to be a tag:

Off to a good start already. And a lot of information about the employee can be represented as relationships to simple objects, such as date-of-birth, title, salary, etc, such as:

Relationships to complex objects are markup

You might want all of the employee’s address information to be in its own tag, call it <AddressInformation>. That might be better for readability, or so that you could share the same schema information with your <Customer> schema, etc. Since this can’t be represented as an attribute any more, we can’t use an attribute to describe the relationship, so we use Xaml’s property element syntax. In this syntax, we use a <Parent.Relationship> tag to relate a parent object to the referent object. So in

<Employee.ContactInformation>

</Employee.ContactInformation>

</Employee>

… The employee has a “ContactInformation” relationship to an AddressInformation object.

Relationships can be to individual objects or lists

The above showed a relationship to a single object (employee to address). Let’s promote the employee to a manager by adding a relationship to a list of other employee objects.

<Employee.DirectReports>

...

</Employee.DirectReports>

</Employee>

Looking at these last two examples, you might think that the <Employee.ContactInformation> and <Employee.DirectReports> tags seems redundant. For example you could guess what the <AddressInformation> is for without the explicit ContactInformation relationship. And in fact we used to allow this kind of domain-specific implicit relationship in Xaml. But other relationships are more ambiguous, and implicit relationships are more difficult for tools to reason about, which is why Xaml now almost always requires the property element syntax. That “almost” part, though, is because …

For one relationship, you can skip the property element tag

In Xaml content syntax you can have one relationship that is considered the default, to which Xml content (other than property element tags) is associated. Let’s use that for the “DirectReports” relationship. That way, while the above markup with direct reports is valid, it can be simplified by removing the <Employee.DirectReports> tag:

...

</Employee>

Follow naming conventions in the .Net Design Guidelines

This last guideline for Xaml-inspired markup, to follow the .Net Design Guidelines, isn’t a strict part of the Xaml specification. If you haven’t seen them before, the .Net Design Guidelines describe a lot of conventions for writing code [that “code” doesn’t count]. There’s exceptions to every rule, but generally the .Net framework follows these guidelines from end to end. The rules in there about naming conventions apply equally well to a pure markup problem we’re discussing here, and the consistency of following those guidelines is nice.

As I said, there are a lot of guidelines in that document, but I think the most important/relevant ones here can be reduced to the following:

Use capital letters

For example <Employee>, not <employee>. (This is “pascal casing”.)

Use words, not abbreviations

For example “Address” not “Addr”. And watch out for typos that you replicate all over your markup accidentally with copy/paste.

Use plural names for lists

For example “DirectReports” for the list of, er, direct reports.

Make names sounds like you would say it

For example “Employee.HasDependents” reads nicer than “Employee.Dependents”. (The latter also sounds like a list.)

Don’t create complex attribute values

For example, you could create a “mini-language”, as we call it, for the address information, where you use hyphens to recognize the phone number, semi-colons to separate the address from the phone numbers, parenthesis to distinguish the cell phone from the office phone, etc. It might look concise and elegant, but it’s difficult to remember how to write it, and difficult for an XML schema or other tool to define it. Simple attributes, like numbers, strings, or things you’d put in an enum [doh!] are great.

Use consistent attribute value syntax

.Net already defines attribute value syntax for a lot of types. That includes obvious types such as integers, reals, etc. That also includes a few more complex types, such as dates and time spans. Whenever possible, use a syntax that already exists somewhere.

And so with all that in place, here’s what our company hierarchy might look like:

<Employee Name="Rob" Title="President"

xmlns="http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx">

<Employee.ContactInformation>

</Employee.ContactInformation>

<Employee.ContactInformation>

</Employee.ContactInformation>

<Employee.ContactInformation>

</Employee.ContactInformation>

</Employee>

<Employee.ContactInformation>

</Employee.ContactInformation>

</Employee>

… And here’s what a representation of this markup might look like in code:

using System;

using System.Collections.Generic;

using System.Text;

using System.Globalization;

[assembly: System.Windows.Markup.XmlnsDefinition(

"http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx",

"EmployeeDatabase")]

namespace EmployeeDatabase

{

public class AddressInformation

{

private string _officePhone;

public string OfficePhone

{

get { return _officePhone; }

set { _officePhone = value; }

}

private string _cellPhone;

public string CellPhone

{

get { return _cellPhone; }

set { _cellPhone = value; }

}

private Uri _blog;

public Uri Blog

{

get { return _blog; }

set { _blog = value; }

}

// ...

}

[System.Windows.Markup.ContentProperty("DirectReports")]

public class Employee

{

private AddressInformation _contactInformation;

public AddressInformation ContactInformation

{

get { return _contactInformation; }

set { _contactInformation = value; }

}

private List<Employee> _directReports = new List<Employee>(0);

public List<Employee> DirectReports

{

get { return _directReports; }

}

private string _name;

public string Name

{

get { return _name; }

set { _name = value; }

}

private string _title;

public string Title

{

get { return _title; }

set { _title = value; }

}

// ...

}

… And for fun, here’s that same Employee markup with a data template mapping it to a tree view (I stole the HandleRequestNavigate code for the hyperlink from Lauren):

<Window x:Class="Scratch.Window1"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

xmlns:EmployeeDatabase="http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx"

Title="Org Structure"

<Window.Resources>

</WrapPanel>

</WrapPanel>

</WrapPanel>

</Hyperlink>

</TextBlock>

</WrapPanel>

</StackPanel>

</HierarchicalDataTemplate>

</Window.Resources>

<TreeView.Background>

</LinearGradientBrush>

</TreeView.Background>

<Employee Name="Rob" Title="President"

xmlns="http://blogs.msdn.com/mikehillberg/archive/2006/09/27/XamlInspiredMarkup.aspx">

<Employee.ContactInformation>

</Employee.ContactInformation>

<Employee.ContactInformation>

</Employee.ContactInformation>

<Employee.ContactInformation>

</Employee.ContactInformation>

</Employee>

<Employee.ContactInformation>

</Employee.ContactInformation>

</Employee>

</TreeView>

</Window>

When you build & run this, it looks like:

Being written by XamlWriter

MikeHillberg — Sat, 16 Sep 2006 10:41:00 GMT

A big part of WPF (Avalon) is the Xaml format for creating object trees. You can also go in the other direction – take an object tree and write it out to Xaml – with the XamlWriter class.

It’s frequently easy for XamlWriter to convert an object into a good Xaml representation. Sometimes, though, it’s harder to get right, because you can’t always tell how to write an object to Xaml just by looking at its properties. So when you’re creating a new class, there’s a few things you can do to help out. And when you do that, not only are you making your class work better in XamlWriter, you’re making your class work better in designer tools, such as Expression Interactive Designer (Sparkle) and Visual Studio’s Cider, since they use the same information.

The things you can do to your class to help XamlWriter is that the rest of this article is about …

What is XamlWriter?

XamlWriter is a class that lets you create Xaml from objects. That's easiest to explain with an example. This example uses WPF (Avalon) types, but none of this is specific to WPF; you can use XamlWriter and XamlReader for any managed types, such as those created in C#, VB.Net, etc.

Say we have this code snippet:

Button button = new Button();

button.Width = 100.0;

button.Background = KnownColors.Red;

… now write it to Xaml like this:

xamlString = XamlWriter.Save( button );

Console.WriteLine( xamlString );

… and you get this:

<Button xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

Width="100"

Background="Red"/>

The long xmlns Uri is used to map the tags to the assemblies. It's useful, but a bit distracting here, so I'll leave it out from here forward. Thus it's simply:

Pretty simple -- write the object's type as a tag, and its property as an attribute.

KnownColors.Red in this example is a simple SolidColorBrush, which is easy to represent as an attribute. But a LinearGradientBrush is more difficult – that's going to require some further XML. For example:

<Button.Background>

...

</LinearGradientBrush>

</Button.Background>

</Button>

In this case we used Xaml's property element syntax; the dot in the Button.Background tag indicates that the content of that tag is actually a value for the Background property, a LinearGradientBrush in this case.

So that shows XamlWriter in a nutshell – the Save method takes objects and turns them into Xaml. The basic algorithm is to write an object's type name as the tag, and then write the object's property values as either attributes (if they're simple properties) or nested markup under a property element tag.

By the way, if you've looked at Xaml much already, you probably already know that sometimes the property element tag gets left out. For example, for Grid, the Children property is its content property, So this

<Grid>

<Grid.Children>

</Grid.Children>

</Grid>

… can be simplified to this:

<Grid>

</Grid>

That's basic Xaml syntax (based on the [ContentProperty] attribute), but the point here is that XamlWriter understands it, and will write the simpler syntax when possible.

What to expect from XamlWriter, and what not to expect

The basic algorithm above is pretty simple, but there are things that can't be written, at least not without some help. This is mostly due to the fact that not all classes can be represented in Xaml. For example, Xaml can't (for the most part) represent types unless they have a default constructor, and so XamlWriter won't write such a type either. As another example, Xaml can't natively represent graphs of objects. For example, if two objects are being written and they reference a shared object, the shared object will be written twice.

Other limitations:

· Fields
Only properties are written, not fields.

· Read-only properties
That is, a property with a setter but not a getter. The motivation for this is that there is no point in writing the property if it's invalid Xaml, and read-only properties can be set from Xaml. This can be overridden, though, with the [DesignerSerializationVisibility] attribute described below.

· Internal/private properties
Only public properties are written

· Internal/private classes
Similarly, only public classes are written. Actually, an attempt to write a non-public class causes an exception to be thrown.

· Event listeners
For example if you have a listener attached to a Button.Click event, you won't get <Button Click="OnClick"/>, the Click handler will be dropped.

Finally, if you read Xaml with XamlReader, then write it with XamlWriter, you won't get the exact same XML. For example, no attempt is made to preserve the formatting of the original Xaml. As another example, some markup extensions, such as {x:Static}, are resolved at load-time by XamlReader and the markup extension itself is discarded, so there is no means for XamlWriter to re-produce it.

Which properties to write?

So an object gets written as a tag, and properties get written as either an attribute or a property element tag. For the most part, you don't do anything, and the right properties get written. But maybe not, in which case you can do some work in the class definition to take more control. There are several different options …

Not writing the default value

In general, if a property is its default value, it would be redundant to write it out. A type author (i.e. someone defining a class or struct) can let XamlWriter know the default value of a property using the [DefalutValue] attribute. For example, in the following, MyProperty won't get written out on a MyClass object if its value is zero:

class MyClass

{

[DefaultValue(0)]

public int MyProperty

{

get … set …

}

This rule is slightly different, though, if the property is backed by a DependencyProperty. In that case, the property is only written if it is actually set. For example, the following button is getting its Background property set not on the button itself, but from the button’s style:

<Window.Resources>

</Style>

</Window.Resources>

<Button Name="button1">Click</Button>

</Window>

So in this example, if you call button1.Background from code, you'll get a red brush. But if you write it with XamlWriter, you'll only get:

<Button Name="button1">Click</Button>

Writing read-only properties

There's usually no point in writing to Xaml the value of a read-only property, because it won't be possible to load it back from the Xaml, since Xaml can't set read-only properties. There is one case, however, where Xaml can set to a read-only property, and that's with collection type properties. In that case, it’s not setting the property itself, but adding to the collection. For example, the Grid.Children property is read-only, but you can still add new items to the Children property with:

<Grid>

<Grid.Children>

</Grid.Children>

</Grid>

So read-only collection properties can usually be written OK, but XamlWriter doesn't write them by default. To override this, you can override this in the class definition with the [DesignerSerializationVisibility] attribute:

class Grid

{

…

[DesignerSerializationVisibility(DesignerSerializationVisibility.Content)]

public UIElementCollection Children

{

get { … }

}

...

}

Not writing read/write properties

The opposite situation is if you have a property that is read/write and looks perfectly fine to write to Xaml, but you don't want it to be anyway. For example, in the following class the DoorChanges property is a runtime counter that doesn’t make sense to persist. Here we use the “Hidden” value of the [DesignerSerializationVisibility] attribute to keep it from being written:

class Car

{

…

int _doorChanges = 0;

[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]

public int DoorChanges

{

get { return _doorChanges; }

set { _doorChanges = value; }

}

...

}

Procrastinate and decide at run-time

So the DesignerSerializationVisibility attribute is a method to declaratively determine if a property gets written or not by XamlWriter. You can also be called by XamlWriter during the Save call, and then make a run-time decision. To do this, you add a "ShouldSerializeProperty" method along with the property, where "Property" is the name of the property. For example:

class MyClass

{

…

public int Foo

{

get { return _foo; }

set { _foo = value; }

}

public bool ShouldSerializeFoo()

{

if( … )

return false;

else

return true;

}

...

}

There is one additional variation on this run-time check if a property is backed by a DependencyProperty. In that case, you can still use this ShouldSerializeProperty pattern, or you can override the DependencyObject.ShouldSerializeProperty virtual. For example:

override bool ShouldSerializeProperty( DependencyProperty dp )

{

if( dp == FooProperty )

{

if( … )

return false;

}

return true;

}

Writing a property as an attribute with a TypeConverter

The last section was about whether or not a property should be written to Xaml. Once it's been decided that it should, the next decision is how to write it -- as an attribute like the Width property in the following example, or as markup like the Background below it:

Click

<Button.Background>

<LinearGradientBrush.GradientStops>

</LinearGradientBrush.GradientStops>

</LinearGradientBrush>

</Button.Background>

</Button>

How does the Width integer get converted to the string "100"? The answer is type converters. A type converter is associated with a type, and is used to convert to and from other types. When Xaml is loaded, type converters are used to convert from a string, and when writing Xaml type converters are used to convert to a string.

The double type has a built-in type converter which was used above to create the string "100". Similarly string, float, int, and all the other basic types have built-in type converters. Enum also has a built-in type converter, where you can simply use the field name. This is all standard type converter functionality; nothing about this is new or different for Xaml.

But since Xaml recognizes type converters, it means that you can create your own type converter for your class:

[TypeConverter( typeof( FooConverter ))]

class Foo

{

...

}

… so that if another class had a property of that type:

class Bar

{

public Foo Foo

{

get ... set ...

}

… it could be referenced in Xaml as an attribute using your type converter:

Just don’t forget that while all you need to implement in your type converter is ConvertFrom and CanConvertFrom, you also need to implement ConvertTo and CanConvertTo to be used by XamlWriter.

Also, in addition to registering a type converter with a class, you can also register it on a property. If a type converter is specified both on a property and on the property’s type, the one on the property wins. So, in:

class Bar

{

[TypeConverter( typeof( SpecialFooConverter ))]

public Foo Foo

{

get … set ...

}

… the Foo class has a type converter, but on Bar, Bar.Foo overrides it with its own type converter.

Writing a property as an attribute with a ValueSerializer

XamlWriter also introduces one new way to write a property value as an attribute, called ValueSerializer, which is similar to a type converter. It’s easiest to explain its use by describing the motivating problem …

One of the most common cases in WPF where a property is written as an attribute is the Brush. That's because everyone expects it to be possible to set a button’s Background property to “Red” using a simple attribute, not the verbose <Button.Background><SolidColorBrush …/></Button.Background>.

But Brush in particular presents a different kind of problem, because the way you can write a Brush to Xaml is ambiguous. That’s because Brush is the base class for SolidColorBrush, which gives you simple colors, as well as more complicated brushes such as LinearGradientBrush, ImageBrush, VisualBrush, and others. If you put the type converter on Brush, and XamlWriter calls your CanConvertTo method to see if you can convert to string, the answer is a definite "maybe". That's because if the value is a SolidColorBrush, you can convert it to string (either a simple string like "Red" or if fall back on "##AARRGGBB" syntax), but other brushes such as LinearGradientBrush can't be converted to an attribute string. The problem is that type converter doesn't give you a way to make this decision; when CanConvertTo is called, you don't get a reference to the actual Brush object being written.

The solution to that with XamlWriter is the ValueSerializer. A value serializer is much like a type converter, in that it has ConvertTo/From, CanConvertTo/From methods. You also point to it with the [ValueSerializer] attribute just like you point to a type converter with a [TypeConverter] attribute. One difference in value serializer from type converter is that it only converts objects to and from strings, rather than converting to/from any type. The other key difference is that it gives you the object being serialized.

So, in WPF, the Brush class looks something like this:

[TypeConverter(typeof(BrushConverter))]

[ValueSerializer(typeof(BrushValueSerializer))]

public abstract class Brush : ...

{

...

}

And the BrushValueSerializer looks something like this:

class BrushSerializer : ValueSerializer

{

...

public override bool CanConvertToString(object value, IValueSerializerContext context)

{

if( value is SolidColorBrush )

return true;

else

return false;

}

...

}

Notice that Brush has both a type converter as well as a value serializer. That’s because XamlReader doesn’t recognize value serializers; it only uses type converters. XamlWriter, on the other hand, when it sees that both a value serializer and a type converter is available, chooses the value serializer.

That’s It

So in the end, the key points are that you can control which properties on your class will get written by XamlWriter (or by designers like Sparkle and Cider), and you can control if they’re written to Xaml as attributes or as property elements. The majority of the time, classes you create will work well with XamlWriter even if you don’t do anything. By far the most likely problem you’ll run into is that read-only collection properties don’t get written by default. So the thing you’re most likely to have to do is set the [DesignerSerializationVisibility(DesignerSerializationVisibility.Content)] attribute on the property.