ResourceDictionary class

Defines a dictionary that contains resources used by components of the app. This dictionary is oriented toward defining the resources in XAML, and then retrieving them through XAML references via the StaticResource markup extension. Alternatively, you can access resources in code, but that is less common.

Inheritance

Object

  DependencyObject

    ResourceDictionary

Syntax

public ref class ResourceDictionary : DependencyObject,
    IMap<Object, Object>,
    IIterable<IKeyValuePair>

<ResourceDictionary>
  oneOrMoreResources
</ResourceDictionary>

<frameworkElement>
  <frameworkElement.Resources>
    oneOrMoreResources
  </frameworkElement.Resources>
</frameworkElement>

XAML Values

oneOrMoreResources

One or more object elements that support a XAML object element creation syntax and are intended to be referenced as keyed resources. Each resource that you specify must have a unique value as a key.

Attributes

MarshalingBehaviorAttribute(Agile)

ThreadingAttribute(Both)

VersionAttribute(NTDDI_WIN8)

WebHostHiddenAttribute()

Members

The ResourceDictionary class has these types of members:

• Constructors
• Methods
• Properties

Constructors

The ResourceDictionary class has these constructors.

Methods

The ResourceDictionary class has these methods. It also inherits methods from the Object class.

Properties

The ResourceDictionary class has these properties.

Remarks

The main purpose of a ResourceDictionary in your app is to enable you to define resources in XAML, and then retrieve them through XAML references made with the StaticResource markup extension. By doing this, you can reuse resources you've already defined once, and also can control the complexity of your UI definition XAML by following best practices for how to factor XAML-defined elements and any value that 's shared. For more info, see ResourceDictionary and StaticResource references

The ResourceDictionary type is used as the value of two important properties in the overall structure of a Windows Store app built for Windows using C++, C#, or Visual Basic: FrameworkElement.Resources and Application.Resources. Nearly all of the XAML files that you get from a starting project template for an app will start with initial values for FrameworkElement.Resources, and the app.xaml file will start with initial values for Application.Resources. Exactly what resources are defined there depends on which project template you're using.

A ResourceDictionary also sometimes serves as the root element of a XAML file. This is the case if a particular resource area is factored out of a main FrameworkElement.Resources and Application.Resources ResourceDictionary value, for example by MergedDictionaries or ThemeDictionaries. An example of this is the StandardStyles.xaml file you see in most of the starting project templates.

Resource dictionaries are inherently a XAML-oriented feature, and XAML usages of ResourceDictionary are more common than code usages. Defining keyed resources in XAML markup that are referenced later as templates or additional resources required by such templates is one of the main scenarios in XAML UI development.

In XAML, the keys for ResourceDictionary items are declared by setting the x:Key attribute on elements that instantiate the resources. Typically, a child element for a ResourceDictionary that does not have a key value throws a parse exception or run-time exception. This might also be noted as a warning by XAML design surfaces. However, there are three notable exceptions where a ResourceDictionary child element doesn't need an x:Key value:

• A Style can use its TargetType as the implicit key. For more info on how implicit keys for styles and control templates work, see Quickstart: Styling controls.
• The ResourceDictionary elements with Source values in a ResourceDictionary.MergedDictionaries property element can't have an x:Key attribute. Within the merged dictionary itself, (the one referenced by Source) you do need keys.
• x:Name attribute can be used instead of x:Key attribute. However, x:Name doesn't enable StaticResource lookup of that item. The x:Name attribute identifying convention is used for certain scenarios such as defining storyboarded animations. For more info, see x:Name attribute.

ResourceDictionary and Microsoft Visual Studio

Microsoft Visual Studio provides an Add New Item page choice for a resource dictionary. Use this option whenever you want to define a new loose XAML resource dictionary, for example to serve as the source for a merged dictionary. Visual Studio also adds a loose XAML resource dictionary to the project whenever you use Add New Item to create a templated control. This resource dictionary provides the default theme templates. Visual Studio might create a new ResourceDictionary for you in your XAML if you are editing copies of styles or templates and a ResourceDictionary for your chosen resource location (app, page, or standalone) doesn't exist yet.

Notes on XAML syntax

Notice that the XAML implicit collection syntax for ResourceDictionary does not include an object 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 / map Add method.

For a merged resource dictionary, you do need to explicitly declare a ResourceDictionary object element, so that you can also declare the ResourceDictionary.MergedDictionaries property element. Thus there are a minimum of two ResourceDictionary object elements involved, and you use this 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 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.

Shareable types and UIElement types

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. Examples of types where sharing is supported include Style, any FrameworkTemplate subclass, the XAML intrinsic data types, brushes, colors, and transforms. For more info on which types are considered shareable, see ResourceDictionary and StaticResource references. Generally, 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 exist in only one place in an object tree after it is instantiated, and having a UIElement be shareable would potentially violate this principle.

In practice, the vast majority of the resources defined in a ResourceDictionary will be one of these:

• Control templates for a control, including its visual states.
• Supporting styles for parts of controls
• Styles for elements that are part of typical app UI but aren't controls, like TextBlock
• Data templates for controls and panels that use data binding
• Specific Brush values, mostly SolidColorBrush
• Strings or other constants that never need to be localized (strings and constants that do need to be localized shouldn't be in a ResourceDictionary; for more info see Quickstart: Translating UI resources)

Accessing a ResourceDictionary object in code-behind

We stated that the most common way you use a ResourceDictionary is through XAML definitions. But you can also access a ResourceDictionary at run-time, after the XAML ResourceDictionary has been parsed. ResourceDictionary has different code-behind API for its collection support depending on which programming language you use:

• For C# or Microsoft Visual Basic you use APIs that implement IDictionary and IEnumerable. For example, TryGetValue or the Item indexer.
• For Visual C++ component extensions (C++/CX) you use APIs that implement IMap and IIterable. For example, Lookup.
• APIs that aren't part of collection support, like Source, are the same in all languages.

For more info on how to use ResourceDictionary in code, see "Using a ResourceDictionary from code" section of ResourceDictionary and StaticResource references.

Requirements

See also

DependencyObject

IMap(Object, Object)

IIterable(IKeyValuePair)

ResourceDictionary and StaticResource references

Application resources and localization sample

Build date: 1/31/2013