ResourceDictionary Class

ResourceDictionary supports collection APIs that support two signatures for the type of the key component, one that takes strings and one that takes Object. Most Silverlight scenarios should use strings as the resource key for resources in a ResourceDictionary. The Object as key signatures exist for compatibility and for interface conformance, but internally the dictionary is implemented such that only strings are accepted as keys. See "Keys and Resources" section of Resource Dictionaries.

In XAML, the keys for ResourceDictionary items are declared by setting the x:Key Attribute. Attempting to add a child element for a ResourceDictionary that does not have a key value throws a parse exception or run time exception. However, there are cases where no exception is thrown:

• ResourceDictionary supports a legacy usage where items in the dictionary can use x:Name rather than x:Key as the key when defined in XAML. See Resource Dictionaries.

• While not strictly speaking a child element, any dictionaries for MergedDictionaries do not require (and should not have) a key.

• A Style can use its TargetType as an implicit key, but this technique only works within the context of the templates defined for a control in generic.xaml. For more information, see Control Customization.

Notice that the XAML implicit collection syntax for ResourceDictionary shown above does not include an element for the ResourceDictionary. This is an example of XAML implicit collection syntax; a tag representing the collection element can be omitted. The elements that are added as items to the collection are specified as child elements of a property element of a property whose underlying type supports a dictionary Add method.

The Object Element Syntax shown is generally usable only at the root of a loose XAML file, unless a custom type supports constructing new ResourceDictionary instances for a particular property.

For a merged resource dictionary, there are a minimum of two ResourceDictionary object elements involved, and you use the following syntax:

<ResourceDictionary>
  <ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="uri" />
    ...
  </ResourceDictionary.MergedDictionaries>
...
</ResourceDictionary>

In this syntax the outer ResourceDictionary is the primary ResourceDictionary. The inner ResourceDictionary is the ResourceDictionary being merged. For more information, see MergedDictionaries or Resource Dictionaries.

For the implicit collection usage, the placeholder as appropriate for the property FrameworkElement.Resources is shown. You could also use this implicit collection usage for the Application.Resources property, or potentially for a custom property that uses ResourceDictionary as its property type.

A resource dictionary is a technique for defining shareable types and values of these types in XAML. Not all types or values are suitable for usage from a ResourceDictionary. For more information on which types are considered shareable in Silverlight, see Resource Dictionaries.

In particular, all UIElement derived types are not shareable unless they come from templates and application of a template on a specific control instance. Excluding the template case, a UIElement is expected to only exist in one place in an object tree once instantiated, and having a UIElement be shareable would potentially violate this principle.

Silverlight enforces shareable type usages differently than the equivalent ResourceDictionary implementation in WPF. In Silverlight, attempting to specify a resource that is not shareable does not generate parse exceptions against the ResourceDictionary declaration. Instead, you will get a parse exception against any StaticResource Markup Extension usage that attempts to reference that resource, even as the first time. The specific parse exception will report in the message that the value is out of range. 

In code, if you try to access a nonshareable ResourceDictionary, you can retrieve the item successfully as an object. However, if you attempt to add the returned object to any point in the object tree, you get an exception where the message reads: Element is already the child of another element.

In contrast, WPF permits you to place a UIElement in a ResourceDictionary, and you can successfully reference it and connect it to the object tree exactly once. However, if you attempt to add a second reference to that object and connect it to the object tree again in WPF (either in XAML or code), you get an exception that indicates you have attempted to reparent an object that is already in the object tree.

For more information on other resource dictionary differences between Silverlight and WPF, see XAML Processing Differences Between Silverlight Versions and WPF.