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 using the StaticResource or ThemeResource markup extensions in XAML. Alternatively, you can access resources in code, but that is less common.
public class ResourceDictionary : DependencyObject, IDictionary<Object, Object>, IEnumerable<KeyValuePair>
<frameworkElement> <frameworkElement.Resources> oneOrMoreResources </frameworkElement.Resources> </frameworkElement>
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.
The ResourceDictionary class has these types of members:
The ResourceDictionary class has these constructors.
|ResourceDictionary||Initializes a new instance of the ResourceDictionary class.|
The ResourceDictionary class has these methods. It also inherits methods from the Object class.
|Add(KeyValuePair) [C#, VB]||Adds a new key-value pair to the ResourceDictionary.|
|Add(Object) [C#, VB]||Adds an item to the ResourceDictionary.|
|Clear||Removes all items from this ResourceDictionary.|
|ClearValue||Clears the local value of a dependency property. (Inherited from DependencyObject)|
|Contains [C#, VB]||Returns a value that indicates whether a specified key-value pair exists in the ResourceDictionary.|
|ContainsKey [C#, VB]||Returns a value that indicates whether a specified key exists in the ResourceDictionary.|
|CopyTo [C#, VB]||Copies the elements of the collection to an array, starting at a particular array index.|
|First [C++]||Returns an iterator for the items in the collection.|
|GetAnimationBaseValue||Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)|
|GetValue||Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)|
|GetView [C++]||Retrieves a view against the ResourceDictionary.|
|HasKey [C++]||Returns whether the ResourceDictionary has an entry with the requested key.|
|Insert [C++]||Adds a new entry to the ResourceDictionary.|
|Lookup [C++]||Returns the value from the requested key, if an entry with that key exists.|
|ReadLocalValue||Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)|
|Remove [C++]||Removes a specific item from the ResourceDictionary.|
|Remove(KeyValuePair) [C#, VB]||Removes a specific key-value pair from the ResourceDictionary.|
|Remove(Object) [C#, VB]||Removes a specific item from the ResourceDictionary.|
|SetValue||Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)|
|TryGetValue [C#, VB]||Returns a value that indicates whether a specified key exists in the ResourceDictionary. If an item with that key exists, the item is retrieved as an out parameter.|
The ResourceDictionary class has these properties.
Count [C#, VB]
|Read-only||Gets the number of elements contained in the collection.|
|Read-only||Gets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject)|
IsReadOnly [C#, VB]
|Read-only||Gets a value indicating whether the dictionary is read-only.|
Item [C#, VB]
|Read/write||Gets or sets the element value at the specified key index.|
Keys [C#, VB]
|Read-only||Gets an ICollection object containing the keys of the ResourceDictionary.|
|Read-only||Gets a collection of the ResourceDictionary dictionaries that constitute the various resource dictionaries in the merged dictionaries.|
|Read-only||Gets the number of elements contained in the collection.|
|Read/write||Gets or sets a Uniform Resource Identifier (URI) that provides the source location of a merged resource dictionary.|
|Read-only||Gets a collection of merged resource dictionaries that are specifically keyed and composed to address theme scenarios, for example supplying theme values for HighContrast.|
Values [C#, VB]
|Read-only||Gets an ICollection object containing the values of the ResourceDictionary .|
The 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 either the StaticResource markup extension or the ThemeResource markup extension. By doing this, you can reuse resources you've already defined once in XAML. You can control the complexity of your XAML by following best practices for how to factor XAML-defined elements and any value that's shared, and you can enforce that certain values such as brush colors or pixel measurements are used consistently. For more info on how ResourceDictionary is used for XAML resources techniques, see ResourceDictionary and XAML resource references.
The ResourceDictionary type is used as the value of two important properties in the overall structure of a Windows Store app using C++, C#, or Visual Basic: FrameworkElement.Resources and Application.Resources. 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 might start with initial values for Application.Resources. Exactly what resources are defined there depends on which project starting 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 generic.xaml file you see in starting project templates for a XAML templated control.
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 represent the XAML resources. Typically, if you try to put a child element that does not have a key value into a ResourceDictionary, this throws a XAML parse exception or a Windows Runtime exception. The exception condition might also be noted as a warning by XAML design surfaces. However, there are three notable cases where a ResourceDictionary child element won't require an x:Key value:
- A Style resource can use its TargetType value as the implicit resource key. For more info on how implicit keys for styles and control templates work, see Quickstart: Styling controls.
- The ResourceDictionary elements with Source values that represent ResourceDictionary.MergedDictionaries values can't have an x:Key attribute on ResourceDictionary. Within each merged dictionary file, (the one referenced by URI as its Source) you do need keys for each resource.
- x:Name attribute can be used instead of x:Key attribute, for legacy reasons. However, x:Name by itself doesn't enable XAML resource 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.
You can iterate through a
in C# or Microsoft Visual Basic. In many cases, such as using foreach syntax, the compiler does this casting for you and you won't need to cast to
IEnumerable explicitly. If you do need to cast explicitly, for example if you want to call GetEnumerator, cast to IEnumerable<T> with a KeyValuePair<Object,Object> constraint.
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.
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 and Source. 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.
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 XAML resource 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)
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 Visual Basic you use APIs that implement IDictionary<K,V> and IEnumerable<T>. For example, TryGetValue or the Item indexer.
- For Visual C++ component extensions (C++/CX) you use APIs that implement IMap<K,V> and IIterable<T>. 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 XAML resource references.
Some theme resources reference system resource values as an underlying sub-value. A system resource is a special resource value that isn't found in any XAML resource dictionary. These values rely on behavior in Windows Runtime XAML support to forward values from the system itself, and represent them in a form that a XAML resource can reference.
Starting with Windows 8.1, there's a resource loading optimization that's enabled by the app model and the Windows Runtime XAML parser. For Windows 8, the XAML parser loaded resources from app.xaml and created each of them as objects as part of startup. That wasn't very efficient if there were big dictionaries there. Also, those resources included the items that were needed by all three themes, and two of the three themes wouldn't even be active. Starting with Windows 8.1, the XAML parser only creates the resources when they're specifically requested. The request might come from other resources or from app or page XAML as each is loaded. This parser behavior minimizes the time it takes to read the app-level dictionary at startup time, and enables the first app page to load faster in most cases. Resources needed by other currently inactive themes are only loaded if that theme is chosen to become the active theme by the user. At that time, any resource where the ThemeResource markup extension was used for the request is recalculated based on the newly active theme.
Windows 8 didn't have the optimizations described above. The ResourceDictionary for
Application.Resources had to finish parsing before any page other than the splash screen could load into the app's Window. Because of this you might see some differences in timing when you retarget your app for Windows 8.1. The app should be loading faster, however it may not be possible to isolate this improvement versus other changes you've made to your app code as part of retargeting. Some of the places where you might see evidence of timing changes due to optimized resource loading include when the constructors are called by the parser, for objects like Application objects, converters, or other custom classes. Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.
For more info on performance and XAML resource factoring, see Optimize loading XAML.
Minimum supported client
|Windows 8 [Windows Store apps only]|
Minimum supported server
|Windows Server 2012 [Windows Store apps only]|
- IMap(Object, Object)
- ResourceDictionary and XAML resource references
- Application resources and localization sample
- ThemeResource markup extension
- StaticResource markup extension
- x:Key attribute
Build date: 11/16/2013