0% found this document useful (0 votes)

277 views1,269 pages

Dotnet Desktop WPF Advanced Netframeworkdesktop 4.8

The document provides an overview of the Windows Presentation Foundation (WPF) architecture. It describes the major components of WPF including the managed and unmanaged code portions. It discusses key concepts like the dispatcher for handling concurrency, the dependency property system, and how visual elements are rendered through the composition system to the display.

Uploaded by

jlgultraboom

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

277 views1,269 pages

Dotnet Desktop WPF Advanced Netframeworkdesktop 4.8

Uploaded by

jlgultraboom

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1269

Tell us about your PDF experience.

Advanced (Windows Presentation

Foundation)
Article • 11/07/2022

This section describes some of the advanced areas in WPF.

In This Section
WPF Architecture
XAML in WPF
Base Element Classes
Element Tree and Serialization
WPF Property System
Events in WPF
Input
Drag and Drop
Resources
Documents
Globalization and Localization
Layout
Types migrated from WPF to System.Xaml
Migration and Interoperability
Performance
Threading Model
Unmanaged WPF API Reference
WPF Architecture
Article • 02/06/2023

This topic provides a guided tour of the Windows Presentation Foundation (WPF) class
hierarchy. It covers most of the major subsystems of WPF, and describes how they
interact. It also details some of the choices made by the architects of WPF.

System.Object
The primary WPF programming model is exposed through managed code. Early in the
design phase of WPF there were a number of debates about where the line should be
drawn between the managed components of the system and the unmanaged ones. The
CLR provides a number of features that make development more productive and robust
(including memory management, error handling, common type system, etc.) but they
come at a cost.

The major components of WPF are illustrated in the figure below. The red sections of
the diagram (PresentationFramework, PresentationCore, and milcore) are the major
code portions of WPF. Of these, only one is an unmanaged component – milcore.
Milcore is written in unmanaged code in order to enable tight integration with DirectX.
All display in WPF is done through the DirectX engine, allowing for efficient hardware
and software rendering. WPF also required fine control over memory and execution. The
composition engine in milcore is extremely performance sensitive, and required giving
up many advantages of the CLR to gain performance.
Communication between the managed and unmanaged portions of WPF is discussed
later in this topic. The remainder of the managed programming model is described
below.

System.Threading.DispatcherObject
Most objects in WPF derive from DispatcherObject, which provides the basic constructs
for dealing with concurrency and threading. WPF is based on a messaging system
implemented by the dispatcher. This works much like the familiar Win32 message pump;
in fact, the WPF dispatcher uses User32 messages for performing cross thread calls.

There are really two core concepts to understand when discussing concurrency in WPF –
the dispatcher and thread affinity.

During the design phase of WPF, the goal was to move to a single thread of execution,
but a non-thread "affinitized" model. Thread affinity happens when a component uses
the identity of the executing thread to store some type of state. The most common form
of this is to use the thread local store (TLS) to store state. Thread affinity requires that
each logical thread of execution be owned by only one physical thread in the operating
system, which can become memory intensive. In the end, WPF’s threading model was
kept in sync with the existing User32 threading model of single threaded execution with
thread affinity. The primary reason for this was interoperability – systems like OLE 2.0,
the clipboard, and Internet Explorer all require single thread affinity (STA) execution.

Given that you have objects with STA threading, you need a way to communicate
between threads, and validate that you are on the correct thread. Herein lies the role of
the dispatcher. The dispatcher is a basic message dispatching system, with multiple
prioritized queues. Examples of messages include raw input notifications (mouse
moved), framework functions (layout), or user commands (execute this method). By
deriving from DispatcherObject, you create a CLR object that has STA behavior, and will
be given a pointer to a dispatcher at creation time.

System.Windows.DependencyObject
One of the primary architectural philosophies used in building WPF was a preference for
properties over methods or events. Properties are declarative and allow you to more
easily specify intent instead of action. This also supported a model driven, or data
driven, system for displaying user interface content. This philosophy had the intended
effect of creating more properties that you could bind to, in order to better control the
behavior of an application.

In order to have more of the system driven by properties, a richer property system than
what the CLR provides was needed. A simple example of this richness is change
notifications. In order to enable two way binding, you need both sides of the bind to
support change notification. In order to have behavior tied to property values, you need
to be notified when the property value changes. The Microsoft .NET Framework has an
interface, INotifyPropertyChange, which allows an object to publish change
notifications, however it is optional.

WPF provides a richer property system, derived from the DependencyObject type. The
property system is truly a "dependency" property system in that it tracks dependencies
between property expressions and automatically revalidates property values when
dependencies change. For example, if you have a property that inherits (like FontSize),
the system is automatically updated if the property changes on a parent of an element
that inherits the value.

The foundation of the WPF property system is the concept of a property expression. In
this first release of WPF, the property expression system is closed, and the expressions
are all provided as part of the framework. Expressions are why the property system
doesn’t have data binding, styling, or inheritance hard coded, but rather provided by
later layers within the framework.
The property system also provides for sparse storage of property values. Because
objects can have dozens (if not hundreds) of properties, and most of the values are in
their default state (inherited, set by styles, etc.), not every instance of an object needs to
have the full weight of every property defined on it.

The final new feature of the property system is the notion of attached properties. WPF
elements are built on the principle of composition and component reuse. It is often the
case that some containing element (like a Grid layout element) needs additional data on
child elements to control its behavior (like the Row/Column information). Instead of
associating all of these properties with every element, any object is allowed to provide
property definitions for any other object. This is similar to the "expando" features of
JavaScript.

System.Windows.Media.Visual
With a system defined, the next step is getting pixels drawn to the screen. The Visual
class provides for building a tree of visual objects, each optionally containing drawing
instructions and metadata about how to render those instructions (clipping,
transformation, etc.). Visual is designed to be extremely lightweight and flexible, so most
of the features have no public API exposure and rely heavily on protected callback
functions.

Visual is really the entry point to the WPF composition system. Visual is the point of
connection between these two subsystems, the managed API and the unmanaged
milcore.

WPF displays data by traversing the unmanaged data structures managed by the
milcore. These structures, called composition nodes, represent a hierarchical display tree
with rendering instructions at each node. This tree, illustrated on the right hand side of
the figure below, is only accessible through a messaging protocol.

When programming WPF, you create Visual elements, and derived types, which
internally communicate to the composition tree through this messaging protocol. Each
Visual in WPF may create one, none, or several composition nodes.
There is a very important architectural detail to notice here – the entire tree of visuals
and drawing instructions is cached. In graphics terms, WPF uses a retained rendering
system. This enables the system to repaint at high refresh rates without the composition
system blocking on callbacks to user code. This helps prevent the appearance of an
unresponsive application.

Another important detail that isn’t really noticeable in the diagram is how the system
actually performs composition.

In User32 and GDI, the system works on an immediate mode clipping system. When a
component needs to be rendered, the system establishes a clipping bounds outside of
which the component isn’t allowed to touch the pixels, and then the component is
asked to paint pixels in that box. This system works very well in memory constrained
systems because when something changes you only have to touch the affected
component – no two components ever contribute to the color of a single pixel.

WPF uses a "painter's algorithm" painting model. This means that instead of clipping
each component, each component is asked to render from the back to the front of the
display. This allows each component to paint over the previous component's display.
The advantage of this model is that you can have complex, partially transparent shapes.
With today’s modern graphics hardware, this model is relatively fast (which wasn’t the
case when User32/ GDI were created).

As mentioned previously, a core philosophy of WPF is to move to a more declarative,

"property centric" model of programming. In the visual system, this shows up in a
couple of interesting places.

First, if you think about the retained mode graphic system, this is really moving away
from an imperative DrawLine/DrawLine type model, to a data oriented model – new
Line()/new Line(). This move to data driven rendering allows complex operations on the
drawing instructions to be expressed using properties. The types deriving from Drawing
are effectively the object model for rendering.

Second, if you evaluate the animation system, you'll see that it is almost completely
declarative. Instead of requiring a developer to compute the next location, or next color,
you can express animations as a set of properties on an animation object. These
animations can then express the intent of the developer or designer (move this button
from here to there in 5 seconds), and the system can determine the most efficient way
to accomplish that.

System.Windows.UIElement
UIElement defines core subsystems including Layout, Input, and Events.

Layout is a core concept in WPF. In many systems there is either a fixed set of layout
models (HTML supports three models for layout; flow, absolute, and tables) or no model
for layout (User32 really only supports absolute positioning). WPF started with the
assumption that developers and designers wanted a flexible, extensible layout model,
which could be driven by property values rather than imperative logic. At the UIElement
level, the basic contract for layout is introduced – a two phase model with Measure and
Arrange passes.

Measure allows a component to determine how much size it would like to take. This is a
separate phase from Arrange because there are many situations where a parent element
will ask a child to measure several times to determine its optimal position and size. The
fact that parent elements ask child elements to measure demonstrates another key
philosophy of WPF – size to content. All controls in WPF support the ability to size to the
natural size of their content. This makes localization much easier, and allows for dynamic
layout of elements as things resize. The Arrange phase allows a parent to position and
determine the final size of each child.

A lot of time is often spent talking about the output side of WPF – Visual and related
objects. However there is a tremendous amount of innovation on the input side as well.
Probably the most fundamental change in the input model for WPF is the consistent
model by which input events are routed through the system.

Input originates as a signal on a kernel mode device driver and gets routed to the
correct process and thread through an intricate process involving the Windows kernel
and User32. Once the User32 message corresponding to the input is routed to WPF, it is
converted into a WPF raw input message and sent to the dispatcher. WPF allows for raw
input events to be converted to multiple actual events, enabling features like
"MouseEnter" to be implemented at a low level of the system with guaranteed delivery.
Each input event is converted to at least two events – a "preview" event and the actual
event. All events in WPF have a notion of routing through the element tree. Events are
said to "bubble" if they traverse from a target up the tree to the root, and are said to
"tunnel" if they start at the root and traverse down to a target. Input preview events
tunnel, enabling any element in the tree an opportunity to filter or take action on the
event. The regular (non-preview) events then bubble from the target up to the root.

This split between the tunnel and bubble phase makes implementation of features like
keyboard accelerators work in a consistent fashion in a composite world. In User32 you
would implement keyboard accelerators by having a single global table containing all
the accelerators you wanted to support (Ctrl+N mapping to "New"). In the dispatcher
for your application you would call TranslateAccelerator which would sniff the input
messages in User32 and determine if any matched a registered accelerator. In WPF this
wouldn’t work because the system is fully "composable" – any element can handle and
use any keyboard accelerator. Having this two phase model for input allows
components to implement their own "TranslateAccelerator".

To take this one step further, UIElement also introduces the notion of
CommandBindings. The WPF command system allows developers to define functionality
in terms of a command end point – something that implements ICommand. Command
bindings enable an element to define a mapping between an input gesture (Ctrl+N) and
a command (New). Both the input gestures and command definitions are extensible, and
can be wired together at usage time. This makes it trivial, for example, to allow an end
user to customize the key bindings that they want to use within an application.

To this point in the topic, "core" features of WPF – features implemented in the
PresentationCore assembly, have been the focus. When building WPF, a clean
separation between foundational pieces (like the contract for layout with Measure and
Arrange) and framework pieces (like the implementation of a specific layout like Grid)
was the desired outcome. The goal was to provide an extensibility point low in the stack
that would allow external developers to create their own frameworks if needed.

System.Windows.FrameworkElement
FrameworkElement can be looked at in two different ways. It introduces a set of policies
and customizations on the subsystems introduced in lower layers of WPF. It also
introduces a set of new subsystems.

The primary policy introduced by FrameworkElement is around application layout.

FrameworkElement builds on the basic layout contract introduced by UIElement and
adds the notion of a layout "slot" that makes it easier for layout authors to have a
consistent set of property driven layout semantics. Properties like HorizontalAlignment,
VerticalAlignment, MinWidth, and Margin (to name a few) give all components derived
from FrameworkElement consistent behavior inside of layout containers.

FrameworkElement also provides easier API exposure to many features found in the core
layers of WPF. For example, FrameworkElement provides direct access to animation
through the BeginStoryboard method. A Storyboard provides a way to script multiple
animations against a set of properties.

The two most critical things that FrameworkElement introduces are data binding and
styles.

The data binding subsystem in WPF should be relatively familiar to anyone that has used
Windows Forms or ASP.NET for creating an application user interface (UI). In each of
these systems, there is a simple way to express that you want one or more properties
from a given element to be bound to a piece of data. WPF has full support for property
binding, transformation, and list binding.

One of the most interesting features of data binding in WPF is the introduction of data
templates. Data templates allow you to declaratively specify how a piece of data should
be visualized. Instead of creating a custom user interface that can be bound to data, you
can instead turn the problem around and let the data determine the display that will be
created.

Styling is really a lightweight form of data binding. Using styling you can bind a set of
properties from a shared definition to one or more instances of an element. Styles get
applied to an element either by explicit reference (by setting the Style property) or
implicitly by associating a style with the CLR type of the element.

System.Windows.Controls.Control
Control’s most significant feature is templating. If you think about WPF’s composition
system as a retained mode rendering system, templating allows a control to describe its
rendering in a parameterized, declarative manner. A ControlTemplate is really nothing
more than a script to create a set of child elements, with bindings to properties offered
by the control.

Control provides a set of stock properties, Foreground, Background, Padding, to name a

few, which template authors can then use to customize the display of a control. The
implementation of a control provides a data model and interaction model. The
interaction model defines a set of commands (like Close for a window) and bindings to
input gestures (like clicking the red X in the upper corner of the window). The data
model provides a set of properties to either customize the interaction model or
customize the display (determined by the template).

This split between the data model (properties), interaction model (commands and
events), and display model (templates) enables complete customization of a control’s
look and behavior.

A common aspect of the data model of controls is the content model. If you look at a
control like Button, you will see that it has a property named "Content" of type Object.
In Windows Forms and ASP.NET, this property would typically be a string – however that
limits the type of content you can put in a button. Content for a button can either be a
simple string, a complex data object, or an entire element tree. In the case of a data
object, the data template is used to construct a display.

Summary
WPF is designed to allow you to create dynamic, data driven presentation systems. Every
part of the system is designed to create objects through property sets that drive
behavior. Data binding is a fundamental part of the system, and is integrated at every
layer.

Traditional applications create a display and then bind to some data. In WPF, everything
about the control, every aspect of the display, is generated by some type of data
binding. The text found inside a button is displayed by creating a composed control
inside of the button and binding its display to the button’s content property.

When you begin developing WPF based applications, it should feel very familiar. You can
set properties, use objects, and data bind in much the same way that you can using
Windows Forms or ASP.NET. With a deeper investigation into the architecture of WPF,
you'll find that the possibility exists for creating much richer applications that
fundamentally treat data as the core driver of the application.

See also
Visual
UIElement
ICommand
FrameworkElement
DispatcherObject
CommandBinding
Control
Data Binding Overview
Layout
Animation Overview
XAML in WPF
Article • 08/10/2023

Extensible Application Markup Language (XAML) is a markup language for declarative

application programming. Windows Presentation Foundation (WPF) implements a XAML
processor implementation and provides XAML language support. The WPF types are
implemented such that they can provide the required type backing for a XAML
representation. In general, you can create the majority of your WPF application UI in
XAML markup.

In This Section
XAML in WPF
XAML Syntax In Detail
Code-Behind and XAML in WPF
XAML and Custom Classes for WPF
Markup Extensions and WPF XAML
XAML Namespaces and Namespace Mapping for WPF XAML
WPF XAML Namescopes
Inline Styles and Templates
White-space Processing in XAML
TypeConverters and XAML
XML Character Entities and XAML
XAML Namespace (x:) Language Features
WPF XAML Extensions
Markup Compatibility (mc:) Language Features

Related Sections
WPF Architecture
Base Elements
Element Tree and Serialization
Properties
Events
Input
Resources
Styling and Templating
Threading Model
XAML overview in WPF (.NET
Framework)
Article • 02/16/2023

This article describes the features of the XAML language and demonstrates how you can
use XAML to write Windows Presentation Foundation (WPF) apps. This article specifically
describes XAML as implemented by WPF. XAML itself is a larger language concept than
WPF.

What is XAML
XAML is a declarative markup language. As applied to the .NET Framework
programming model, XAML simplifies creating a UI for a .NET Framework app. You can
create visible UI elements in the declarative XAML markup, and then separate the UI
definition from the run-time logic by using code-behind files that are joined to the
markup through partial class definitions. XAML directly represents the instantiation of
objects in a specific set of backing types defined in assemblies. This is unlike most other
markup languages, which are typically an interpreted language without such a direct tie
to a backing type system. XAML enables a workflow where separate parties can work on
the UI and the logic of an app, using potentially different tools.

When represented as text, XAML files are XML files that generally have the .xaml
extension. The files can be encoded by any XML encoding, but encoding as UTF-8 is
typical.

The following example shows how you might create a button as part of a UI. This
example is intended to give you a flavor of how XAML represents common UI
programming metaphors (it is not a complete sample).

XAML

XAML syntax in brief

The following sections explain the basic forms of XAML syntax, and give a short markup
example. These sections are not intended to provide complete information about each
syntax form, such as how these are represented in the backing type system. For more
information about the specifics of XAML syntax, see XAML Syntax In Detail.

Much of the material in the next few sections will be elementary to you if you have
previous familiarity with the XML language. This is a consequence of one of the basic
design principles of XAML. The XAML language defines concepts of its own, but these
concepts work within the XML language and markup form.

XAML object elements

An object element typically declares an instance of a type. That type is defined in the
assemblies referenced by the technology that uses XAML as a language.

Object element syntax always starts with an opening angle bracket ( < ). This is followed
by the name of the type where you want to create an instance. (The name can include a
prefix, a concept that will be explained later.) After this, you can optionally declare
attributes on the object element. To complete the object element tag, end with a closing
angle bracket ( > ). You can instead use a self-closing form that does not have any
content, by completing the tag with a forward slash and closing angle bracket in
succession ( /> ). For example, look at the previously shown markup snippet again.

XAML

This specifies two object elements: <StackPanel> (with content, and a closing tag later),
and <Button .../> (the self-closing form, with several attributes). The object elements
StackPanel and Button each map to the name of a class that is defined by WPF and is

part of the WPF assemblies. When you specify an object element tag, you create an
instruction for XAML processing to create a new instance of the underlying type. Each
instance is created by calling the parameterless constructor of the underlying type when
parsing and loading the XAML.

Attribute syntax (properties)

Properties of an object can often be expressed as attributes of the object element. The
attribute syntax names the object property that is being set, followed by the assignment
operator (=). The value of an attribute is always specified as a string that is contained
within quotation marks.
Attribute syntax is the most streamlined property setting syntax and is the most intuitive
syntax to use for developers who have used markup languages in the past. For example,
the following markup creates a button that has red text and a blue background in
addition to display text specified as Content .

XAML

<Button Background="Blue" Foreground="Red" Content="This is a button"/>

Property element syntax

For some properties of an object element, attribute syntax is not possible, because the
object or information necessary to provide the property value cannot be adequately
expressed within the quotation mark and string restrictions of attribute syntax. For these
cases, a different syntax known as property element syntax can be used.

The syntax for the property element start tag is <TypeName.PropertyName> . Generally, the
content of that tag is an object element of the type that the property takes as its value.
After specifying the content, you must close the property element with an end tag. The
syntax for the end tag is </TypeName.PropertyName> .

If an attribute syntax is possible, using the attribute syntax is typically more convenient
and enables a more compact markup, but that is often just a matter of style, not a
technical limitation. The following example shows the same properties being set as in
the previous attribute syntax example, but this time by using property element syntax
for all properties of the Button .

XAML

<Button>
<Button.Background>
<SolidColorBrush Color="Blue"/>
</Button.Background>
<Button.Foreground>
<SolidColorBrush Color="Red"/>
</Button.Foreground>
<Button.Content>
This is a button
</Button.Content>
</Button>

Collection syntax
The XAML language includes some optimizations that produce more human-readable
markup. One such optimization is that if a particular property takes a collection type,
then items that you declare in markup as child elements within that property's value
become part of the collection. In this case a collection of child object elements is the
value being set to the collection property.

The following example shows collection syntax for setting values of the GradientStops
property.

XAML

XAML content properties

XAML specifies a language feature whereby a class can designate exactly one of its
properties to be the XAML content property. Child elements of that object element are
used to set the value of that content property. In other words, for the content property
uniquely, you can omit a property element when setting that property in XAML markup
and produce a more visible parent/child metaphor in the markup.

For example, Border specifies a content property of Child. The following two Border
elements are treated identically. The first one takes advantage of the content property
syntax and omits the Border.Child property element. The second one shows
Border.Child explicitly.

XAML

<Border>
<TextBox Width="300"/>
</Border>

<Border>
<Border.Child>
<TextBox Width="300"/>
</Border.Child>
</Border>
As a rule of the XAML language, the value of a XAML content property must be given
either entirely before or entirely after any other property elements on that object
element. For instance, the following markup does not compile.

XAML

<Button>I am a
<Button.Background>Blue</Button.Background>
blue button</Button>

For more information about the specifics of XAML syntax, see XAML Syntax In Detail.

Text content
A small number of XAML elements can directly process text as their content. To enable
this, one of the following cases must be true:

The class must declare a content property, and that content property must be of a
type assignable to a string (the type could be Object). For instance, any
ContentControl uses Content as its content property and it is type Object, and this
supports the following usage on a ContentControl such as a Button:
<Button>Hello</Button> .

The type must declare a type converter, in which case the text content is used as
initialization text for that type converter. For example, <Brush>Blue</Brush>
converts the content value of Blue into a brush. This case is less common in
practice.

The type must be a known XAML language primitive.

Content properties and collection syntax combined

Consider this example.

XAML

<StackPanel>
<Button>First Button</Button>
<Button>Second Button</Button>
</StackPanel>

Here, each Button is a child element of StackPanel. This is a streamlined and intuitive
markup that omits two tags for two different reasons.
Omitted StackPanel.Children property element: StackPanel derives from Panel.
Panel defines Panel.Children as its XAML content property.

Omitted UIElementCollection object element: The Panel.Children property takes

the type UIElementCollection, which implements IList. The collection's element tag
can be omitted, based on the XAML rules for processing collections such as IList.
(In this case, UIElementCollection actually cannot be instantiated because it does
not expose a parameterless constructor, and that is why the UIElementCollection
object element is shown commented out).

XAML

<StackPanel>
<StackPanel.Children>

<Button>First Button</Button>
<Button>Second Button</Button>

</StackPanel.Children>
</StackPanel>

Attribute syntax (events)

Attribute syntax can also be used for members that are events rather than properties. In
this case, the attribute's name is the name of the event. In the WPF implementation of
events for XAML, the attribute's value is the name of a handler that implements that
event's delegate. For example, the following markup assigns a handler for the Click
event to a Button created in markup:

XAML

There is more to events and XAML in WPF than just this example of the attribute syntax.
For example, you might wonder what the ClickHandler referenced here represents and
how it is defined. This will be explained in the upcoming Events and XAML code-behind
section of this article.
Case and white space in XAML
In general, XAML is case-sensitive. For purposes of resolving backing types, WPF XAML
is case-sensitive by the same rules that the CLR is case-sensitive. Object elements,
property elements, and attribute names must all be specified by using the sensitive
casing when compared by name to the underlying type in the assembly, or to a member
of a type. XAML language keywords and primitives are also case-sensitive. Values are
not always case-sensitive. Case sensitivity for values will depend on the type converter
behavior associated with the property that takes the value, or the property value type.
For example, properties that take the Boolean type can take either true or True as
equivalent values, but only because the native WPF XAML parser type conversion for
string to Boolean already permits these as equivalents.

WPF XAML processors and serializers will ignore or drop all nonsignificant white space,
and will normalize any significant white space. This is consistent with the default white-
space behavior recommendations of the XAML specification. This behavior is only of
consequence when you specify strings within XAML content properties. In simplest
terms, XAML converts space, linefeed, and tab characters into spaces, and then
preserves one space if found at either end of a contiguous string. The full explanation of
XAML white-space handling is not covered in this article. For more information, see
White space processing in XAML.

Markup extensions
Markup extensions are a XAML language concept. When used to provide the value of an
attribute syntax, curly braces ( { and } ) indicate a markup extension usage. This usage
directs the XAML processing to escape from the general treatment of attribute values as
either a literal string or a string-convertible value.

The most common markup extensions used in WPF app programming are Binding, used
for data binding expressions, and the resource references StaticResource and
DynamicResource. By using markup extensions, you can use attribute syntax to provide
values for properties even if that property does not support an attribute syntax in
general. Markup extensions often use intermediate expression types to enable features
such as deferring values or referencing other objects that are only present at run-time.

For example, the following markup sets the value of the Style property using attribute
syntax. The Style property takes an instance of the Style class, which by default could not
be instantiated by an attribute syntax string. But in this case, the attribute references a
particular markup extension, StaticResource . When that markup extension is processed,
it returns a reference to a style that was previously instantiated as a keyed resource in a
resource dictionary.

XAML

<Page.Resources>
<SolidColorBrush x:Key="MyBrush" Color="Gold"/>
<Style TargetType="Border" x:Key="PageBackground">
<Setter Property="Background" Value="Blue"/>
</Style>

XAML

</Page.Resources>
<StackPanel>
<Border Style="{StaticResource PageBackground}">

XAML

</Border>
</StackPanel>

For a reference listing of all markup extensions for XAML implemented specifically in
WPF, see WPF XAML Extensions. For a reference listing of the markup extensions that
are defined by System.Xaml and are more widely available for .NET Framework XAML
implementations, see XAML Namespace (x:) Language Features. For more information
about markup extension concepts, see Markup Extensions and WPF XAML.

Type converters
In the XAML Syntax in Brief section, it was stated that the attribute value must be able to
be set by a string. The basic, native handling of how strings are converted into other
object types or primitive values is based on the String type itself, in addition to native
processing for certain types such as DateTime or Uri. But many WPF types or members
of those types extend the basic string attribute processing behavior in such a way that
instances of more complex object types can be specified as strings and attributes.

The Thickness structure is an example of a type that has a type conversion enabled for
XAML usages. Thickness indicates measurements within a nested rectangle and is used
as the value for properties such as Margin. By placing a type converter on Thickness, all
properties that use a Thickness are easier to specify in XAML because they can be
specified as attributes. The following example uses a type conversion and attribute
syntax to provide a value for a Margin:
XAML

<Button Margin="10,20,10,30" Content="Click me"/>

The previous attribute syntax example is equivalent to the following more verbose
syntax example, where the Margin is instead set through property element syntax
containing a Thickness object element. The four key properties of Thickness are set as
attributes on the new instance:

XAML

<Button Content="Click me">

<Button.Margin>
<Thickness Left="10" Top="20" Right="10" Bottom="30"/>
</Button.Margin>
</Button>

７ Note

There are also a limited number of objects where the type conversion is the only
public way to set a property to that type without involving a subclass, because the
type itself does not have a parameterless constructor. An example is Cursor.

For more information on type conversion, see TypeConverters and XAML.

XAML root elements and XAML namespaces

A XAML file must have only one root element, in order to be both a well-formed XML
file and a valid XAML file. For typical WPF scenarios, you use a root element that has a
prominent meaning in the WPF app model (for example, Window or Page for a page,
ResourceDictionary for an external dictionary, or Application for the app definition). The
following example shows the root element of a typical XAML file for a WPF page, with
the root element of Page.

XAML

XAML
</Page>

The root element also contains the attributes xmlns and xmlns:x . These attributes
indicate to a XAML processor which XAML namespaces contain the type definitions for
backing types that the markup will reference as elements. The xmlns attribute
specifically indicates the default XAML namespace. Within the default XAML namespace,
object elements in the markup can be specified without a prefix. For most WPF app
scenarios, and for almost all of the examples given in the WPF sections of the SDK, the
default XAML namespace is mapped to the WPF namespace
http://schemas.microsoft.com/winfx/2006/xaml/presentation . The xmlns:x attribute

indicates an additional XAML namespace, which maps the XAML language namespace
http://schemas.microsoft.com/winfx/2006/xaml .

This usage of xmlns to define a scope for usage and mapping of a namescope is
consistent with the XML 1.0 specification. XAML namescopes are different from XML
namescopes only in that a XAML namescope also implies something about how the
namescope's elements are backed by types when it comes to type resolution and
parsing the XAML.

The xmlns attributes are only strictly necessary on the root element of each XAML file.
xmlns definitions will apply to all descendant elements of the root element (this

behavior is again consistent with the XML 1.0 specification for xmlns .) xmlns attributes
are also permitted on other elements underneath the root, and would apply to any
descendant elements of the defining element. However, frequent definition or
redefinition of XAML namespaces can result in a XAML markup style that is difficult to
read.

The WPF implementation of its XAML processor includes an infrastructure that has
awareness of the WPF core assemblies. The WPF core assemblies are known to contain
the types that support the WPF mappings to the default XAML namespace. This is
enabled through configuration that is part of your project build file and the WPF build
and project systems. Therefore, declaring the default XAML namespace as the default
xmlns is all that is necessary in order to reference XAML elements that come from WPF

assemblies.

The x: prefix
In the previous root element example, the prefix x: was used to map the XAML
namespace http://schemas.microsoft.com/winfx/2006/xaml , which is the dedicated
XAML namespace that supports XAML language constructs. This x: prefix is used for
mapping this XAML namespace in the templates for projects, in examples, and in
documentation throughout this SDK. The XAML namespace for the XAML language
contains several programming constructs that you will use frequently in your XAML. The
following is a listing of the most common x: prefix programming constructs you will
use:

x:Key: Sets a unique key for each resource in a ResourceDictionary (or similar
dictionary concepts in other frameworks). x:Key will probably account for 90
percent of the x: usages you will see in a typical WPF app's markup.

x:Class: Specifies the CLR namespace and class name for the class that provides
code-behind for a XAML page. You must have such a class to support code-behind
per the WPF programming model, and therefore you almost always see x:
mapped, even if there are no resources.

x:Name: Specifies a run-time object name for the instance that exists in run-time
code after an object element is processed. In general, you will frequently use a
WPF-defined equivalent property for x:Name. Such properties map specifically to a
CLR backing property and are thus more convenient for app programming, where
you frequently use run-time code to find the named elements from initialized
XAML. The most common such property is FrameworkElement.Name. You might
still use x:Name when the equivalent WPF framework-level Name property is not
supported in a particular type. This occurs in certain animation scenarios.

x:Static: Enables a reference that returns a static value that is not otherwise a
XAML-compatible property.

x:Type: Constructs a Type reference based on a type name. This is used to specify
attributes that take Type, such as Style.TargetType, although frequently the
property has native string-to-Type conversion in such a way that the x:Type
markup extension usage is optional.

There are additional programming constructs in the x: prefix/XAML namespace, which

are not as common. For details, see XAML Namespace (x:) Language Features.

Custom prefixes and custom types in XAML

For your own custom assemblies, or for assemblies outside the WPF core of
PresentationCore, PresentationFramework and WindowsBase, you can specify the
assembly as part of a custom xmlns mapping. You can then reference types from that
assembly in your XAML, so long as that type is correctly implemented to support the
XAML usages you are attempting.
The following is a basic example of how custom prefixes work in XAML markup. The
prefix custom is defined in the root element tag, and mapped to a specific assembly that
is packaged and available with the app. This assembly contains a type NumericUpDown ,
which is implemented to support general XAML usage as well as using a class
inheritance that permits its insertion at this particular point in a WPF XAML content
model. An instance of this NumericUpDown control is declared as an object element, using
the prefix so that a XAML parser knows which XAML namespace contains the type, and
therefore where the backing assembly is that contains the type definition.

XAML

For more information about custom types in XAML, see XAML and Custom Classes for
WPF.

For more information about how XML namespaces and code namespaces in assemblies
are related, see XAML Namespaces and Namespace Mapping for WPF XAML.

Events and XAML code-behind

Most WPF apps consist of both XAML markup and code-behind. Within a project, the
XAML is written as a .xaml file, and a CLR language such as Microsoft Visual Basic or C#
is used to write a code-behind file. When a XAML file is markup compiled as part of the
WPF programming and application models, the location of the XAML code-behind file
for a XAML file is identified by specifying a namespace and class as the x:Class
attribute of the root element of the XAML.

In the examples so far, you have seen several buttons, but none of these buttons had
any logical behavior associated with them yet. The primary application-level mechanism
for adding a behavior for an object element is to use an existing event of the element
class, and to write a specific handler for that event that is invoked when that event is
raised at run-time. The event name and the name of the handler to use are specified in
the markup, whereas the code that implements your handler is defined in the code-
behind.

XAML

namespace ExampleNamespace
{
public partial class ExamplePage
{
void Button_Click(object sender, RoutedEventArgs e)
{
Button b = e.Source as Button;
b.Foreground = Brushes.Red;
}
}
}

Notice that the code-behind file uses the CLR namespace ExampleNamespace and
declares ExamplePage as a partial class within that namespace. This parallels the x:Class
attribute value of ExampleNamespace . ExamplePage that was provided in the markup root.
The WPF markup compiler will create a partial class for any compiled XAML file, by
deriving a class from the root element type. When you provide code-behind that also
defines the same partial class, the resulting code is combined within the same
namespace and class of the compiled app.

For more information about requirements for code-behind programming in WPF, see
Code-behind, Event Handler, and Partial Class Requirements in WPF.

If you do not want to create a separate code-behind file, you can also inline your code
in a XAML file. However, inline code is a less versatile technique that has substantial
limitations. For more informaiton, see Code-Behind and XAML in WPF.

Routed events
A particular event feature that is fundamental to WPF is a routed event. Routed events
enable an element to handle an event that was raised by a different element, as long as
the elements are connected through a tree relationship. When specifying event handling
with a XAML attribute, the routed event can be listened for and handled on any element,
including elements that do not list that particular event in the class members table. This
is accomplished by qualifying the event name attribute with the owning class name. For
instance, the parent StackPanel in the ongoing StackPanel / Button example could
register a handler for the child element button's Click event by specifying the attribute
Button.Click on the StackPanel object element, with your handler name as the
attribute value. For more information, see Routed Events Overview.

XAML named elements

By default, the object instance that is created in an object graph by processing a XAML
object element does not possess a unique identifier or object reference. In contrast, if
you call a constructor in code, you almost always use the constructor result to set a
variable to the constructed instance, so that you can reference the instance later in your
code. In order to provide standardized access to objects that were created through a
markup definition, XAML defines the x:Name attribute. You can set the value of the
x:Name attribute on any object element. In your code-behind, the identifier you choose
is equivalent to an instance variable that refers to the constructed instance. In all
respects, named elements function as if they were object instances (the name references
that instance), and your code-behind can reference the named elements to handle run-
time interactions within the app. This connection between instances and variables is
accomplished by the WPF XAML markup compiler, and more specifically involve features
and patterns such as InitializeComponent that will not be discussed in detail in this
article.

WPF framework-level XAML elements inherit a Name property, which is equivalent to

the XAML defined x:Name attribute. Certain other classes also provide property-level
equivalents for x:Name , which is also generally defined as a Name property. Generally
speaking, if you cannot find a Name property in the members table for your chosen
element/type, use x:Name instead. The x:Name values will provide an identifier to a
XAML element that can be used at run-time, either by specific subsystems or by utility
methods such as FindName.

The following example sets Name on a StackPanel element. Then, a handler on a Button
within that StackPanel references the StackPanel through its instance reference
buttonContainer as set by Name.

XAML

<StackPanel Name="buttonContainer">
XAML

<Button Click="RemoveThis">Click to remove this button</Button>

</StackPanel>

void RemoveThis(object sender, RoutedEventArgs e)

{
FrameworkElement fe = e.Source as FrameworkElement;
if (buttonContainer.Children.Contains(fe))
{
buttonContainer.Children.Remove(fe);
}
}

Just like a variable, the XAML name for an instance is governed by a concept of scope,
so that names can be enforced to be unique within a certain scope that is predictable.
The primary markup that defines a page denotes one unique XAML namescope, with
the XAML namescope boundary being the root element of that page. However, other
markup sources can interact with a page at run-time, such as styles or templates within
styles, and such markup sources often have their own XAML namescopes that do not
necessarily connect with the XAML namescope of the page. For more information on
x:Name and XAML namescopes, see Name, x:Name Directive, or WPF XAML

Namescopes.

Attached properties and attached events

XAML specifies a language feature that enables certain properties or events to be
specified on any element, regardless of whether the property or event exists in the
type's definitions for the element it is being set on. The properties version of this feature
is called an attached property, the events version is called an attached event.
Conceptually, you can think of attached properties and attached events as global
members that can be set on any XAML element/object instance. However, that
element/class or a larger infrastructure must support a backing property store for the
attached values.

Attached properties in XAML are typically used through attribute syntax. In attribute
syntax, you specify an attached property in the form ownerType.propertyName .

Superficially, this resembles a property element usage, but in this case the ownerType
you specify is always a different type than the object element where the attached
property is being set. ownerType is the type that provides the accessor methods that are
required by a XAML processor in order to get or set the attached property value.

The most common scenario for attached properties is to enable child elements to report
a property value to their parent element.

The following example illustrates the DockPanel.Dock attached property. The DockPanel
class defines the accessors for DockPanel.Dock and therefore owns the attached
property. The DockPanel class also includes logic that iterates its child elements and
specifically checks each element for a set value of DockPanel.Dock. If a value is found,
that value is used during layout to position the child elements. Use of the
DockPanel.Dock attached property and this positioning capability is in fact the
motivating scenario for the DockPanel class.

XAML

<DockPanel>
<Button DockPanel.Dock="Left" Width="100" Height="20">I am on the
left</Button>
<Button DockPanel.Dock="Right" Width="100" Height="20">I am on the
right</Button>
</DockPanel>

In WPF, most or all the attached properties are also implemented as dependency
properties. For more information, see Attached Properties Overview.

Attached events use a similar ownerType.eventName form of attribute syntax. Just like the
non-attached events, the attribute value for an attached event in XAML specifies the
name of the handler method that is invoked when the event is handled on the element.
Attached event usages in WPF XAML are less common. For more information, see
Attached Events Overview.

Base types and XAML

Underlying WPF XAML and its XAML namespace is a collection of types that correspond
to CLR objects in addition to markup elements for XAML. However, not all classes can be
mapped to elements. Abstract classes, such as ButtonBase, and certain non-abstract
base classes, are used for inheritance in the CLR objects model. Base classes, including
abstract ones, are still important to XAML development because each of the concrete
XAML elements inherits members from some base class in its hierarchy. Often these
members include properties that can be set as attributes on the element, or events that
can be handled. FrameworkElement is the concrete base UI class of WPF at the WPF
framework level. When designing UI, you will use various shape, panel, decorator, or
control classes, which all derive from FrameworkElement. A related base class,
FrameworkContentElement, supports document-oriented elements that work well for a
flow layout presentation, using APIs that deliberately mirror the APIs in
FrameworkElement. The combination of attributes at the element level and a CLR object
model provides you with a set of common properties that are settable on most concrete
XAML elements, regardless of the specific XAML element and its underlying type.

XAML security
XAML is a markup language that directly represents object instantiation and execution.
Therefore, elements created in XAML have the same ability to interact with system
resources (network access, file system IO, for example) as the equivalent generated code
does. XAML loaded in to a fully trusted app has the same access to the system resources
as the hosting app does.

Code Access Security (CAS) in WPF

WPF for .NET Framework supports Code Access Security (CAS). This means that WPF
content running in the internet zone has reduced execution permissions. "Loose XAML"
(pages of noncompiled XAML interpreted at load time by a XAML viewer) and XBAP are
usually run in this internet zone and use the same permission set. However, XAML
loaded in to a fully trusted application has the same access to the system resources as
the hosting application does. For more information, see WPF Partial Trust Security.

Loading XAML from code

XAML can be used to define all of the UI, but it is sometimes also appropriate to define
just a piece of the UI in XAML. This capability could be used to enable partial
customization, local storage of information, using XAML to provide a business object, or
a variety of possible scenarios. The key to these scenarios is the XamlReader class and its
Load method. The input is a XAML file, and the output is an object that represents all of
the run-time tree of objects that was created from that markup. You then can insert the
object to be a property of another object that already exists in the app. So long as the
property is an appropriate property in the content model that has eventual display
capabilities and that will notify the execution engine that new content has been added
into the app, you can modify a running app's contents easily by loading in XAML. For
.NET Framework, this capability is generally only available in full-trust applications,
because of the obvious security implications of loading files into applications as they
run.
See also
XAML Syntax In Detail
XAML and Custom Classes for WPF
XAML Namespace (x:) Language Features
WPF XAML Extensions
Base Elements Overview
Trees in WPF
XAML Syntax In Detail
Article • 02/06/2023

This topic defines the terms that are used to describe the elements of XAML syntax.
These terms are used frequently throughout the remainder of this documentation, both
for WPF documentation specifically and for the other frameworks that use XAML or the
basic XAML concepts enabled by the XAML language support at the System.Xaml level.
This topic expands on the basic terminology introduced in the topic XAML in WPF.

The XAML Language Specification

The XAML syntax terminology defined here is also defined or referenced within the
XAML language specification. XAML is a language based on XML and follows or expands
upon XML structural rules. Some of the terminology is shared from or is based on the
terminology commonly used when describing the XML language or the XML document
object model.

For more information about the XAML language specification, download [MS-XAML]
from the Microsoft Download Center.

XAML and CLR

XAML is a markup language. The common language runtime (CLR), as implied by its
name, enables runtime execution. XAML is not by itself one of the common languages
that is directly consumed by the CLR runtime. Instead, you can think of XAML as
supporting its own type system. The particular XAML parsing system that is used by
WPF is built on the CLR and the CLR type system. XAML types are mapped to CLR types
to instantiate a run time representation when the XAML for WPF is parsed. For this
reason, the remainder of discussion of syntax in this document will include references to
the CLR type system, even though the equivalent syntax discussions in the XAML
language specification do not. (Per the XAML language specification level, XAML types
could be mapped to any other type system, which does not have to be the CLR, but that
would require the creation and use of a different XAML parser.)

Members of Types and Class Inheritance

Properties and events as they appear as XAML members of a WPF type are often
inherited from base types. For example, consider this example: <Button
Background="Blue" .../> . The Background property is not an immediately declared
property on the Button class, if you were to look at the class definition, reflection results,
or the documentation. Instead, Background is inherited from the base Control class.

The class inheritance behavior of WPF XAML elements is a significant departure from a
schema-enforced interpretation of XML markup. Class inheritance can become complex,
particularly when intermediate base classes are abstract, or when interfaces are involved.
This is one reason that the set of XAML elements and their permissible attributes is
difficult to represent accurately and completely using the schema types that are typically
used for XML programming, such as DTD or XSD format. Another reason is that
extensibility and type-mapping features of the XAML language itself preclude
completeness of any fixed representation of the permissible types and members.

Object Element Syntax

Object element syntax is the XAML markup syntax that instantiates a CLR class or
structure by declaring an XML element. This syntax resembles the element syntax of
other markup languages such as HTML. Object element syntax begins with a left angle
bracket (<), followed immediately by the type name of the class or structure being
instantiated. Zero or more spaces can follow the type name, and zero or more attributes
may also be declared on the object element, with one or more spaces separating each
attribute name="value" pair. Finally, one of the following must be true:

The element and tag must be closed by a forward slash (/) followed immediately
by a right angle bracket (>).

The opening tag must be completed by a right angle bracket (>). Other object
elements, property elements, or inner text, can follow the opening tag. Exactly
what content may be contained here is typically constrained by the object model
of the element. The equivalent closing tag for the object element must also exist,
in proper nesting and balance with other opening and closing tag pairs.

XAML as implemented by .NET has a set of rules that map object elements into types,
attributes into properties or events, and XAML namespaces to CLR namespaces plus
assembly. For WPF and .NET, XAML object elements map to .NET types as defined in
referenced assemblies, and the attributes map to members of those types. When you
reference a CLR type in XAML, you have access to the inherited members of that type as
well.

For example, the following example is object element syntax that instantiates a new
instance of the Button class, and also specifies a Name attribute and a value for that
attribute:
XAML

The following example is object element syntax that also includes XAML content
property syntax. The inner text contained within will be used to set the TextBox XAML
content property, Text.

XAML

<TextBox>This is a Text Box</TextBox>

Content Models
A class might support a usage as a XAML object element in terms of the syntax, but that
element will only function properly in an application or page when it is placed in an
expected position of an overall content model or element tree. For example, a
MenuItem should typically only be placed as a child of a MenuBase derived class such as
Menu. Content models for specific elements are documented as part of the remarks on
the class pages for controls and other WPF classes that can be used as XAML elements.

Properties of Object Elements

Properties in XAML are set by a variety of possible syntaxes. Which syntax can be used
for a particular property will vary, based on the underlying type system characteristics of
the property that you are setting.

By setting values of properties, you add features or characteristics to objects as they

exist in the run time object graph. The initial state of the created object from a object
element is based on the parameterless constructor behavior. Typically, your application
will use something other than a completely default instance of any given object.

Attribute Syntax (Properties)

Attribute syntax is the XAML markup syntax that sets a value for a property by declaring
an attribute on an existing object element. The attribute name must match the CLR
member name of the property of the class that backs the relevant object element. The
attribute name is followed by an assignment operator (=). The attribute value must be a
string enclosed within quotes.
７ Note

You can use alternating quotes to place a literal quotation mark within an attribute.
For instance you can use single quotes as a means to declare a string that contains
a double quote character within it. Whether you use single or double quotes, you
should use a matching pair for opening and closing the attribute value string. There
are also escape sequences or other techniques available for working around
character restrictions imposed by any particular XAML syntax. See XML Character
Entities and XAML.

In order to be set through attribute syntax, a property must be public and must be
writeable. The value of the property in the backing type system must be a value type, or
must be a reference type that can be instantiated or referenced by a XAML processor
when accessing the relevant backing type.

For WPF XAML events, the event that is referenced as the attribute name must be public
and have a public delegate.

The property or event must be a member of the class or structure that is instantiated by
the containing object element.

Processing of Attribute Values

The string value contained within the opening and closing quotation marks is processed
by a XAML processor. For properties, the default processing behavior is determined by
the type of the underlying CLR property.

The attribute value is filled by one of the following, using this processing order:

1. If the XAML processor encounters a curly brace, or an object element that derives
from MarkupExtension, then the referenced markup extension is evaluated first
rather than processing the value as a string, and the object returned by the markup
extension is used as the value. In many cases the object returned by a markup
extension will be a reference to an existing object, or an expression that defers
evaluation until run time, and is not a newly instantiated object.

2. If the property is declared with an attributed TypeConverter, or the value type of

that property is declared with an attributed TypeConverter, the string value of the
attribute is submitted to the type converter as a conversion input, and the
converter will return a new object instance.
3. If there is no TypeConverter, a direct conversion to the property type is attempted.
This final level is a direct conversion at the parser-native value between XAML
language primitive types, or a check for the names of named constants in an
enumeration (the parser then accesses the matching values).

Enumeration Attribute Values

Enumerations in XAML are processed intrinsically by XAML parsers, and the members of
an enumeration should be specified by specifying the string name of one of the
enumeration's named constants.

For nonflag enumeration values, the native behavior is to process the string of an
attribute value and resolve it to one of the enumeration values. You do not specify the
enumeration in the format Enumeration.Value, as you do in code. Instead, you specify
only Value, and Enumeration is inferred by the type of the property you are setting. If
you specify an attribute in the Enumeration.Value form, it will not resolve correctly.

For flagwise enumerations, the behavior is based on the Enum.Parse method. You can
specify multiple values for a flagwise enumeration by separating each value with a
comma. However, you cannot combine enumeration values that are not flagwise. For
instance, you cannot use the comma syntax to attempt to create a Trigger that acts on
multiple conditions of a nonflag enumeration:

XAML

<!--This will not compile, because Visibility is not a flagwise

enumeration.-->
...
<Trigger Property="Visibility" Value="Collapsed,Hidden">
<Setter ... />
</Trigger>
...

Flagwise enumerations that support attributes that are settable in XAML are rare in WPF.
However, one such enumeration is StyleSimulations. You could, for instance, use the
comma-delimited flagwise attribute syntax to modify the example provided in the
Remarks for the Glyphs class; StyleSimulations = "BoldSimulation" could become
StyleSimulations = "BoldSimulation,ItalicSimulation" . KeyBinding.Modifiers is
another property where more than one enumeration value can be specified. However,
this property happens to be a special case, because the ModifierKeys enumeration
supports its own type converter. The type converter for modifiers uses a plus sign (+) as
a delimiter rather than a comma (,). This conversion supports the more traditional syntax
to represent key combinations in Microsoft Windows programming, such as "Ctrl+Alt".
Properties and Event Member Name References
When specifying an attribute, you can reference any property or event that exists as a
member of the CLR type you instantiated for the containing object element.

Or, you can reference an attached property or attached event, independent of the
containing object element. (Attached properties are discussed in an upcoming section.)

You can also name any event from any object that is accessible through the default
namespace by using a typeName.event partially qualified name; this syntax supports
attaching handlers for routed events where the handler is intended to handle events
routing from child elements, but the parent element does not also have that event in its
members table. This syntax resembles an attached event syntax, but the event here is
not a true attached event. Instead, you are referencing an event with a qualified name.
For more information, see Routed Events Overview.

For some scenarios, property names are sometimes provided as the value of an
attribute, rather than the attribute name. That property name can also include qualifiers,
such as the property specified in the form ownerType.dependencyPropertyName. This
scenario is common when writing styles or templates in XAML. The processing rules for
property names provided as an attribute value are different, and are governed by the
type of the property being set or by the behaviors of particular WPF subsystems. For
details, see Styling and Templating.

Another usage for property names is when an attribute value describes a property-
property relationship. This feature is used for data binding and for storyboard targets,
and is enabled by the PropertyPath class and its type converter. For a more complete
description of the lookup semantics, see PropertyPath XAML Syntax.

Property Element Syntax

Property element syntax is a syntax that diverges somewhat from the basic XML syntax
rules for elements. In XML, the value of an attribute is a de facto string, with the only
possible variation being which string encoding format is being used. In XAML, you can
assign other object elements to be the value of a property. This capability is enabled by
the property element syntax. Instead of the property being specified as an attribute
within the element tag, the property is specified using an opening element tag in
elementTypeName.propertyName form, the value of the property is specified within, and
then the property element is closed.

Specifically, the syntax begins with a left angle bracket (<), followed immediately by the
type name of the class or structure that the property element syntax is contained within.
This is followed immediately by a single dot (.), then by the name of a property, then by
a right angle bracket (>). As with attribute syntax, that property must exist within the
declared public members of the specified type. The value to be assigned to the property
is contained within the property element. Typically, the value is given as one or more
object elements, because specifying objects as values is the scenario that property
element syntax is intended to address. Finally, an equivalent closing tag specifying the
same elementTypeName.propertyName combination must be provided, in proper
nesting and balance with other element tags.

For example, the following is property element syntax for the ContextMenu property of
a Button.

XAML

<Button>
<Button.ContextMenu>
<ContextMenu>
<MenuItem Header="1">First item</MenuItem>
<MenuItem Header="2">Second item</MenuItem>
</ContextMenu>
</Button.ContextMenu>
Right-click me!</Button>

The value within a property element can also be given as inner text, in cases where the
property type being specified is a primitive value type, such as String, or an enumeration
where a name is specified. These two usages are somewhat uncommon, because each of
these cases could also use a simpler attribute syntax. One scenario for filling a property
element with a string is for properties that are not the XAML content property but still
are used for representation of UI text, and particular white-space elements such as
linefeeds are required to appear in that UI text. Attribute syntax cannot preserve
linefeeds, but property element syntax can, so long as significant white-space
preservation is active (for details, see White space processing in XAML). Another
scenario is so that x:Uid Directive can be applied to the property element and thus mark
the value within as a value that should be localized in the WPF output BAML or by other
techniques.

A property element is not represented in the WPF logical tree. A property element is just
a particular syntax for setting a property, and is not an element that has an instance or
object backing it. (For details on the logical tree concept, see Trees in WPF.)

For properties where both attribute and property element syntax are supported, the two
syntaxes generally have the same result, although subtleties such as white-space
handling can vary slightly between syntaxes.
Collection Syntax
The XAML specification requires XAML processor implementations to identify properties
where the value type is a collection. The general XAML processor implementation in
.NET is based on managed code and the CLR, and it identifies collection types through
one of the following:

Type implements IList.

Type implements IDictionary.

Type derives from Array (for more information about arrays in XAML, see x:Array
Markup Extension.)

If the type of a property is a collection, then the inferred collection type does not need
to be specified in the markup as an object element. Instead, the elements that are
intended to become the items in the collection are specified as one or more child
elements of the property element. Each such item is evaluated to an object during
loading and added to the collection by calling the Add method of the implied collection.
For example, the Triggers property of Style takes the specialized collection type
TriggerCollection, which implements IList. It is not necessary to instantiate a
TriggerCollection object element in the markup. Instead, you specify one or more
Trigger items as elements within the Style.Triggers property element, where Trigger (or
a derived class) is the type expected as the item type for the strongly typed and implicit
TriggerCollection.

XAML

<Style x:Key="SpecialButton" TargetType="{x:Type Button}">

<Style.Triggers>
<Trigger Property="Button.IsMouseOver" Value="true">
<Setter Property = "Background" Value="Red"/>
</Trigger>
<Trigger Property="Button.IsPressed" Value="true">
<Setter Property = "Foreground" Value="Green"/>
</Trigger>
</Style.Triggers>
</Style>

A property may be both a collection type and the XAML content property for that type
and derived types, which is discussed in the next section of this topic.

An implicit collection element creates a member in the logical tree representation, even
though it does not appear in the markup as an element. Usually the constructor of the
parent type performs the instantiation for the collection that is one of its properties, and
the initially empty collection becomes part of the object tree.

７ Note

The generic list and dictionary interfaces (IList<T> and IDictionary<TKey,TValue>)

are not supported for collection detection. However, you can use the List<T> class
as a base class, because it implements IList directly, or Dictionary<TKey,TValue> as
a base class, because it implements IDictionary directly.

In the .NET Reference pages for collection types, this syntax with the deliberate omission
of the object element for a collection is occasionally noted in the XAML syntax sections
as Implicit Collection Syntax.

With the exception of the root element, every object element in a XAML file that is
nested as a child element of another element is really an element that is one or both of
the following cases: a member of an implicit collection property of its parent element, or
an element that specifies the value of the XAML content property for the parent element
(XAML content properties will be discussed in an upcoming section). In other words, the
relationship of parent elements and child elements in a markup page is really a single
object at the root, and every object element beneath the root is either a single instance
that provides a property value of the parent, or one of the items within a collection that
is also a collection-type property value of the parent. This single-root concept is
common with XML, and is frequently reinforced in the behavior of APIs that load XAML
such as Load.

The following example is a syntax with the object element for a collection
(GradientStopCollection) specified explicitly.

XAML

Note that it is not always possible to explicitly declare the collection. For instance,
attempting to declare TriggerCollection explicitly in the previously shown Triggers
example would fail. Explicitly declaring the collection requires that the collection class
must support a parameterless constructor, and TriggerCollection does not have a
parameterless constructor.

XAML Content Properties

XAML content syntax is a syntax that is only enabled on classes that specify the
ContentPropertyAttribute as part of their class declaration. The
ContentPropertyAttribute references the property name that is the content property for
that type of element (including derived classes). When processed by a XAML processor,
any child elements or inner text that are found between the opening and closing tags of
the object element will be assigned to be the value of the XAML content property for
that object. You are permitted to specify explicit property elements for the content
property, but this usage is not generally shown in the XAML syntax sections in the .NET
reference. The explicit/verbose technique has occasional value for markup clarity or as a
matter of markup style, but usually the intent of a content property is to streamline the
markup so that elements that are intuitively related as parent-child can be nested
directly. Property element tags for other properties on an element are not assigned as
"content" per a strict XAML language definition; they are processed previously in the
XAML parser's processing order and are not considered to be "content".

XAML Content Property Values Must Be Contiguous

The value of a XAML content property must be given either entirely before or entirely
after any other property elements on that object element. This is true whether the value
of a XAML content property is specified as a string, or as one or more objects. For
example, the following markup does not parse:

XAML

<Button>I am a
<Button.Background>Blue</Button.Background>
blue button</Button>

This is illegal essentially because if this syntax were made explicit by using property
element syntax for the content property, then the content property would be set twice:

XAML

<Button>
<Button.Content>I am a </Button.Content>
<Button.Background>Blue</Button.Background>
<Button.Content> blue button</Button.Content>
</Button>
A similarly illegal example is if the content property is a collection, and child elements
are interspersed with property elements:

XAML

<StackPanel>
<Button>This example</Button>
<StackPanel.Resources>
<SolidColorBrush x:Key="BlueBrush" Color="Blue"/>
</StackPanel.Resources>
<Button>... is illegal XAML</Button>
</StackPanel>

Content Properties and Collection Syntax

Combined
In order to accept more than a single object element as content, the type of the content
property must specifically be a collection type. Similar to property element syntax for
collection types, a XAML processor must identify types that are collection types. If an
element has a XAML content property and the type of the XAML content property is a
collection, then the implied collection type does not need to be specified in the markup
as an object element and the XAML content property does not need to be specified as a
property element. Therefore the apparent content model in the markup can now have
more than one child element assigned as the content. The following is content syntax
for a Panel derived class. All Panel derived classes establish the XAML content property
to be Children, which requires a value of type UIElementCollection.

XAML

Note that neither the property element for Children nor the element for the
UIElementCollection is required in the markup. This is a design feature of XAML so that
recursively contained elements that define a UI are more intuitively represented as a tree
of nested elements with immediate parent-child element relationships, without
intervening property element tags or collection objects. In fact, UIElementCollection
cannot be specified explicitly in markup as an object element, by design. Because its
only intended use is as an implicit collection, UIElementCollection does not expose a
public parameterless constructor and thus cannot be instantiated as an object element.

Mixing Property Elements and Object Elements in an

Object with a Content Property
The XAML specification declares that a XAML processor can enforce that object
elements that are used to fill the XAML content property within an object element must
be contiguous, and must not be mixed. This restriction against mixing property
elements and content is enforced by the WPF XAML processors.

You can have a child object element as the first immediate markup within an object
element. Then you can introduce property elements. Or, you can specify one or more
property elements, then content, then more property elements. But once a property
element follows content, you cannot introduce any further content, you can only add
property elements.

This content / property element order requirement does not apply to inner text used as
content. However, it is still a good markup style to keep inner text contiguous, because
significant white space will be difficult to detect visually in the markup if property
elements are interspersed with inner text.

XAML Namespaces
None of the preceding syntax examples specified a XAML namespace other than the
default XAML namespace. In typical WPF applications, the default XAML namespace is
specified to be the WPF namespace. You can specify XAML namespaces other than the
default XAML namespace and still use similar syntax. But then, anywhere where a class is
named that is not accessible within the default XAML namespace, that class name must
be preceded with the prefix of the XAML namespace as mapped to the corresponding
CLR namespace. For example, <custom:Example/> is object element syntax to instantiate
an instance of the Example class, where the CLR namespace containing that class (and
possibly the external assembly information that contains backing types) was previously
mapped to the custom prefix.

For more information about XAML namespaces, see XAML Namespaces and Namespace
Mapping for WPF XAML.
Markup Extensions
XAML defines a markup extension programming entity that enables an escape from the
normal XAML processor handling of string attribute values or object elements, and
defers the processing to a backing class. The character that identifies a markup
extension to a XAML processor when using attribute syntax is the opening curly brace
({), followed by any character other than a closing curly brace (}). The first string
following the opening curly brace must reference the class that provides the particular
extension behavior, where the reference may omit the substring "Extension" if that
substring is part of the true class name. Thereafter, a single space may appear, and then
each succeeding character is used as input by the extension implementation, up until
the closing curly brace is encountered.

The .NET XAML implementation uses the MarkupExtension abstract class as the basis for
all of the markup extensions supported by WPF as well as other frameworks or
technologies. The markup extensions that WPF specifically implements are often
intended to provide a means to reference other existing objects, or to make deferred
references to objects that will be evaluated at run time. For example, a simple WPF data
binding is accomplished by specifying the {Binding} markup extension in place of the
value that a particular property would ordinarily take. Many of the WPF markup
extensions enable an attribute syntax for properties where an attribute syntax would not
otherwise be possible. For example, a Style object is a relatively complex type that
contains a nested series of objects and properties. Styles in WPF are typically defined as
a resource in a ResourceDictionary, and then referenced through one of the two WPF
markup extensions that request a resource. The markup extension defers the evaluation
of the property value to a resource lookup and enables providing the value of the Style
property, taking type Style, in attribute syntax as in the following example:

<Button Style="{StaticResource MyStyle}">My button</Button>

Here, StaticResource identifies the StaticResourceExtension class providing the markup

extension implementation. The next string MyStyle is used as the input for the non-
default StaticResourceExtension constructor, where the parameter as taken from the
extension string declares the requested ResourceKey. MyStyle is expected to be the
x:Key value of a Style defined as a resource. The StaticResource Markup Extension usage
requests that the resource be used to provide the Style property value through static
resource lookup logic at load time.

For more information about markup extensions, see Markup Extensions and WPF XAML.
For a reference of markup extensions and other XAML programming features enabled in
the general .NET XAML implementation, see XAML Namespace (x:) Language Features.
For WPF-specific markup extensions, see WPF XAML Extensions.
Attached Properties
Attached properties are a programming concept introduced in XAML whereby
properties can be owned and defined by a particular type, but set as attributes or
property elements on any element. The primary scenario that attached properties are
intended for is to enable child elements in a markup structure to report information to a
parent element without requiring an extensively shared object model across all
elements. Conversely, attached properties can be used by parent elements to report
information to child elements. For more information on the purpose of attached
properties and how to create your own attached properties, see Attached Properties
Overview.

Attached properties use a syntax that superficially resembles property element syntax, in
that you also specify a typeName.propertyName combination. There are two important
differences:

You can use the typeName.propertyName combination even when setting an

attached property through attribute syntax. Attached properties are the only case
where qualifying the property name is a requirement in an attribute syntax.

You can also use property element syntax for attached properties. However, for
typical property element syntax, the typeName you specify is the object element
that contains the property element. If you are referring to an attached property,
then the typeName is the class that defines the attached property, not the
containing object element.

Attached Events
Attached events are another programming concept introduced in XAML where events
can be defined by a specific type, but handlers may be attached on any object element.
In the WOF implementation, often the type that defines an attached event is a static
type that defines a service, and sometimes those attached events are exposed by a
routed event alias in types that expose the service. Handlers for attached events are
specified through attribute syntax. As with attached events, the attribute syntax is
expanded for attached events to allow a typeName.eventName usage, where typeName
is the class that provides Add and Remove event handler accessors for the attached event
infrastructure, and eventName is the event name.

Anatomy of a XAML Root Element

The following table shows a typical XAML root element broken down, showing the
specific attributes of a root element:

Attribute Description

<Page Opening object element

of the root element

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" The default (WPF) XAML

namespace

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

XAML namespace

x:Class="ExampleNamespace.ExampleCode" The partial class

declaration that connects
markup to any code-
behind defined for the
partial class

> End of object element for

the root. Object is not
closed yet because the
element contains child
elements

Optional and Nonrecommended XAML Usages

The following sections describe XAML usages that are technically supported by XAML
processors, but that produce verbosity or other aesthetic issues that interfere with XAML
files remaining human-readable when you develop applications that contain XAML
sources.

Optional Property Element Usages

Optional property element usages include explicitly writing out element content
properties that the XAML processor considers implicit. For example, when you declare
the contents of a Menu, you could choose to explicitly declare the Items collection of
the Menu as a <Menu.Items> property element tag, and place each MenuItem within
<Menu.Items> , rather than using the implicit XAML processor behavior that all child

elements of a Menu must be a MenuItem and are placed in the Items collection.
Sometimes the optional usages can help to visually clarify the object structure as
represented in the markup. Or sometimes an explicit property element usage can avoid
markup that is technically functional but visually confusing, such as nested markup
extensions within an attribute value.

Full typeName.memberName Qualified Attributes

The typeName.memberName form for an attribute actually works more universally than
just the routed event case. But in other situations that form is superfluous and you
should avoid it, if only for reasons of markup style and readability. In the following
example, each of the three references to the Background attribute are completely
equivalent:

XAML

<Button Background="Blue">Background</Button>
<Button Button.Background="Blue">Button.Background</Button>
<Button Control.Background="Blue">Control.Background</Button>

Button.Background works because the qualified lookup for that property on Button is

successful (Background was inherited from Control) and Button is the class of the object
element or a base class. Control.Background works because the Control class actually
defines Background and Control is a Button base class.

However, the following typeName.memberName form example does not work and is
thus shown commented:

XAML

Label is another derived class of Control, and if you had specified Label.Background
within a Label object element, this usage would have worked. However, because Label is
not the class or base class of Button, the specified XAML processor behavior is to then
process Label.Background as an attached property. Label.Background is not an available
attached property, and this usage fails.

baseTypeName.memberName Property Elements

In an analogous way to how the typeName.memberName form works for attribute
syntax, a baseTypeName.memberName syntax works for property element syntax. For
instance, the following syntax works:

XAML
<Button>Control.Background PE
<Control.Background>
<LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
<GradientStop Color="Yellow" Offset="0.0" />
<GradientStop Color="LimeGreen" Offset="1.0" />
</LinearGradientBrush>
</Control.Background>
</Button>

Here, the property element was given as Control.Background even though the property
element was contained in Button .

But just like typeName.memberName form for attributes, baseTypeName.memberName

is poor style in markup, and you should avoid it.

See also
XAML in WPF
XAML Namespace (x:) Language Features
WPF XAML Extensions
Dependency Properties Overview
TypeConverters and XAML
XAML and Custom Classes for WPF
Code-Behind and XAML in WPF
Article • 08/10/2023

Code-behind is a term used to describe the code that is joined with markup-defined
objects, when a XAML page is markup-compiled. This topic describes requirements for
code-behind as well as an alternative inline code mechanism for code in XAML.

This topic contains the following sections:

Prerequisites

Code-Behind and the XAML Language

Code-behind, Event Handler, and Partial Class Requirements in WPF

x:Code

Inline Code Limitations

Prerequisites
This topic assumes that you have read the XAML in WPF and have some basic
knowledge of the CLR and object-oriented programming.

Code-Behind and the XAML Language

The XAML language includes language-level features that make it possible to associate
code files with markup files, from the markup file side. Specifically, the XAML language
defines the language features x:Class Directive, x:Subclass Directive, and x:ClassModifier
Directive. Exactly how the code should be produced, and how to integrate markup and
code, is not part of what the XAML language specifies. It is left up to frameworks such as
WPF to determine how to integrate the code, how to use XAML in the application and
programming models, and the build actions or other support that all this requires.

Code-behind, Event Handler, and Partial Class

Requirements in WPF
The partial class must derive from the type that backs the root element.

Note that under the default behavior of the markup compile build actions, you can
leave the derivation blank in the partial class definition on the code-behind side.
The compiled result will assume the page root's backing type to be the basis for
the partial class, even if it not specified. However, relying on this behavior is not a
best practice.

The event handlers you write in the code-behind must be instance methods and
cannot be static methods. These methods must be defined by the partial class
within the CLR namespace identified by x:Class . You cannot qualify the name of
an event handler to instruct a XAML processor to look for an event handler for
event wiring in a different class scope.

The handler must match the delegate for the appropriate event in the backing type
system.

For the Microsoft Visual Basic language specifically, you can use the language-
specific Handles keyword to associate handlers with instances and events in the
handler declaration, instead of attaching handlers with attributes in XAML.
However, this technique does have some limitations because the Handles keyword
cannot support all of the specific features of the WPF event system, such as certain
routed event scenarios or attached events. For details, see Visual Basic and WPF
Event Handling.

x:Code
x:Code is a directive element defined in XAML. An x:Code directive element can contain
inline programming code. The code that is defined inline can interact with the XAML on
the same page. The following example illustrates inline C# code. Notice that the code is
inside the x:Code element and that the code must be surrounded by <CDATA[ ... ]]> to
escape the contents for XML, so that a XAML processor (interpreting either the XAML
schema or the WPF schema) will not try to interpret the contents literally as XML.

XAML

Inline Code Limitations

You should consider avoiding or limiting the use of inline code. In terms of architecture
and coding philosophy, maintaining a separation between markup and code-behind
keeps the designer and developer roles much more distinct. On a more technical level,
the code that you write for inline code can be awkward to write, because you are always
writing into the XAML generated partial class, and can only use the default XML
namespace mappings. Because you cannot add using statements, you must fully qualify
many of the API calls that you make. The default WPF mappings include most but not all
CLR namespaces that are present in the WPF assemblies; you will have to fully qualify
calls to types and members contained within the other CLR namespaces. You also
cannot define anything beyond the partial class in the inline code, and all user code
entities you reference must exist as a member or variable within the generated partial
class. Other language specific programming features, such as macros or #ifdef against
global variables or build variables, are also not available. For more information, see
x:Code Intrinsic XAML Type.

See also
XAML in WPF
x:Code Intrinsic XAML Type
Building a WPF Application
XAML Syntax In Detail
XAML and Custom Classes for WPF
Article • 02/06/2023

XAML as implemented in common language runtime (CLR) frameworks supports the

ability to define a custom class or structure in any common language runtime (CLR)
language, and then access that class using XAML markup. You can use a mixture of
Windows Presentation Foundation (WPF)-defined types and your custom types within
the same markup file, typically by mapping the custom types to a XAML namespace
prefix. This topic discusses the requirements that a custom class must satisfy to be
usable as a XAML element.

Custom Classes in Applications or Assemblies

Custom classes that are used in XAML can be defined in two distinct ways: within the
code-behind or other code that produces the primary Windows Presentation
Foundation (WPF) application, or as a class in a separate assembly, such as an
executable or DLL used as a class library. Each of these approaches has particular
advantages and disadvantages.

The advantage of creating a class library is that any such custom classes can be
shared across many different possible applications. A separate library also makes
versioning issues of applications easier to control, and simplifies creating a class
where the intended class usage is as a root element on a XAML page.

The advantage of defining the custom classes in the application is that this
technique is relatively lightweight and minimizes the deployment and testing
issues encountered when you introduce separate assemblies beyond the main
application executable.

Whether defined in the same or different assembly, custom classes need to be

mapped between CLR namespace and XML namespace in order to be used in
XAML as elements. See XAML Namespaces and Namespace Mapping for WPF
XAML.

Requirements for a Custom Class as a XAML

Element
In order to be able to be instantiated as an object element, your class must meet the
following requirements:
Your custom class must be public and support a default (parameterless) public
constructor. (See following section for notes regarding structures.)

Your custom class must not be a nested class. Nested classes and the "dot" in their
general CLR usage syntax interfere with other WPF and/or XAML features such as
attached properties.

In addition to enabling object element syntax, your object definition also enables
property element syntax for any other public properties that take that object as the
value type. This is because the object can now be instantiated as an object element and
can fill the property element value of such a property.

Structures
Structures that you define as custom types are always able to be constructed in XAML in
WPF .This is because the CLR compilers implicitly create a parameterless constructor for
a structure that initializes all property values to their defaults. In some cases, the default
construction behavior and/or object element usage for a structure is not desirable. This
might be because the structure is intended to fill values and function conceptually as a
union, where the values contained might have mutually exclusive interpretations and
thus none of its properties are settable. A WPF example of such a structure is
GridLength. Generally, such structures should implement a type converter such that the
values can be expressed in attribute form, using string conventions that create the
different interpretations or modes of the structure's values. The structure should also
expose similar behavior for code construction through a non-parameterless constructor.

Requirements for Properties of a Custom Class

as XAML Attributes
Properties must reference a by-value type (such as a primitive), or use a class for type
that has either a parameterless constructor or a dedicated type converter that a XAML
processor can access. In the CLR XAML implementation, XAML processors either find
such converters through native support for language primitives, or through application
of TypeConverterAttribute to a type or member in backing type definitions

Alternatively, the property may reference an abstract class type, or an interface. For
abstract classes or interfaces, the expectation for XAML parsing is that the property
value must be filled with practical class instances that implement the interface, or
instances of types that derive from the abstract class.
Properties can be declared on an abstract class, but can only be set on practical classes
that derive from the abstract class. This is because creating the object element for the
class at all requires a public parameterless constructor on the class.

TypeConverter Enabled Attribute Syntax

If you provide a dedicated, attributed type converter at the class level, the applied type
conversion enables attribute syntax for any property that needs to instantiate that type.
A type converter does not enable object element usage of the type; only the presence of
a parameterless constructor for that type enables object element usage. Therefore,
properties that are type-converter enabled are generally speaking not usable in property
syntax, unless the type itself also supports object element syntax. The exception to this
is that you can specify a property element syntax, but have the property element contain
a string. That usage is really essentially equivalent to an attribute syntax usage, and such
a usage is not common unless there is a need for more robust white-space handling of
the attribute value. For example, the following is a property element usage that takes a
string, and the attribute usage equivalent:

XAML

<Button>Hallo!
<Button.Language>
de-DE
</Button.Language>
</Button>

XAML

<Button Language="de-DE">Hallo!</Button>

Examples of properties where attribute syntax is allowed but property element syntax
that contains an object element is disallowed through XAML are various properties that
take the Cursor type. The Cursor class has a dedicated type converter CursorConverter,
but does not expose a parameterless constructor, so the Cursor property can only be set
through attribute syntax even though the actual Cursor type is a reference type.

Per-Property Type Converters

Alternatively, the property itself may declare a type converter at the property level. This
enables a "mini language" that instantiates objects of the type of the property inline, by
processing incoming string values of the attribute as input for a ConvertFrom operation
based on the appropriate type. Typically this is done to provide a convenience accessor,
and not as the sole means to enable setting a property in XAML. However, it is also
possible to use type converters for attributes where you want to use existing CLR types
that do not supply either a parameterless constructor or an attributed type converter.
Examples from the WPF API are certain properties that take the CultureInfo type. In this
case, WPF used the existing Microsoft .NET Framework CultureInfo type to better
address compatibility and migration scenarios that were used in earlier versions of
frameworks, but the CultureInfo type did not support the necessary constructors or
type-level type conversion to be usable as a XAML property value directly.

Whenever you expose a property that has a XAML usage, particularly if you are a control
author, you should strongly consider backing that property with a dependency property.
This is particularly true if you use the existing Windows Presentation Foundation (WPF)
implementation of the XAML processor, because you can improve performance by using
DependencyProperty backing. A dependency property will expose property system
features for your property that users will come to expect for a XAML accessible property.
This includes features such as animation, data binding, and style support. For more
information, see Custom Dependency Properties and XAML Loading and Dependency
Properties.

Writing and Attributing a Type Converter

You occasionally will need to write a custom TypeConverter derived class to provide type
conversion for your property type. For instructions on how to derive from and create a
type converter that can support XAML usages, and how to apply the
TypeConverterAttribute, see TypeConverters and XAML.

Requirements for XAML Event Handler

Attribute Syntax on Events of a Custom Class
To be usable as a CLR event, the event must be exposed as a public event on a class that
supports a parameterless constructor, or on an abstract class where the event can be
accessed on derived classes. In order to be used conveniently as a routed event, your
CLR event should implement explicit add and remove methods, which add and remove
handlers for the CLR event signature and forward those handlers to the AddHandler and
RemoveHandler methods. These methods add or remove the handlers to the routed
event handler store on the instance that the event is attached to.

７ Note
It is possible to register handlers directly for routed events using AddHandler, and
to deliberately not define a CLR event that exposes the routed event. This is not
generally recommended because the event will not enable XAML attribute syntax
for attaching handlers, and your resulting class will offer a less transparent XAML
view of that type's capabilities.

Writing Collection Properties

Properties that take a collection type have a XAML syntax that enables you to specify
objects that are added to the collection. This syntax has two notable features.

The object that is the collection object does not need to be specified in object
element syntax. The presence of that collection type is implicit whenever you
specify a property in XAML that takes a collection type.

Child elements of the collection property in markup are processed to become

members of the collection. Ordinarily, the code access to the members of a
collection is performed through list/dictionary methods such as Add , or through an
indexer. But XAML syntax does not support methods or indexers (exception: XAML
2009 can support methods, but using XAML 2009 restricts the possible WPF
usages; see XAML 2009 Language Features). Collections are obviously a very
common requirement for building a tree of elements, and you need some way to
populate these collections in declarative XAML. Therefore, child elements of a
collection property are processed by adding them to the collection that is the
collection property type value.

The .NET Framework XAML Services implementation and thus the WPF XAML processor
uses the following definition for what constitutes a collection property. The property
type of the property must implement one of the following:

Implements IList.

Implements IDictionary.

Derives from Array (for more information about arrays in XAML, see x:Array
Markup Extension.)

Implements IAddChild (an interface defined by WPF).

Each of these types in CLR has an Add method, which is used by the XAML processor to
add items to the underlying collection when creating the object graph.
７ Note

The generic List and Dictionary interfaces (IList<T> and

IDictionary<TKey,TValue>) are not supported for collection detection by the WPF
XAML processor. However, you can use the List<T> class as a base class, because it
implements IList directly, or Dictionary<TKey,TValue> as a base class, because it
implements IDictionary directly.

When you declare a property that takes a collection, be cautious about how that
property value is initialized in new instances of the type. If you are not implementing the
property as a dependency property, then having the property use a backing field that
calls the collection type constructor is adequate. If your property is a dependency
property, then you may need to initialize the collection property as part of the default
type constructor. This is because a dependency property takes its default value from
metadata, and you typically do not want the initial value of a collection property to be a
static, shared collection. There should be a collection instance per each containing type
instance. For more information, see Custom Dependency Properties.

You can implement a custom collection type for your collection property. Because of
implicit collection property treatment, the custom collection type does not need to
provide a parameterless constructor in order to be used in XAML implicitly. However,
you can optionally provide a parameterless constructor for the collection type. This can
be a worthwhile practice. Unless you do provide a parameterless constructor, you
cannot explicitly declare the collection as an object element. Some markup authors
might prefer to see the explicit collection as a matter of markup style. Also, a
parameterless constructor can simplify the initialization requirements when you create
new objects that use your collection type as a property value.

Declaring XAML Content Properties

The XAML language defines the concept of a XAML content property. Each class that is
usable in object syntax can have exactly one XAML content property. To declare a
property to be the XAML content property for your class, apply the
ContentPropertyAttribute as part of the class definition. Specify the name of the
intended XAML content property as the Name in the attribute. The property is specified
as a string by name, not as a reflection construct such as PropertyInfo.

You can specify a collection property to be the XAML content property. This results in a
usage for that property whereby the object element can have one or more child
elements, without any intervening collection object elements or property element tags.
These elements are then treated as the value for the XAML content property and added
to the backing collection instance.

Some existing XAML content properties use the property type of Object . This enables a
XAML content property that can take primitive values such as a String as well as taking a
single reference object value. If you follow this model, your type is responsible for type
determination as well as the handling of possible types. The typical reason for an Object
content type is to support both a simple means of adding object content as a string
(which receives a default presentation treatment), or an advanced means of adding
object content that specifies a non-default presentation or additional data.

Serializing XAML
For certain scenarios, such as if you are a control author, you may also want to assure
that any object representation that can be instantiated in XAML can also be serialized
back to equivalent XAML markup. Serialization requirements are not described in this
topic. See Control Authoring Overview and Element Tree and Serialization.

See also
XAML in WPF
Custom Dependency Properties
Control Authoring Overview
Base Elements Overview
XAML Loading and Dependency Properties
Markup Extensions and WPF XAML
Article • 02/06/2023

This topic introduces the concept of markup extensions for XAML, including their syntax
rules, purpose, and the class object model that underlies them. Markup extensions are a
general feature of the XAML language and of the .NET implementation of XAML
services. This topic specifically details markup extensions for use in WPF XAML.

XAML Processors and Markup Extensions

Generally speaking, a XAML parser can either interpret an attribute value as a literal
string that can be converted to a primitive, or convert it to an object by some means.
One such means is by referencing a type converter; this is documented in the topic
TypeConverters and XAML. However, there are scenarios where different behavior is
required. For example, a XAML processor can be instructed that a value of an attribute
should not result in a new object in the object graph. Instead, the attribute should result
in an object graph that makes a reference to an already constructed object in another
part of the graph, or a static object. Another scenario is that a XAML processor can be
instructed to use a syntax that provides non-default arguments to the constructor of an
object. These are the types of scenarios where a markup extension can provide the
solution.

Basic Markup Extension Syntax

A markup extension can be implemented to provide values for properties in an attribute
usage, properties in a property element usage, or both.

When used to provide an attribute value, the syntax that distinguishes a markup
extension sequence to a XAML processor is the presence of the opening and closing
curly braces ({ and }). The type of markup extension is then identified by the string token
immediately following the opening curly brace.

When used in property element syntax, a markup extension is visually the same as any
other element used to provide a property element value: a XAML element declaration
that references the markup extension class as an element, enclosed within angle
brackets (<>).

XAML-Defined Markup Extensions

Several markup extensions exist that are not specific to the WPF implementation of
XAML, but are instead implementations of intrinsics or features of XAML as a language.
These markup extensions are implemented in the System.Xaml assembly as part of the
general .NET Framework XAML services, and are within the XAML language XAML
namespace. In terms of common markup usage, these markup extensions are typically
identifiable by the x: prefix in the usage. The MarkupExtension base class (also defined
in System.Xaml) provides the pattern that all markup extensions should use in order to
be supported in XAML readers and XAML writers, including in WPF XAML.

x:Type supplies the Type object for the named type. This facility is used most
frequently in styles and templates. For details, see x:Type Markup Extension.

x:Static produces static values. The values come from value-type code entities

that are not directly the type of a target property's value, but can be evaluated to
that type. For details, see x:Static Markup Extension.

x:Null specifies null as a value for a property and can be used either for
attributes or property element values. For details, see x:Null Markup Extension.

x:Array provides support for creation of general arrays in XAML syntax, for cases

where the collection support provided by WPF base elements and control models
is deliberately not used. For details, see x:Array Markup Extension.

７ Note

The x: prefix is used for the typical XAML namespace mapping of the XAML
language intrinsics, in the root element of a XAML file or production. For example,
the Visual Studio templates for WPF applications initiate a XAML file using this x:
mapping. You could choose a different prefix token in your own XAML namespace
mapping, but this documentation will assume the default x: mapping as a means
of identifying those entities that are a defined part of the XAML namespace for the
XAML language, as opposed to the WPF default namespace or other XAML
namespaces not related to a specific framework.

WPF-Specific Markup Extensions

The most common markup extensions used in WPF programming are those that
support resource references ( StaticResource and DynamicResource ), and those that
support data binding ( Binding ).
StaticResource provides a value for a property by substituting the value of an

already defined resource. A StaticResource evaluation is ultimately made at XAML

load time and does not have access to the object graph at run time. For details, see
StaticResource Markup Extension.

DynamicResource provides a value for a property by deferring that value to be a

run-time reference to a resource. A dynamic resource reference forces a new

lookup each time that such a resource is accessed and has access to the object
graph at run time. In order to get this access, DynamicResource concept is
supported by dependency properties in the WPF property system, and evaluated
expressions. Therefore you can only use DynamicResource for a dependency
property target. For details, see DynamicResource Markup Extension.

Binding provides a data bound value for a property, using the data context that
applies to the parent object at run time. This markup extension is relatively
complex, because it enables a substantial inline syntax for specifying a data
binding. For details, see Binding Markup Extension.

RelativeSource provides source information for a Binding that can navigate

several possible relationships in the run-time object tree. This provides specialized
sourcing for bindings that are created in multi-use templates or created in code
without full knowledge of the surrounding object tree. For details, see
RelativeSource MarkupExtension.

TemplateBinding enables a control template to use values for templated properties

that come from object-model-defined properties of the class that will use the
template. In other words, the property within the template definition can access a
context that only exists once the template is applied. For details, see
TemplateBinding Markup Extension. For more information on the practical use of
TemplateBinding , see Styling with ControlTemplates Sample .

ColorConvertedBitmap supports a relatively advanced imaging scenario. For details,

see ColorConvertedBitmap Markup Extension.

ComponentResourceKey and ThemeDictionary support aspects of resource lookup,

particularly for resources and themes that are packaged with custom controls. For
more information, see ComponentResourceKey Markup Extension,
ThemeDictionary Markup Extension, or Control Authoring Overview.

*Extension Classes
For both the general XAML language and WPF-specific markup extensions, the behavior
of each markup extension is identified to a XAML processor through a *Extension class
that derives from MarkupExtension, and provides an implementation of the
ProvideValue method. This method on each extension provides the object that is
returned when the markup extension is evaluated. The returned object is typically
evaluated based on the various string tokens that are passed to the markup extension.

For example, the StaticResourceExtension class provides the surface implementation of

actual resource lookup so that its ProvideValue implementation returns the object that is
requested, with the input of that particular implementation being a string that is used to
look up the resource by its x:Key . Much of this implementation detail is unimportant if
you are using an existing markup extension.

Some markup extensions do not use string token arguments. This is either because they
return a static or consistent value, or because context for what value should be returned
is available through one of the services passed through the serviceProvider parameter.

The *Extension naming pattern is for convenience and consistency. It is not necessary in
order for a XAML processor to identify that class as support for a markup extension. So
long as your codebase includes System.Xaml and uses .NET Framework XAML Services
implementations, all that is necessary to be recognized as a XAML markup extension is
to derive from MarkupExtension and to support a construction syntax. WPF defines
markup extension-enabling classes that do not follow the *Extension naming pattern,
for example Binding. Typically the reason for this is that the class supports scenarios
beyond pure markup extension support. In the case of Binding, that class supports run-
time access to methods and properties of the object for scenarios that have nothing to
do with XAML.

Extension Class Interpretation of Initialization Text

The string tokens following the markup extension name and still within the braces are
interpreted by a XAML processor in one of the following ways:

A comma always represents the separator or delimiter of individual tokens.

If the individual separated tokens do not contain any equals signs, each token is
treated as a constructor argument. Each constructor parameter must be given as
the type expected by that signature, and in the proper order expected by that
signature.

７ Note
A XAML processor must call the constructor that matches the argument count
of the number of pairs. For this reason, if you are implementing a custom
markup extension, do not provide multiple constructors with the same
argument count. The behavior for how a XAML processor behaves if more
than one markup extension constructor path with the same parameter count
exists is not defined, but you should anticipate that a XAML processor is
permitted to throw an exception on usage if this situation exists in the markup
extension type definitions.

If the individual separated tokens contain equals signs, then a XAML processor first
calls the parameterless constructor for the markup extension. Then, each
name=value pair is interpreted as a property name that exists on the markup
extension, and a value to assign to that property.

If there is a parallel result between the constructor behavior and the property
setting behavior in a markup extension, it does not matter which behavior you use.
It is more common usage to use the property = value pairs for markup extensions
that have more than one settable property, if only because it makes your markup
more intentional and you are less likely to accidentally transpose constructor
parameters. (When you specify property=value pairs, those properties may be in
any order.) Also, there is no guarantee that a markup extension supplies a
constructor parameter that sets every one of its settable properties. For example,
Binding is a markup extension, with many properties that are settable through the
extension in property = value form, but Binding only supports two constructors: a
parameterless constructor, and one that sets an initial path.

A literal comma cannot be passed to a markup extension without escapement.

Escape Sequences and Markup Extensions

Attribute handling in a XAML processor uses the curly braces as indicators of a markup
extension sequence. It is also possible to produce a literal curly brace character attribute
value if necessary, by entering an escape sequence using an empty curly brace pair
followed by the literal curly brace. See {} Escape Sequence - Markup Extension.

Nesting Markup Extensions in XAML Usage

Nesting of multiple markup extensions is supported, and each markup extension will be
evaluated deepest first. For example, consider the following usage:
XAML

In this usage, the x:Static statement is evaluated first and returns a string. That string
is then used as the argument for DynamicResource .

Markup Extensions and Property Element

Syntax
When used as an object element that fills a property element value, a markup extension
class is visually indistinguishable from a typical type-backed object element that can be
used in XAML. The practical difference between a typical object element and a markup
extension is that the markup extension is either evaluated to a typed value or deferred
as an expression. Therefore the mechanisms for any possible type errors of property
values for the markup extension will be different, similar to how a late-bound property is
treated in other programming models. An ordinary object element will be evaluated for
type match against the target property it is setting when the XAML is parsed.

Most markup extensions, when used in object element syntax to fill a property element,
would not have content or any further property element syntax within. Thus you would
close the object element tag, and provide no child elements. Whenever any object
element is encountered by a XAML processor, the constructor for that class is called,
which instantiates the object created from the parsed element. A markup extension class
is no different: if you want your markup extension to be usable in object element syntax,
you must provide a parameterless constructor. Some existing markup extensions have at
least one required property value that must be specified for effective initialization. If so,
that property value is typically given as a property attribute on the object element. In
the XAML Namespace (x:) Language Features and WPF XAML Extensions reference
pages, markup extensions that have required properties (and the names of required
properties) will be noted. Reference pages will also note if either object element syntax
or attribute syntax is disallowed for particular markup extensions. A notable case is
x:Array Markup Extension, which cannot support attribute syntax because the contents
of that array must be specified within the tagging as content. The array contents are
handled as general objects, therefore no default type converter for the attribute is
feasible. Also, x:Array Markup Extension requires a type parameter.

See also
XAML in WPF
XAML Namespace (x:) Language Features
WPF XAML Extensions
StaticResource Markup Extension
Binding Markup Extension
DynamicResource Markup Extension
x:Type Markup Extension
XAML Namespaces and Namespace
Mapping for WPF XAML
Article • 03/17/2022

This topic further explains the presence and purpose of the two XAML namespace
mappings as often found in the root tag of a WPF XAML file. It also describes how to
produce similar mappings for using elements that are defined in your own code, and/or
within separate assemblies.

What is a XAML Namespace

A XAML namespace is really an extension of the concept of an XML namespace. The
techniques of specifying a XAML namespace rely on the XML namespace syntax, the
convention of using URIs as namespace identifiers, using prefixes to provide a means to
reference multiple namespaces from the same markup source, and so on. The primary
concept that is added to the XAML definition of the XML namespace is that a XAML
namespace implies both a scope of uniqueness for the markup usages, and also
influences how markup entities are potentially backed by specific CLR namespaces and
referenced assemblies. This latter consideration is also influenced by the concept of a
XAML schema context. But for purposes of how WPF works with XAML namespaces, you
can generally think of XAML namespaces in terms of a default XAML namespace, the
XAML language namespace, and any further XAML namespaces as mapped by your
XAML markup directly to specific backing CLR namespaces and referenced assemblies.

The WPF and XAML Namespace Declarations

Within the namespace declarations in the root tag of many XAML files, you will see that
there are typically two XML namespace declarations. The first declaration maps the
overall WPF client / framework XAML namespace as the default:

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

The second declaration maps a separate XAML namespace, mapping it (typically) to the
x: prefix.

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

The relationship between these declarations is that the x: prefix mapping supports the
intrinsics that are part of the XAML language definition, and WPF is one implementation
that uses XAML as a language and defines a vocabulary of its objects for XAML. Because
the WPF vocabulary's usages will be far more common than the XAML intrinsics usages,
the WPF vocabulary is mapped as the default.

The x: prefix convention for mapping the XAML language intrinsics support is followed
by project templates, sample code, and the documentation of language features within
this SDK. The XAML namespace defines many commonly-used features that are
necessary even for basic WPF applications. For instance, in order to join any code-
behind to a XAML file through a partial class, you must name that class as the x:Class
attribute in the root element of the relevant XAML file. Or, any element as defined in a
XAML page that you wish to access as a keyed resource should have the x:Key attribute
set on the element in question. For more information on these and other aspects of
XAML see XAML in WPF or XAML Syntax In Detail.

Mapping to Custom Classes and Assemblies

You can map XML namespaces to assemblies using a series of tokens within an xmlns
prefix declaration, similar to how the standard WPF and XAML-intrinsics XAML
namespaces are mapped to prefixes.

The syntax takes the following possible named tokens and following values:

clr-namespace: The CLR namespace declared within the assembly that contains the

public types to expose as elements.

assembly= The assembly that contains some or all of the referenced CLR namespace.

This value is typically just the name of the assembly, not the path, and does not include
the extension (such as .dll or .exe). The path to that assembly must be established as a
project reference in the project file that contains the XAML you are trying to map. In
order to incorporate versioning and strong-name signing, the assembly value can be a
string as defined by AssemblyName, rather than the simple string name.

Note that the character separating the clr-namespace token from its value is a colon (:)
whereas the character separating the assembly token from its value is an equals sign (=).
The character to use between these two tokens is a semicolon. Also, do not include any
white space anywhere in the declaration.

A Basic Custom Mapping Example

The following code defines an example custom class:
C#

namespace SDKSample {
public class ExampleClass : ContentControl {
public ExampleClass() {
...
}
}
}

This custom class is then compiled into a library, which per the project settings (not
shown) is named SDKSampleLibrary .

In order to reference this custom class, you also need to include it as a reference for
your current project, which you would typically do using the Solution Explorer UI in
Visual Studio.

Now that you have a library containing a class, and a reference to it in project settings,
you can add the following prefix mapping as part of your root element in XAML:

xmlns:custom="clr-namespace:SDKSample;assembly=SDKSampleLibrary"

To put it all together, the following is XAML that includes the custom mapping along
with the typical default and x: mappings in the root tag, then uses a prefixed reference
to instantiate ExampleClass in that UI:

XAML

Mapping to Current Assemblies

assembly can be omitted if the clr-namespace referenced is being defined within the
same assembly as the application code that is referencing the custom classes. Or, an
equivalent syntax for this case is to specify assembly= , with no string token following the
equals sign.
Custom classes cannot be used as the root element of a page if defined in the same
assembly. Partial classes do not need to be mapped; only classes that are not the partial
class of a page in your application need to be mapped if you intend to reference them
as elements in XAML.

Mapping CLR Namespaces to XML Namespaces

in an Assembly
WPF defines a CLR attribute that is consumed by XAML processors in order to map
multiple CLR namespaces to a single XAML namespace. This attribute,
XmlnsDefinitionAttribute, is placed at the assembly level in the source code that
produces the assembly. The WPF assembly source code uses this attribute to map the
various common namespaces, such as System.Windows and System.Windows.Controls,
to the http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace.

The XmlnsDefinitionAttribute takes two parameters: the XML/XAML namespace name,

and the CLR namespace name. More than one XmlnsDefinitionAttribute can exist to
map multiple CLR namespaces to the same XML namespace. Once mapped, members of
those namespaces can also be referenced without full qualification if desired by
providing the appropriate using statement in the partial-class code-behind page. For
more details, see XmlnsDefinitionAttribute.

Designer Namespaces and Other Prefixes From

XAML Templates
If you are working with development environments and/or design tools for WPF XAML,
you may notice that there are other defined XAML namespaces / prefixes within the
XAML markup.

WPF Designer for Visual Studio uses a designer namespace that is typically mapped to
the prefix d: . More recent project templates for WPF might pre-map this XAML
namespace to support interchange of the XAML between WPF Designer for Visual
Studio and other design environments. This design XAML namespace is used to
perpetuate design state while roundtripping XAML-based UI in the designer. It is also
used for features such as d:IsDataSource , which enable runtime data sources in a
designer.

Another prefix you might see mapped is mc: . mc: is for markup compatibility, and is
leveraging a markup compatibility pattern that is not necessarily XAML-specific. To some
extent, the markup compatibility features can be used to exchange XAML between
frameworks or across other boundaries of backing implementation, work between XAML
schema contexts, provide compatibility for limited modes in designers, and so on. For
more information on markup compatibility concepts and how they relate to WPF, see
Markup Compatibility (mc:) Language Features.

WPF and Assembly Loading

The XAML schema context for WPF integrates with the WPF application model, which in
turn uses the CLR-defined concept of AppDomain. The following sequence describes
how XAML schema context interprets how to either load assemblies or find types at run
time or design time, based on the WPF use of AppDomain and other factors.

1. Iterate through the AppDomain, looking for an already-loaded assembly that

matches all aspects of the name, starting from the most recently loaded assembly.

2. If the name is qualified, call Assembly.Load(String) on the qualified name.

3. If the short name + public key token of a qualified name matches the assembly
that the markup was loaded from, return that assembly.

4. Use the short name + public key token to call Assembly.Load(String).

5. If the name is unqualified, call Assembly.LoadWithPartialName.

Loose XAML does not use Step 3; there is no loaded-from assembly.

Compiled XAML for WPF (generated via XamlBuildTask) does not use the already-loaded
assemblies from AppDomain (Step 1). Also, the name should never be unqualified from
XamlBuildTask output, so Step 5 does not apply.

Compiled BAML (generated via PresentationBuildTask) uses all steps, although BAML
also should not contain unqualified assembly names.

See also
Understanding XML Namespaces
XAML in WPF
WPF XAML Namescopes
Article • 02/06/2023

XAML namescopes are a concept that identifies objects that are defined in XAML. The
names in a XAML namescope can be used to establish relationships between the XAML-
defined names of objects and their instance equivalents in an object tree. Typically,
XAML namescopes in WPF managed code are created when loading the individual
XAML page roots for a XAML application. XAML namescopes as the programming
object are defined by the INameScope interface and are also implemented by the
practical class NameScope.

Namescopes in Loaded XAML Applications

In a broader programming or computer science context, programming concepts often
include the principle of a unique identifier or name that can be used to access an object.
For systems that use identifiers or names, the namescope defines the boundaries within
which a process or technique will search if an object of that name is requested, or the
boundaries wherein uniqueness of identifying names is enforced. These general
principles are true for XAML namescopes. In WPF, XAML namescopes are created on the
root element for a XAML page when the page is loaded. Each name specified within the
XAML page starting at the page root is added to a pertinent XAML namescope.

In WPF XAML, elements that are common root elements (such as Page, and Window)
always control a XAML namescope. If an element such as FrameworkElement or
FrameworkContentElement is the root element of the page in markup, a XAML
processor adds a Page root implicitly so that the Page can provide a working XAML
namescope.

７ Note

WPF build actions create a XAML namescope for a XAML production even if no
Name or x:Name attributes are defined on any elements in the XAML markup.

If you try to use the same name twice in any XAML namescope, an exception is raised.
For WPF XAML that has code-behind and is part of a compiled application, the
exception is raised at build time by WPF build actions, when creating the generated
class for the page during the initial markup compile. For XAML that is not markup-
compiled by any build action, exceptions related to XAML namescope issues might be
raised when the XAML is loaded. XAML designers might also anticipate XAML
namescope issues at design time.

Adding Objects to Runtime Object Trees

The moment that XAML is parsed represents the moment in time that a WPF XAML
namescope is created and defined. If you add an object to an object tree at a point in
time after the XAML that produced that tree was parsed, a Name or x:Name value on the
new object does not automatically update the information in a XAML namescope. To
add a name for an object into a WPF XAML namescope after XAML is loaded, you must
call the appropriate implementation of RegisterName on the object that defines the
XAML namescope, which is typically the XAML page root. If the name is not registered,
the added object cannot be referenced by name through methods such as FindName,
and you cannot use that name for animation targeting.

The most common scenario for application developers is that you will use RegisterName
to register names into the XAML namescope on the current root of the page.
RegisterName is part of an important scenario for storyboards that target objects for
animations. For more information, see Storyboards Overview.

If you call RegisterName on an object other than the object that defines the XAML
namescope, the name is still registered to the XAML namescope that the calling object
is held within, as if you had called RegisterName on the XAML namescope defining
object.

XAML Namescopes in Code

You can create and then use XAML namescopes in code. The APIs and the concepts
involved in XAML namescope creation are the same even for a pure code usage,
because the XAML processor for WPF uses these APIs and concepts when it processes
XAML itself. The concepts and API exist mainly for the purpose of being able to find
objects by name within an object tree that is typically defined partially or entirely in
XAML.

For applications that are created programmatically, and not from loaded XAML, the
object that defines a XAML namescope must implement INameScope, or be a
FrameworkElement or FrameworkContentElement derived class, in order to support
creation of a XAML namescope on its instances.

Also, for any element that is not loaded and processed by a XAML processor, the XAML
namescope for the object is not created or initialized by default. You must explicitly
create a new XAML namescope for any object that you intend to register names into
subsequently. To create a XAML namescope, you call the static SetNameScope method.
Specify the object that will own it as the dependencyObject parameter, and a new
NameScope constructor call as the value parameter.

If the object provided as dependencyObject for SetNameScope is not a INameScope

implementation, FrameworkElement or FrameworkContentElement, calling
RegisterName on any child elements will have no effect. If you fail to create the new
XAML namescope explicitly, then calls to RegisterName will raise an exception.

For an example of using XAML namescope APIs in code, see Define a Name Scope.

XAML Namescopes in Styles and Templates

Styles and templates in WPF provide the ability to reuse and reapply content in a
straightforward way. However, styles and templates might also include elements with
XAML names defined at the template level. That same template might be used multiple
times in a page. For this reason, styles and templates both define their own XAML
namescopes, independent of whatever location in an object tree where the style or
template is applied.

Consider the following example:

XAML

Here, the same template is applied to two different buttons. If templates did not have
discrete XAML namescopes, the TheBorder name used in the template would cause a
name collision in the XAML namescope. Each instantiation of the template has its own
XAML namescope, so in this example each instantiated template's XAML namescope
would contain exactly one name.

Styles also define their own XAML namescope, mostly so that parts of storyboards can
have particular names assigned. These names enable control specific behaviors that will
target elements of that name, even if the template was re-defined as part of control
customization.

Because of the separate XAML namescopes, finding named elements in a template is

more challenging than finding a non-templated named element in a page. You first
need to determine the applied template, by getting the Template property value of the
control where the template is applied. Then, you call the template version of FindName,
passing the control where the template was applied as the second parameter.

If you are a control author and you are generating a convention where a particular
named element in an applied template is the target for a behavior that is defined by the
control itself, you can use the GetTemplateChild method from your control
implementation code. The GetTemplateChild method is protected, so only the control
author has access to it.

If you are working from within a template, and need to get to the XAML namescope
where the template is applied, get the value of TemplatedParent, and then call
FindName there. An example of working within the template would be if you are writing
the event handler implementation where the event will be raised from an element in an
applied template.

XAML Namescopes and Name-related APIs

FrameworkElement has FindName, RegisterName and UnregisterName methods. If the
object you call these methods on owns a XAML namescope, the methods call into the
methods of the relevant XAML namescope. Otherwise, the parent element is checked to
see if it owns a XAML namescope, and this process continues recursively until a XAML
namescope is found (because of the XAML processor behavior, there is guaranteed to
be a XAML namescope at the root). FrameworkContentElement has analogous
behaviors, with the exception that no FrameworkContentElement will ever own a XAML
namescope. The methods exist on FrameworkContentElement so that the calls can be
forwarded eventually to a FrameworkElement parent element.

SetNameScope is used to map a new XAML namescope to an existing object. You can
call SetNameScope more than once in order to reset or clear the XAML namescope, but
that is not a common usage. Also, GetNameScope is not typically used from code.
XAML Namescope Implementations
The following classes implement INameScope directly:

NameScope

Style

ResourceDictionary

FrameworkTemplate

ResourceDictionary does not use XAML names or namescopes ; it uses keys instead,
because it is a dictionary implementation. The only reason that ResourceDictionary
implements INameScope is so it can raise exceptions to user code that help clarify the
distinction between a true XAML namescope and how a ResourceDictionary handles
keys, and also to assure that XAML namescopes are not applied to a ResourceDictionary
by parent elements.

FrameworkTemplate and Style implement INameScope through explicit interface

definitions. The explicit implementations allow these XAML namescopes to behave
conventionally when they are accessed through the INameScope interface, which is how
XAML namescopes are communicated by WPF internal processes. But the explicit
interface definitions are not part of the conventional API surface of FrameworkTemplate
and Style, because you seldom need to call the INameScope methods on
FrameworkTemplate and Style directly, and instead would use other API such as
GetTemplateChild.

The following classes define their own XAML namescope, by using the
System.Windows.NameScope helper class and connecting to its XAML namescope
implementation through the NameScope.NameScope attached property:

FrameworkElement

FrameworkContentElement

See also
XAML Namespaces and Namespace Mapping for WPF XAML
x:Name Directive
Inline Styles and Templates
Article • 08/10/2023

Windows Presentation Foundation (WPF) provides Style objects and template objects
(FrameworkTemplate subclasses) as a way to define the visual appearance of an element
in resources, so that they can be used multiple times. For this reason, attributes in XAML
that take the types Style and FrameworkTemplate almost always make resource
references to existing styles and templates rather than define new ones inline.

Limitations of Inline Styles and Templates

In Extensible Application Markup Language (XAML), style and template properties can
technically be set in one of two ways. You can use attribute syntax to reference a style
that was defined within a resource, for example < object Style="
{StaticResource myResourceKey }" .../> . Or you can use property element syntax to

define a style inline, for instance:

< object >

< object .Style>

< Style .../>

</ object .Style>

</ object >

The attribute usage is much more common. A style that is defined inline and not
defined in resources is necessarily scoped to the containing element only, and cannot be
re-used as easily because it has no resource key. In general a resource-defined style is
more versatile and useful, and is more in keeping with the general Windows
Presentation Foundation (WPF) programming model principle of separating program
logic in code from design in markup.

Usually there is no reason to set a style or template inline, even if you only intend to use
that style or template in that location. Most elements that can take a style or template
also support a content property and a content model. If you are only using whatever
logical tree you create through styling or templating once, it would be even easier to
just fill that content property with the equivalent child elements in direct markup. This
would bypass the style and template mechanisms altogether.
Other syntaxes enabled by markup extensions that return an object are also possible for
styles and templates. Two such extensions that have possible scenarios include
TemplateBinding and Binding.

See also
Styling and Templating
TypeConverters and XAML
Article • 02/06/2023

This topic introduces the purpose of type conversion from string as a general XAML
language feature. In the .NET Framework, the TypeConverter class serves a particular
purpose as part of the implementation for a managed custom class that can be used as
a property value in XAML attribute usage. If you write a custom class, and you want
instances of your class to be usable as XAML settable attribute values, you might need
to apply a TypeConverterAttribute to your class, write a custom TypeConverter class, or
both.

Type Conversion Concepts

XAML and String Values

When you set an attribute value in a XAML file, the initial type of that value is a string in
pure text. Even other primitives such as Double are initially text strings to a XAML
processor.

A XAML processor needs two pieces of information in order to process an attribute

value. The first piece of information is the value type of the property that is being set.
Any string that defines an attribute value and that is processed in XAML must ultimately
be converted or resolved to a value of that type. If the value is a primitive that is
understood by the XAML parser (such as a numeric value), a direct conversion of the
string is attempted. If the value is an enumeration, the string is used to check for a name
match to a named constant in that enumeration. If the value is neither a parser-
understood primitive nor an enumeration, then the type in question must be able to
provide an instance of the type, or a value, based on a converted string. This is done by
indicating a type converter class. The type converter is effectively a helper class for
providing values of another class, both for the XAML scenario and also potentially for
code calls in .NET code.

Using Existing Type Conversion Behavior in XAML

Depending on your familiarity with the underlying XAML concepts, you may already be
using type conversion behavior in basic application XAML without realizing it. For
instance, WPF defines literally hundreds of properties that take a value of type Point. A
Point is a value that describes a coordinate in a two-dimensional coordinate space, and
it really just has two important properties: X and Y. When you specify a point in XAML,
you specify it as a string with a delimiter (typically a comma) between the X and Y values
you provide. For example: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1"/> .

Even this simple type of Point and its simple usage in XAML involve a type converter. In
this case that is the class PointConverter.

The type converter for Point defined at the class level streamlines the markup usages of
all properties that take Point. Without a type converter here, you would need the
following much more verbose markup for the same example shown previously:

XAML

Whether to use the type conversion string or a more verbose equivalent syntax is
generally a coding style choice. Your XAML tooling workflow might also influence how
values are set. Some XAML tools tend to emit the most verbose form of the markup
because it is easier to round-trip to designer views or its own serialization mechanism.

Existing type converters can generally be discovered on WPF and .NET Framework types
by checking a class (or property) for the presence of an applied TypeConverterAttribute.
This attribute will name the class that is the supporting type converter for values of that
type, for XAML purposes as well as potentially other purposes.

Type Converters and Markup Extensions

Markup extensions and type converters fill orthogonal roles in terms of XAML processor
behavior and the scenarios that they are applied to. Although context is available for
markup extension usages, type conversion behavior of properties where a markup
extension provides a value is generally is not checked in the markup extension
implementations. In other words, even if a markup extension returns a text string as its
ProvideValue output, type conversion behavior on that string as applied to a specific
property or property value type is not invoked, Generally, the purpose of a markup
extension is to process a string and return an object without any type converter
involved.
One common situation where a markup extension is necessary rather than a type
converter is to make a reference to an object that already exists. At best, a stateless type
converter could only generate a new instance, which might not be desirable. For more
information on markup extensions, see Markup Extensions and WPF XAML.

Native Type Converters

In the WPF and .NET Framework implementation of the XAML parser, there are certain
types that have native type conversion handling, yet are not types that might
conventionally be thought of as primitives. An example of such a type is DateTime. The
reason for this is based on how the .NET Framework architecture works: the type
DateTime is defined in mscorlib, the most basic library in .NET. DateTime is not
permitted to be attributed with an attribute that comes from another assembly that
introduces a dependency (TypeConverterAttribute is from System) so the usual type
converter discovery mechanism by attributing cannot be supported. Instead, the XAML
parser has a list of types that need such native processing and processes these similarly
to how the true primitives are processed. (In the case of DateTime this involves a call to
Parse.)

Implementing a Type Converter

TypeConverter
In the Point example given previously, the class PointConverter was mentioned. For .NET
implementations of XAML, all type converters that are used for XAML purposes are
classes that derive from the base class TypeConverter. The TypeConverter class existed in
versions of .NET Framework that precede the existence of XAML; one of its original
usages was to provide string conversion for property dialogs in visual designers. For
XAML, the role of TypeConverter is expanded to include being the base class for to-
string and from-string conversions that enable parsing a string attribute value, and
possibly processing a run-time value of a particular object property back into a string for
serialization as an attribute.

TypeConverter defines four members that are relevant for converting to and from
strings for XAML processing purposes:

CanConvertTo

CanConvertFrom

ConvertTo
ConvertFrom

Of these, the most important method is ConvertFrom. This method converts the input
string to the required object type. Strictly speaking, the ConvertFrom method could be
implemented to convert a much wider range of types into the converter's intended
destination type, and thus serve purposes that extend beyond XAML such as supporting
run-time conversions, but for XAML purposes it is only the code path that can process a
String input that matters.

The next most important method is ConvertTo. If an application is converted to a

markup representation (for instance, if it is saved to XAML as a file), ConvertTo is
responsible for producing a markup representation. In this case, the code path that
matters for XAML is when you pass a destinationType of String .

CanConvertTo and CanConvertFrom are support methods that are used when a service
queries the capabilities of the TypeConverter implementation. You must implement
these methods to return true for type-specific cases that the equivalent conversion
methods of your converter support. For XAML purposes, this generally means the String
type.

Culture Information and Type Converters for XAML

Each TypeConverter implementation can have its own interpretation of what constitutes
a valid string for a conversion, and can also use or ignore the type description passed as
parameters. There is an important consideration with regard to culture and XAML type
conversion. Using localizable strings as attribute values is entirely supported by XAML.
But using that localizable string as type converter input with specific culture
requirements is not supported, because type converters for XAML attribute values
involve a necessarily fixed-language parsing behavior, using en-US culture. For more
information on the design reasons for this restriction, you should consult the XAML
language specification ([MS-XAML] .

As an example where culture can be an issue, some cultures use a comma as their
decimal point delimiter for numbers. This will collide with the behavior that many of the
WPF XAML type converters have, which is to use a comma as a delimiter (based on
historical precedents such as the common X,Y form, or comma delimited lists). Even
passing a culture in the surrounding XAML (setting Language or xml:lang to the sl-SI
culture, an example of a culture that uses a comma for decimal in this way) does not
solve the issue.

Implementing ConvertFrom
To be usable as a TypeConverter implementation that supports XAML, the ConvertFrom
method for that converter must accept a string as the value parameter. If the string was
in valid format, and can be converted by the TypeConverter implementation, then the
returned object must support a cast to the type expected by the property. Otherwise,
the ConvertFrom implementation must return null .

Each TypeConverter implementation can have its own interpretation of what constitutes
a valid string for a conversion, and can also use or ignore the type description or culture
contexts passed as parameters. However, the WPF XAML processing might not pass
values to the type description context in all cases, and also might not pass culture based
on xml:lang .

７ Note

Do not use the curly brace characters, particularly {, as a possible element of your
string format. These characters are reserved as the entry and exit for a markup
extension sequence.

Implementing ConvertTo
ConvertTo is potentially used for serialization support. Serialization support through
ConvertTo for your custom type and its type converter is not an absolute requirement.
However, if you are implementing a control, or using serialization of as part of the
features or design of your class, you should implement ConvertTo.

To be usable as a TypeConverter implementation that supports XAML, the ConvertTo

method for that converter must accept an instance of the type (or a value) being
supported as the value parameter. When the destinationType parameter is the type
String, then the returned object must be able to be cast as String. The returned string
must represent a serialized value of value . Ideally, the serialization format you choose
should be capable of generating the same value if that string were passed to the
ConvertFrom implementation of the same converter, without significant loss of
information.

If the value cannot be serialized, or the converter does not support serialization, the
ConvertTo implementation must return null , and is permitted to throw an exception in
this case. But if you do throw exceptions, you should report the inability to use that
conversion as part of your CanConvertTo implementation so that the best practice of
checking with CanConvertTo first to avoid exceptions is supported.
If destinationType parameter is not of type String, you can choose your own converter
handling. Typically, you would revert to base implementation handling, which in the
basemost ConvertTo raises a specific exception.

Implementing CanConvertTo
Your CanConvertTo implementation should return true for destinationType of type
String, and otherwise defer to the base implementation.

Implementing CanConvertFrom
Your CanConvertFrom implementation should return true for sourceType of type String,
and otherwise defer to the base implementation.

Applying the TypeConverterAttribute

In order for your custom type converter to be used as the acting type converter for a
custom class by a XAML processor, you must apply the TypeConverterAttribute to your
class definition. The ConverterTypeName that you specify through the attribute must be
the type name of your custom type converter. With this attribute applied, when a XAML
processor handles values where the property type uses your custom class type, it can
input strings and return object instances.

You can also provide a type converter on a per-property basis. Instead of applying a
TypeConverterAttribute to the class definition, apply it to a property definition (the main
definition, not the get / set implementations within it). The type of the property must
match the type that is processed by your custom type converter. With this attribute
applied, when a XAML processor handles values of that property, it can process input
strings and return object instances. The per-property type converter technique is
particularly useful if you choose to use a property type from Microsoft .NET Framework
or from some other library where you cannot control the class definition and cannot
apply a TypeConverterAttribute there.

See also
TypeConverter
XAML in WPF
Markup Extensions and WPF XAML
XAML Syntax In Detail
WPF XAML Extensions
Article • 02/06/2023

In This Section
Binding Markup Extension
ColorConvertedBitmap Markup Extension
ComponentResourceKey Markup Extension
DynamicResource Markup Extension
RelativeSource MarkupExtension
StaticResource Markup Extension
TemplateBinding Markup Extension
ThemeDictionary Markup Extension
PropertyPath XAML Syntax
PresentationOptions:Freeze Attribute
Binding Markup Extension
Article • 02/06/2023

Defers a property value to be a data-bound value, creating an intermediate expression

object and interpreting the data context that applies to the element and its binding at
run time.

Binding Expression Usage

XAML

<object property="{Binding}" .../>

-or-
<object property="{Binding bindProp1=value1[, bindPropN=valueN]*}" ...
/>
-or-
<object property="{Binding path}" .../>
-or
<object property="{Binding path[, bindPropN=valueN]*}" .../>

Syntax Notes
In these syntaxes, the [] and * are not literals. They are part of a notation to indicate
that zero or more bindProp = value pairs can be used, with a , separator between them
and preceding bindProp = value pairs.

Any of the properties listed in the "Binding Properties That Can Be Set with the Binding
Extension" section could instead be set using attributes of a Binding object element.
However, that is not truly the markup extension usage of Binding, it is just the general
XAML processing of attributes that set properties of the CLR Binding class. In other
words, <Binding bindProp1 =" value1 "[ bindPropN =" valueN "]*/> is an equivalent
syntax for attributes of Binding object element usage instead of a Binding expression
usage. To learn about the XAML attribute usage of specific properties of Binding, see the
"XAML Attribute Usage" section of the relevant property of Binding in the .NET
Framework Class Library.

XAML Values
Value Description
Value Description

bindProp1, The name of the Binding or BindingBase property to set. Not all Binding properties
bindPropN can be set with the Binding extension, and some properties are settable within a
Binding expression only by using further nested markup extensions. See "Binding
Properties That Can Be Set with the Binding Extension" section.

value1, The value to set the property to. The handling of the attribute value is ultimately
valueN specific to the type and logic of the specific Binding property being set.

path The path string that sets the implicit Binding.Path property. See also PropertyPath
XAML Syntax.

Unqualified {Binding}
The {Binding} usage shown in "Binding Expression Usage" creates a Binding object with
default values, which includes an initial Binding.Path of null . This is still useful in many
scenarios, because the created Binding might be relying on key data binding properties
such as Binding.Path and Binding.Source being set in the run-time data context. For
more information on the concept of data context, see Data Binding.

Implicit Path
The Binding markup extension uses Binding.Path as a conceptual "default property",
where Path= does not need to appear in the expression. If you specify a Binding
expression with an implicit path, the implicit path must appear first in the expression,
prior to any other bindProp = value pairs where the Binding property is specified by
name. For example: {Binding PathString} , where PathString is a string that is
evaluated to be the value of Binding.Path in the Binding created by the markup
extension usage. You can append an implicit path with other named properties after the
comma separator, for example, {Binding LastName, Mode=TwoWay} .

Binding Properties That Can Be Set with the

Binding Extension
The syntax shown in this topic uses the generic bindProp = value approximation,
because there are many read/write properties of BindingBase or Binding that can be set
through the Binding markup extension / expression syntax. They can be set in any
order, with the exception of an implicit Binding.Path. (You do have the option to
explicitly specify Path= , in which case it can be set in any order). Basically, you can set
zero or more of the properties in the list below, using bindProp = value pairs separated
by commas.

Several of these property values require object types that do not support a native type
conversion from a text syntax in XAML, and thus require markup extensions in order to
be set as an attribute value. Check the XAML Attribute Usage section in the .NET
Framework Class Library for each property for more information; the string you use for
XAML attribute syntax with or without further markup extension usage is basically the
same as the value you specify in a Binding expression, with the exception that you do
not place quotation marks around each bindProp = value in the Binding expression.

BindingGroupName: a string that identifies a possible binding group. This is a

relatively advanced binding concept; see reference page for BindingGroupName.

BindsDirectlyToSource: Boolean, can be either true or false . The default is false .

Converter: can be set as a bindProp = value string in the expression, but to do so

requires an object reference for the value, such as a StaticResource Markup
Extension. The value in this case is an instance of a custom converter class.

ConverterCulture: settable in the expression as a standards-based identifier; see

the reference topic for ConverterCulture.

ConverterParameter: can be set as a bindProp = value string in the expression, but

this is dependent on the type of the parameter being passed. If passing a reference
type for the value, this usage requires an object reference such as a nested
StaticResource Markup Extension.

ElementName: mutually exclusive versus RelativeSource and Source; each of these

binding properties represents a particular binding methodology. See Data Binding
Overview.

FallbackValue: can be set as a bindProp = value string in the expression, but this is
dependent on the type of the value being passed. If passing a reference type,
requires an object reference such as a nested StaticResource Markup Extension.

IsAsync: Boolean, can be either true or false . The default is false .

Mode: value is a constant name from the BindingMode enumeration. For example,
{Binding Mode=OneWay} .

NotifyOnSourceUpdated: Boolean, can be either true or false . The default is

false .
NotifyOnTargetUpdated: Boolean, can be either true or false . The default is
false .

NotifyOnValidationError: Boolean, can be either true or false . The default is

false .

Path: a string that describes a path into a data object or a general object model.
The format provides several different conventions for traversing an object model
that cannot be adequately described in this topic. See PropertyPath XAML Syntax.

RelativeSource: mutually exclusive versus with ElementName and Source; each of

these binding properties represents a particular binding methodology. See Data
Binding Overview. Requires a nested RelativeSource MarkupExtension usage to
specify the value.

Source: mutually exclusive versus RelativeSource and ElementName; each of these

binding properties represents a particular binding methodology. See Data Binding
Overview. Requires a nested extension usage, typically a StaticResource Markup
Extension that refers to an object data source from a keyed resource dictionary.

StringFormat: a string that describes a string format convention for the bound
data. This is a relatively advanced binding concept; see reference page for
StringFormat.

TargetNullValue: can be set as a bindProp = value string in the expression, but this
is dependent on the type of the parameter being passed. If passing a reference
type for the value, requires an object reference such as a nested StaticResource
Markup Extension.

UpdateSourceTrigger: value is a constant name from the UpdateSourceTrigger

enumeration. For example, {Binding UpdateSourceTrigger=LostFocus} . Specific
controls potentially have different default values for this binding property. See
UpdateSourceTrigger.

ValidatesOnDataErrors: Boolean, can be either true or false . The default is false .

See Remarks.

ValidatesOnExceptions: Boolean, can be either true or false . The default is false .

See Remarks.

XPath: a string that describes a path into the XMLDOM of an XML data source. See
Bind to XML Data Using an XMLDataProvider and XPath Queries.
The following are properties of Binding that cannot be set using the Binding markup
extension/ {Binding} expression form.

UpdateSourceExceptionFilter: this property expects a reference to a callback

implementation. Callbacks/methods other than event handlers cannot be
referenced in XAML syntax.

ValidationRules: the property takes a generic collection of ValidationRule objects.

This could be expressed as a property element in a Binding object element, but has
no readily available attribute-parsing technique for usage in a Binding expression.
See reference topic for ValidationRules.

XmlNamespaceManager

Remarks

） Important

In terms of dependency property precedence, a Binding expression is equivalent to

a locally set value. If you set a local value for a property that previously had a
Binding expression, the Binding is completely removed. For details, see

Dependency Property Value Precedence.

Describing data binding at a basic level is not covered in this topic. See Data Binding
Overview.

７ Note

MultiBinding and PriorityBinding do not support a XAML extension syntax. You

would instead use property elements. See reference topics for MultiBinding and
PriorityBinding.

Boolean values for XAML are case insensitive. For example you could specify either
{Binding NotifyOnValidationError=true} or {Binding NotifyOnValidationError=True} .

Bindings that involve data validation are typically specified by an explicit Binding
element rather than as a {Binding ...} expression, and setting ValidatesOnDataErrors
or ValidatesOnExceptions in an expression is uncommon. This is because the companion
property ValidationRules cannot be readily set in the expression form. For more
information, see Implement Binding Validation.
Binding is a markup extension. Markup extensions are typically implemented when

there is a requirement to escape attribute values to be other than literal values or

handler names, and the requirement is more global than type converters attributed on
certain types or properties. All markup extensions in XAML use the { and } characters
in their attribute syntax, which is the convention by which a XAML processor recognizes
that a markup extension must process the string contents. For more information, see
Markup Extensions and WPF XAML.

Binding is an atypical markup extension in that the Binding class that implements the

extension functionality for WPF's XAML implementation also implements several other
methods and properties that are not related to XAML. The other members are intended
to make Binding a more versatile and self-contained class that can address many data
binding scenarios in addition to functioning as a XAML markup extension.

See also
Binding
Data Binding Overview
XAML in WPF
Markup Extensions and WPF XAML
ColorConvertedBitmap Markup
Extension
Article • 02/06/2023

Provides a way to specify a bitmap source that does not have an embedded profile.
Color contexts / profiles are specified by URI, as is the image source URI.

XAML Attribute Usage

XML

<object property="{ColorConvertedBitmap imageSource sourceIIC

destinationIIC}" ... />

XAML Values
Value Description

imageSource The URI of the nonprofiled bitmap.

sourceIIC The URI of the source profile configuration.

destinationIIC The URI of the destination profile configuration

Remarks
This markup extension is intended to fill a related set of image-source property values
such as UriSource.

Attribute syntax is the most common syntax used with this markup extension.
ColorConvertedBitmap (or ColorConvertedBitmapExtension ) cannot be used in property

element syntax, because the values can only be set as values on the initial constructor,
which is the string following the extension identifier.

ColorConvertedBitmap is a markup extension. Markup extensions are typically

implemented when there is a requirement to escape attribute values to be other than

literal values or handler names, and the requirement is more global than just putting
type converters on certain types or properties. All markup extensions in XAML use the {
and } characters in their attribute syntax, which is the convention by which a XAML
processor recognizes that a markup extension must process the attribute. For more
information, see Markup Extensions and WPF XAML.

See also
UriSource
Markup Extensions and WPF XAML
Imaging Overview
ComponentResourceKey Markup
Extension
Article • 02/06/2023

Defines and references keys for resources that are loaded from external assemblies. This
enables a resource lookup to specify a target type in an assembly, rather than an explicit
resource dictionary in an assembly or on a class.

XAML Attribute Usage (setting key, compact)

XML

<object x:Key="{ComponentResourceKey {x:Type targetTypeName}, targetID}" ...

XAML Attribute Usage (setting key, verbose)

XML

<object x:Key="{ComponentResourceKey TypeInTargetAssembly={x:Type

targetTypeName}, ResourceID=targetID}" ... />

XAML Attribute Usage (requesting resource,

compact)
XML

<object property="{DynamicResource {ComponentResourceKey {x:Type

targetTypeName}, targetID}}" ... />

XAML Attribute Usage (requesting resource,

verbose)
XML

<object property="{DynamicResource {ComponentResourceKey

TypeInTargetAssembly={x:Type targetTypeName}, ResourceID=targetID}}" ... />
XAML Values
Value Description

targetTypeName The name of the public common language runtime (CLR) type that is defined in
the resource assembly.

targetID The key for the resource. When resources are looked up, targetID will be
analogous to the x:Key Directive of the resource.

Remarks
As seen in the usages above, a { ComponentResourceKey } markup extension usage is found
in two places:

The definition of a key within a theme resource dictionary, as provided by a control

author.

Accessing a theme resource from the assembly, when you are retemplating the
control but want to use property values that come from resources provided by the
control's themes.

For referencing component resources that come from themes, it is generally

recommended that you use {DynamicResource} rather than {StaticResource} . This is
shown in the usages. {DynamicResource} is recommended because the theme itself can
be changed by the user. If you want the component resource that most closely matches
the control author's intent for supporting a theme, you should enable your component
resource reference to be dynamic also.

The TypeInTargetAssembly identifies a type that exists in the target assembly where the
resource is actually defined. A ComponentResourceKey can be defined and used
independently of knowing exactly where the TypeInTargetAssembly is defined, but
eventually must resolve the type through referenced assemblies.

A common usage for ComponentResourceKey is to define keys that are then exposed as
members of a class. For this usage, you use the ComponentResourceKey class
constructor, not the markup extension. For more information, see
ComponentResourceKey, or the "Defining and Referencing Keys for Theme Resources"
section of the topic Control Authoring Overview.
For both establishing keys and referencing keyed resources, attribute syntax is
commonly used for the ComponentResourceKey markup extension.

The compact syntax shown relies on the ComponentResourceKey constructor signature

and positional parameter usage of a markup extension. The order in which the
targetTypeName and targetID are given is important. The verbose syntax relies on the

ComponentResourceKey parameterless constructor, and then sets the

TypeInTargetAssembly and ResourceId in a way that is analogous to a true attribute
syntax on an object element. In the verbose syntax, the order in which the properties are
set is not important. The relationship and mechanisms of these two alternatives
(compact and verbose) is described in more detail in the topic Markup Extensions and
WPF XAML.

Technically, the value for targetID can be any object, it does not have to be a string.
However, the most common usage in WPF is to align the targetID value with forms that
are strings, and where such strings are valid in the XamlName Grammar.

ComponentResourceKey can be used in object element syntax. In this case, specifying the

value of both the TypeInTargetAssembly and ResourceId properties is required to

properly initialize the extension.

In the WPF XAML reader implementation, the handling for this markup extension is
defined by the ComponentResourceKey class.

ComponentResourceKey is a markup extension. Markup extensions are typically

implemented when there is a requirement to escape attribute values to be other than

See also
ComponentResourceKey
ControlTemplate
Control Authoring Overview
XAML in WPF
Markup Extensions and WPF XAML
DateTime XAML Syntax
Article • 02/06/2023

Some controls, such as Calendar and DatePicker, have properties that use the DateTime
type. Although you typically specify an initial date or time for these controls in the code-
behind at run time, you can specify an initial date or time in XAML. The WPF XAML
parser handles parsing of DateTime values using a built-in XAML text syntax. This topic
describes the specifics of the DateTime XAML text syntax.

When To Use DateTime XAML Syntax

Setting dates in XAML is not always necessary and may not even be desirable. For
example, you could use the DateTime.Now property to initialize a date at run time, or
you could do all your date adjustments for a calendar in the code-behind based on user
input. However, there are scenarios where you may want to hard-code dates into a
Calendar and DatePicker in a control template. The DateTime XAML syntax must be
used for these scenarios.

DateTime XAML Syntax is a Native Behavior

DateTime is a class that is defined in the base class libraries of the CLR. Because of how
the base class libraries relate to the rest of the CLR, it is not possible to apply
TypeConverterAttribute to the class and use a type converter to process strings from
XAML and convert them to DateTime in the run time object model. There is no
DateTimeConverter class that provides the conversion behavior; the conversion behavior

described in this topic is native to the WPF XAML parser.

Format Strings for DateTime XAML Syntax

You can specify the format of a DateTime with a format string. Format strings formalize
the text syntax that can be used to create a value. DateTime values for the existing WPF
controls generally only use the date components of DateTime and not the time
components.

When specifying a DateTime in XAML, you can use any of the format strings
interchangeably.

You can also use formats and format strings that are not specifically shown in this topic.
Technically, the XAML for any DateTime value that is specified and then parsed by the
WPF XAML parser uses an internal call to DateTime.Parse, therefore you could use any
string accepted by DateTime.Parse for your XAML input. For more information, see
DateTime.Parse.

） Important

The DateTime XAML syntax always uses en-us as the CultureInfo for its native
conversion. This is not influenced by Language value or xml:lang value in the
XAML, because XAML attribute-level type conversion acts without that context. Do
not attempt to interpolate the format strings shown here due to cultural variations,
such as the order in which day and month appear. The format strings shown here
are the exact format strings used when parsing the XAML regardless of other
culture settings.

The following sections describe some of the common DateTime format strings.

Short Date Pattern ("d")

The following shows the short date format for a DateTime in XAML:

M/d/YYYY

This is the simplest form that specifies all necessary information for typical usages by
WPF controls, and cannot be influenced by accidental time zone offsets versus a time
component, and is therefore recommended over the other formats.

For example, to specify the date of June 1, 2010, use the following string:

3/1/2010

For more information, see DateTimeFormatInfo.ShortDatePattern.

Sortable DateTime Pattern ("s")

The following shows the sortable DateTime pattern in XAML:

yyyy'-'MM'-'dd'T'HH':'mm':'ss

For example, to specify the date of June 1, 2010, use the following string (time
components are all entered as 0):

2010-06-01T000:00:00
RFC1123 Pattern ("r")
The RFC1123 pattern is useful because it could be a string input from other date
generators that also use the RFC1123 pattern for culture invariant reasons. The following
shows the RFC1123 DateTime pattern in XAML:

ddd, dd MMM yyyy HH':'mm':'ss 'UTC'

For example, to specify the date of June 1, 2010, use the following string (time
components are all entered as 0):

Mon, 01 Jun 2010 00:00:00 UTC

Other Formats and Patterns

As stated previously, a DateTime in XAML can be specified as any string that is
acceptable as input for DateTime.Parse. This includes other formalized formats (for
example UniversalSortableDateTimePattern), and formats that are not formalized as a
particular DateTimeFormatInfo form. For example, the form YYYY/mm/dd is acceptable as
input for DateTime.Parse. This topic does not attempt to describe all possible formats
that work, and instead recommends the short date pattern as a standard practice.

See also
XAML in WPF
DynamicResource Markup Extension
Article • 02/06/2023

Provides a value for any XAML property attribute by deferring that value to be a
reference to a defined resource. Lookup behavior for that resource is analogous to run-
time lookup.

XAML Attribute Usage

XML

<object property="{DynamicResource key}" ... />

XAML Property Element Usage

XML

XAML Values
Value Description

key The key for the requested resource. This key was initially assigned by the x:Key Directive if
a resource was created in markup, or was provided as the key parameter when calling
ResourceDictionary.Add if the resource was created in code.

Remarks
A DynamicResource will create a temporary expression during the initial compilation and
thus defer lookup for resources until the requested resource value is actually required in
order to construct an object. This may potentially be after the XAML page is loaded. The
resource value will be found based on key search against all active resource dictionaries
starting from the current page scope, and is substituted for the placeholder expression
from compilation.
） Important

In terms of dependency property precedence, a DynamicResource expression is

equivalent to the position where the dynamic resource reference is applied. If you
set a local value for a property that previously had a DynamicResource expression as
the local value, the DynamicResource is completely removed. For details, see
Dependency Property Value Precedence.

Certain resource access scenarios are particularly appropriate for DynamicResource as

opposed to a StaticResource Markup Extension. See XAML Resources for a discussion
about the relative merits and performance implications of DynamicResource and
StaticResource .

The specified ResourceKey should correspond to an existing resource determined by

x:Key Directive at some level in your page, application, the available control themes and
external resources, or system resources, and the resource lookup will happen in that
order. For more information about resource lookup for static and dynamic resources,
see XAML Resources.

A resource key may be any string defined in the XamlName Grammar. A resource key
may also be other object types, such as a Type. A Type key is fundamental to how
controls can be styled by themes. For more information, see Control Authoring
Overview.

APIs for lookup of resource values, such as FindResource, follow the same resource
lookup logic as used by DynamicResource .

The alternative declarative means of referencing a resource is as a StaticResource

Markup Extension.

Attribute syntax is the most common syntax used with this markup extension. The string
token provided after the DynamicResource identifier string is assigned as the
ResourceKey value of the underlying DynamicResourceExtension extension class.

DynamicResource can be used in object element syntax. In this case, specifying the value

of the ResourceKey property is required.

DynamicResource can also be used in a verbose attribute usage that specifies the
ResourceKey property as a property=value pair:

XML
<object property="{DynamicResource ResourceKey=key}" ... />

The verbose usage is often useful for extensions that have more than one settable
property, or if some properties are optional. Because DynamicResource has only one
settable property, which is required, this verbose usage is not typical.

In the WPF XAML processor implementation, the handling for this markup extension is
defined by the DynamicResourceExtension class.

DynamicResource is a markup extension. Markup extensions are typically implemented

See also
XAML Resources
Resources and Code
x:Key Directive
XAML in WPF
Markup Extensions and WPF XAML
StaticResource Markup Extension
Markup Extensions and WPF XAML
RelativeSource MarkupExtension
Article • 03/17/2022

Specifies properties of a RelativeSource binding source, to be used within a Binding

Markup Extension, or when setting the RelativeSource property of a Binding element
established in XAML.

XAML Attribute Usage

XML

<Binding RelativeSource="{RelativeSource modeEnumValue}" ... />

XAML Attribute Usage (nested within Binding

extension)
XML

<object property="{Binding RelativeSource={RelativeSource modeEnumValue}

...}" ... />

XAML Object Element Usage

XML

-or-

XML

XAML Values
Value Description

modeEnumValue One of the following:

- The string token Self ; corresponds to a RelativeSource as created with its

Mode property set to Self.
- The string token TemplatedParent ; corresponds to a RelativeSource as created
with its Mode property set to TemplatedParent.
- The string token PreviousData ; corresponds to a RelativeSource as created with
its Mode property set to PreviousData.
- See below for information on FindAncestor mode.

FindAncestor The string token FindAncestor . Using this token enters a mode whereby a
RelativeSource specifies an ancestor type and optionally an ancestor level. This
corresponds to a RelativeSource as created with its Mode property set to
FindAncestor.

typeName Required for FindAncestor mode. The name of a type, which fills the
AncestorType property.

intLevel Optional for FindAncestor mode. An ancestor level (evaluated towards the
parent direction in the logical tree).

Remarks
{RelativeSource TemplatedParent} binding usages are a key technique that addresses a

larger concept of the separation of a control's UI and a control's logic. This enables
binding from within the template definition to the templated parent (the run time object
instance where the template is applied). For this case, the TemplateBinding Markup
Extension is in fact a shorthand for the following binding expression: {Binding
RelativeSource={RelativeSource TemplatedParent}} . TemplateBinding or
{RelativeSource TemplatedParent} usages are both only relevant within the XAML that

defines a template. For more information, see TemplateBinding Markup Extension.

{RelativeSource FindAncestor} is mainly used in control templates or predictable self-

contained UI compositions, for cases where a control is always expected to be in a visual
tree of a certain ancestor type. For example, items of an items control might use
FindAncestor usages to bind to properties of their items control parent ancestor. Or,

elements that are part of control composition in a template can use FindAncestor
bindings to the parent elements in that same composition structure.

In the object element syntax for FindAncestor mode shown in the XAML Syntax
sections, the second object element syntax is used specifically for FindAncestor mode.
FindAncestor mode requires an AncestorType value. You must set AncestorType as an

attribute using an x:Type Markup Extension reference to the type of ancestor to look for.
The AncestorType value is used when the binding request is processed at run-time.

For FindAncestor mode, the optional property AncestorLevel can help disambiguate the
ancestor lookup in cases where there is possibly more than one ancestor of that type
existing in the element tree.

For more information on how to use the FindAncestor mode, see RelativeSource.

{RelativeSource Self} is useful for scenarios where one property of an instance should

depend on the value of another property of the same instance, and no general
dependency property relationship (such as coercion) already exists between those two
properties. Although it is rare that two properties exist on an object such that the values
are literally identical (and are identically typed), you can also apply a Converter
parameter to a binding that has {RelativeSource Self} , and use the converter to
convert between source and target types. Another scenario for {RelativeSource Self} is
as part of a MultiDataTrigger.

For example, the following XAML defines a Rectangle element such that no matter what
value is entered for Width, the Rectangle is always a square: <Rectangle Width="200"
Height="{Binding RelativeSource={RelativeSource Self}, Path=Width}" .../>

{RelativeSource PreviousData} is useful either in data templates, or in cases where

bindings are using a collection as the data source. You can use {RelativeSource
PreviousData} to highlight relationships between adjacent data items in the collection. A
related technique is to establish a MultiBinding between the current and previous items
in the data source, and use a converter on that binding to determine the difference
between the two items and their properties.

In the following example, the first TextBlock in the items template displays the current
number. The second TextBlock binding is a MultiBinding that nominally has two Binding
constituents: the current record, and a binding that deliberately uses the previous data
record by using {RelativeSource PreviousData} . Then, a converter on the MultiBinding
calculates the difference and returns it to the binding.
XML

<ListBox Name="fibolist">
<ListBox.ItemTemplate>
<DataTemplate>
<StackPanel Orientation="Horizontal">
<TextBlock Text="{Binding}"/>
<TextBlock>, difference = </TextBlock>
<TextBlock>
<TextBlock.Text>
<MultiBinding Converter="{StaticResource
DiffConverter}">
<Binding/>
<Binding RelativeSource="{RelativeSource
PreviousData}"/>
</MultiBinding>
</TextBlock.Text>
</TextBlock>
</StackPanel>
</DataTemplate>
</ListBox.ItemTemplate>
</ListBox>

Describing data binding as a concept is not covered here, see Data Binding Overview.

In the WPF XAML processor implementation, the handling for this markup extension is
defined by the RelativeSource class.

RelativeSource is a markup extension. Markup extensions are typically implemented

See also
Binding
Styling and Templating
XAML in WPF
Markup Extensions and WPF XAML
Data Binding Overview
Binding Declarations Overview
x:Type Markup Extension
StaticResource Markup Extension
Article • 02/06/2023

Provides a value for any XAML property attribute by looking up a reference to an

already defined resource. Lookup behavior for that resource is analogous to load-time
lookup, which will look for resources that were previously loaded from the markup of
the current XAML page as well as other application sources, and will generate that
resource value as the property value in the run-time objects.

XAML Attribute Usage

XML

<object property="{StaticResource key}" ... />

XAML Object Element Usage

XML

XAML Values
Value Description

Remarks

） Important
A StaticResource must not attempt to make a forward reference to a resource that
is defined lexically further within the XAML file. Attempting to do so is not
supported, and even if such a reference does not fail, attempting the forward
reference will incur a load time performance penalty when the internal hash tables
representing a ResourceDictionary are searched. For best results, adjust the
composition of your resource dictionaries such that forward references can be
avoided. If you cannot avoid a forward reference, use DynamicResource Markup
Extension instead.

The specified ResourceKey should correspond to an existing resource, identified with an

x:Key Directive at some level in your page, application, the available control themes and
external resources, or system resources. The resource lookup occurs in that order. For
more information about resource lookup behavior for static and dynamic resources, see
XAML Resources.

A resource key can be any string defined in the XamlName Grammar. A resource key can
also be other object types, such as a Type. A Type key is fundamental to how controls
can be styled by themes, through an implicit style key. For more information, see
Control Authoring Overview.

The alternative declarative means of referencing a resource is as a DynamicResource

Markup Extension.

Attribute syntax is the most common syntax used with this markup extension. The string
token provided after the StaticResource identifier string is assigned as the ResourceKey
value of the underlying StaticResourceExtension extension class.

StaticResource can be used in object element syntax. In this case, specifying the value

of the ResourceKey property is required.

StaticResource can also be used in a verbose attribute usage that specifies the

ResourceKey property as a property=value pair:

XML

<object property="{StaticResource ResourceKey=key}" ... />

The verbose usage is often useful for extensions that have more than one settable
property, or if some properties are optional. Because StaticResource has only one
settable property, which is required, this verbose usage is not typical.
In the WPF XAML processor implementation, the handling for this markup extension is
defined by the StaticResourceExtension class.

StaticResource is a markup extension. Markup extensions are typically implemented

See also
Styling and Templating
XAML in WPF
Markup Extensions and WPF XAML
XAML Resources
Resources and Code
TemplateBinding Markup Extension
Article • 02/06/2023

Links the value of a property in a control template to be the value of another property
on the templated control.

XAML Attribute Usage

XML

<object property="{TemplateBinding sourceProperty}" ... />

XAML Attribute Usage (for Setter property in

template or style)
XML

<Setter Property="propertyName" Value="{TemplateBinding sourceProperty}" ...

XAML Values
Value Description

propertyName DependencyProperty.Name of the property being set in the setter syntax.

sourceProperty Another dependency property that exists on the type being templated,
specified by its DependencyProperty.Name.

- or -

A "dotted-down" property name that is defined by a different type than the

target type being templated. This is actually a PropertyPath. See PropertyPath
XAML Syntax.

Remarks
A TemplateBinding is an optimized form of a Binding for template scenarios, analogous
to a Binding constructed with {Binding RelativeSource={RelativeSource
TemplatedParent}, Mode=OneWay} . A TemplateBinding is always a one-way binding, even if

properties involved default to two-way binding. Both properties involved must be

dependency properties. In order to achieve two-way binding to a templated parent use
the following binding statement instead {Binding RelativeSource={RelativeSource
TemplatedParent}, Mode=TwoWay, Path=MyDependencyProperty} .

RelativeSource is another markup extension that is sometimes used in conjunction with

or instead of TemplateBinding in order to perform relative property binding within a
template.

Describing control templates as a concept is not covered here; for more information, see
Control Styles and Templates.

Attribute syntax is the most common syntax used with this markup extension. The string
token provided after the TemplateBinding identifier string is assigned as the Property
value of the underlying TemplateBindingExtension extension class.

Object element syntax is possible, but it is not shown because it has no realistic
application. TemplateBinding is used to fill values within setters, using evaluated
expressions, and using object element syntax for TemplateBinding to fill
<Setter.Property> property element syntax is unnecessarily verbose.

TemplateBinding can also be used in a verbose attribute usage that specifies the

Property property as a property=value pair:

XML

<object property="{TemplateBinding Property=sourceProperty}" ... />

The verbose usage is often useful for extensions that have more than one settable
property, or if some properties are optional. Because TemplateBinding has only one
settable property, which is required, this verbose usage is not typical.

In the WPF XAML processor implementation, the handling for this markup extension is
defined by the TemplateBindingExtension class.

TemplateBinding is a markup extension. Markup extensions are typically implemented

when there is a requirement to escape attribute values to be other than literal values or
handler names, and the requirement is more global than just putting type converters on
certain types or properties. All markup extensions in XAML use the { and } characters
in their attribute syntax, which is the convention by which a XAML processor recognizes
that a markup extension must process the attribute. For more information, see Markup
Extensions and WPF XAML.
See also
Style
ControlTemplate
Styling and Templating
XAML in WPF
Markup Extensions and WPF XAML
RelativeSource MarkupExtension
Binding Markup Extension
ThemeDictionary Markup Extension
Article • 02/06/2023

Provides a way for custom control authors or applications that integrate third-party
controls to load theme-specific resource dictionaries to use in styling the control.

XAML Attribute Usage

XML

<object property="{ThemeDictionary assemblyUri}" ... />

XAML Object Element Usage

XML

XAML Values
Value Description

assemblyUri The uniform resource identifier (URI) of the assembly that contains theme
information. Typically, this is a pack URI that references an assembly in the larger
package. Assembly resources and pack URIs simplify deployment issues. For more
information see Pack URIs in WPF.

Remarks
This extension is intended to fill only one specific property value: a value for
ResourceDictionary.Source.

By using this extension, you can specify a single resources-only assembly that contains
some styles to use only when the Windows Aero theme is applied to the user's system,
other styles only when the Luna theme is active, and so on. By using this extension, the
contents of a control-specific resource dictionary can be automatically invalidated and
reloaded to be specific for another theme when required.

The assemblyUri string (AssemblyName property value) forms the basis of a naming
convention that identifies which dictionary applies for a particular theme. The
ProvideValue logic for ThemeDictionary completes the convention by generating a
uniform resource identifier (URI) that points to a particular theme dictionary variant, as
contained within a precompiled resource assembly. Describing this convention, or
theme interactions with general control styling and page/application level styling as a
concept, is not covered fully here. The basic scenario for using ThemeDictionary is to
specify the Source property of a ResourceDictionary declared at the application level.
When you provide a URI for the assembly through a ThemeDictionary extension rather
than as a direct URI, the extension logic will provide invalidation logic that applies
whenever the system theme changes.

Attribute syntax is the most common syntax used with this markup extension. The string
token provided after the ThemeDictionary identifier string is assigned as the
AssemblyName value of the underlying ThemeDictionaryExtension extension class.

ThemeDictionary may also be used in object element syntax. In this case, specifying the
value of the AssemblyName property is required.

ThemeDictionary can also be used in a verbose attribute usage that specifies the
Member property as a property=value pair:

XML

<object property="{ThemeDictionary AssemblyName=assemblyUri}" ... />

The verbose usage is often useful for extensions that have more than one settable
property, or if some properties are optional. Because ThemeDictionary has only one
settable property, which is required, this verbose usage is not typical.

In the WPF XAML processor implementation, the handling for this markup extension is
defined by the ThemeDictionaryExtension class.

ThemeDictionary is a markup extension. Markup extensions are typically implemented

See also
Styling and Templating
XAML in WPF
Markup Extensions and WPF XAML
WPF Application Resource, Content, and Data Files
PropertyPath XAML Syntax
Article • 08/18/2022

The PropertyPath object supports a complex inline XAML syntax for setting various
properties that take the PropertyPath type as their value. This topic documents the
PropertyPath syntax as applied to binding and animation syntaxes.

Where PropertyPath Is Used

PropertyPath is a common object that is used in several Windows Presentation
Foundation (WPF) features. Despite using the common PropertyPath to convey property
path information, the usages for each feature area where PropertyPath is used as a type
vary. Therefore, it is more practical to document the syntaxes on a per-feature basis.

Primarily, WPF uses PropertyPath to describe object-model paths for traversing the
properties of an object data source, and to describe the target path for targeted
animations.

Some style and template properties such as Setter.Property take a qualified property
name that superficially resembles a PropertyPath. But this is not a true PropertyPath;
instead it is a qualified owner.property string format usage that is enabled by the WPF
XAML processor in combination with the type converter for DependencyProperty.

PropertyPath for Objects in Data Binding

Data binding is a WPF feature whereby you can bind to the target value of any
dependency property. However, the source of such a data binding need not be a
dependency property; it can be any property type that is recognized by the applicable
data provider. Property paths are particularly used for the ObjectDataProvider, which is
used for obtaining binding sources from common language runtime (CLR) objects and
their properties.

Note that data binding to XML does not use PropertyPath, because it does not use Path
in the Binding. Instead, you use XPath and specify valid XPath syntax into the XML
Document Object Model (DOM) of the data. XPath is also specified as a string, but is not
documented here; see Bind to XML Data Using an XMLDataProvider and XPath Queries.

A key to understanding property paths in data binding is that you can target the
binding to an individual property value, or you can instead bind to target properties that
take lists or collections. If you are binding collections, for instance binding a ListBox that
will expand depending on how many data items are in the collection, then your property
path should reference the collection object, not individual collection items. The data
binding engine will match the collection used as the data source to the type of the
binding target automatically, resulting in behavior such as populating a ListBox with an
items array.

Single Property on the Immediate Object as Data Context

XML

<Binding Path="propertyName" ... />

propertyName must resolve to be the name of a property that is in the current

DataContext for a Path usage. If your binding updates the source, that property must be
read/write and the source object must be mutable.

Single Indexer on the Immediate Object as Data Context

XML

<Binding Path="[key]" ... />

key must be either the typed index to a dictionary or hash table, or the integer index of

an array. Also, the value of the key must be a type that is directly bindable to the
property where it is applied. For instance, a hash table that contains string keys and
string values can be used this way to bind to Text for a TextBox. Or, if the key points to a
collection or subindex, you could use this syntax to bind to a target collection property.
Otherwise, you need to reference a specific property, through a syntax such as <Binding
Path="[key].propertyName" .../> .

You can specify the type of the index if necessary. For details on this aspect of an
indexed property path, see Binding.Path.

Multiple Property (Indirect Property Targeting)

XML

<Binding Path="propertyName.propertyName2" ... />

propertyName must resolve to be the name of a property that is the current DataContext.

The path properties propertyName and propertyName2 can be any properties that exist in
a relationship, where propertyName2 is a property that exists on the type that is the value
of propertyName .

Single Property, Attached or Otherwise Type-Qualified

XML

<object property="(ownerType.propertyName)" ... />

The parentheses indicate that this property in a PropertyPath should be constructed

using a partial qualification. It can use an XML namespace to find the type with an
appropriate mapping. The ownerType searches types that a XAML processor has access
to, through the XmlnsDefinitionAttribute declarations in each assembly. Most
applications have the default XML namespace mapped to the
http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, so a prefix is

usually only necessary for custom types or types otherwise outside that namespace.
propertyName must resolve to be the name of a property existing on the ownerType . This

syntax is generally used for one of the following cases:

The path is specified in XAML that is in a style or template that does not have a
specified Target Type. A qualified usage is generally not valid for cases other than
this, because in non-style, non-template cases, the property exists on an instance,
not a type.

The property is an attached property.

You are binding to a static property.

For use as storyboard target, the property specified as propertyName must be a

DependencyProperty.

Source Traversal (Binding to Hierarchies of Collections)

XML

<object Path="propertyName/propertyNameX" ... />

The / in this syntax is used to navigate within a hierarchical data source object, and
multiple steps into the hierarchy with successive / characters are supported. The source
traversal accounts for the current record pointer position, which is determined by
synchronizing the data with the UI of its view. For details on binding with hierarchical
data source objects, and the concept of current record pointer in data binding, see Use
the Master-Detail Pattern with Hierarchical Data or Data Binding Overview.

７ Note

Superficially, this syntax resembles XPath. A true XPath expression for binding to an
XML data source is not used as a Path value and should instead be used for the
mutually exclusive XPath property.

Collection Views
To reference a named collection view, prefix the collection view name with the hash
character ( # ).

Current Record Pointer

To reference the current record pointer for a collection view or master detail data
binding scenario, start the path string with a forward slash ( / ). Any path past the
forward slash is traversed starting from the current record pointer.

Multiple Indexers
XAML

<object Path="[index1,index2...]" ... />

XAML

<object Path="propertyName[index,index2...]" ... />

If a given object supports multiple indexers, those indexers can be specified in order,
similar to an array referencing syntax. The object in question can be either the current
context or the value of a property that contains a multiple index object.

By default, the indexer values are typed by using the characteristics of the underlying
object. You can specify the type of the index if necessary. For details on typing the
indexers, see Binding.Path.

Mixing Syntaxes
Each of the syntaxes shown above can be interspersed. For instance, the following is an
example that creates a property path to the color at a particular x,y of a ColorGrid
property that contains a pixel grid array of SolidColorBrush objects:

XML

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" ... />

Escapes for Property Path Strings

For certain business objects, you might encounter a case where the property path string
requires an escape sequence in order to parse correctly. The need to escape should be
rare, because many of these characters have similar naming-interaction issues in
languages that would typically be used to define the business object.

Inside indexers ([ ]), the caret character (^) escapes the next character.

You must escape (using XML entities) certain characters that are special to the XML
language definition. Use & to escape the character "&". Use > to escape the end
tag ">".

You must escape (using backslash \ ) characters that are special to the WPF XAML
parser behavior for processing a markup extension.

Backslash ( \ ) is the escape character itself.

The equal sign ( = ) separates property name from property value.

Comma ( , ) separates properties.

The right curly brace ( } ) is the end of a markup extension.

７ Note

Technically, these escapes work for a storyboard property path also, but you are
usually traversing object models for existing WPF objects, and escaping should be
unnecessary.
PropertyPath for Animation Targets
The target property of an animation must be a dependency property that takes either a
Freezable or a primitive type. However, the targeted property on a type and the
eventual animated property can exist on different objects. For animations, a property
path is used to define the connection between the named animation target object's
property and the intended target animation property, by traversing object-property
relationships in the property values.

General Object-Property Considerations for Animations

For more information on animation concepts in general, see Storyboards Overview and
Animation Overview.

The value type or the property being animated must be either a Freezable type or a
primitive. The property that starts the path must resolve to be the name of a
dependency property that exists on the specified TargetName type.

In order to support cloning for animating a Freezable that is already frozen, the object
specified by TargetName must be a FrameworkElement or FrameworkContentElement
derived class.

Single Property on the Target Object

XML

<animation Storyboard.TargetProperty="propertyName" ... />

propertyName must resolve to be the name of a dependency property that exists on the
specified TargetName type.

Indirect Property Targeting

XML

<animation Storyboard.TargetProperty="propertyName.propertyName2" ... />

propertyName must be a property that is either a Freezable value type or a primitive,

which exists on the specified TargetName type.
propertyName2 must be the name of a dependency property that exists on the object

that is the value of propertyName . In other words, propertyName2 must exist as a

dependency property on the type that is the propertyName PropertyType.

Indirect targeting of animations is necessary because of applied styles and templates. In

order to target an animation, you need a TargetName on a target object, and that name
is established by x:Name or Name. Although template and style elements also can have
names, those names are only valid within the namescope of the style and template. (If
templates and styles did share namescopes with application markup, names couldn't be
unique. The styles and templates are literally shared between instances and would
perpetuate duplicate names.) Thus, if the individual properties of an element that you
might wish to animate came from a style or template, you need to start with a named
element instance that is not from a style template, and then target into the style or
template visual tree to arrive at the property you wish to animate.

For instance, the Background property of a Panel is a complete Brush (actually a

SolidColorBrush) that came from a theme template. To animate a Brush completely,
there would need to be a BrushAnimation (probably one for every Brush type) and there
is no such type. To animate a Brush, you instead animate properties of a particular Brush
type. You need to get from SolidColorBrush to its Color to apply a ColorAnimation there.
The property path for this example would be Background.Color .

Attached Properties
XML

<animation Storyboard.TargetProperty="(ownerType.propertyName)" ... />

The parentheses indicate that this property in a PropertyPath should be constructed

using a partial qualification. It can use an XML namespace to find the type. The
ownerType searches types that a WPF attached properties are implemented as

dependency properties, so this issue is only of concern for custom attached properties.)

Indexers
XML

<animation
Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3"
... />
Most dependency properties or Freezable types do not support an indexer. Therefore,
the only usage for an indexer in an animation path is at an intermediate position
between the property that starts the chain on the named target and the eventual
animated property. In the provided syntax, that is propertyName2 . For instance, an
indexer usage might be necessary if the intermediate property is a collection such as
TransformGroup, in a property path such as RenderTransform.Children[1].Angle .

PropertyPath in Code
Code usage for PropertyPath, including how to construct a PropertyPath, is documented
in the reference topic for PropertyPath.

In general, PropertyPath is designed to use two different constructors, one for the
binding usages and simplest animation usages, and one for the complex animation
usages. Use the PropertyPath(Object) signature for binding usages, where the object is a
string. Use the PropertyPath(Object) signature for one-step animation paths, where the
object is a DependencyProperty. Use the PropertyPath(String, Object[]) signature for
complex animations. This latter constructor uses a token string for the first parameter
and an array of objects that fill positions in the token string to define a property path
relationship.

See also
PropertyPath
Data Binding Overview
Storyboards Overview
PresentationOptions:Freeze Attribute
Article • 08/10/2023

Sets the IsFrozen state to true on the containing Freezable element. Default behavior
for a Freezable without the PresentationOptions:Freeze attribute specified is that
IsFrozen is false at load time, and dependent on general Freezable behavior at runtime.

XAML Attribute Usage

XAML

<object

xmlns:PresentationOptions="http://schemas.microsoft.com/winfx/2006/xaml/pres
entation/options"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="PresentationOptions">
<freezableElement PresentationOptions:Freeze="true"/>
</object>

XAML Values
Value Description

PresentationOptions An XML namespace prefix, which can be any valid prefix string, per the
XML 1.0 specification. The prefix PresentationOptions is used for
identification purposes in this documentation.

freezableElement An element that instantiates any derived class of Freezable.

Remarks
The Freeze attribute is the only attribute or other programming element defined in the
http://schemas.microsoft.com/winfx/2006/xaml/presentation/options XML namespace.

The Freeze attribute exists in this special namespace specifically so that it can be
designated as ignorable, using mc:Ignorable Attribute as part of the root element
declarations. The reason that Freeze must be able to be ignorable is because not all
XAML processor implementations are able to freeze a Freezable at load time; this
capability is not part of the XAML specification.
The ability to process the Freeze attribute is specifically built in to the XAML processor
that processes XAML for compiled applications. The attribute is not supported by any
class, and the attribute syntax is not extensible or modifiable. If you are implementing
your own XAML processor you can choose to parallel the freezing behavior of the WPF
XAML processor when processing the Freeze attribute on Freezable elements at load
time.

Any value for the Freeze attribute other than true (not case sensitive) generates a load
time error. (Specifying the Freeze attribute as false is not an error, but that is already
the default, so setting to false does nothing).

See also
Freezable
Freezable Objects Overview
mc:Ignorable Attribute
Markup Compatibility (mc:) Language
Features
Article • 02/06/2023

In This Section
mc:Ignorable Attribute
mc:ProcessContent Attribute
mc:Ignorable Attribute
Article • 02/06/2023

Specifies which XML namespace prefixes encountered in a markup file may be ignored
by a XAML processor. The mc:Ignorable attribute supports markup compatibility both
for custom namespace mapping and for XAML versioning.

XAML Attribute Usage (Single Prefix)

XAML

XAML Attribute Usage (Two Prefixes)

XAML

XAML Values
Value Description

ignorablePrefix, Any valid prefix string, per the XML 1.0 specification.
ignorablePrefix1, etc.

ignorableUri Any valid URI for designating a namespace, per the XML 1.0
specification.
Value Description

ThisElementCanBeIgnored An element that can be ignored by Extensible Application Markup

Language (XAML) processor implementations, if the underlying type
cannot be resolved.

Remarks
The mc XML namespace prefix is the recommended prefix convention to use when
mapping the XAML compatibility namespace
http://schemas.openxmlformats.org/markup-compatibility/2006 .

Elements or attributes where the prefix portion of the element name are identified as
mc:Ignorable will not raise errors when processed by a XAML processor. If that attribute
could not be resolved to an underlying type or programming construct, then that
element is ignored. Note however that ignored elements might still generate additional
parsing errors for additional element requirements that are side effects of that element
not being processed. For instance, a particular element content model might require
exactly one child element, but if the specified child element was in an mc:Ignorable
prefix, and the specified child element could not be resolved to a type, then the XAML
processor might raise an error.

mc:Ignorable only applies to namespace mappings to identifier strings. mc:Ignorable

does not apply to namespace mappings into assemblies, which specify a CLR
namespace and an assembly (or default to the current executable as the assembly).

If you are implementing a XAML processor, your processor implementation must not
raise parsing or processing errors on type resolution for any element or attribute that is
qualified by a prefix that is identified as mc:Ignorable . But your processor
implementation can still raise exceptions that are a secondary result of an element
failing to load or be processed, such as the one-child element example given earlier.

By default, a XAML processor will ignore content within an ignored element. However,
you can specify an additional attribute, mc:ProcessContent Attribute, to require
continued processing of content within an ignored element by the next available parent
element.

Multiple prefixes can be specified in the attribute, using one or more white-space
characters as the separator, for example: mc:Ignorable="ignore1 ignore2" .

The http://schemas.openxmlformats.org/markup-compatibility/2006 namespace defines

other elements and attributes that are not documented within this area of the SDK. For
more information, see XML Markup Compatibility Specification.

See also
XamlReader
PresentationOptions:Freeze Attribute
XAML in WPF
Documents in WPF
mc:ProcessContent Attribute
Article • 03/17/2022

Specifies which XAML elements should still have content processed by relevant parent
elements, even if the immediate parent element may be ignored by a XAML processor
due to specifying mc:Ignorable Attribute. The mc:ProcessContent attribute supports
markup compatibility both for custom namespace mapping and for XAML versioning.

XAML Attribute Usage

XAML

XAML Values
Value Description

ignorablePrefix Any valid prefix string, per the XML 1.0 specification.

ignorableUri Any valid URI for designating a namespace, per the XML 1.0
specification.

ThisElementCanBeIgnored An element that can be ignored by Extensible Application Markup

Language (XAML) processor implementations, if the underlying type
cannot be resolved.

[content] ThisElementCanBeIgnored is marked ignorable. If the processor

ignores that element, [content] is processed by object.

Remarks
By default, a XAML processor will ignore content within an ignored element. You can
specify a specific element by mc:ProcessContent , and a XAML processor will continue to
process the content within the ignored element. This would typically be used if the
content is nested within several tags, at least one of which is ignorable and at least one
of which is not ignorable.

Multiple prefixes may be specified in the attribute, using a space separator, for example:
mc:ProcessContent="ignore:Element1 ignore:Element2" .

The http://schemas.openxmlformats.org/markup-compatibility/2006 namespace defines

other elements and attributes that are not documented within this area of the SDK. For
more information, see XML Markup Compatibility Specification.

See also
mc:Ignorable Attribute
XAML in WPF
Base Elements
Article • 02/06/2023

Four key classes--UIElement, ContentElement, FrameworkElement, and

FrameworkContentElement--implement a substantial percentage of the common
element functionality available in WPF programming. These four classes are referred to
in this SDK as the base element classes.

In This Section
Base Elements Overview
Freezable Objects Overview
Alignment, Margins, and Padding Overview
How-to Topics

Reference
UIElement

ContentElement

FrameworkElement

FrameworkContentElement

Related Sections
WPF Architecture
XAML in WPF
Element Tree and Serialization
Properties
Events
Input
Resources
Styling and Templating
Threading Model
Base Elements Overview
Article • 02/06/2023

A high percentage of classes in Windows Presentation Foundation (WPF) are derived

from four classes which are commonly referred to in the SDK documentation as the base
element classes. These classes are UIElement, FrameworkElement, ContentElement, and
FrameworkContentElement. The DependencyObject class is also related, because it is a
common base class of both UIElement and ContentElement

Base Element APIs in WPF Classes

Both UIElement and ContentElement are derived from DependencyObject, through
somewhat different pathways. The split at this level deals with how a UIElement or
ContentElement are used in a user interface and what purpose they serve in an
application. UIElement also has Visual in its class hierarchy, which is a class that exposes
the lower-level graphics support underlying the Windows Presentation Foundation
(WPF). Visual provides a rendering framework by defining independent rectangular
screen regions. In practice, UIElement is for elements that will support a larger object
model, are intended to render and layout into regions that can be described as
rectangular screen regions, and where the content model is deliberately more open, to
allow different combinations of elements. ContentElement does not derive from Visual;
its model is that a ContentElement would be consumed by something else, such as a
reader or viewer that would then interpret the elements and produce the complete
Visual for Windows Presentation Foundation (WPF) to consume. Certain UIElement
classes are intended to be content hosts: they provide the hosting and rendering for
one or more ContentElement classes (DocumentViewer is an example of such a class).
ContentElement is used as base class for elements with somewhat smaller object models
and that more address the text, information, or document content that might be hosted
within a UIElement.

Framework-Level and Core-Level

UIElement serves as the base class for FrameworkElement, and ContentElement serves
as the base class for FrameworkContentElement. The reason for this next level of classes
is to support a WPF core level that is separate from a WPF framework level, with this
division also existing in how the APIs are divided between the PresentationCore and
PresentationFramework assemblies. The WPF framework level presents a more complete
solution for basic application needs, including the implementation of the layout
manager for presentation. The WPF core level provides a way to use much of WPF
without taking the overhead of the additional assembly. The distinction between these
levels very rarely matters for most typical application development scenarios, and in
general you should think of the WPF APIs as a whole and not concern yourself with the
difference between WPF framework level and WPF core level. You might need to know
about the level distinctions if your application design chooses to replace substantial
quantities of WPF framework level functionality, for instance if your overall solution
already has its own implementations of user interface (UI) composition and layout.

Choosing Which Element to Derive From

The most practical way to create a custom class that extends WPF is by deriving from
one of the WPF classes where you get as much as possible of your desired functionality
through the existing class hierarchy. This section lists the functionality that comes with
three of the most important element classes to help you decide which class to inherit
from.

If you are implementing a control, which is really one of the more common reasons for
deriving from a WPF class, you probably want to derive from a class that is a practical
control, a control family base class, or at least from the Control base class. For some
guidance and practical examples, see Control Authoring Overview.

If you are not creating a control and need to derive from a class that is higher in the
hierarchy, the following sections are intended as a guide for what characteristics are
defined in each base element class.

If you create a class that derives from DependencyObject, you inherit the following
functionality:

GetValue and SetValue support, and general property system support.

Ability to use dependency properties and attached properties that are

implemented as dependency properties.

If you create a class that derives from UIElement, you inherit the following functionality
in addition to that provided by DependencyObject:

Basic support for animated property values. For more information, see Animation
Overview.

Basic input event support, and commanding support. For more information, see
Input Overview and Commanding Overview.

Virtual methods that can be overridden to provide information to a layout system.

If you create a class that derives from FrameworkElement, you inherit the following
functionality in addition to that provided by UIElement:

Support for styling and storyboards. For more information, see Style and
Storyboards Overview.

Support for data binding. For more information, see Data Binding Overview.

Support for dynamic resource references. For more information, see XAML
Resources.

Property value inheritance support, and other flags in the metadata that help
report conditions about properties to framework services such as data binding,
styles, or the framework implementation of layout. For more information, see
Framework Property Metadata.

The concept of the logical tree. For more information, see Trees in WPF.

Support for the practical WPF framework-level implementation of the layout

system, including an OnPropertyChanged override that can detect changes to
properties that influence layout.

If you create a class that derives from ContentElement, you inherit the following
functionality in addition to that provided by DependencyObject:

Support for animations. For more information, see Animation Overview.

Basic input event support, and commanding support. For more information, see
Input Overview and Commanding Overview.

If you create a class that derives from FrameworkContentElement, you get the following
functionality in addition to that provided by ContentElement:

Support for styling and storyboards. For more information, see Style and
Animation Overview.

Support for data binding. For more information, see Data Binding Overview.

Support for dynamic resource references. For more information, see XAML
Resources.

Property value inheritance support, and other flags in the metadata that help
report conditions about properties to framework services like data binding, styles,
or the framework implementation of layout. For more information, see Framework
Property Metadata.
You do not inherit access to layout system modifications (such as
ArrangeOverride). Layout system implementations are only available on
FrameworkElement. However, you inherit an OnPropertyChanged override that can
detect changes to properties that influence layout and report these to any content
hosts.

Content models are documented for a variety of classes. The content model for a class is
one possible factor you should consider if you want to find an appropriate class to
derive from. For more information, see WPF Content Model.

Other Base Classes

DispatcherObject
DispatcherObject provides support for the WPF threading model and enables all objects
created for WPF applications to be associated with a Dispatcher. Even if you do not
derive from UIElement, DependencyObject, or Visual, you should consider deriving from
DispatcherObject in order to get this threading model support. For more information,
see Threading Model.

Visual
Visual implements the concept of a 2D object that generally requires visual presentation
in a roughly rectangular region. The actual rendering of a Visual happens in other
classes (it is not self-contained), but the Visual class provides a known type that is used
by rendering processes at various levels. Visual implements hit testing, but it does not
expose events that report hit-testing positives (these are in UIElement). For more
information, see Visual Layer Programming.

Freezable
Freezable simulates immutability in a mutable object by providing the means to
generate copies of the object when an immutable object is required or desired for
performance reasons. The Freezable type provides a common basis for certain graphics
elements such as geometries and brushes, as well as animations. Notably, a Freezable is
not a Visual; it can hold properties that become subproperties when the Freezable is
applied to fill a property value of another object, and those subproperties might affect
rendering. For more information, see Freezable Objects Overview.

Animatable
Animatable is a Freezable derived class that specifically adds the animation control layer
and some utility members so that currently animated properties can be distinguished
from nonanimated properties.

Control
Control is the intended base class for the type of object that is variously termed a
control or component, depending on the technology. In general, WPF control classes
are classes that either directly represent a UI control or participate closely in control
composition. The primary functionality that Control enables is control templating.

See also
Control
Dependency Properties Overview
Control Authoring Overview
WPF Architecture
Freezable Objects Overview
Article • 08/04/2022

This topic describes how to effectively use and create Freezable objects, which provide
special features that can help improve application performance. Examples of freezable
objects include brushes, pens, transformations, geometries, and animations.

What Is a Freezable?
A Freezable is a special type of object that has two states: unfrozen and frozen. When
unfrozen, a Freezable appears to behave like any other object. When frozen, a Freezable
can no longer be modified.

A Freezable provides a Changed event to notify observers of any modifications to the

object. Freezing a Freezable can improve its performance, because it no longer needs to
spend resources on change notifications. A frozen Freezable can also be shared across
threads, while an unfrozen Freezable cannot.

Although the Freezable class has many applications, most Freezable objects in Windows
Presentation Foundation (WPF) are related to the graphics sub-system.

The Freezable class makes it easier to use certain graphics system objects and can help
improve application performance. Examples of types that inherit from Freezable include
the Brush, Transform, and Geometry classes. Because they contain unmanaged
resources, the system must monitor these objects for modifications, and then update
their corresponding unmanaged resources when there is a change to the original object.
Even if you don't actually modify a graphics system object, the system must still spend
some of its resources monitoring the object, in case you do change it.

For example, suppose you create a SolidColorBrush brush and use it to paint the
background of a button.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);
myButton.Background = myBrush;

When the button is rendered, the WPF graphics sub-system uses the information you
provided to paint a group of pixels to create the appearance of a button. Although you
used a solid color brush to describe how the button should be painted, your solid color
brush doesn't actually do the painting. The graphics system generates fast, low-level
objects for the button and the brush, and it is those objects that actually appear on the
screen.

If you were to modify the brush, those low-level objects would have to be regenerated.
The freezable class is what gives a brush the ability to find its corresponding generated,
low-level objects and to update them when it changes. When this ability is enabled, the
brush is said to be "unfrozen."

A freezable's Freeze method enables you to disable this self-updating ability. You can
use this method to make the brush become "frozen," or unmodifiable.

７ Note

Not every Freezable object can be frozen. To avoid throwing an

InvalidOperationException, check the value of the Freezable object's CanFreeze
property to determine whether it can be frozen before attempting to freeze it.

if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}

When you no longer need to modify a freezable, freezing it provides performance

benefits. If you were to freeze the brush in this example, the graphics system would no
longer need to monitor it for changes. The graphics system can also make other
optimizations, because it knows the brush won't change.

７ Note

For convenience, freezable objects remain unfrozen unless you explicitly freeze
them.

Using Freezables
Using an unfrozen freezable is like using any other type of object. In the following
example, the color of a SolidColorBrush is changed from yellow to red after it's used to
paint the background of a button. The graphics system works behind the scenes to
automatically change the button from yellow to red the next time the screen is
refreshed.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);
myButton.Background = myBrush;

// Changes the button's background to red.

myBrush.Color = Colors.Red;

Freezing a Freezable
To make a Freezable unmodifiable, you call its Freeze method. When you freeze an
object that contains freezable objects, those objects are frozen as well. For example, if
you freeze a PathGeometry, the figures and segments it contains would be frozen too.

A Freezable can't be frozen if any of the following are true:

It has animated or data bound properties.

It has properties set by a dynamic resource. (See the XAML Resources for more
information about dynamic resources.)

It contains Freezable sub-objects that can't be frozen.

If these conditions are false, and you don't intend to modify the Freezable, then you
should freeze it to gain the performance benefits described earlier.

Once you call a freezable's Freeze method, it can no longer be modified. Attempting to
modify a frozen object causes an InvalidOperationException to be thrown. The following
code throws an exception, because we attempt to modify the brush after it's been
frozen.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}
myButton.Background = myBrush;

try {

// Throws an InvalidOperationException, because the brush is frozen.

myBrush.Color = Colors.Red;
}catch(InvalidOperationException ex)
{
MessageBox.Show("Invalid operation: " + ex.ToString());
}

To avoid throwing this exception, you can use the IsFrozen method to determine
whether a Freezable is frozen.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}

myButton.Background = myBrush;

if (myBrush.IsFrozen) // Evaluates to true.

{
// If the brush is frozen, create a clone and
// modify the clone.
SolidColorBrush myBrushClone = myBrush.Clone();
myBrushClone.Color = Colors.Red;
myButton.Background = myBrushClone;
}
else
{
// If the brush is not frozen,
// it can be modified directly.
myBrush.Color = Colors.Red;
}

In the preceding code example, a modifiable copy was made of a frozen object using
the Clone method. The next section discusses cloning in more detail.

７ Note
Because a frozen freezable cannot be animated, the animation system will
automatically create modifiable clones of frozen Freezable objects when you try to
animate them with a Storyboard. To eliminate the performance overhead caused
by cloning, leave an object unfrozen if you intend to animate it. For more
information about animating with storyboards, see the Storyboards Overview.

Freezing from Markup

To freeze a Freezable object declared in markup, you use the
PresentationOptions:Freeze attribute. In the following example, a SolidColorBrush is

declared as a page resource and frozen. It is then used to set the background of a
button.

XAML

<Page.Resources>

<Button Content="A Button"

Background="{StaticResource MyBrush}">
</Button>

</StackPanel>
</Page>

To use the Freeze attribute, you must map to the presentation options namespace:
http://schemas.microsoft.com/winfx/2006/xaml/presentation/options .

PresentationOptions is the recommended prefix for mapping this namespace:

XAML

Because not all XAML readers recognize this attribute, it's recommended that you use
the mc:Ignorable Attribute to mark the Presentation:Freeze attribute as ignorable:

XAML

xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="PresentationOptions"

For more information, see the mc:Ignorable Attribute page.

"Unfreezing" a Freezable
Once frozen, a Freezable can never be modified or unfrozen; however, you can create an
unfrozen clone using the Clone or CloneCurrentValue method.

In the following example, the button's background is set with a brush and that brush is
then frozen. An unfrozen copy is made of the brush using the Clone method. The clone
is modified and used to change the button's background from yellow to red.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

// Freezing a Freezable before it provides

// performance improvements if you don't
// intend on modifying it.
if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}

myButton.Background = myBrush;

// If you need to modify a frozen brush,

// the Clone method can be used to
// create a modifiable copy.
SolidColorBrush myBrushClone = myBrush.Clone();

// Changing myBrushClone does not change

// the color of myButton, because its
// background is still set by myBrush.
myBrushClone.Color = Colors.Red;

// Replacing myBrush with myBrushClone

// makes the button change to red.
myButton.Background = myBrushClone;

７ Note

Regardless of which clone method you use, animations are never copied to the new
Freezable.

The Clone and CloneCurrentValue methods produce deep copies of the freezable. If the
freezable contains other frozen freezable objects, they are also cloned and made
modifiable. For example, if you clone a frozen PathGeometry to make it modifiable, the
figures and segments it contains are also copied and made modifiable.

Creating Your Own Freezable Class

A class that derives from Freezable gains the following features.

Special states: a read-only (frozen) and a writable state.

Thread safety: a frozen Freezable can be shared across threads.

Detailed change notification: Unlike other DependencyObjects, Freezable objects

provide change notifications when sub-property values change.

Easy cloning: the Freezable class has already implemented several methods that
produce deep clones.

A Freezable is a type of DependencyObject, and therefore uses the dependency

property system. Your class properties don't have to be dependency properties, but
using dependency properties will reduce the amount of code you have to write, because
the Freezable class was designed with dependency properties in mind. For more
information about the dependency property system, see the Dependency Properties
Overview.

Every Freezable subclass must override the CreateInstanceCore method. If your class
uses dependency properties for all its data, you're finished.

If your class contains non-dependency property data members, you must also override
the following methods:

CloneCore
CloneCurrentValueCore

GetAsFrozenCore

GetCurrentValueAsFrozenCore

FreezeCore

You must also observe the following rules for accessing and writing to data members
that are not dependency properties:

At the beginning of any API that reads non-dependency property data members,
call the ReadPreamble method.

At the beginning of any API that writes non-dependency property data members,
call the WritePreamble method. (Once you've called WritePreamble in an API, you
don't need to make an additional call to ReadPreamble if you also read non-
dependency property data members.)

Call the WritePostscript method before exiting methods that write to non-
dependency property data members.

If your class contains non-dependency-property data members that are

DependencyObject objects, you must also call the OnFreezablePropertyChanged
method each time you change one of their values, even if you're setting the member to
null .

７ Note

It's very important that you begin each Freezable method you override with a call
to the base implementation.

For an example of a custom Freezable class, see the Custom Animation Sample .

See also
Freezable
Custom Animation Sample
Dependency Properties Overview
Custom Dependency Properties
Alignment, Margins, and Padding
Overview
Article • 03/17/2022

The FrameworkElement class exposes several properties that are used to precisely
position child elements. This topic discusses four of the most important properties:
HorizontalAlignment, Margin, Padding, and VerticalAlignment. The effects of these
properties are important to understand, because they provide the basis for controlling
the position of elements in Windows Presentation Foundation (WPF) applications.

Introduction to Element Positioning

There are numerous ways to position elements using WPF. However, achieving ideal
layout goes beyond simply choosing the right Panel element. Fine control of positioning
requires an understanding of the HorizontalAlignment, Margin, Padding, and
VerticalAlignment properties.

The following illustration shows a layout scenario that utilizes several positioning
properties.

At first glance, the Button elements in this illustration may appear to be placed
randomly. However, their positions are actually precisely controlled by using a
combination of margins, alignments, and padding.

The following example describes how to create the layout in the preceding illustration. A
Border element encapsulates a parent StackPanel, with a Padding value of 15 device
independent pixels. This accounts for the narrow LightBlue band that surrounds the
child StackPanel. Child elements of the StackPanel are used to illustrate each of the
various positioning properties that are detailed in this topic. Three Button elements are
used to demonstrate both the Margin and HorizontalAlignment properties.

C#
// Create the application's main Window.
mainWindow = new Window ();
mainWindow.Title = "Margins, Padding and Alignment Sample";

// Add a Border
myBorder = new Border();
myBorder.Background = Brushes.LightBlue;
myBorder.BorderBrush = Brushes.Black;
myBorder.Padding = new Thickness(15);
myBorder.BorderThickness = new Thickness(2);

myStackPanel = new StackPanel();

myStackPanel.Background = Brushes.White;
myStackPanel.HorizontalAlignment = HorizontalAlignment.Center;
myStackPanel.VerticalAlignment = VerticalAlignment.Top;

TextBlock myTextBlock = new TextBlock();

myTextBlock.Margin = new Thickness(5, 0, 5, 0);
myTextBlock.FontSize = 18;
myTextBlock.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock.Text = "Alignment, Margin and Padding Sample";
Button myButton1 = new Button();
myButton1.HorizontalAlignment = HorizontalAlignment.Left;
myButton1.Margin = new Thickness(20);
myButton1.Content = "Button 1";
Button myButton2 = new Button();
myButton2.HorizontalAlignment = HorizontalAlignment.Right;
myButton2.Margin = new Thickness(10);
myButton2.Content = "Button 2";
Button myButton3 = new Button();
myButton3.HorizontalAlignment = HorizontalAlignment.Stretch;
myButton3.Margin = new Thickness(0);
myButton3.Content = "Button 3";

// Add child elements to the parent StackPanel.

myStackPanel.Children.Add(myTextBlock);
myStackPanel.Children.Add(myButton1);
myStackPanel.Children.Add(myButton2);
myStackPanel.Children.Add(myButton3);

// Add the StackPanel as the lone Child of the Border.

myBorder.Child = myStackPanel;

// Add the Border as the Content of the Parent Window Object.

mainWindow.Content = myBorder;
mainWindow.Show ();

The following diagram provides a close-up view of the various positioning properties
that are used in the preceding sample. Subsequent sections in this topic describe in
greater detail how to use each positioning property.
Understanding Alignment Properties
The HorizontalAlignment and VerticalAlignment properties describe how a child element
should be positioned within a parent element's allocated layout space. By using these
properties together, you can position child elements precisely. For example, child
elements of a DockPanel can specify four different horizontal alignments: Left, Right, or
Center, or to Stretch to fill available space. Similar values are available for vertical
positioning.

７ Note

Explicitly-set Height and Width properties on an element take precedence over the
Stretch property value. Attempting to set Height, Width, and a
HorizontalAlignment value of Stretch results in the Stretch request being
ignored.

HorizontalAlignment Property
The HorizontalAlignment property declares the horizontal alignment characteristics to
apply to child elements. The following table shows each of the possible values of the
HorizontalAlignment property.

Member Description

Left Child elements are aligned to the left of the parent element's allocated layout space.
Member Description

Center Child elements are aligned to the center of the parent element's allocated layout
space.

Right Child elements are aligned to the right of the parent element's allocated layout space.

Stretch Child elements are stretched to fill the parent element's allocated layout space.
(Default) Explicit Width and Height values take precedence.

The following example shows how to apply the HorizontalAlignment property to Button
elements. Each attribute value is shown, to better illustrate the various rendering
behaviors.

Button myButton1 = new Button();

myButton1.HorizontalAlignment = HorizontalAlignment.Left;
myButton1.Content = "Button 1 (Left)";
Button myButton2 = new Button();
myButton2.HorizontalAlignment = HorizontalAlignment.Right;
myButton2.Content = "Button 2 (Right)";
Button myButton3 = new Button();
myButton3.HorizontalAlignment = HorizontalAlignment.Center;
myButton3.Content = "Button 3 (Center)";
Button myButton4 = new Button();
myButton4.HorizontalAlignment = HorizontalAlignment.Stretch;
myButton4.Content = "Button 4 (Stretch)";

The preceding code yields a layout similar to the following image. The positioning
effects of each HorizontalAlignment value are visible in the illustration.

VerticalAlignment Property
The VerticalAlignment property describes the vertical alignment characteristics to apply
to child elements. The following table shows each of the possible values for the
VerticalAlignment property.
Member Description

Top Child elements are aligned to the top of the parent element's allocated layout space.

Center Child elements are aligned to the center of the parent element's allocated layout
space.

Bottom Child elements are aligned to the bottom of the parent element's allocated layout
space.

Stretch Child elements are stretched to fill the parent element's allocated layout space.
(Default) Explicit Width and Height values take precedence.

The following example shows how to apply the VerticalAlignment property to Button
elements. Each attribute value is shown, to better illustrate the various rendering
behaviors. For purposes of this sample, a Grid element with visible gridlines is used as
the parent, to better illustrate the layout behavior of each property value.

TextBlock myTextBlock = new TextBlock();

myTextBlock.FontSize = 18;
myTextBlock.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock.Text = "VerticalAlignment Sample";
Grid.SetRow(myTextBlock, 0);
Button myButton1 = new Button();
myButton1.VerticalAlignment = VerticalAlignment.Top;
myButton1.Content = "Button 1 (Top)";
Grid.SetRow(myButton1, 1);
Button myButton2 = new Button();
myButton2.VerticalAlignment = VerticalAlignment.Bottom;
myButton2.Content = "Button 2 (Bottom)";
Grid.SetRow(myButton2, 2);
Button myButton3 = new Button();
myButton3.VerticalAlignment = VerticalAlignment.Center;
myButton3.Content = "Button 3 (Center)";
Grid.SetRow(myButton3, 3);
Button myButton4 = new Button();
myButton4.VerticalAlignment = VerticalAlignment.Stretch;
myButton4.Content = "Button 4 (Stretch)";
Grid.SetRow(myButton4, 4);

XAML

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
WindowTitle="VerticalAlignment Sample">
<Border Background="LightBlue" BorderBrush="Black" BorderThickness="2"
Padding="15">
<Grid Background="White" ShowGridLines="True">
<Grid.RowDefinitions>
<RowDefinition Height="25"/>
<RowDefinition Height="50"/>
<RowDefinition Height="50"/>
<RowDefinition Height="50"/>
<RowDefinition Height="50"/>
</Grid.RowDefinitions>
<TextBlock Grid.Row="0" Grid.Column="0" FontSize="18"
HorizontalAlignment="Center">VerticalAlignment Sample</TextBlock>
<Button Grid.Row="1" Grid.Column="0"
VerticalAlignment="Top">Button 1 (Top)</Button>
<Button Grid.Row="2" Grid.Column="0"
VerticalAlignment="Bottom">Button 2 (Bottom)</Button>
<Button Grid.Row="3" Grid.Column="0"
VerticalAlignment="Center">Button 3 (Center)</Button>
<Button Grid.Row="4" Grid.Column="0"
VerticalAlignment="Stretch">Button 4 (Stretch)</Button>
</Grid>
</Border>
</Page>

The preceding code yields a layout similar to the following image. The positioning
effects of each VerticalAlignment value are visible in the illustration.

Understanding Margin Properties

The Margin property describes the distance between an element and its child or peers.
Margin values can be uniform, by using syntax like Margin="20" . With this syntax, a
uniform Margin of 20 device independent pixels would be applied to the element.
Margin values can also take the form of four distinct values, each value describing a
distinct margin to apply to the left, top, right, and bottom (in that order), like
Margin="0,10,5,25" . Proper use of the Margin property enables very fine control of an

element's rendering position and the rendering position of its neighbor elements and
children.
７ Note

A non-zero margin applies space outside the element's ActualWidth and

ActualHeight.

The following example shows how to apply uniform margins around a group of Button
elements. The Button elements are spaced evenly with a ten-pixel margin buffer in each
direction.

Button myButton7 = new Button();

myButton7.Margin = new Thickness(10);
myButton7.Content = "Button 7";
Button myButton8 = new Button();
myButton8.Margin = new Thickness(10);
myButton8.Content = "Button 8";
Button myButton9 = new Button();
myButton9.Margin = new Thickness(10);
myButton9.Content = "Button 9";

XAML

<Button Margin="10">Button 7</Button>

<Button Margin="10">Button 8</Button>
<Button Margin="10">Button 9</Button>

In many instances, a uniform margin is not appropriate. In these cases, non-uniform

spacing can be applied. The following example shows how to apply non-uniform margin
spacing to child elements. Margins are described in this order: left, top, right, bottom.

Button myButton1 = new Button();

myButton1.Margin = new Thickness(0, 10, 0, 10);
myButton1.Content = "Button 1";
Button myButton2 = new Button();
myButton2.Margin = new Thickness(0, 10, 0, 10);
myButton2.Content = "Button 2";
Button myButton3 = new Button();
myButton3.Margin = new Thickness(0, 10, 0, 10);

XAML

<Button Margin="0,10,0,10">Button 1</Button>

<Button Margin="0,10,0,10">Button 2</Button>
<Button Margin="0,10,0,10">Button 3</Button>

Understanding the Padding Property

Padding is similar to Margin in most respects. The Padding property is exposed on only
on a few classes, primarily as a convenience: Block, Border, Control, and TextBlock are
samples of classes that expose a Padding property. The Padding property enlarges the
effective size of a child element by the specified Thickness value.

The following example shows how to apply Padding to a parent Border element.

myBorder = new Border();

myBorder.Background = Brushes.LightBlue;
myBorder.BorderBrush = Brushes.Black;
myBorder.BorderThickness = new Thickness(2);
myBorder.CornerRadius = new CornerRadius(45);
myBorder.Padding = new Thickness(25);

XAML

Using Alignment, Margins, and Padding in an

Application
HorizontalAlignment, Margin, Padding, and VerticalAlignment provide the positioning
control necessary to create a complex user interface (UI). You can use the effects of each
property to change child-element positioning, enabling flexibility in creating dynamic
applications and user experiences.

The following example demonstrates each of the concepts that are detailed in this topic.
Building on the infrastructure found in the first sample in this topic, this example adds a
Grid element as a child of the Border in the first sample. Padding is applied to the parent
Border element. The Grid is used to partition space between three child StackPanel
elements. Button elements are again used to show the various effects of Margin and
HorizontalAlignment. TextBlock elements are added to each ColumnDefinition to better
define the various properties applied to the Button elements in each column.

mainWindow = new Window();

myBorder = new Border();

// Define the Grid.

myGrid = new Grid();
myGrid.Background = Brushes.White;
myGrid.ShowGridLines = true;

// Define the Columns.

ColumnDefinition myColDef1 = new ColumnDefinition();
myColDef1.Width = new GridLength(1, GridUnitType.Auto);
ColumnDefinition myColDef2 = new ColumnDefinition();
myColDef2.Width = new GridLength(1, GridUnitType.Star);
ColumnDefinition myColDef3 = new ColumnDefinition();
myColDef3.Width = new GridLength(1, GridUnitType.Auto);

// Add the ColumnDefinitions to the Grid.

myGrid.ColumnDefinitions.Add(myColDef1);
myGrid.ColumnDefinitions.Add(myColDef2);
myGrid.ColumnDefinitions.Add(myColDef3);

// Add the first child StackPanel.

StackPanel myStackPanel = new StackPanel();
myStackPanel.HorizontalAlignment = HorizontalAlignment.Left;
myStackPanel.VerticalAlignment = VerticalAlignment.Top;
Grid.SetColumn(myStackPanel, 0);
Grid.SetRow(myStackPanel, 0);
TextBlock myTextBlock1 = new TextBlock();
myTextBlock1.FontSize = 18;
myTextBlock1.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock1.Margin = new Thickness(0, 0, 0, 15);
myTextBlock1.Text = "StackPanel 1";
Button myButton1 = new Button();
myButton1.Margin = new Thickness(0, 10, 0, 10);
myButton1.Content = "Button 1";
Button myButton2 = new Button();
myButton2.Margin = new Thickness(0, 10, 0, 10);
myButton2.Content = "Button 2";
Button myButton3 = new Button();
myButton3.Margin = new Thickness(0, 10, 0, 10);
TextBlock myTextBlock2 = new TextBlock();
myTextBlock2.Text = @"ColumnDefinition.Width = ""Auto""";
TextBlock myTextBlock3 = new TextBlock();
myTextBlock3.Text = @"StackPanel.HorizontalAlignment = ""Left""";
TextBlock myTextBlock4 = new TextBlock();
myTextBlock4.Text = @"StackPanel.VerticalAlignment = ""Top""";
TextBlock myTextBlock5 = new TextBlock();
myTextBlock5.Text = @"StackPanel.Orientation = ""Vertical""";
TextBlock myTextBlock6 = new TextBlock();
myTextBlock6.Text = @"Button.Margin = ""1,10,0,10""";
myStackPanel.Children.Add(myTextBlock1);
myStackPanel.Children.Add(myButton1);
myStackPanel.Children.Add(myButton2);
myStackPanel.Children.Add(myButton3);
myStackPanel.Children.Add(myTextBlock2);
myStackPanel.Children.Add(myTextBlock3);
myStackPanel.Children.Add(myTextBlock4);
myStackPanel.Children.Add(myTextBlock5);
myStackPanel.Children.Add(myTextBlock6);

// Add the second child StackPanel.

StackPanel myStackPanel2 = new StackPanel();
myStackPanel2.HorizontalAlignment = HorizontalAlignment.Stretch;
myStackPanel2.VerticalAlignment = VerticalAlignment.Top;
myStackPanel2.Orientation = Orientation.Vertical;
Grid.SetColumn(myStackPanel2, 1);
Grid.SetRow(myStackPanel2, 0);
TextBlock myTextBlock7 = new TextBlock();
myTextBlock7.FontSize = 18;
myTextBlock7.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock7.Margin = new Thickness(0, 0, 0, 15);
myTextBlock7.Text = "StackPanel 2";
Button myButton4 = new Button();
myButton4.Margin = new Thickness(10, 0, 10, 0);
myButton4.Content = "Button 4";
Button myButton5 = new Button();
myButton5.Margin = new Thickness(10, 0, 10, 0);
myButton5.Content = "Button 5";
Button myButton6 = new Button();
myButton6.Margin = new Thickness(10, 0, 10, 0);
myButton6.Content = "Button 6";
TextBlock myTextBlock8 = new TextBlock();
myTextBlock8.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock8.Text = @"ColumnDefinition.Width = ""*""";
TextBlock myTextBlock9 = new TextBlock();
myTextBlock9.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock9.Text = @"StackPanel.HorizontalAlignment = ""Stretch""";
TextBlock myTextBlock10 = new TextBlock();
myTextBlock10.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock10.Text = @"StackPanel.VerticalAlignment = ""Top""";
TextBlock myTextBlock11 = new TextBlock();
myTextBlock11.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock11.Text = @"StackPanel.Orientation = ""Horizontal""";
TextBlock myTextBlock12 = new TextBlock();
myTextBlock12.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock12.Text = @"Button.Margin = ""10,0,10,0""";
myStackPanel2.Children.Add(myTextBlock7);
myStackPanel2.Children.Add(myButton4);
myStackPanel2.Children.Add(myButton5);
myStackPanel2.Children.Add(myButton6);
myStackPanel2.Children.Add(myTextBlock8);
myStackPanel2.Children.Add(myTextBlock9);
myStackPanel2.Children.Add(myTextBlock10);
myStackPanel2.Children.Add(myTextBlock11);
myStackPanel2.Children.Add(myTextBlock12);

// Add the final child StackPanel.

StackPanel myStackPanel3 = new StackPanel();
myStackPanel3.HorizontalAlignment = HorizontalAlignment.Left;
myStackPanel3.VerticalAlignment = VerticalAlignment.Top;
Grid.SetColumn(myStackPanel3, 2);
Grid.SetRow(myStackPanel3, 0);
TextBlock myTextBlock13 = new TextBlock();
myTextBlock13.FontSize = 18;
myTextBlock13.HorizontalAlignment = HorizontalAlignment.Center;
myTextBlock13.Margin = new Thickness(0, 0, 0, 15);
myTextBlock13.Text = "StackPanel 3";
Button myButton7 = new Button();
myButton7.Margin = new Thickness(10);
myButton7.Content = "Button 7";
Button myButton8 = new Button();
myButton8.Margin = new Thickness(10);
myButton8.Content = "Button 8";
Button myButton9 = new Button();
myButton9.Margin = new Thickness(10);
myButton9.Content = "Button 9";
TextBlock myTextBlock14 = new TextBlock();
myTextBlock14.Text = @"ColumnDefinition.Width = ""Auto""";
TextBlock myTextBlock15 = new TextBlock();
myTextBlock15.Text = @"StackPanel.HorizontalAlignment = ""Left""";
TextBlock myTextBlock16 = new TextBlock();
myTextBlock16.Text = @"StackPanel.VerticalAlignment = ""Top""";
TextBlock myTextBlock17 = new TextBlock();
myTextBlock17.Text = @"StackPanel.Orientation = ""Vertical""";
TextBlock myTextBlock18 = new TextBlock();
myTextBlock18.Text = @"Button.Margin = ""10""";
myStackPanel3.Children.Add(myTextBlock13);
myStackPanel3.Children.Add(myButton7);
myStackPanel3.Children.Add(myButton8);
myStackPanel3.Children.Add(myButton9);
myStackPanel3.Children.Add(myTextBlock14);
myStackPanel3.Children.Add(myTextBlock15);
myStackPanel3.Children.Add(myTextBlock16);
myStackPanel3.Children.Add(myTextBlock17);
myStackPanel3.Children.Add(myTextBlock18);

// Add child content to the parent Grid.

myGrid.Children.Add(myStackPanel);
myGrid.Children.Add(myStackPanel2);
myGrid.Children.Add(myStackPanel3);

// Add the Grid as the lone child of the Border.

myBorder.Child = myGrid;
// Add the Border to the Window as Content and show the Window.
mainWindow.Content = myBorder;
mainWindow.Title = "Margin, Padding, and Alignment Sample";
mainWindow.Show();

XAML

<StackPanel Grid.Column="0" Grid.Row="0" HorizontalAlignment="Left"

Name="StackPanel1" VerticalAlignment="Top">
<TextBlock FontSize="18" HorizontalAlignment="Center"
Margin="0,0,0,15">StackPanel1</TextBlock>
<Button Margin="0,10,0,10">Button 1</Button>
<Button Margin="0,10,0,10">Button 2</Button>
<Button Margin="0,10,0,10">Button 3</Button>
<TextBlock>ColumnDefinition.Width="Auto"</TextBlock>
<TextBlock>StackPanel.HorizontalAlignment="Left"</TextBlock>
<TextBlock>StackPanel.VerticalAlignment="Top"</TextBlock>
<TextBlock>StackPanel.Orientation="Vertical"</TextBlock>
<TextBlock>Button.Margin="0,10,0,10"</TextBlock>
</StackPanel>

<StackPanel Grid.Column="1" Grid.Row="0" HorizontalAlignment="Stretch"

Name="StackPanel2" VerticalAlignment="Top" Orientation="Vertical">
<TextBlock FontSize="18" HorizontalAlignment="Center"
Margin="0,0,0,15">StackPanel2</TextBlock>
<Button Margin="10,0,10,0">Button 4</Button>
<Button Margin="10,0,10,0">Button 5</Button>
<Button Margin="10,0,10,0">Button 6</Button>
<TextBlock HorizontalAlignment="Center">ColumnDefinition.Width="*"
</TextBlock>
<TextBlock
HorizontalAlignment="Center">StackPanel.HorizontalAlignment="Stretch"
</TextBlock>
<TextBlock
HorizontalAlignment="Center">StackPanel.VerticalAlignment="Top"</TextBlock>
<TextBlock
HorizontalAlignment="Center">StackPanel.Orientation="Horizontal"</TextBlock>
<TextBlock HorizontalAlignment="Center">Button.Margin="10,0,10,0"
</TextBlock>
</StackPanel>

<StackPanel Grid.Column="2" Grid.Row="0" HorizontalAlignment="Left"

Name="StackPanel3" VerticalAlignment="Top">
<TextBlock FontSize="18" HorizontalAlignment="Center"
Margin="0,0,0,15">StackPanel3</TextBlock>
<Button Margin="10">Button 7</Button>
<Button Margin="10">Button 8</Button>
<Button Margin="10">Button 9</Button>
<TextBlock>ColumnDefinition.Width="Auto"</TextBlock>
<TextBlock>StackPanel.HorizontalAlignment="Left"</TextBlock>
<TextBlock>StackPanel.VerticalAlignment="Top"</TextBlock>
<TextBlock>StackPanel.Orientation="Vertical"</TextBlock>
<TextBlock>Button.Margin="10"</TextBlock>
</StackPanel>
</Grid>
</Border>
</Page>

When compiled, the preceding application yields a UI that looks like the following
illustration. The effects of the various property values are evident in the spacing between
elements, and significant property values for elements in each column are shown within
TextBlock elements.

What's Next
Positioning properties defined by the FrameworkElement class enable fine control of
element placement within WPF applications. You now have several techniques you can
use to better position elements using WPF.

Additional resources are available that explain WPF layout in greater detail. The Panels
Overview topic contains more detail about the various Panel elements. The topic
Walkthrough: My first WPF desktop application introduces advanced techniques that
use layout elements to position components and bind their actions to data sources.

See also
FrameworkElement
HorizontalAlignment
VerticalAlignment
Margin
Panels Overview
Layout
WPF Layout Gallery Sample
Base Elements How-to Topics
Article • 02/06/2023

The topics in this section describe how to use the four WPF base elements: UIElement,
ContentElement, FrameworkElement, and FrameworkContentElement.

In This Section
Make a UIElement Transparent or Semi-Transparent
Animate the Size of a FrameworkElement
Determine Whether a Freezable Is Frozen
Handle a Loaded Event
Set Margins of Elements and Controls
Make a Freezable Read-Only
Obtain a Writable Copy of a Read-Only Freezable
Flip a UIElement Horizontally or Vertically
Use a ThicknessConverter Object
Handle the ContextMenuOpening Event

Reference
UIElement

ContentElement

FrameworkElement

FrameworkContentElement

Related Sections
Base Elements
How to: Make a UIElement Transparent
or Semi-Transparent
Article • 02/06/2023

This example shows how to make a UIElement transparent or semi-transparent. To make

an element transparent or semi-transparent, you set its Opacity property. A value of 0.0
makes the element completely transparent, while a value of 1.0 makes the element
completely opaque. A value of 0.5 makes the element 50% opaque, and so on. An
element's Opacity is set to 1.0 by default.

Example
The following example sets the Opacity of a button to 0.25 , making it and its contents
(in this case, the button's text) 25% opaque.

XAML

<Button Opacity="0.25">A Button</Button>

//
// Both the button and its text are made 25% opaque.
//
Button myTwentyFivePercentOpaqueButton = new Button();
myTwentyFivePercentOpaqueButton.Opacity = new Double();
myTwentyFivePercentOpaqueButton.Opacity = 0.25;
myTwentyFivePercentOpaqueButton.Content = "A Button";

If an element's contents have their own Opacity settings, those values are multiplied
against the containing elements Opacity.

The following example sets a button's Opacity to 0.25 , and the Opacity of an Image
control contained with in the button to 0.5 . As a result, the image appears 12.5%
opaque: 0.25 * 0.5 = 0.125.

XAML

<!-- The image contained within this button has an effective

opacity of 0.125 (0.25 * 0.5 = 0.125). -->
<Button Opacity="0.25">
<StackPanel Orientation="Horizontal">
<TextBlock VerticalAlignment="Center" Margin="10">A Button</TextBlock>
<Image Source="sampleImages\berries.jpg" Width="50" Height="50"
Opacity="0.5"/>
</StackPanel>
</Button>

//
// The image contained within this button has an
// effective opacity of 0.125 (0.25*0.5 = 0.125);
//
Button myImageButton = new Button();
myImageButton.Opacity = new Double();
myImageButton.Opacity = 0.25;

StackPanel myImageStackPanel = new StackPanel();

myImageStackPanel.Orientation = Orientation.Horizontal;

TextBlock myTextBlock = new TextBlock();

myTextBlock.VerticalAlignment = VerticalAlignment.Center;
myTextBlock.Margin = new Thickness(10);
myTextBlock.Text = "A Button";
myImageStackPanel.Children.Add(myTextBlock);

Image myImage = new Image();

BitmapImage myBitmapImage = new BitmapImage();
myBitmapImage.BeginInit();
myBitmapImage.UriSource = new
Uri("sampleImages/berries.jpg",UriKind.Relative);
myBitmapImage.EndInit();
myImage.Source = myBitmapImage;
ImageBrush myImageBrush = new ImageBrush(myBitmapImage);
myImage.Width = 50;
myImage.Height = 50;
myImage.Opacity = 0.5;
myImageStackPanel.Children.Add(myImage);
myImageButton.Content = myImageStackPanel;

Another way to control the opacity of an element is to set the opacity of the Brush that
paints the element. This approach enables you to selectively alter the opacity of portions
of an element, and provides performance benefits over using the element's Opacity
property. The following example sets the Opacity of a SolidColorBrush used to paint the
button's Background is set to 0.25 . As a result, the brush's background is 25% opaque,
but its contents (the button's text) remain 100% opaque.

XAML

<Button>
<Button.Background>
<SolidColorBrush Color="Gray" Opacity="0.25" />
</Button.Background>
A Button
</Button>

//
// This button's background is made 25% opaque,
// but its text remains 100% opaque.
//
Button myOpaqueTextButton = new Button();
SolidColorBrush mySolidColorBrush = new SolidColorBrush(Colors.Gray);
mySolidColorBrush.Opacity = 0.25;
myOpaqueTextButton.Background = mySolidColorBrush;
myOpaqueTextButton.Content = "A Button";

You may also control the opacity of individual colors within a brush. For more
information about colors and brushes, see Painting with Solid Colors and Gradients
Overview. For an example showing how to animate an element's opacity, see Animate
the Opacity of an Element or Brush.
How to: Animate the Size of a
FrameworkElement
Article • 02/06/2023

To animate the size of a FrameworkElement, you can either animate its Width and
Height properties or use an animated ScaleTransform.

In the following example animates the size of two buttons using these two approaches.
One button is resized by animating its Width property and another is resized by
animating a ScaleTransform applied to its RenderTransform property. Each button
contains some text. Initially, the text appears the same in both buttons, but as the
buttons are resized, the text in the second button becomes distorted.

Example
XAML

<Page
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="Microsoft.Samples.Animation.AnimatingSizeExample"
WindowTitle="Animating Size Example">
<Canvas Width="650" Height="400">

<Button Name="AnimatedWidthButton"
Canvas.Left="20" Canvas.Top="20"
Width="200" Height="150"
BorderBrush="Red" BorderThickness="5">
Click Me
<Button.Triggers>

<Button
Canvas.Left="20" Canvas.Top="200"
Width="200" Height="150"
BorderBrush="Black" BorderThickness="3">
Click Me
<Button.RenderTransform>
<ScaleTransform x:Name="MyAnimatedScaleTransform"
ScaleX="1" ScaleY="1" />
</Button.RenderTransform>
<Button.Triggers>

<!-- Animate the ScaleX property of a ScaleTransform

applied to the button. -->
<EventTrigger RoutedEvent="Button.Loaded">
<BeginStoryboard>
<Storyboard>
<DoubleAnimation
Storyboard.TargetName="MyAnimatedScaleTransform"
Storyboard.TargetProperty="(ScaleTransform.ScaleX)"
To="3.0" Duration="0:0:10" AutoReverse="True"
RepeatBehavior="Forever" />
</Storyboard>
</BeginStoryboard>
</EventTrigger>
</Button.Triggers>
</Button>
</Canvas>
</Page>

When you transform an element, the entire element and its contents are transformed.
When you directly alter the size of an element, as in the case of the first button, the
element's contents are not resized unless their size and position depend on the size of
their parent element.

Animating the size of an element by applying an animated transform to its

RenderTransform property provides better performance than animated its Width and
Height directly, because the RenderTransform property does not trigger a layout pass.

For more information about animating properties, see the Animation Overview. For
more information about transforms, see the Transforms Overview.
How to: Determine Whether a Freezable
Is Frozen
Article • 02/06/2023

This example shows how to determine whether a Freezable object is frozen. If you try to
modify a frozen Freezable object, it throws an InvalidOperationException. To avoid
throwing this exception, use the IsFrozen property of the Freezable object to determine
whether it is frozen.

Example
The following example freezes a SolidColorBrush and then tests it by using the IsFrozen
property to determine whether it is frozen.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}

myButton.Background = myBrush;

if (myBrush.IsFrozen) // Evaluates to true.

For more information about Freezable objects, see the Freezable Objects Overview.
See also
Freezable
IsFrozen
Freezable Objects Overview
How-to Topics
How to: Handle a Loaded Event
Article • 02/06/2023

This example shows how to handle the FrameworkElement.Loaded event, and an

appropriate scenario for handling that event. The handler creates a Button when the
page loads.

Example
The following example uses Extensible Application Markup Language (XAML) together
with a code-behind file.

XAML

void OnLoad(object sender, RoutedEventArgs e)

{
Button b1 = new Button();
b1.Content = "New Button";
root.Children.Add(b1);
b1.Height = 25;
b1.Width = 200;
b1.HorizontalAlignment = HorizontalAlignment.Left;
}

See also
FrameworkElement
Object Lifetime Events
Routed Events Overview
How-to Topics
How to: Set Margins of Elements and
Controls
Article • 08/10/2023

This example describes how to set the Margin property, by changing any existing
property value for the margin in code-behind. The Margin property is a property of the
FrameworkElement base element, and is thus inherited by a variety of controls and other
elements.

This example is written in Extensible Application Markup Language (XAML), with a code-
behind file that the XAML refers to. The code-behind is shown in both a C# and a
Microsoft Visual Basic version.

Example
XAML

<Button Click="OnClick" Margin="10" Name="btn1">

Click To See Change!!</Button>

void OnClick(object sender, RoutedEventArgs e)

{
// Get the current value of the property.
Thickness marginThickness = btn1.Margin;
// If the current leftlength value of margin is set to 10 then change it
to a new value.
// Otherwise change it back to 10.
if(marginThickness.Left == 10)
{
btn1.Margin = new Thickness(60);
} else {
btn1.Margin = new Thickness(10);
}
}
How to: Make a Freezable Read-Only
Article • 02/06/2023

This example shows how to make a Freezable read-only by calling its Freeze method.

You cannot freeze a Freezable object if any one of the following conditions is true
about the object:

It has animated or data bound properties.

It has properties that are set by a dynamic resource. For more information about
dynamic resources, see the XAML Resources.

It contains Freezable sub-objects that cannot be frozen.

If these conditions are false for your Freezable object and you do not intend to modify
it, consider freezing it to gain performance benefits.

Example
The following example freezes a SolidColorBrush, which is a type of Freezable object.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}

myButton.Background = myBrush;

For more information about Freezable objects, see the Freezable Objects Overview.

See also
Freezable
CanFreeze
Freeze
Freezable Objects Overview
How-to Topics
How to: Obtain a Writable Copy of a
Read-Only Freezable
Article • 02/06/2023

This example shows how to use the Clone method to create a writable copy of a read-
only Freezable.

After a Freezable object is marked as read-only ("frozen"), you cannot modify it.
However, you can use the Clone method to create a modifiable clone of the frozen
object.

Example
The following example creates a modifiable clone of a frozen SolidColorBrush object.

Button myButton = new Button();

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

// Freezing a Freezable before it provides

// performance improvements if you don't
// intend on modifying it.
if (myBrush.CanFreeze)
{
// Makes the brush unmodifiable.
myBrush.Freeze();
}

myButton.Background = myBrush;

// If you need to modify a frozen brush,

// the Clone method can be used to
// create a modifiable copy.
SolidColorBrush myBrushClone = myBrush.Clone();

// Changing myBrushClone does not change

// the color of myButton, because its
// background is still set by myBrush.
myBrushClone.Color = Colors.Red;

// Replacing myBrush with myBrushClone

// makes the button change to red.
myButton.Background = myBrushClone;

For more information about Freezable objects, see the Freezable Objects Overview.
See also
Freezable
CloneCurrentValue
Freezable Objects Overview
How-to Topics
How to: Flip a UIElement Horizontally or
Vertically
Article • 02/06/2023

This example shows how to use a ScaleTransform to flip a UIElement horizontally or

vertically. In this example, a Button control (a type of UIElement) is flipped by applying a
ScaleTransform to its RenderTransform property.

Illustration to flip a button

The following illustration shows the button to flip.

The UIElement to flip

The following shows the code that creates the button.

XAML

<Button Content="Flip me!" Padding="5">

</Button>

Illustration to flip a button horizontally

To flip the button horizontally, create a ScaleTransform and set its ScaleX property to -1.
Apply the ScaleTransform to the button's RenderTransform property.

XAML

<Button Content="Flip me!" Padding="5">

<Button.RenderTransform>
<ScaleTransform ScaleX="-1" />
</Button.RenderTransform>
</Button>
The button after applying the ScaleTransform

Illustration to flip a button at its place

As you can see from the previous illustration, the button was flipped, but it was also
moved. That's because the button was flipped from its top left corner. To flip the button
in place, you want to apply the ScaleTransform to its center, not its corner. An easy way
to apply the ScaleTransform to the buttons center is to set the button's
RenderTransformOrigin property to 0.5, 0.5.

XAML

<Button Content="Flip me!" Padding="5"

RenderTransformOrigin="0.5,0.5">
<Button.RenderTransform>
<ScaleTransform ScaleX="-1" />
</Button.RenderTransform>
</Button>

The button with a RenderTransformOrigin of 0.5, 0.5

Illustration to flip a button vertically

To flip the button vertically, set the ScaleTransform object's ScaleY property instead of its
ScaleX property.

XAML
<Button Content="Flip me!" Padding="5"
RenderTransformOrigin="0.5,0.5">
<Button.RenderTransform>
<ScaleTransform ScaleY="-1" />
</Button.RenderTransform>
</Button>

The vertically flipped button

See also
Transforms Overview
How to: Use a ThicknessConverter
Object
Article • 08/18/2022

Example
This example shows how to create an instance of ThicknessConverter and use it to
change the thickness of a border.

The example defines a custom method called changeThickness ; this method first
converts the contents of a ListBoxItem, as defined in a separate Extensible Application
Markup Language (XAML) file, to an instance of Thickness, and later converts the
content into a String. This method passes the ListBoxItem to a ThicknessConverter
object, which converts the Content of a ListBoxItem to an instance of Thickness. This
value is then passed back as the value of the BorderThickness property of the Border.

This example does not run.

private void changeThickness(object sender, SelectionChangedEventArgs args)

{
ListBoxItem li = ((sender as ListBox).SelectedItem as ListBoxItem);
ThicknessConverter myThicknessConverter = new ThicknessConverter();
Thickness th1 =
(Thickness)myThicknessConverter.ConvertFromString(li.Content.ToString());
border1.BorderThickness = th1;
bThickness.Text = "Border.BorderThickness =" + li.Content.ToString();
}

See also
Thickness
ThicknessConverter
Border
How to: Change the Margin Property
How to: Convert a ListBoxItem to a new Data Type
Panels Overview
How to: Handle the
ContextMenuOpening Event
Article • 02/06/2023

The ContextMenuOpening event can be handled in an application to either adjust an

existing context menu prior to display or to suppress the menu that would otherwise be
displayed by setting the Handled property to true in the event data. The typical reason
for setting Handled to true in the event data is to replace the menu entirely with a new
ContextMenu object, which sometimes requires canceling the operation and starting a
new open. If you write handlers for the ContextMenuOpening event, you should be
aware of timing issues between a ContextMenu control and the service that is
responsible for opening and positioning context menus for controls in general. This
topic illustrates some of the code techniques for various context menu opening
scenarios and illustrates a case where the timing issue comes into play.

There are several scenarios for handling the ContextMenuOpening event:

Adjusting the menu items before display.

Replacing the entire menu before display.

Completely suppressing any existing context menu and displaying no context

menu.

Example

Adjusting the Menu Items Before Display

Adjusting the existing menu items is fairly simple and is probably the most common
scenario. You might do this in order to add or subtract context menu options in
response to current state information in your application or particular state information
that is available as a property on the object where the context menu is requested.

The general technique is to get the source of the event, which is the specific control that
was right-clicked, and get the ContextMenu property from it. You typically want to check
the Items collection to see what context menu items already exist in the menu, and then
add or remove appropriate new MenuItem items to or from the collection.

C#
void AddItemToCM(object sender, ContextMenuEventArgs e)
{
//check if Item4 is already there, this will probably run more than once
FrameworkElement fe = e.Source as FrameworkElement;
ContextMenu cm = fe.ContextMenu;
foreach (MenuItem mi in cm.Items)
{
if ((String)mi.Header == "Item4") return;
}
MenuItem mi4 = new MenuItem();
mi4.Header = "Item4";
fe.ContextMenu.Items.Add(mi4);
}

Replacing the Entire Menu Before Display

An alternative scenario is if you want to replace the entire context menu. You could of
course also use a variation of the preceding code, to remove every item of an existing
context menu and add new ones starting with item zero. But the more intuitive
approach for replacing all items in the context menu is to create a new ContextMenu,
populate it with items, and then set the FrameworkElement.ContextMenu property of a
control to be the new ContextMenu.

The following is the simple handler code for replacing a ContextMenu. The code
references a custom BuildMenu method, which is separated out because it is called by
more than one of the example handlers.

void HandlerForCMO(object sender, ContextMenuEventArgs e)

{
FrameworkElement fe = e.Source as FrameworkElement;
fe.ContextMenu = BuildMenu();
}

ContextMenu BuildMenu()
{
ContextMenu theMenu = new ContextMenu();
MenuItem mia = new MenuItem();
mia.Header = "Item1";
MenuItem mib = new MenuItem();
mib.Header = "Item2";
MenuItem mic = new MenuItem();
mic.Header = "Item3";
theMenu.Items.Add(mia);
theMenu.Items.Add(mib);
theMenu.Items.Add(mic);
return theMenu;
}

However, if you use this style of handler for ContextMenuOpening, you can potentially
expose a timing issue if the object where you are setting the ContextMenu does not
have a preexisting context menu. When a user right-clicks a control,
ContextMenuOpening is raised even if the existing ContextMenu is empty or null. But in
this case, whatever new ContextMenu you set on the source element arrives too late to
be displayed. Also, if the user happens to right-click a second time, this time your new
ContextMenu appears, the value is non null, and your handler will properly replace and
display the menu when the handler runs a second time. This suggests two possible
workarounds:

1. Insure that ContextMenuOpening handlers always run against controls that have at
least a placeholder ContextMenu available, which you intend to be replaced by the
handler code. In this case, you can still use the handler shown in the previous
example, but you typically want to assign a placeholder ContextMenu in the initial
markup:

XAML

<StackPanel>
<Rectangle Fill="Yellow" Width="200" Height="100"
ContextMenuOpening="HandlerForCMO">
<Rectangle.ContextMenu>
<ContextMenu>
<MenuItem>Initial menu; this will be replaced ...</MenuItem>
</ContextMenu>
</Rectangle.ContextMenu>
</Rectangle>
<TextBlock>Right-click the rectangle above, context menu gets
replaced</TextBlock>
</StackPanel>

2. Assume that the initial ContextMenu value might be null, based on some
preliminary logic. You could either check ContextMenu for null, or use a flag in
your code to check whether your handler has been run at least once. Because you
assume that the ContextMenu is about to be displayed, your handler then sets
Handled to true in the event data. To the ContextMenuService that is responsible
for context menu display, a true value for Handled in the event data represents a
request to cancel the display for the context menu / control combination that
raised the event.
Now that you have suppressed the potentially suspect context menu, the next step is to
supply a new one, then display it. Setting the new one is basically the same as the
previous handler: you build a new ContextMenu and set the control source's
FrameworkElement.ContextMenu property with it. The additional step is that you must
now force the display of the context menu, because you suppressed the first attempt. To
force the display, you set the Popup.IsOpen property to true within the handler. Be
careful when you do this, because opening the context menu in the handler raises the
ContextMenuOpening event again. If you reenter your handler, it becomes infinitely
recursive. This is why you always need to check for null or use a flag if you open a
context menu from within a ContextMenuOpening event handler.

Suppressing Any Existing Context Menu and

Displaying No Context Menu
The final scenario, writing a handler that suppresses a menu totally, is uncommon. If a
given control is not supposed to display a context menu, there are probably more
appropriate ways to assure this than by suppressing the menu just when a user requests
it. But if you want to use the handler to suppress a context menu and show nothing,
then your handler should simply set Handled to true in the event data. The
ContextMenuService that is responsible for displaying a context menu will check the
event data of the event it raised on the control. If the event was marked Handled
anywhere along the route, then the context menu open action that initiated the event is
suppressed.

void HandlerForCMO2(object sender, ContextMenuEventArgs e)

{
if (!FlagForCustomContextMenu)
{
e.Handled = true; //need to suppress empty menu
FrameworkElement fe = e.Source as FrameworkElement;
fe.ContextMenu = BuildMenu();
FlagForCustomContextMenu = true;
fe.ContextMenu.IsOpen = true;
}
}
}

See also
ContextMenu
FrameworkElement.ContextMenu
Base Elements Overview
ContextMenu Overview
Element Tree and Serialization
Article • 02/06/2023

WPF programming elements often exist in some form of tree relationship to each other.
For instance, an application UI created in XAML can be conceptualized as an object tree.
The element tree can be further divided into two discrete yet sometimes parallel trees:
the logical tree and the visual tree. Serialization in WPF involves saving the state of these
two trees as well as application state and writing it to a file, potentially as XAML.

In This Section
Trees in WPF
Serialization Limitations of XamlWriter.Save
Initialization for Object Elements Not in an Object Tree
How-to Topics

Reference
System.Windows.Markup

LogicalTreeHelper

VisualTreeHelper

Related Sections
WPF Architecture
XAML in WPF
Base Elements
Properties
Events
Input
Resources
Styling and Templating
Threading Model
Trees in WPF
Article • 08/18/2022

In many technologies, elements and components are organized in a tree structure where
developers directly manipulate the object nodes in the tree to affect the rendering or
behavior of an application. Windows Presentation Foundation (WPF) also uses several
tree structure metaphors to define relationships between program elements. For the
most part WPF developers can create an application in code or define portions of the
application in XAML while thinking conceptually about the object tree metaphor, but
will be calling specific API or using specific markup to do so rather than some general
object tree manipulation API such as you might use in XML DOM. WPF exposes two
helper classes that provide a tree metaphor view, LogicalTreeHelper and
VisualTreeHelper. The terms visual tree and logical tree are also used in the WPF
documentation because these same trees are useful for understanding the behavior of
certain key WPF features. This topic defines what the visual tree and logical tree
represent, discusses how such trees relate to an overall object tree concept, and
introduces LogicalTreeHelper and VisualTreeHelpers.

Trees in WPF
The most complete tree structure in WPF is the object tree. If you define an application
page in WPF subsystems and affect choices you make in markup or code.

Even though you do not always manipulate either the logical tree or the visual tree
directly, understanding the concepts of how the trees interact is useful for
understanding WPF as a technology. Thinking of WPF as a tree metaphor of some kind
is also crucial to understanding how property inheritance and event routing work in
WPF.

７ Note

Because the object tree is more of a concept than an actual API, another way to
think of the concept is as an object graph. In practice, there are relationships
between objects at run time where the tree metaphor will break down.
Nevertheless, particularly with XAML-defined UI, the tree metaphor is relevant
enough that most WPF documentation will use the term object tree when
referencing this general concept.
The Logical Tree
In WPF, you add content to UI elements by setting properties of the objects that back
those elements. For example, you add items to a ListBox control by manipulating its
Items property. By doing this, you are placing items into the ItemCollection that is the
Items property value. Similarly, to add objects to a DockPanel, you manipulate its
Children property value. Here, you are adding objects to the UIElementCollection. For a
code example, see How to: Add an Element Dynamically.

In Extensible Application Markup Language (XAML), when you place list items in a
ListBox or controls or other UI elements in a DockPanel, you also use the Items and
Children properties, either explicitly or implicitly, as in the following example.

XAML

If you were to process this XAML as XML under a document object model, and if you
had included the tags commented out as implicit (which would have been legal), then
the resulting XML DOM tree would have included elements for <ListBox.Items> and the
other implicit items. But XAML does not process that way when you read the markup
and write to objects, the resulting object graph does not literally include ListBox.Items .
It does however have a ListBox property named Items that contains a ItemCollection,
and that ItemCollection is initialized but empty when the ListBox XAML is processed.
Then, each child object element that exists as content for the ListBox is added to the
ItemCollection by parser calls to ItemCollection.Add . This example of processing XAML
into an object tree is so far seemingly an example where the created object tree is
basically the logical tree.

However, the logical tree is not the entire object graph that exists for your application UI
at run time, even with the XAML implicit syntax items factored out. The main reason for
this is visuals and templates. For example, consider the Button. The logical tree reports
the Button object and also its string Content . But there is more to this button in the run-
time object tree. In particular, the button only appears on screen the way it does
because a specific Button control template was applied. The visuals that come from an
applied template (such as the template-defined Border of dark gray around the visual
button) are not reported in the logical tree, even if you are looking at the logical tree
during run time (such as handling an input event from the visible UI and then reading
the logical tree). To find the template visuals, you would instead need to examine the
visual tree.

For more information about how XAML syntax maps to the created object graph, and
implicit syntax in XAML, see XAML Syntax In Detail or XAML in WPF.

The Purpose of the Logical Tree

The logical tree exists so that content models can readily iterate over their possible child
objects, and so that content models can be extensible. Also, the logical tree provides a
framework for certain notifications, such as when all objects in the logical tree are
loaded. Basically, the logical tree is an approximation of a run time object graph at the
framework level, which excludes visuals, but is adequate for many querying operations
against your own run time application's composition.

In addition, both static and dynamic resource references are resolved by looking
upwards through the logical tree for Resources collections on the initial requesting
object, and then continuing up the logical tree and checking each FrameworkElement
(or FrameworkContentElement) for another Resources value that contains a
ResourceDictionary, possibly containing that key. The logical tree is used for resource
lookup when both the logical tree and the visual tree are present. For more information
on resource dictionaries and lookup, see XAML Resources.

Composition of the Logical Tree

The logical tree is defined at the WPF framework-level, which means that the WPF base
element that is most relevant for logical tree operations is either FrameworkElement or
FrameworkContentElement. However, as you can see if you actually use the
LogicalTreeHelper API, the logical tree sometimes contains nodes that are not either
FrameworkElement or FrameworkContentElement. For instance, the logical tree reports
the Text value of a TextBlock, which is a string.

Overriding the Logical Tree

Advanced control authors can override the logical tree by overriding several APIs that
define how a general object or content model adds or removes objects within the
logical tree. For an example of how to override the logical tree, see Override the Logical
Tree.

Property Value Inheritance

Property value inheritance operates through a hybrid tree. The actual metadata that
contains the Inherits property that enables property inheritance is the WPF framework-
level FrameworkPropertyMetadata class. Therefore, both the parent that holds the
original value and the child object that inherits that value must both be
FrameworkElement or FrameworkContentElement, and they must both be part of some
logical tree. However, for existing WPF properties that support property inheritance,
property value inheritance is able to perpetuate through an intervening object that is
not in the logical tree. Mainly this is relevant for having template elements use any
inherited property values set either on the instance that is templated, or at still higher
levels of page-level composition and therefore higher in the logical tree. In order for
property value inheritance to work consistently across such a boundary, the inheriting
property must be registered as an attached property, and you should follow this pattern
if you intend to define a custom dependency property with property inheritance
behavior. The exact tree used for property inheritance cannot be entirely anticipated by
a helper class utility method, even at run time. For more information, see Property Value
Inheritance.

The Visual Tree

In addition to the concept of the logical tree, there is also the concept of the visual tree
in WPF. The visual tree describes the structure of visual objects, as represented by the
Visual base class. When you write a template for a control, you are defining or
redefining the visual tree that applies for that control. The visual tree is also of interest
to developers who want lower-level control over drawing for performance and
optimization reasons. One exposure of the visual tree as part of conventional WPF
application programming is that event routes for a routed event mostly travel along the
visual tree, not the logical tree. This subtlety of routed event behavior might not be
immediately apparent unless you are a control author. Routing events through the visual
tree enables controls that implement composition at the visual level to handle events or
create event setters.

Trees, Content Elements, and Content Hosts

Content elements (classes that derive from ContentElement) are not part of the visual
tree; they do not inherit from Visual and do not have a visual representation. In order to
appear in a UI at all, a ContentElement must be hosted in a content host that is both a
Visual and a logical tree participant. Usually such an object is a FrameworkElement. You
can conceptualize that the content host is somewhat like a "browser" for the content
and chooses how to display that content within the screen region that the host controls.
When the content is hosted, the content can be made a participant in certain tree
processes that are normally associated with the visual tree. Generally, the
FrameworkElement host class includes implementation code that adds any hosted
ContentElement to the event route through subnodes of the content logical tree, even
though the hosted content is not part of the true visual tree. This is necessary so that a
ContentElement can source a routed event that routes to any element other than itself.

Tree Traversal
The LogicalTreeHelper class provides the GetChildren, GetParent, and FindLogicalNode
methods for logical tree traversal. In most cases, you should not have to traverse the
logical tree of existing controls, because these controls almost always expose their
logical child elements as a dedicated collection property that supports collection access
such as Add , an indexer, and so on. Tree traversal is mainly a scenario that is used by
control authors who choose not to derive from intended control patterns such as
ItemsControl or Panel where collection properties are already defined, and who intend
to provide their own collection property support.

The visual tree also supports a helper class for visual tree traversal, VisualTreeHelper. The
visual tree is not exposed as conveniently through control-specific properties, so the
VisualTreeHelper class is the recommended way to traverse the visual tree if that is
necessary for your programming scenario. For more information, see WPF Graphics
Rendering Overview.

７ Note

Sometimes it is necessary to examine the visual tree of an applied template. You

should be careful when using this technique. Even if you are traversing a visual tree
for a control where you define the template, consumers of your control can always
change the template by setting the Template property on instances, and even the
end user can influence the applied template by changing the system theme.

Routes for Routed Events as a "Tree"

As mentioned before, the route of any given routed event travels along a single and
predetermined path of a tree that is a hybrid of the visual and logical tree
representations. The event route can travel either in the up or down directions within
the tree depending on whether it is a tunneling or bubbling routed event. The event
route concept does not have a directly supporting helper class that could be used to
"walk" the event route independently of raising an event that actually routes. There is a
class that represents the route, EventRoute, but the methods of that class are generally
for internal use only.

Resource Dictionaries and Trees

Resource dictionary lookup for all Resources defined in a page traverses basically the
logical tree. Objects that are not in the logical tree can reference keyed resources, but
the resource lookup sequence begins at the point where that object is connected to the
logical tree. In WPF, only logical tree nodes can have a Resources property that contains
a ResourceDictionary, therefore there is no benefit in traversing the visual tree looking
for keyed resources from a ResourceDictionary.

However, resource lookup can also extend beyond the immediate logical tree. For
application markup, the resource lookup can then continue onward to application-level
resource dictionaries and then to theme support and system values that are referenced
as static properties or keys. Themes themselves can also reference system values outside
of the theme logical tree if the resource references are dynamic. For more information
on resource dictionaries and the lookup logic, see XAML Resources.

See also
Input Overview
WPF Graphics Rendering Overview
Routed Events Overview
Initialization for Object Elements Not in an Object Tree
WPF Architecture
Serialization Limitations of
XamlWriter.Save
Article • 02/06/2023

The API Save can be used to serialize the contents of a Windows Presentation
Foundation (WPF) application as a Extensible Application Markup Language (XAML) file.
However, there are some notable limitations in exactly what is serialized. These
limitations and some general considerations are documented in this topic.

Run-Time, Not Design-Time Representation

The basic philosophy of what is serialized by a call to Save is that the result will be a
representation of the object being serialized, at run-time. Many design-time properties
of the original XAML file may already be optimized or lost by the time that the XAML is
loaded as in-memory objects, and are not preserved when you call Save to serialize. The
serialized result is an effective representation of the constructed logical tree of the
application, but not necessarily of the original XAML that produced it. These issues make
it extremely difficult to use the Save serialization as part of an extensive XAML design
surface.

Serialization is Self-Contained
The serialized output of Save is self-contained; everything that is serialized is contained
inside a XAML single page, with a single root element, and no external references other
than URIs. For instance, if your page referenced resources from application resources,
these will appear as if they were a component of the page being serialized.

Extension References are Dereferenced

Common references to objects made by various markup extension formats, such as
StaticResource or Binding , will be dereferenced by the serialization process. These

were already dereferenced at the time that in-memory objects were created by the
application runtime, and the Save logic does not revisit the original XAML to restore
such references to the serialized output. This potentially freezes any databound or
resource obtained value to be the value last used by the run-time representation, with
only limited or indirect ability to distinguish such a value from any other value set
locally. Images are also serialized as object references to images as they exist in the
project, rather than as original source references, losing whatever filename or URI was
originally referenced. Even resources declared within the same page are seen serialized
into the point where they were referenced, rather than being preserved as a key of a
resource collection.

Event Handling is Not Preserved

When event handlers that are added through XAML are serialized, they are not
preserved. XAML without code-behind (and also without the related x:Code mechanism)
has no way of serializing runtime procedural logic. Because serialization is self-contained
and limited to the logical tree, there is no facility for storing the event handlers. As a
result, event handler attributes, both the attribute itself and the string value that names
the handler, are removed from the output XAML.

Realistic Scenarios for Use of XAMLWriter.Save

While the limitations listed here are fairly substantial, there are still several appropriate
scenarios for using Save for serialization.

Vector or graphical output: The output of the rendered area can be used to
reproduce the same vector or graphics when reloaded.

Rich text and flow documents: Text and all element formatting and element
containment within it is preserved in the output. This can be useful for mechanisms
that approximate a clipboard functionality.

Preserving business object data: If you have stored data in custom elements, such
as XML data, so long as your business objects follow basic XAML rules such as
providing custom constructors and conversion for by-reference property values,
these business objects can be perpetuated through serialization.
Initialization for Object Elements Not in
an Object Tree
Article • 02/06/2023

Some aspects of Windows Presentation Foundation (WPF) initialization are deferred to

processes that typically rely on that element being connected to either the logical tree
or visual tree. This topic describes the steps that may be necessary in order to initialize
an element that is not connected to either tree.

Elements and the Logical Tree

When you create an instance of a Windows Presentation Foundation (WPF) class in
code, you should be aware that several aspects of object initialization for a Windows
Presentation Foundation (WPF) class are deliberately not a part of the code that is
executed when calling the class constructor. Particularly for a control class, most of the
visual representation of that control is not defined by the constructor. Instead, the visual
representation is defined by the control's template. The template potentially comes
from a variety of sources, but most often the template is obtained from theme styles.
Templates are effectively late-binding; the necessary template is not attached to the
control in question until the control is ready for layout. And the control is not ready for
layout until it is attached to a logical tree that connects to a rendering surface at the
root. It is that root-level element that initiates the rendering of all of its child elements
as defined in the logical tree.

The visual tree also participates in this process. Elements that are part of the visual tree
through the templates are also not fully instantiated until connected.

The consequences of this behavior are that certain operations that rely on the
completed visual characteristics of an element require additional steps. An example is if
you are attempting to get the visual characteristics of a class that was constructed but
not yet attached to a tree. For instance, if you want to call Render on a
RenderTargetBitmap and the visual you are passing is an element not connected to a
tree, that element is not visually complete until additional initialization steps are
completed.

Using BeginInit and EndInit to Initialize the Element

Various classes in WPF implement the ISupportInitialize interface. You use the BeginInit
and EndInit methods of the interface to denote a region in your code that contains
initialization steps (such as setting property values that affect rendering). After EndInit is
called in the sequence, the layout system can process the element and start looking for
an implicit style.

If the element you are setting properties on is a FrameworkElement or

FrameworkContentElement derived class, then you can call the class versions of
BeginInit and EndInit rather than casting to ISupportInitialize.

Sample Code
The following example is sample code for a console application that uses rendering APIs
and XamlReader.Load(Stream) of a loose XAML file to illustrate the proper placement of
BeginInit and EndInit around other API calls that adjust properties that affect rendering.

The example illustrates the main function only. The functions Rasterize and Save (not
shown) are utility functions that take care of image processing and IO.

[STAThread]
static void Main(string[] args)
{
UIElement e;
string file = Directory.GetCurrentDirectory() + "\\starting.xaml";
using (Stream stream = File.Open(file, FileMode.Open))
{
// loading files from current directory, project settings take care
of copying the file
ParserContext pc = new ParserContext();
pc.BaseUri = new Uri(file, UriKind.Absolute);
e = (UIElement)XamlReader.Load(stream, pc);
}

Size paperSize = new Size(8.5 * 96, 11 * 96);

e.Measure(paperSize);
e.Arrange(new Rect(paperSize));
e.UpdateLayout();

/*
* Render effect at normal dpi, indicator is the original RED
rectangle
*/
RenderTargetBitmap image1 = Rasterize(e, paperSize.Width,
paperSize.Height, 96, 96);
Save(image1, "render1.png");

Button b = new Button();

b.BeginInit();
b.Background = Brushes.Blue;
b.Width = b.Height = 200;
b.EndInit();
b.Measure(paperSize);
b.Arrange(new Rect(paperSize));
b.UpdateLayout();

// now render the altered version, with the element built up and
initialized

RenderTargetBitmap image2 = Rasterize(b, paperSize.Width,

paperSize.Height, 96, 96);
Save(image2, "render2.png");
}

See also
Trees in WPF
WPF Graphics Rendering Overview
XAML in WPF
Element Tree and Serialization How-to
Topics
Article • 02/06/2023

The topics in this section describe how to use the WPF element tree.

In This Section
Find an Element by Its Name
Override the Logical Tree

Reference
LogicalTreeHelper

VisualTreeHelper

System.Windows.Markup

Related Sections
How to: Find an Element by Its Name
Article • 02/06/2023

This example describes how to use the FindName method to find an element by its
Name value.

Example
In this example, the method to find a particular element by its name is written as the
event handler of a button. stackPanel is the Name of the root FrameworkElement being
searched, and the example method then visually indicates the found element by casting
it as TextBlock and changing one of the TextBlock visible UI properties.

void Find(object sender, RoutedEventArgs e)

{
object wantedNode = stackPanel.FindName("dog");
if (wantedNode is TextBlock)
{
// Following executed if Text element was found.
TextBlock wantedChild = wantedNode as TextBlock;
wantedChild.Foreground = Brushes.Blue;
}
}
How to: Override the Logical Tree
Article • 02/06/2023

Although it is not necessary in most cases, advanced control authors have the option to
override the logical tree.

Example
This example describes how to subclass StackPanel to override the logical tree, in this
case to enforce a behavior that the panel may only have and will only render a single
child element. This isn't necessarily a practically desirable behavior, but is shown here as
a means of illustrating the scenario for overriding an element's normal logical tree.

public class SingletonPanel : StackPanel

{
//private UIElementCollection _children;
private FrameworkElement _child;

public SingletonPanel()
{
}

public FrameworkElement SingleChild

{

get { return _child; }

set
{
if (value == null)
{
RemoveLogicalChild(_child);
}
else
{
if (_child == null)
{
_child = value;
}
else
{
// raise an exception?
MessageBox.Show("Needs to be a single element");
}
}
}
}
public void SetSingleChild(object child)
{
this.AddLogicalChild(child);
}

public new void AddLogicalChild(object child)

{
_child = (FrameworkElement)child;
if (this.Children.Count == 1)
{
this.RemoveLogicalChild(this.Children[0]);
this.Children.Add((UIElement)child);
}
else
{
this.Children.Add((UIElement)child);
}
}

public new void RemoveLogicalChild(object child)

{
_child = null;
this.Children.Clear();
}
protected override IEnumerator LogicalChildren
{
get
{
// cheat, make a list with one member and return the enumerator
ArrayList _list = new ArrayList();
_list.Add(_child);
return (IEnumerator)_list.GetEnumerator();
}
}
}

For more information on the logical tree, see Trees in WPF.

Properties (WPF)
Article • 02/06/2023

Windows Presentation Foundation (WPF) provides a set of services that can be used to
extend the functionality of a common language runtime (CLR) property. Collectively,
these services are typically referred to as the WPF property system. A property that is
backed by the WPF property system is known as a dependency property.

In This Section
Dependency Properties Overview
Attached Properties Overview
Custom Dependency Properties
Dependency Property Metadata
Dependency Property Callbacks and Validation
Framework Property Metadata
Dependency Property Value Precedence
Read-Only Dependency Properties
Property Value Inheritance
Dependency Property Security
Safe Constructor Patterns for DependencyObjects
Collection-Type Dependency Properties
XAML Loading and Dependency Properties
How-to Topics

Reference
DependencyProperty

PropertyMetadata

FrameworkPropertyMetadata

DependencyObject

Related Sections
WPF Architecture
XAML in WPF
Base Elements
Element Tree and Serialization
Events
Input
Resources
WPF Content Model
Threading Model
Dependency properties overview
Article • 02/06/2023

Windows Presentation Foundation (WPF) provides a set of services that can be used to
extend the functionality of a type's property. Collectively, these services are typically
referred to as the WPF property system. A property that is backed by the WPF property
system is known as a dependency property. This overview describes the WPF property
system and the capabilities of a dependency property. This includes how to use existing
dependency properties in XAML and in code. This overview also introduces specialized
aspects of dependency properties, such as dependency property metadata, and how to
create your own dependency property in a custom class.

Prerequisites
This topic assumes that you have some basic knowledge of the .NET type system and
object-oriented programming. In order to follow the examples in this topic, you should
also understand XAML and know how to write WPF applications. For more information,
see Walkthrough: My first WPF desktop application.

Dependency properties and CLR properties

In WPF, properties are typically exposed as standard .NET properties. At a basic level,
you could interact with these properties directly and never know that they are
implemented as a dependency property. However, you should become familiar with
some or all of the features of the WPF property system, so that you can take advantage
of these features.

The purpose of dependency properties is to provide a way to compute the value of a

property based on the value of other inputs. These other inputs might include system
properties such as themes and user preference, just-in-time property determination
mechanisms such as data binding and animations/storyboards, multiple-use templates
such as resources and styles, or values known through parent-child relationships with
other elements in the element tree. In addition, a dependency property can be
implemented to provide self-contained validation, default values, callbacks that monitor
changes to other properties, and a system that can coerce property values based on
potentially runtime information. Derived classes can also change some specific
characteristics of an existing property by overriding dependency property metadata,
rather than overriding the actual implementation of existing properties or creating new
properties.
In the SDK reference, you can identify which property is a dependency property by the
presence of the Dependency Property Information section on the managed reference
page for that property. The Dependency Property Information section includes a link to
the DependencyProperty identifier field for that dependency property, and also includes
a list of the metadata options that are set for that property, per-class override
information, and other details.

Dependency properties back CLR properties

Dependency properties and the WPF property system extend property functionality by
providing a type that backs a property, as an alternative implementation to the standard
pattern of backing the property with a private field. The name of this type is
DependencyProperty. The other important type that defines the WPF property system is
DependencyObject. DependencyObject defines the base class that can register and own
a dependency property.

The following lists the terminology that is used with dependency properties:

Dependency property: A property that is backed by a DependencyProperty.

Dependency property identifier: A DependencyProperty instance, which is

obtained as a return value when registering a dependency property, and then
stored as a static member of a class. This identifier is used as a parameter for many
of the APIs that interact with the WPF property system.

CLR "wrapper": The actual get and set implementations for the property. These
implementations incorporate the dependency property identifier by using it in the
GetValue and SetValue calls, thus providing the backing for the property using the
WPF property system.

The following example defines the IsSpinning dependency property, and shows the
relationship of the DependencyProperty identifier to the property that it backs.

public static readonly DependencyProperty IsSpinningProperty =

DependencyProperty.Register(
"IsSpinning", typeof(Boolean),
typeof(MyCode)
);
public bool IsSpinning
{
get { return (bool)GetValue(IsSpinningProperty); }
set { SetValue(IsSpinningProperty, value); }
}
The naming convention of the property and its backing DependencyProperty field is
important. The name of the field is always the name of the property, with the suffix
Property appended. For more information about this convention and the reasons for it,
see Custom Dependency Properties.

Setting property values

You can set properties either in code or in XAML.

Setting property values in XAML

The following XAML example specifies the background color of a button as red. This
example illustrates a case where the simple string value for a XAML attribute is type-
converted by the WPF XAML parser into a WPF type (a Color, by way of a
SolidColorBrush) in the generated code.

XAML

<Button Background="Red" Content="Button!"/>

XAML supports a variety of syntax forms for setting properties. Which syntax to use for a
particular property will depend on the value type that a property uses, as well as other
factors such as the presence of a type converter. For more information on XAML syntax
for property setting, see XAML in WPF and XAML Syntax In Detail.

As an example of non-attribute syntax, the following XAML example shows another

button background. This time rather than setting a simple solid color, the background is
set to an image, with an element representing that image and the source of that image
specified as an attribute of the nested element. This is an example of property element
syntax.

XAML

Setting properties in code

Setting dependency property values in code is typically just a call to the set
implementation exposed by the CLR "wrapper".

Button myButton = new Button();

myButton.Width = 200.0;

Getting a property value is also essentially a call to the get "wrapper" implementation:

double whatWidth;
whatWidth = myButton.Width;

You can also call the property system APIs GetValue and SetValue directly. This is not
typically necessary if you are using existing properties (the wrappers are more
convenient, and provide better exposure of the property for developer tools), but calling
the APIs directly is appropriate for certain scenarios.

Properties can be also set in XAML and then accessed later in code, through code-
behind. For details, see Code-Behind and XAML in WPF.

Property functionality provided by a

dependency property
A dependency property provides functionality that extends the functionality of a
property as opposed to a property that is backed by a field. Often, such functionality
represents or supports one of the following specific features:

Resources

Data binding

Styles

Animations

Metadata overrides

Property value inheritance

WPF Designer integration

Resources
A dependency property value can be set by referencing a resource. Resources are
typically specified as the Resources property value of a page root element, or of the
application (these locations enable the most convenient access to the resource). The
following example shows how to define a SolidColorBrush resource.

XAML

<DockPanel.Resources>
<SolidColorBrush x:Key="MyBrush" Color="Gold"/>
</DockPanel.Resources>

Once the resource is defined, you can reference the resource and use it to provide a
property value:

XAML

<Button Background="{DynamicResource MyBrush}" Content="I am gold" />

This particular resource is referenced as a DynamicResource Markup Extension (in WPF

XAML, you can use either a static or dynamic resource reference). To use a dynamic
resource reference, you must be setting to a dependency property, so it is specifically
the dynamic resource reference usage that is enabled by the WPF property system. For
more information, see XAML Resources.

７ Note

Resources are treated as a local value, which means that if you set another local
value, you will eliminate the resource reference. For more information, see
Dependency Property Value Precedence.

Data binding
A dependency property can reference a value through data binding. Data binding works
through a specific markup extension syntax in XAML, or the Binding object in code. With
data binding, the final property value determination is deferred until run time, at which
time the value is obtained from a data source.

The following example sets the Content property for a Button, using a binding declared
in XAML. The binding uses an inherited data context and an XmlDataProvider data
source (not shown). The binding itself specifies the desired source property by XPath
within the data source.

XAML

<Button Content="{Binding XPath=Team/@TeamName}"/>

７ Note

Bindings are treated as a local value, which means that if you set another local
value, you will eliminate the binding. For details, see Dependency Property Value
Precedence.

Dependency properties, or the DependencyObject class, do not natively support

INotifyPropertyChanged for purposes of producing notifications of changes in
DependencyObject source property value for data binding operations. For more
information on how to create properties for use in data binding that can report changes
to a data binding target, see Data Binding Overview.

Styles
Styles and templates are two of the chief motivating scenarios for using dependency
properties. Styles are particularly useful for setting properties that define application
user interface (UI). Styles are typically defined as resources in XAML. Styles interact with
the property system because they typically contain "setters" for particular properties, as
well as "triggers" that change a property value based on the real-time value for another
property.

The following example creates a simple style (which would be defined inside a
Resources dictionary, not shown), then applies that style directly to the Style property
for a Button. The setter within the style sets the Background property for a styled Button
to green.

XAML

XAML

<Button Style="{StaticResource GreenButtonStyle}">I am green!</Button>

For more information, see Styling and Templating.

Animations
Dependency properties can be animated. When an animation is applied and is running,
the animated value operates at a higher precedence than any value (such as a local
value) that the property otherwise has.

The following example animates the Background on a Button property (technically, the
Background is animated by using property element syntax to specify a blank
SolidColorBrush as the Background, then the Color property of that SolidColorBrush is
the property that is directly animated).

XAML

<Button>I am animated
<Button.Background>
<SolidColorBrush x:Name="AnimBrush"/>
</Button.Background>
<Button.Triggers>
<EventTrigger RoutedEvent="Button.Loaded">
<BeginStoryboard>
<Storyboard>
<ColorAnimation
Storyboard.TargetName="AnimBrush"
Storyboard.TargetProperty="(SolidColorBrush.Color)"
From="Red" To="Green" Duration="0:0:5"
AutoReverse="True" RepeatBehavior="Forever" />
</Storyboard>
</BeginStoryboard>
</EventTrigger>
</Button.Triggers>
</Button>

For more information on animating properties, see Animation Overview and Storyboards
Overview.

Metadata overrides
You can change certain behaviors of a dependency property by overriding the metadata
for that property when you derive from the class that originally registers the
dependency property. Overriding metadata relies on the DependencyProperty identifier.
Overriding metadata does not require reimplementing the property. The metadata
change is handled natively by the property system; each class potentially holds
individual metadata for all properties that are inherited from base classes, on a per-type
basis.

The following example overrides metadata for a dependency property DefaultStyleKey.

Overriding this particular dependency property metadata is part of an implementation
pattern that creates controls that can use default styles from themes.

public class SpinnerControl : ItemsControl

{
static SpinnerControl()
{
DefaultStyleKeyProperty.OverrideMetadata(
typeof(SpinnerControl),
new FrameworkPropertyMetadata(typeof(SpinnerControl))
);
}
}

For more information about overriding or obtaining property metadata, see

Dependency Property Metadata.

Property value inheritance

An element can inherit the value of a dependency property from its parent in the object
tree.

７ Note

Property value inheritance behavior is not globally enabled for all dependency
properties, because the calculation time for inheritance does have some
performance impact. Property value inheritance is typically only enabled for
properties where a particular scenario suggests that property value inheritance is
appropriate. You can determine whether a dependency property inherits by looking
at the Dependency Property Information section for that dependency property in
the SDK reference.

The following example shows a binding, and sets the DataContext property that
specifies the source of the binding, which was not shown in the earlier binding example.
Any subsequent bindings in child objects do not need to specify the source, they can
use the inherited value from DataContext in the parent StackPanel object. (Alternatively,
a child object could instead choose to directly specify its own DataContext or a Source
in the Binding, and to deliberately not use the inherited value for data context of its
bindings.)

XAML

<StackPanel Canvas.Top="50" DataContext="{Binding Source={StaticResource

XmlTeamsSource}}">
<Button Content="{Binding XPath=Team/@TeamName}"/>
</StackPanel>

For more information, see Property Value Inheritance.

WPF designer integration

A custom control with properties that are implemented as dependency properties will
receive appropriate WPF Designer for Visual Studio support. One example is the ability
to edit direct and attached dependency properties with the Properties window. For
more information, see Control Authoring Overview.

Dependency property value precedence

When you get the value of a dependency property, you are potentially obtaining a value
that was set on that property through any one of the other property-based inputs that
participate in the WPF property system. Dependency property value precedence exists
so that a variety of scenarios for how properties obtain their values can interact in a
predictable way.

Consider the following example. The example includes a style that applies to all buttons
and their Background properties, but then also specifies one button with a locally set
Background value.

７ Note

The SDK documentation uses the terms "local value" or "locally set value"
occasionally when discussing dependency properties. A locally set value is a
property value that is set directly on an object instance in code, or as an attribute
on an element in XAML.

In principle, for the first button, the property is set twice, but only one value applies: the
value with the highest precedence. A locally set value has the highest precedence
(except for a running animation, but no animation applies in this example) and thus the
locally set value is used instead of the style setter value for the background on the first
button. The second button has no local value (and no other value with higher
precedence than a style setter) and thus the background in that button comes from the
style setter.

XAML

<StackPanel>
<StackPanel.Resources>
<Style x:Key="{x:Type Button}" TargetType="{x:Type Button}">
<Setter Property="Background" Value="Red"/>
</Style>
</StackPanel.Resources>
<Button Background="Green">I am NOT red!</Button>
<Button>I am styled red</Button>
</StackPanel>

Why does dependency property precedence exist?

Typically, you would not want styles to always apply and to obscure even a locally set
value of an individual element (otherwise, it would be difficult to use either styles or
elements in general). Therefore, the values that come from styles operate at a lower
precedent than a locally set value. For a more thorough listing of dependency properties
and where a dependency property effective value might come from, see Dependency
Property Value Precedence.

７ Note

There are a number of properties defined on WPF elements that are not
dependency properties. By and large, properties were implemented as dependency
properties only when there were needs to support at least one of the scenarios
enabled by the property system: data binding, styling, animation, default value
support, inheritance, attached properties, or invalidation.

Learning more about dependency properties

An attached property is a type of property that supports a specialized syntax in
XAML. An attached property often does not have a 1:1 correspondence with a
common language runtime (CLR) property, and is not necessarily a dependency
property. The typical purpose of an attached property is to allow child elements to
report property values to a parent element, even if the parent element and child
element do not both possess that property as part of the class members listings.
One primary scenario is to enable child elements to inform the parent how they
should be presented in UI; for an example, see Dock or Left. For details, see
Attached Properties Overview.

Component developers or application developers may wish to create their own

dependency property, in order to enable capabilities such as data binding or styles
support, or for invalidation and value coercion support. For details, see Custom
Dependency Properties.

Consider dependency properties to be public properties, accessible or at least

discoverable by any caller that has access to an instance. For more information, see
Dependency Property Security.

See also
Custom Dependency Properties
Read-Only Dependency Properties
XAML in WPF
WPF Architecture
Attached Properties Overview
Article • 03/17/2022

An attached property is a concept defined by XAML. An attached property is intended to

be used as a type of global property that is settable on any dependency object. In
Windows Presentation Foundation (WPF), attached properties are typically defined as a
specialized form of dependency property that does not have the conventional property
"wrapper".

Prerequisites
This article assumes that you understand dependency properties from the perspective of
a consumer of existing dependency properties on Windows Presentation Foundation
(WPF) classes, and have read the Dependency Properties Overview. To follow the
examples in this article, you should also understand XAML and know how to write WPF
applications.

Why Use Attached Properties

One purpose of an attached property is to allow different child elements to specify
unique values for a property that's defined in a parent element. A specific application of
this scenario is having child elements inform the parent element of how they are to be
presented in the user interface (UI). One example is the DockPanel.Dock property. The
DockPanel.Dock property is created as an attached property because it is designed to be
set on elements that are contained within a DockPanel rather than on DockPanel itself.
The DockPanel class defines the static DependencyProperty field named DockProperty,
and then provides the GetDock and SetDock methods as public accessors for the
attached property.

Attached Properties in XAML

In XAML, you set attached properties by using the syntax
AttachedPropertyProvider.PropertyName

The following is an example of how you can set DockPanel.Dock in XAML:

XAML

<DockPanel>
<TextBox DockPanel.Dock="Top">Enter text</TextBox>
</DockPanel>

The usage is somewhat similar to a static property; you always reference the type
DockPanel that owns and registers the attached property, rather than referring to any
instance specified by name.

Also, because an attached property in XAML is an attribute that you set in markup, only
the set operation has any relevance. You cannot directly get a property in XAML,
although there are some indirect mechanisms for comparing values, such as triggers in
styles (for details, see Styling and Templating).

Attached Property Implementation in WPF

In Windows Presentation Foundation (WPF), most of the UI-related attached properties
on WPF types are implemented as dependency properties. Attached properties are a
XAML concept, whereas dependency properties are a WPF concept. Because WPF
attached properties are dependency properties, they support dependency property
concepts such as property metadata, and default values from that property metadata.

How Attached Properties Are Used by the

Owning Type
Although attached properties are settable on any object, that does not automatically
mean that setting the property will produce a tangible result, or that the value will ever
be used by another object. Generally, attached properties are intended so that objects
coming from a wide variety of possible class hierarchies or logical relationships can each
report common information to the type that defines the attached property. The type
that defines the attached property typically follows one of these models:

The type that defines the attached property is designed so that it can be the
parent element of the elements that will set values for the attached property. The
type then iterates its child objects through internal logic against some object tree
structure, obtains the values, and acts on those values in some manner.

The type that defines the attached property will be used as the child element for a
variety of possible parent elements and content models.

The type that defines the attached property represents a service. Other types set
values for the attached property. Then, when the element that set the property is
evaluated in the context of the service, the attached property values are obtained
through internal logic of the service class.
An Example of a Parent-Defined Attached Property
The most typical scenario where WPF defines an attached property is when a parent
element supports a child element collection, and also implements a behavior where the
specifics of the behavior are reported individually for each child element.

DockPanel defines the DockPanel.Dock attached property, and DockPanel has class-level
code as part of its rendering logic (specifically, MeasureOverride and ArrangeOverride).
A DockPanel instance will always check to see whether any of its immediate child
elements have set a value for DockPanel.Dock. If so, those values become input for the
rendering logic applied to that particular child element. Nested DockPanel instances
each treat their own immediate child element collections, but that behavior is
implementation-specific to how DockPanel processes DockPanel.Dock values. It is
theoretically possible to have attached properties that influence elements beyond the
immediate parent. If the DockPanel.Dock attached property is set on an element that
has no DockPanel parent element to act upon it, no error or exception is raised. This
simply means that a global property value was set, but it has no current DockPanel
parent that could consume the information.

Attached Properties in Code

Attached properties in WPF do not have the typical CLR "wrapper" methods for easy
get/set access. This is because the attached property is not necessarily part of the CLR
namespace for instances where the property is set. However, a XAML processor must be
able to set those values when XAML is parsed. To support an effective attached property
usage, the owner type of the attached property must implement dedicated accessor
methods in the form GetPropertyName and SetPropertyName. These dedicated
accessor methods are also useful to get or set the attached property in code. From a
code perspective, an attached property is similar to a backing field that has method
accessors instead of property accessors, and that backing field can exist on any object
rather than needing to be specifically defined.

The following example shows how you can set an attached property in code. In this
example, myCheckBox is an instance of the CheckBox class.

DockPanel myDockPanel = new DockPanel();

CheckBox myCheckBox = new CheckBox();
myCheckBox.Content = "Hello";
myDockPanel.Children.Add(myCheckBox);
DockPanel.SetDock(myCheckBox, Dock.Top);
Similar to the XAML case, if myCheckBox had not already been added as a child element
of myDockPanel by the fourth line of code, the fifth line of code would not raise an
exception, but the property value would not interact with a DockPanel parent and thus
would do nothing. Only a DockPanel.Dock value set on a child element combined with
the presence of a DockPanel parent element will cause an effective behavior in the
rendered application. (In this case, you could set the attached property, then attach to
the tree. Or you could attach to the tree then set the attached property. Either action
order provides the same result.)

Attached Property Metadata

When registering the property, FrameworkPropertyMetadata is set to specify
characteristics of the property, such as whether the property affects rendering,
measurement, and so on. Metadata for an attached property is generally no different
than on a dependency property. If you specify a default value in an override to attached
property metadata, that value becomes the default value of the implicit attached
property on instances of the overriding class. Specifically, your default value is reported
if some process queries for the value of an attached property through the Get method
accessor for that property, specifying an instance of the class where you specified the
metadata, and the value for that attached property was otherwise not set.

If you want to enable property value inheritance on a property, you should use attached
properties rather than non-attached dependency properties. For details, see Property
Value Inheritance.

Custom Attached Properties

When to Create an Attached Property

You might create an attached property when there is a reason to have a property setting
mechanism available for classes other than the defining class. The most common
scenario for this is layout. Examples of existing layout properties are DockPanel.Dock,
Panel.ZIndex, and Canvas.Top. The scenario enabled here is that elements that exist as
child elements to layout-controlling elements are able to express layout requirements to
their layout parent elements individually, each setting a property value that the parent
defined as an attached property.

Another scenario for using an attached property is when your class represents a service,
and you want classes to be able to integrate the service more transparently.
Yet another scenario is to receive Visual Studio WPF Designer support, such as
Properties window editing. For more information, see Control Authoring Overview.

As mentioned before, you should register as an attached property if you want to use
property value inheritance.

How to Create an Attached Property

If your class is defining the attached property strictly for use on other types, then the
class does not have to derive from DependencyObject. But you do need to derive from
DependencyObject if you follow the overall WPF model of having your attached
property also be a dependency property.

Define your attached property as a dependency property by declaring a public static

readonly field of type DependencyProperty. You define this field by using the return

value of the RegisterAttached method. The field name must match the attached
property name, appended with the string Property , to follow the established WPF
pattern of naming the identifying fields versus the properties that they represent. The
attached property provider must also provide static GetPropertyName and
SetPropertyName methods as accessors for the attached property; failing to do this
results in the property system being unable to use your attached property.

７ Note

If you omit the attached property's get accessor, data binding on the property will
not work in design tools, such as Visual Studio and Blend for Visual Studio.

The Get Accessor

The signature for the GetPropertyName accessor must be:

public static object GetPropertyName(object target)

The target object can be specified as a more specific type in your implementation.
For example, the DockPanel.GetDock method types the parameter as UIElement,
because the attached property is only intended to be set on UIElement instances.

The return value can be specified as a more specific type in your implementation.
For example, the GetDock method types it as Dock, because the value can only be
set to that enumeration.
The Set Accessor
The signature for the SetPropertyName accessor must be:

public static void SetPropertyName(object target, object value)

The target object can be specified as a more specific type in your implementation.
For example, the SetDock method types it as UIElement, because the attached
property is only intended to be set on UIElement instances.

The value object can be specified as a more specific type in your implementation.
For example, the SetDock method types it as Dock, because the value can only be
set to that enumeration. Remember that the value for this method is the input
coming from the XAML loader when it encounters your attached property in an
attached property usage in markup. That input is the value specified as a XAML
attribute value in markup. Therefore there must be type conversion, value
serializer, or markup extension support for the type you use, such that the
appropriate type can be created from the attribute value (which is ultimately just a
string).

The following example shows the dependency property registration (using the
RegisterAttached method), as well as the GetPropertyName and SetPropertyName
accessors. In the example, the attached property name is IsBubbleSource . Therefore, the
accessors must be named GetIsBubbleSource and SetIsBubbleSource .

public static readonly DependencyProperty IsBubbleSourceProperty =

DependencyProperty.RegisterAttached(
"IsBubbleSource",
typeof(Boolean),
typeof(AquariumObject),
new FrameworkPropertyMetadata(false,
FrameworkPropertyMetadataOptions.AffectsRender)
);
public static void SetIsBubbleSource(UIElement element, Boolean value)
{
element.SetValue(IsBubbleSourceProperty, value);
}
public static Boolean GetIsBubbleSource(UIElement element)
{
return (Boolean)element.GetValue(IsBubbleSourceProperty);
}

Attached Property Attributes

WPF defines several .NET attributes that are intended to provide information about
attached properties to reflection processes, and to typical users of reflection and
property information such as designers. Because attached properties have a type of
unlimited scope, designers need a way to avoid overwhelming users with a global list of
all the attached properties that are defined in a particular technology implementation
that uses XAML. The .NET attributes that WPF defines for attached properties can be
used to scope the situations where a given attached property should be shown in a
properties window. You might consider applying these attributes for your own custom
attached properties also. The purpose and syntax of the .NET attributes is described on
the appropriate reference pages:

AttachedPropertyBrowsableAttribute

AttachedPropertyBrowsableForChildrenAttribute

AttachedPropertyBrowsableForTypeAttribute

AttachedPropertyBrowsableWhenAttributePresentAttribute

Learning More About Attached Properties

For more information on creating an attached property, see Register an Attached
Property.

For more advanced usage scenarios for dependency properties and attached
properties, see Custom Dependency Properties.

You can also register a property as an attached property, and as a dependency

property, but then still expose "wrapper" implementations. In this case, the
property can be set either on that element, or on any element through the XAML
attached property syntax. An example of a property with an appropriate scenario
for both standard and attached usages is FrameworkElement.FlowDirection.

See also
DependencyProperty
Dependency Properties Overview
Custom Dependency Properties
XAML in WPF
Register an Attached Property
Custom Dependency Properties
Article • 03/17/2022

This topic describes the reasons that Windows Presentation Foundation (WPF)
application developers and component authors might want to create custom
dependency property, and describes the implementation steps as well as some
implementation options that can improve performance, usability, or versatility of the
property.

Prerequisites
This topic assumes that you understand dependency properties from the perspective of
a consumer of existing dependency properties on WPF classes, and have read the
Dependency Properties Overview topic. In order to follow the examples in this topic, you
should also understand WPF applications.

What Is a Dependency Property?

You can enable what would otherwise be a common language runtime (CLR) property to
support styling, data binding, inheritance, animations, and default values by
implementing it as a dependency property. Dependency properties are properties that
are registered with the WPF property system by calling the Register method (or
RegisterReadOnly), and that are backed by a DependencyProperty identifier field.
Dependency properties can be used only by DependencyObject types, but
DependencyObject is quite high in the WPF class hierarchy, so the majority of classes
available in WPF can support dependency properties. For more information about
dependency properties and some of the terminology and conventions used for
describing them in this SDK, see Dependency Properties Overview.

Examples of Dependency Properties

Examples of dependency properties that are implemented on WPF classes include the
Background property, the Width property, and the Text property, among many others.
Each dependency property exposed by a class has a corresponding public static field of
type DependencyProperty exposed on that same class. This is the identifier for the
dependency property. The identifier is named using a convention: the name of the
dependency property with the string Property appended to it. For example, the
corresponding DependencyProperty identifier field for the Background property is
BackgroundProperty. The identifier stores the information about the dependency
property as it was registered, and the identifier is then used later for other operations
involving the dependency property, such as calling SetValue.

As mentioned in the Dependency Properties Overview, all dependency properties in

WPF (except most attached properties) are also CLR properties because of the "wrapper"
implementation. Therefore, from code, you can get or set dependency properties by
calling CLR accessors that define the wrappers in the same manner that you would use
other CLR properties. As a consumer of established dependency properties, you do not
typically use the DependencyObject methods GetValue and SetValue, which are the
connection point to the underlying property system. Rather, the existing implementation
of the CLR properties will have already called GetValue and SetValue within the get and
set wrapper implementations of the property, using the identifier field appropriately. If
you are implementing a custom dependency property yourself, then you will be defining
the wrapper in a similar way.

When Should You Implement a Dependency

Property?
When you implement a property on a class, so long as your class derives from
DependencyObject, you have the option to back your property with a
DependencyProperty identifier and thus to make it a dependency property. Having your
property be a dependency property is not always necessary or appropriate, and will
depend on your scenario needs. Sometimes, the typical technique of backing your
property with a private field is adequate. However, you should implement your property
as a dependency property whenever you want your property to support one or more of
the following WPF capabilities:

You want your property to be settable in a style. For more information, see Styling
and Templating.

You want your property to support data binding. For more information about data
binding dependency properties, see Bind the Properties of Two Controls.

You want your property to be settable with a dynamic resource reference. For more
information, see XAML Resources.

You want to inherit a property value automatically from a parent element in the
element tree. In this case, register with the RegisterAttached method, even if you
also create a property wrapper for CLR access. For more information, see Property
Value Inheritance.
You want your property to be animatable. For more information, see Animation
Overview.

You want the property system to report when the previous value of the property
has been changed by actions taken by the property system, the environment, or
the user, or by reading and using styles. By using property metadata, your property
can specify a callback method that will be invoked each time the property system
determines that your property value was definitively changed. A related concept is
property value coercion. For more information, see Dependency Property Callbacks
and Validation.

You want to use established metadata conventions that are also used by WPF
processes, such as reporting whether changing a property value should require the
layout system to recompose the visuals for an element. Or you want to be able to
use metadata overrides so that derived classes can change metadata-based
characteristics such as the default value.

You want properties of a custom control to receive Visual Studio WPF Designer
support, such as Properties window editing. For more information, see Control
Authoring Overview.

When you examine these scenarios, you should also consider whether you can achieve
your scenario by overriding the metadata of an existing dependency property, rather
than implementing a completely new property. Whether a metadata override is practical
depends on your scenario and how closely that scenario resembles the implementation
in existing WPF dependency properties and classes. For more information about
overriding metadata on existing properties, see Dependency Property Metadata.

Checklist for Defining a Dependency Property

Defining a dependency property consists of four distinct concepts. These concepts are
not necessarily strict procedural steps, because some of these end up being combined
as single lines of code in the implementation:

(Optional) Create property metadata for the dependency property.

Register the property name with the property system, specifying an owner type
and the type of the property value. Also specify the property metadata, if used.

Define a DependencyProperty identifier as a public static readonly field on the

owner type.
Define a CLR "wrapper" property whose name matches the name of the
dependency property. Implement the CLR "wrapper" property's get and set
accessors to connect with the dependency property that backs it.

Registering the Property with the Property System

In order for your property to be a dependency property, you must register that property
into a table maintained by the property system, and give it a unique identifier that is
used as the qualifier for later property system operations. These operations might be
internal operations, or your own code calling property system APIs. To register the
property, you call the Register method within the body of your class (inside the class,
but outside of any member definitions). The identifier field is also provided by the
Register method call, as the return value. The reason that the Register call is done
outside of other member definitions is because you use this return value to assign and
create a public static readonly field of type DependencyProperty as part of your
class. This field becomes the identifier for your dependency property.

public static readonly DependencyProperty AquariumGraphicProperty =

Dependency Property Name Conventions

There are established naming conventions regarding dependency properties that you
must follow in all but exceptional circumstances.

The dependency property itself will have a basic name, "AquariumGraphic" as in this
example, which is given as the first parameter of Register. That name must be unique
within each registering type. Dependency properties inherited through base types are
considered to be already part of the registering type; names of inherited properties
cannot be registered again. However, there is a technique for adding a class as owner of
a dependency property even when that dependency property is not inherited; for
details, see Dependency Property Metadata.
When you create the identifier field, name this field by the name of the property as you
registered it, plus the suffix Property . This field is your identifier for the dependency
property, and it will be used later as an input for the SetValue and GetValue calls you will
make in the wrappers, by any other code access to the property by your own code, by
any external code access you allow, by the property system, and potentially by XAML
processors.

７ Note

Defining the dependency property in the class body is the typical implementation,
but it is also possible to define a dependency property in the class static
constructor. This approach might make sense if you need more than one line of
code to initialize the dependency property.

Implementing the "Wrapper"

Your wrapper implementation should call GetValue in the get implementation, and
SetValue in the set implementation (the original registration call and field are shown
here too for clarity).

In all but exceptional circumstances, your wrapper implementations should perform only
the GetValue and SetValue actions, respectively. The reason for this is discussed in the
topic XAML Loading and Dependency Properties.

All existing public dependency properties that are provided on the WPF classes use this
simple wrapper implementation model; most of the complexity of how dependency
properties work is either inherently a behavior of the property system, or is
implemented through other concepts such as coercion or property change callbacks
through property metadata.

public static readonly DependencyProperty AquariumGraphicProperty =

DependencyProperty.Register(
"AquariumGraphic",
typeof(Uri),
typeof(AquariumObject),
new FrameworkPropertyMetadata(null,
FrameworkPropertyMetadataOptions.AffectsRender,
new PropertyChangedCallback(OnUriChanged)
)
);
public Uri AquariumGraphic
{
get { return (Uri)GetValue(AquariumGraphicProperty); }
set { SetValue(AquariumGraphicProperty, value); }
}

Again, by convention, the name of the wrapper property must be the same as the name
chosen and given as first parameter of the Register call that registered the property. If
your property does not follow the convention, this does not necessarily disable all
possible uses, but you will encounter several notable issues:

Certain aspects of styles and templates will not work.

Most tools and designers must rely on the naming conventions to properly
serialize XAML, or to provide designer environment assistance at a per-property
level.

The current implementation of the WPF XAML loader bypasses the wrappers
entirely, and relies on the naming convention when processing attribute values. For
more information, see XAML Loading and Dependency Properties.

Property Metadata for a New Dependency Property

When you register a dependency property, the registration through the property system
creates a metadata object that stores property characteristics. Many of these
characteristics have defaults that are set if the property is registered with the simple
signatures of Register. Other signatures of Register allow you to specify the metadata
that you want as you register the property. The most common metadata given for
dependency properties is to give them a default value that is applied on new instances
that use the property.

If you are creating a dependency property that exists on a derived class of

FrameworkElement, you can use the more specialized metadata class
FrameworkPropertyMetadata rather than the base PropertyMetadata class. The
constructor for the FrameworkPropertyMetadata class has several signatures where you
can specify various metadata characteristics in combination. If you want to specify the
default value only, use the signature that takes a single parameter of type Object. Pass
that object parameter as a type-specific default value for your property (the default
value provided must be the type you provided as the propertyType parameter in the
Register call).

For FrameworkPropertyMetadata, you can also specify metadata option flags for your
property. These flags are converted into discrete properties on the property metadata
after registration and are used to communicate certain conditionals to other processes
such as the layout engine.

Setting Appropriate Metadata Flags

If your property (or changes in its value) affects the user interface (UI), and in
particular affects how the layout system should size or render your element in a
page, set one or more of the following flags: AffectsMeasure, AffectsArrange,
AffectsRender.

AffectsMeasure indicates that a change to this property requires a change to UI

rendering where the containing object might require more or less space within
the parent. For example, a "Width" property should have this flag set.

AffectsArrange indicates that a change to this property requires a change to UI

rendering that typically does not require a change in the dedicated space, but
does indicate that the positioning within the space has changed. For example,
an "Alignment" property should have this flag set.

AffectsRender indicates that some other change has occurred that will not affect
layout and measure, but does require another render. An example would be a
property that changes a color of an existing element, such as "Background".

These flags are often used as a protocol in metadata for your own override
implementations of property system or layout callbacks. For instance, you might
have an OnPropertyChanged callback that will call InvalidateArrange if any
property of the instance reports a value change and has AffectsArrange as true
in its metadata.

Some properties may affect the rendering characteristics of the containing parent
element, in ways above and beyond the changes in required size mentioned
above. An example is the MinOrphanLines property used in the flow document
model, where changes to that property can change the overall rendering of the
flow document that contains the paragraph. Use AffectsParentArrange or
AffectsParentMeasure to identify similar cases in your own properties.

By default, dependency properties support data binding. You can deliberately

disable data binding, for cases where there is no realistic scenario for data binding,
or where performance in data binding for a large object is recognized as a
problem.

By default, data binding Mode for dependency properties defaults to OneWay. You
can always change the binding to be TwoWay per binding instance; for details, see
Specify the Direction of the Binding. But as the dependency property author, you
can choose to make the property use TwoWay binding mode by default. An
example of an existing dependency property is MenuItem.IsSubmenuOpen; the
scenario for this property is that the IsSubmenuOpen setting logic and the
compositing of MenuItem interact with the default theme style. The
IsSubmenuOpen property logic uses data binding natively to maintain the state of
the property in accordance to other state properties and method calls. Another
example property that binds TwoWay by default is TextBox.Text.

You can also enable property inheritance in a custom dependency property by

setting the Inherits flag. Property inheritance is useful for a scenario where parent
elements and child elements have a property in common, and it makes sense for
the child elements to have that particular property value set to the same value as
the parent set it. An example inheritable property is DataContext, which is used for
binding operations to enable the important master-detail scenario for data
presentation. By making DataContext inheritable, any child elements inherit that
data context also. Because of property value inheritance, you can specify a data
context at the page or application root, and do not need to respecify it for
bindings in all possible child elements. DataContext is also a good example to
illustrate that inheritance overrides the default value, but it can always be set
locally on any particular child element; for details, see Use the Master-Detail
Pattern with Hierarchical Data. Property value inheritance does have a possible
performance cost, and thus should be used sparingly; for details, see Property
Value Inheritance.

Set the Journal flag to indicate if your dependency property should be detected or
used by navigation journaling services. An example is the SelectedIndex property;
any item selected in a selection control should be persisted when the journaling
history is navigated.

Read-Only Dependency Properties

You can define a dependency property that is read-only. However, the scenarios for why
you might define your property as read-only are somewhat different, as is the procedure
for registering them with the property system and exposing the identifier. For more
information, see Read-Only Dependency Properties.

Collection-Type Dependency Properties

Collection-type dependency properties have some additional implementation issues to
consider. For details, see Collection-Type Dependency Properties.
Dependency Property Security Considerations
Dependency properties should be declared as public properties. Dependency property
identifier fields should be declared as public static fields. Even if you attempt to declare
other access levels (such as protected), a dependency property can always be accessed
through the identifier in combination with the property system APIs. Even a protected
identifier field is potentially accessible because of metadata reporting or value
determination APIs that are part of the property system, such as LocalValueEnumerator.
For more information, see Dependency Property Security.

Dependency Properties and Class Constructors

There is a general principle in managed code programming (often enforced by code
analysis tools such as FxCop) that class constructors should not call virtual methods. This
is because constructors can be called as base initialization of a derived class constructor,
and entering the virtual method through the constructor might occur at an incomplete
initialization state of the object instance being constructed. When you derive from any
class that already derives from DependencyObject, you should be aware that the
property system itself calls and exposes virtual methods internally. These virtual
methods are part of the WPF property system services. Overriding the methods enables
derived classes to participate in value determination. To avoid potential issues with
runtime initialization, you should not set dependency property values within
constructors of classes, unless you follow a very specific constructor pattern. For details,
see Safe Constructor Patterns for DependencyObjects.

See also
Dependency Properties Overview
Dependency Property Metadata
Control Authoring Overview
Collection-Type Dependency Properties
Dependency Property Security
XAML Loading and Dependency Properties
Safe Constructor Patterns for DependencyObjects
Dependency Property Metadata
Article • 02/06/2023

The Windows Presentation Foundation (WPF) property system includes a metadata

reporting system that goes beyond what can be reported about a property through
reflection or general common language runtime (CLR) characteristics. Metadata for a
dependency property can also be assigned uniquely by the class that defines a
dependency property, can be changed when the dependency property is added to a
different class, and can be specifically overridden by all derived classes that inherit the
dependency property from the defining base class.

Prerequisites
This topic assumes that you understand dependency properties from the perspective of
a consumer of existing dependency properties on WPF applications.

How Dependency Property Metadata is Used

Dependency property metadata exists as an object that can be queried to examine the
characteristics of a dependency property. This metadata is also accessed frequently by
the property system as it processes any given dependency property. The metadata
object for a dependency property can contain the following types of information:

Default value for the dependency property, if no other value can be determined for
the dependency property by local value, style, inheritance, etc. For a thorough
discussion of how default values participate in the precedence used by the
property system when assigning values for dependency properties, see
Dependency Property Value Precedence.

References to callback implementations that affect coercion or change-notification

behaviors on a per-owner-type basis. Note that these callbacks are often defined
with a nonpublic access level, so obtaining the actual references from metadata is
generally not possible unless the references are within your permitted access
scope. For more information on dependency property callbacks, see Dependency
Property Callbacks and Validation.

If the dependency property in question is considered to be a WPF framework-level

property, the metadata might contain WPF framework-level dependency property
characteristics, which report information and state for services such as the WPF
framework-level layout engine and property inheritance logic. For more
information on this aspect of dependency property metadata, see Framework
Property Metadata.

Metadata APIs
The type that reports most of the metadata information used by the property system is
the PropertyMetadata class. Metadata instances are optionally specified when
dependency properties are registered with the property system, and can be specified
again for additional types that either add themselves as owners or override metadata
they inherit from the base class dependency property definition. (For cases where a
property registration does not specify metadata, a default PropertyMetadata is created
with default values for that class.)The registered metadata is returned as
PropertyMetadata when you call the various GetMetadata overloads that get metadata
from a dependency property on a DependencyObject instance.

The PropertyMetadata class is then derived from to provide more specific metadata for
architectural divisions such as the WPF framework-level classes. UIPropertyMetadata
adds animation reporting, and FrameworkPropertyMetadata provides the WPF
framework-level properties mentioned in the previous section. When dependency
properties are registered, they can be registered with these PropertyMetadata derived
classes. When the metadata is examined, the base PropertyMetadata type can
potentially be cast to the derived classes so that you can examine the more specific
properties.

７ Note

The property characteristics that can be specified in FrameworkPropertyMetadata

are sometimes referred to in this documentation as "flags". When you create new
metadata instances for use in dependency property registrations or metadata
overrides, you specify these values using the flagwise enumeration
FrameworkPropertyMetadataOptions and then you supply possibly concatenated
values of the enumeration to the FrameworkPropertyMetadata constructor.
However, once constructed, these option characteristics are exposed within a
FrameworkPropertyMetadata as a series of Boolean properties rather than the
constructing enumeration value. The Boolean properties enable you to check each
conditional, rather than requiring you to apply a mask to a flagwise enumeration
value to get the information you are interested in. The constructor uses the
concatenated FrameworkPropertyMetadataOptions in order to keep the length of
the constructor signature reasonable, whereas the actual constructed metadata
exposes the discrete properties to make querying the metadata more intuitive.
When to Override Metadata, When to Derive a
Class
The WPF property system has established capabilities for changing some characteristics
of dependency properties without requiring them to be entirely re-implemented. This is
accomplished by constructing a different instance of property metadata for the
dependency property as it exists on a particular type. Note that most existing
dependency properties are not virtual properties, so strictly speaking "re-implementing"
them on inherited classes could only be accomplished by shadowing the existing
member.

If the scenario you are trying to enable for a dependency property on a type cannot be
accomplished by modifying characteristics of existing dependency properties, it might
then be necessary to create a derived class, and then to declare a custom dependency
property on your derived class. A custom dependency property behaves identically to
dependency properties defined by the WPF APIs. For more details about custom
dependency properties, see Custom Dependency Properties.

One notable characteristic of a dependency property that you cannot override is its
value type. If you are inheriting a dependency property that has the approximate
behavior you require, but you require a different type for it, you will have to implement
a custom dependency property and perhaps link the properties through type conversion
or other implementation on your custom class. Also, you cannot replace an existing
ValidateValueCallback, because this callback exists in the registration field itself and not
within its metadata.

Scenarios for Changing Existing Metadata

If you are working with metadata of an existing dependency property, one common
scenario for changing dependency property metadata is to change the default value.
Changing or adding property system callbacks is a more advanced scenario. You might
want to do this if your implementation of a derived class has different interrelationships
between dependency properties. One of the conditionals of having a programming
model that supports both code and declarative usage is that properties must enable
being set in any order. Thus any dependent properties need to be set just-in-time
without context and cannot rely on knowing a setting order such as might be found in a
constructor. For more information on this aspect of the property system, see
Dependency Property Callbacks and Validation. Note that validation callbacks are not
part of the metadata; they are part of the dependency property identifier. Therefore,
validation callbacks cannot be changed by overriding the metadata.
In some cases you might also want to alter the WPF framework-level property metadata
options on existing dependency properties. These options communicate certain known
conditionals about WPF framework-level properties to other WPF framework-level
processes such as the layout system. Setting the options is generally done only when
registering a new dependency property, but it is also possible to change the WPF
framework-level property metadata as part of a OverrideMetadata or AddOwner call.
For the specific values to use and more information, see Framework Property Metadata.
For more information that is pertinent to how these options should be set for a newly
registered dependency property, see Custom Dependency Properties.

Overriding Metadata
The purpose of overriding metadata is primarily so that you have the opportunity to
change the various metadata-derived behaviors that are applied to the dependency
property as it exists on your type. The reasons for this are explained in more detail in the
Metadata section. For more information including some code examples, see Override
Metadata for a Dependency Property.

Property metadata can be supplied for a dependency property during the registration
call (Register). However, in many cases, you might want to provide type-specific
metadata for your class when it inherits that dependency property. You can do this by
calling the OverrideMetadata method. For an example from the WPF APIs, the
FrameworkElement class is the type that first registers the Focusable dependency
property. But the Control class overrides metadata for the dependency property to
provide its own initial default value, changing it from false to true , and otherwise re-
uses the original Focusable implementation.

When you override metadata, the different metadata characteristics are either merged
or replaced.

PropertyChangedCallback is merged. If you add a new PropertyChangedCallback,

The actual property system behavior for PropertyChangedCallback is that

implementations for all metadata owners in the hierarchy are retained and added
to a table, with order of execution by the property system being that the most
derived class's callbacks are invoked first.

DefaultValue is replaced. If you do not specify a DefaultValue in the override, the

value of DefaultValue comes from the nearest ancestor that specified it in
metadata.

CoerceValueCallback implementations are replaced. If you add a new

CoerceValueCallback, that callback is stored in the metadata. If you do not specify
a CoerceValueCallback in the override, the value of CoerceValueCallback is
promoted as a reference from the nearest ancestor that specified it in metadata.

The property system behavior is that only the CoerceValueCallback in the

immediate metadata is invoked. No references to other CoerceValueCallback
implementations in the hierarchy are retained.

This behavior is implemented by Merge, and can be overridden on derived metadata

classes.

Overriding Attached Property Metadata

In WPF, attached properties are implemented as dependency properties. This means
that they also have property metadata, which individual classes can override. The
scoping considerations for an attached property in WPF are generally that any
DependencyObject can have an attached property set on them. Therefore, any
DependencyObject derived class can override the metadata for any attached property,
as it might be set on an instance of the class. You can override default values, callbacks,
or WPF framework-level characteristic-reporting properties. If the attached property is
set on an instance of your class, those override property metadata characteristics apply.
For instance, you can override the default value, such that your override value is
reported as the value of the attached property on instances of your class, whenever the
property is not otherwise set.

７ Note

The Inherits property is not relevant for attached properties.

Adding a Class as an Owner of an Existing Dependency

Property
A class can add itself as an owner of a dependency property that has already been
registered, by using the AddOwner method. This enables the class to use a dependency
property that was originally registered for a different type. The adding class is typically
not a derived class of the type that first registered that dependency property as owner.
Effectively, this allows your class and its derived classes to "inherit" a dependency
property implementation without the original owner class and the adding class being in
the same true class hierarchy. In addition, the adding class (and all derived classes as
well) can then provide type-specific metadata for the original dependency property.

As well as adding itself as owner through the property system utility methods, the
adding class should declare additional public members on itself in order to make the
dependency property] a full participant in the property system with exposure to both
code and markup. A class that adds an existing dependency property has the same
responsibilities as far as exposing the object model for that dependency property as
does a class that defines a new custom dependency property. The first such member to
expose is a dependency property identifier field. This field should be a public static
readonly field of type DependencyProperty, which is assigned to the return value of the

AddOwner call. The second member to define is the common language runtime (CLR)
"wrapper" property. The wrapper makes it much more convenient to manipulate your
dependency property in code (you avoid calls to SetValue each time, and can make that
call only once in the wrapper itself). The wrapper is implemented identically to how it
would be implemented if you were registering a custom dependency property. For more
information about implementing a dependency property, see Custom Dependency
Properties and Add an Owner Type for a Dependency Property.

AddOwner and Attached Properties

You can call AddOwner for a dependency property that is defined as an attached
property by the owner class. Generally the reason for doing this is to expose the
previously attached property as a non-attached dependency property. You then will
expose the AddOwner return value as a public static readonly field for use as the
dependency property identifier, and will define appropriate "wrapper" properties so that
the property appears in the members table and supports a non-attached property usage
in your class.

See also
PropertyMetadata
DependencyObject
DependencyProperty
GetMetadata
Dependency Properties Overview
Framework Property Metadata
Dependency Property Callbacks and
Validation
Article • 02/06/2023

This topic describes how to create dependency properties using alternative custom
implementations for property-related features such as validation determination,
callbacks that are invoked whenever the property's effective value is changed, and
overriding possible outside influences on value determination. This topic also discusses
scenarios where expanding on the default property system behaviors by using these
techniques is appropriate.

Prerequisites
This topic assumes that you understand the basic scenarios of implementing a
dependency property, and how metadata is applied to a custom dependency property.
See Custom Dependency Properties and Dependency Property Metadata for context.

Validation Callbacks
Validation callbacks can be assigned to a dependency property when you first register it.
The validation callback is not part of property metadata; it is a direct input of the
Register method. Therefore, once a validation callback is created for a dependency
property, it cannot be overridden by a new implementation.

public static readonly DependencyProperty CurrentReadingProperty =

DependencyProperty.Register(
"CurrentReading",
typeof(double),
typeof(Gauge),
new FrameworkPropertyMetadata(
Double.NaN,
FrameworkPropertyMetadataOptions.AffectsMeasure,
new PropertyChangedCallback(OnCurrentReadingChanged),
new CoerceValueCallback(CoerceCurrentReading)
),
new ValidateValueCallback(IsValidReading)
);
public double CurrentReading
{
get { return (double)GetValue(CurrentReadingProperty); }
set { SetValue(CurrentReadingProperty, value); }
}

The callbacks are implemented such that they are provided an object value. They return
true if the provided value is valid for the property; otherwise, they return false . It is
assumed that the property is of the correct type per the type registered with the
property system, so checking type within the callbacks is not ordinarily done. The
callbacks are used by the property system in a variety of different operations. This
includes the initial type initialization by default value, programmatic change by invoking
SetValue, or attempts to override metadata with new default value provided. If the
validation callback is invoked by any of these operations, and returns false , then an
exception will be raised. Application writers must be prepared to handle these
exceptions. A common use of validation callbacks is validating enumeration values, or
constraining values of integers or doubles when the property sets measurements that
must be zero or greater.

Validation callbacks specifically are intended to be class validators, not instance

validators. The parameters of the callback do not communicate a specific
DependencyObject on which the properties to validate are set. Therefore the validation
callbacks are not useful for enforcing the possible "dependencies" that might influence a
property value, where the instance-specific value of a property is dependent on factors
such as instance-specific values of other properties, or run-time state.

The following is example code for a very simple validation callback scenario: validating
that a property that is typed as the Double primitive is not PositiveInfinity or
NegativeInfinity.

public static bool IsValidReading(object value)

{
Double v = (Double)value;
return (!v.Equals(Double.NegativeInfinity) &&
!v.Equals(Double.PositiveInfinity));
}

Coerce Value Callbacks and Property Changed

Events
Coerce value callbacks do pass the specific DependencyObject instance for properties,
as do PropertyChangedCallback implementations that are invoked by the property
system whenever the value of a dependency property changes. Using these two
callbacks in combination, you can create a series of properties on elements where
changes in one property will force a coercion or reevaluation of another property.

A typical scenario for using a linkage of dependency properties is when you have a user
interface driven property where the element holds one property each for the minimum
and maximum value, and a third property for the actual or current value. Here, if the
maximum was adjusted in such a way that the current value exceeded the new
maximum, you would want to coerce the current value to be no greater than the new
maximum, and a similar relationship for minimum to current.

The following is very brief example code for just one of the three dependency properties
that illustrate this relationship. The example shows how the CurrentReading property of
a Min/Max/Current set of related *Reading properties is registered. It uses the validation
as shown in the previous section.

public static readonly DependencyProperty CurrentReadingProperty =

The property changed callback for Current is used to forward the change to other
dependent properties, by explicitly invoking the coerce value callbacks that are
registered for those other properties:

private static void OnCurrentReadingChanged(DependencyObject d,

DependencyPropertyChangedEventArgs e)
{
d.CoerceValue(MinReadingProperty);
d.CoerceValue(MaxReadingProperty);
}
The coerce value callback checks the values of properties that the current property is
potentially dependent upon, and coerces the current value if necessary:

private static object CoerceCurrentReading(DependencyObject d, object value)

{
Gauge g = (Gauge)d;
double current = (double)value;
if (current < g.MinReading) current = g.MinReading;
if (current > g.MaxReading) current = g.MaxReading;
return current;
}

７ Note

Default values of properties are not coerced. A property value equal to the default
value might occur if a property value still has its initial default, or through clearing
other values with ClearValue.

The coerce value and property changed callbacks are part of property metadata.
Therefore, you can change the callbacks for a particular dependency property as it exists
on a type that you derive from the type that owns the dependency property, by
overriding the metadata for that property on your type.

Advanced Coercion and Callback Scenarios

Constraints and Desired Values

The CoerceValueCallback callbacks will be used by the property system to coerce a value
in accordance to the logic you declare, but a coerced value of a locally set property will
still retain a "desired value" internally. If the constraints are based on other property
values that may change dynamically during the application lifetime, the coercion
constraints are changed dynamically also, and the constrained property can change its
value to get as close to the desired value as possible given the new constraints. The
value will become the desired value if all constraints are lifted. You can potentially
introduce some fairly complicated dependency scenarios if you have multiple properties
that are dependent on one another in a circular manner. For instance, in the
Min/Max/Current scenario, you could choose to have Minimum and Maximum be user
settable. If so, you might need to coerce that Maximum is always greater than Minimum
and vice versa. But if that coercion is active, and Maximum coerces to Minimum, it
leaves Current in an unsettable state, because it is dependent on both and is
constrained to the range between the values, which is zero. Then, if Maximum or
Minimum are adjusted, Current will seem to "follow" one of the values, because the
desired value of Current is still stored and is attempting to reach the desired value as
the constraints are loosened.

There is nothing technically wrong with complex dependencies, but they can be a slight
performance detriment if they require large numbers of reevaluations, and can also be
confusing to users if they affect the UI directly. Be careful with property changed and
coerce value callbacks and make sure that the coercion being attempted can be treated
as unambiguously as possible, and does not "overconstrain".

Using CoerceValue to Cancel Value Changes

The property system will treat any CoerceValueCallback that returns the value
UnsetValue as a special case. This special case means that the property change that
resulted in the CoerceValueCallback being called should be rejected by the property
system, and that the property system should instead report whatever previous value the
property had. This mechanism can be useful to check that changes to a property that
were initiated asynchronously are still valid for the current object state, and suppress the
changes if not. Another possible scenario is that you can selectively suppress a value
depending on which component of property value determination is responsible for the
value being reported. To do this, you can use the DependencyProperty passed in the
callback and the property identifier as input for GetValueSource, and then process the
ValueSource.

See also
Dependency Properties Overview
Dependency Property Metadata
Custom Dependency Properties
Framework Property Metadata
Article • 02/06/2023

Framework property metadata options are reported for the properties of object
elements considered to be at the WPF framework level in the WPF presentation APIs
and executables. Framework property metadata is queried by these systems to
determine feature-specific characteristics of particular element properties.

Prerequisites
This topic assumes that you understand dependency properties from the perspective of
a consumer of existing dependency properties on Windows Presentation Foundation
(WPF) classes, and have read the Dependency Properties Overview. You should also have
read Dependency Property Metadata.

What Is Communicated by Framework Property

Metadata
Framework property metadata can be divided into the following categories:

Reporting layout properties that affect an element (AffectsArrange,

AffectsMeasure, AffectsRender). You might set these flags in metadata if the
property affects those respective aspects, and you are also implementing the
MeasureOverride / ArrangeOverride methods in your class to supply specific
rendering behavior and information to the layout system. Typically, such an
implementation would check for property invalidations in dependency properties
where any of these layout properties were true in the property metadata, and only
those invalidations would necessitate requesting a new layout pass.

Reporting layout properties that affect the parent element of an element

(AffectsParentArrange, AffectsParentMeasure). Some examples where these flags
are set by default are FixedPage.Left and Paragraph.KeepWithNext.

Inherits. By default, dependency properties do not inherit values.

OverridesInheritanceBehavior allows the pathway of inheritance to also travel into
a visual tree, which is necessary for some control compositing scenarios.

７ Note
The term "inherits" in the context of property values means something
specific for dependency properties; it means that child elements can inherit
the actual dependency property value from parent elements because of a
WPF framework-level capability of the WPF property system. It has nothing to
do directly with managed code type and members inheritance through
derived types. For details, see Property Value Inheritance.

Reporting data binding characteristics (IsNotDataBindable,

BindsTwoWayByDefault). By default, dependency properties in the framework
support data binding, with a one-way binding behavior. You might disable data
binding if there were no scenario for it whatsoever (because they are intended to
be flexible and extensible, there aren't many examples of such properties in the
default WPF APIs). You might set binding to have a two-way default for properties
that tie together a control's behaviors amongst its component pieces
(IsSubmenuOpen is an example) or where two-way binding is the common and
expected scenario for users (Text is an example). Changing the data binding–
related metadata only influences the default; on a per-binding basis that default
can always be changed. For details on the binding modes and binding in general,
see Data Binding Overview.

Reporting whether properties should be journaled by applications or services that

support journaling (Journal). For general elements, journaling is not enabled by
default, but it is selectively enabled for certain user input controls. This property is
intended to be read by journaling services including the WPF implementation of
journaling, and is typically set on user controls such as user selections within lists
that should be persisted across navigation steps. For information about the journal,
see Navigation Overview.

Reading FrameworkPropertyMetadata
Each of the properties linked above are the specific properties that the
FrameworkPropertyMetadata adds to its immediate base class UIPropertyMetadata.
Each of these properties will be false by default. A metadata request for a property
where knowing the value of these properties is important should attempt to cast the
returned metadata to FrameworkPropertyMetadata, and then check the values of the
individual properties as needed.

Specifying Metadata
When you create a new metadata instance for purposes of applying metadata to a new
dependency property registration, you have the choice of which metadata class to use:
the base PropertyMetadata or some derived class such as FrameworkPropertyMetadata.
In general, you should use FrameworkPropertyMetadata, particularly if your property
has any interaction with property system and WPF functions such as layout and data
binding. Another option for more sophisticated scenarios is to derive from
FrameworkPropertyMetadata to create your own metadata reporting class with extra
information carried in its members. Or you might use PropertyMetadata or
UIPropertyMetadata to communicate the degree of support for features of your
implementation.

For existing properties (AddOwner or OverrideMetadata call), you should always

override with the metadata type used by the original registration.

If you are creating a FrameworkPropertyMetadata instance, there are two ways to

populate that metadata with values for the specific properties that communicate the
framework property characteristics:

1. Use the FrameworkPropertyMetadata constructor signature that allows a flags

parameter. This parameter should be filled with all desired combined values of the
FrameworkPropertyMetadataOptions enumeration flags.

2. Use one of the signatures without a flags parameter, and then set each reporting
Boolean property on FrameworkPropertyMetadata to true for each desired
characteristic change. If you do this, you must set these properties before any
elements with this dependency property are constructed; the Boolean properties
are read-write in order to allow this behavior of avoiding the flags parameter and
still populate the metadata, but the metadata must become effectively sealed
before property use. Thus, attempting to set the properties after metadata is
requested will be an invalid operation.

Framework Property Metadata Merge Behavior

When you override framework property metadata, the different metadata characteristics
are either merged or replaced.

PropertyChangedCallback is merged. If you add a new PropertyChangedCallback,

that callback is stored in the metadata. If you do not specify a
PropertyChangedCallback in the override, the value of PropertyChangedCallback is
promoted as a reference from the nearest ancestor that specified it in metadata.
The actual property system behavior for PropertyChangedCallback is that
implementations for all metadata owners in the hierarchy are retained and added
to a table, with order of execution by the property system being that the callbacks
of the most deeply derived class are invoked first. Inherited callbacks run only
once, counting as being owned by the class that placed them in metadata.

DefaultValue is replaced. If you do not specify a PropertyChangedCallback in the

override, the value of DefaultValue comes from the nearest ancestor that specified
it in metadata.

CoerceValueCallback implementations are replaced. If you add a new

The property system behavior is that only the CoerceValueCallback in the

immediate metadata is invoked. No references to other CoerceValueCallback
implementations in the hierarchy are retained.

The flags of FrameworkPropertyMetadataOptions enumeration are combined as a

bitwise OR operation. If you specify FrameworkPropertyMetadataOptions, the
original options are not overwritten. To change an option, set the corresponding
property on FrameworkPropertyMetadata. For example, if the original
FrameworkPropertyMetadata object sets the
FrameworkPropertyMetadataOptions.NotDataBindable flag, you can change that
by setting FrameworkPropertyMetadata.IsNotDataBindable to false .

This behavior is implemented by Merge, and can be overridden on derived metadata

classes.

See also
GetMetadata
Dependency Property Metadata
Dependency Properties Overview
Custom Dependency Properties
Dependency Property Value Precedence
Article • 02/06/2023

This topic explains how the workings of the Windows Presentation Foundation (WPF)
property system can affect the value of a dependency property, and describes the
precedence by which aspects of the property system apply to the effective value of a
property.

Prerequisites
This topic assumes that you understand dependency properties from the perspective of
a consumer of existing dependency properties on WPF classes, and have read
Dependency Properties Overview. To follow the examples in this topic, you should also
understand WPF applications.

The WPF Property System

The WPF property system offers a powerful way to have the value of dependency
properties be determined by a variety of factors, enabling features such as real-time
property validation, late binding, and notifying related properties of changes to values
for other properties. The exact order and logic that is used to determine dependency
property values is reasonably complex. Knowing this order will help you avoid
unnecessary property setting, and might also clear up confusion over exactly why some
attempt to influence or anticipate a dependency property value did not end up resulting
in the value you expected.

Dependency Properties Might Be "Set" in

Multiple Places
The following is example XAML where the same property (Background) has three
different "set" operations that might influence the value.

XAML

<Button Template="{StaticResource ButtonTemplate}" Background="Red">

<Button.Style>
<Style TargetType="{x:Type Button}">
<Setter Property="Background" Value="Blue"/>
<Style.Triggers>
<Trigger Property="IsMouseOver" Value="True">
<Setter Property="Background" Value="Yellow" />
</Trigger>
</Style.Triggers>
</Style>
</Button.Style>
Which color do you expect?
</Button>
</StackPanel>

Here, which color do you expect will apply—red, green, or blue?

With the exception of animated values and coercion, local property sets are set at the
highest precedence. If you set a value locally you can expect that the value will be
honored, even above any styles or control templates. Here in the example, Background
is set to Red locally. Therefore, the style defined in this scope, even though it is an
implicit style that would otherwise apply to all elements of that type in that scope, is not
the highest precedence for giving the Background property its value. If you removed the
local value of Red from that Button instance, then the style would have precedence and
the button would obtain the Background value from the style. Within the style, triggers
take precedence, so the button will be blue if the mouse is over it, and green otherwise.

Dependency Property Setting Precedence List

The following is the definitive order that the property system uses when assigning the
run-time values of dependency properties. Highest precedence is listed first. This list
expands on some of the generalizations made in the Dependency Properties Overview.

1. Property system coercion. For details on coercion, see Coercion, Animation, and
Base Value later in this topic.

2. Active animations, or animations with a Hold behavior. In order to have any

practical effect, an animation of a property must be able to have precedence over
the base (unanimated) value, even if that value was set locally. For details, see
Coercion, Animation, and Base Value later in this topic.

3. Local value. A local value might be set through the convenience of the "wrapper"
property, which also equates to setting as an attribute or property element in
XAML, or by a call to the SetValue API using a property of a specific instance. If you
set a local value by using a binding or a resource, these each act in the precedence
as if a direct value was set.

4. TemplatedParent template properties. An element has a TemplatedParent if it was

created as part of a template (a ControlTemplate or DataTemplate). For details on
when this applies, see TemplatedParent later in this topic. Within the template, the
following precedence applies:

a. Triggers from the TemplatedParent template.

b. Property sets (typically through XAML attributes) in the TemplatedParent

template.

5. Implicit style. Applies only to the Style property. The Style property is filled by
any style resource with a key that matches the type of that element. That style
resource must exist either in the page or the application; lookup for an implicit
style resource does not proceed into the themes.

6. Style triggers. The triggers within styles from page or application (these styles
might be either explicit or implicit styles, but not from the default styles, which
have lower precedence).

7. Template triggers. Any trigger from a template within a style, or a directly applied
template.

8. Style setters. Values from a Setter within styles from page or application.

9. Default (theme) style. For details on when this applies, and how theme styles
relate to the templates within theme styles, see Default (Theme) Styles later in this
topic. Within a default style, the following order of precedence applies:

a. Active triggers in the theme style.

b. Setters in the theme style.

10. Inheritance. A few dependency properties inherit their values from parent element
to child elements, such that they need not be set specifically on each element
throughout an application. For details see Property Value Inheritance.
11. Default value from dependency property metadata. Any given dependency
property may have a default value as established by the property system
registration of that particular property. Also, derived classes that inherit a
dependency property have the option to override that metadata (including the
default value) on a per-type basis. See Dependency Property Metadata for more
information. Because inheritance is checked before default value, for an inherited
property, a parent element default value takes precedence over a child element.
Consequently, if an inheritable property is not set anywhere, the default value as
specified on the root or parent is used instead of the child element default value.

TemplatedParent
TemplatedParent as a precedence item does not apply to any property of an element
that you declare directly in standard application markup. The TemplatedParent concept
exists only for child items within a visual tree that come into existence through the
application of the template. When the property system searches the TemplatedParent
template for a value, it is searching the template that created that element. The property
values from the TemplatedParent template generally act as if they were set as a local
value on the child element, but this lesser precedence versus the local value exists
because the templates are potentially shared. For details, see TemplatedParent.

The Style Property

The order of lookup described earlier applies to all possible dependency properties
except one: the Style property. The Style property is unique in that it cannot itself be
styled, so the precedence items 5 through 8 do not apply. Also, either animating or
coercing Style is not recommended (and animating Style would require a custom
animation class). This leaves three ways that the Style property might be set:

Explicit style. The Style property is set directly. In most scenarios, the style is not
defined inline, but instead is referenced as a resource, by explicit key. In this case
the Style property itself acts as if it were a local value, precedence item 3.

Implicit style. The Style property is not set directly. However, the Style exists at
some level in the resource lookup sequence (page, application) and is keyed using
a resource key that matches the type the style is to be applied to. In this case, the
Style property itself acts by a precedence identified in the sequence as item 5. This
condition can be detected by using DependencyPropertyHelper against the Style
property and looking for ImplicitStyleReference in the results.
Default style, also known as theme style. The Style property is not set directly, and
in fact will read as null up until run time. In this case, the style comes from the
run-time theme evaluation that is part of the WPF presentation engine.

For implicit styles not in themes, the type must match exactly - a MyButton Button -
derived class will not implicitly use a style for Button .

Default (Theme) Styles

Every control that ships with WPF has a default style. That default style potentially varies
by theme, which is why this default style is sometimes referred to as a theme style.

The most important information that is found within a default style for a control is its
control template, which exists in the theme style as a setter for its Template property. If
there were no template from default styles, a control without a custom template as part
of a custom style would have no visual appearance at all. The template from the default
style gives the visual appearance of each control a basic structure, and also defines the
connections between properties defined in the visual tree of the template and the
corresponding control class. Each control exposes a set of properties that can influence
the visual appearance of the control without completely replacing the template. For
example, consider the default visual appearance of a Thumb control, which is a
component of a ScrollBar.

A Thumb has certain customizable properties. The default template of a Thumb creates
a basic structure / visual tree with several nested Border components to create a bevel
look. If a property that is part of the template is intended to be exposed for
customization by the Thumb class, then that property must be exposed by a
TemplateBinding, within the template. In the case of Thumb, various properties of these
borders share a template binding to properties such as Background or BorderThickness.
But certain other properties or visual arrangements are hard-coded into the control
template or are bound to values that come directly from the theme, and cannot be
changed short of replacing the entire template. Generally, if a property comes from a
templated parent and is not exposed by a template binding, it cannot be adjusted by
styles because there is no easy way to target it. But that property could still be
influenced by property value inheritance in the applied template, or by default value.

The theme styles use a type as the key in their definitions. However, when themes are
applied to a given element instance, themes lookup for this type is performed by
checking the DefaultStyleKey property on a control. This is in contrast to using the literal
Type, as implicit styles do. The value of DefaultStyleKey would inherit to derived classes
even if the implementer did not change it (the intended way of changing the property is
not to override it at the property level, but to instead change its default value in
property metadata). This indirection enables base classes to define the theme styles for
derived elements that do not otherwise have a style (or more importantly, do not have a
template within that style and would thus have no default visual appearance at all).
Thus, you can derive MyButton from Button and will still get the Button default template.
If you were the control author of MyButton and you wanted a different behavior, you
could override the dependency property metadata for DefaultStyleKey on MyButton to
return a different key, and then define the relevant theme styles including template for
MyButton that you must package with your MyButton control. For more details on
themes, styles, and control authoring, see Control Authoring Overview.

Dynamic Resource References and Binding

Dynamic resource references and binding operations respect the precedence of the
location at which they are set. For example, a dynamic resource applied to a local value
acts per precedence item 3, a binding for a property setter within a theme style applies
at precedence item 9, and so on. Because dynamic resource references and binding
must both be able to obtain values from the run time state of the application, this
entails that the actual process of determining the property value precedence for any
given property extends into the run time as well.

Dynamic resource references are not strictly speaking part of the property system, but
they do have a lookup order of their own which interacts with the sequence listed
above. That precedence is documented more thoroughly in the XAML Resources. The
basic summation of that precedence is: element to page root, application, theme,
system.

Dynamic resources and bindings have the precedence of where they were set, but the
value is deferred. One consequence of this is that if you set a dynamic resource or
binding to a local value, any change to the local value replaces the dynamic resource or
binding entirely. Even if you call the ClearValue method to clear the locally set value, the
dynamic resource or binding will not be restored. In fact, if you call ClearValue on a
property that has a dynamic resource or binding in place (with no literal local value),
they are cleared by the ClearValue call too.

SetCurrentValue
The SetCurrentValue method is another way to set a property, but it is not in the order
of precedence. Instead, SetCurrentValue enables you to change the value of a property
without overwriting the source of a previous value. You can use SetCurrentValue any
time that you want to set a value without giving that value the precedence of a local
value. For example, if a property is set by a trigger and then assigned another value via
SetCurrentValue, the property system still respects the trigger and the property will
change if the trigger’s action occurs. SetCurrentValue enables you to change the
property’s value without giving it a source with a higher precedence. Likewise, you can
use SetCurrentValue to change the value of a property without overwriting a binding.

Coercion, Animations, and Base Value

Coercion and animation both act on a value that is termed as the "base value"
throughout this SDK. The base value is thus whatever value is determined through
evaluating upwards in the items until item 2 is reached.

For an animation, the base value can have an effect on the animated value, if that
animation does not specify both "From" and "To" for certain behaviors, or if the
animation deliberately reverts to the base value when completed. To see this in practice,
run the From, To, and By Animation Target Values Sample . Try setting the local values
of the rectangle height in the example, such that the initial local value differs from any
"From" in the animation. You will note that the animations start right away using the
"From" values and replace the base value once started. The animation might specify to
return to the value found before animation once it is completed by specifying the Stop
FillBehavior. Afterwards, normal precedence is used for the base value determination.

Multiple animations might be applied to a single property, with each of these

animations possibly having been defined from different points in the value precedence.
However, these animations will potentially composite their values, rather than just
applying the animation from the higher precedence. This depends on exactly how the
animations are defined, and the type of the value that is being animated. For more
information about animating properties, see Animation Overview.

Coercion applies at the highest level of all. Even an already running animation is subject
to value coercion. Certain existing dependency properties in WPF have built-in coercion.
For a custom dependency property, you define the coercion behavior for a custom
dependency property by writing a CoerceValueCallback and passing the callback as part
of metadata when you create the property. You can also override coercion behavior of
existing properties by overriding the metadata on that property in a derived class.
Coercion interacts with the base value in such a way that the constraints on coercion are
applied as those constraints exist at the time, but the base value is still retained.
Therefore, if constraints in coercion are later lifted, the coercion will return the closest
value possible to that base value, and potentially the coercion influence on a property
will cease as soon as all constraints are lifted. For more information about coercion
behavior, see Dependency Property Callbacks and Validation.

Trigger Behaviors
Controls often define trigger behaviors as part of their default style in themes. Setting
local properties on controls might prevent the triggers from being able to respond to
user-driven events either visually or behaviorally. The most common use of a property
trigger is for control or state properties such as IsSelected. For example, by default when
a Button is disabled (trigger for IsEnabled is false ) then the Foreground value in the
theme style is what causes the control to appear "grayed out". But if you have set a local
Foreground value, that normal gray-out color will be overruled in precedence by your
local property set, even in this property-triggered scenario. Be cautious of setting values
for properties that have theme-level trigger behaviors and make sure you are not
unduly interfering with the intended user experience for that control.

ClearValue and Value Precedence

The ClearValue method provides an expedient means to clear any locally applied value
from a dependency property that is set on an element. However, calling ClearValue is
not a guarantee that the default as established in metadata during property registration
is the new effective value. All of the other participants in value precedence are still
active. Only the locally set value has been removed from the precedence sequence. For
example, if you call ClearValue on a property where that property is also set by a theme
style, then the theme value is applied as the new value rather than the metadata-based
default. If you want to take all property value participants out of the process and set the
value to the registered metadata default, you can obtain that default value definitively
by querying the dependency property metadata, and then you can use the default value
to locally set the property with a call to SetValue.

See also
DependencyObject
DependencyProperty
Dependency Properties Overview
Custom Dependency Properties
Dependency Property Callbacks and Validation
Read-Only Dependency Properties
Article • 02/06/2023

This topic describes read-only dependency properties, including existing read-only

dependency properties and the scenarios and techniques for creating a custom read-
only dependency property.

Existing Read-Only Dependency Properties

Some of the dependency properties defined in the Windows Presentation Foundation
(WPF) framework are read-only. The typical reason for specifying a read-only
dependency property is that these are properties that should be used for state
determination, but where that state is influenced by a multitude of factors, but just
setting the property to that state isn't desirable from a user interface design perspective.
For example, the property IsMouseOver is really just surfacing state as determined from
the mouse input. Any attempt to set this value programmatically by circumventing the
true mouse input would be unpredictable and would cause inconsistency.

By virtue of not being settable, read-only dependency properties aren't appropriate for
many of the scenarios for which dependency properties normally offer a solution
(namely: data binding, directly stylable to a value, validation, animation, inheritance).
Despite not being settable, read-only dependency properties still have some of the
additional capabilities supported by dependency properties in the property system. The
most important remaining capability is that the read-only dependency property can still
be used as a property trigger in a style. You can't enable triggers with a normal common
language runtime (CLR) property; it needs to be a dependency property. The
aforementioned IsMouseOver property is a perfect example of a scenario where it might
be quite useful to define a style for a control, where some visible property such as a
background, foreground, or similar properties of composited elements within the
control will change when the user places a mouse over some defined region of your
control. Changes in a read-only dependency property can also be detected and
reported by the property system's inherent invalidation processes, and this in fact
supports the property trigger functionality internally.
Creating Custom Read-Only Dependency
Properties
Make sure to read the section above regarding why read-only dependency properties
won't work for many typical dependency-property scenarios. But if you have an
appropriate scenario, you may wish to create your own read-only dependency property.

Much of the process of creating a read-only dependency property is the same as is

described in the Custom Dependency Properties and Implement a Dependency Property
topics. There are three important differences:

When registering your property, call the RegisterReadOnly method instead of the
normal Register method for property registration.

When implementing the CLR "wrapper" property, make sure that the wrapper too
doesn't have a set implementation, so that there is no inconsistency in read-only
state for the public wrapper you expose.

The object returned by the read-only registration is DependencyPropertyKey rather

than DependencyProperty. You should still store this field as a member but
typically you would not make it a public member of the type.

Whatever private field or value you have backing your read-only dependency property
can of course be fully writable using whatever logic you decide. However, the most
straightforward way to set the property either initially or as part of runtime logic is to
use the property system's APIs, rather than circumventing the property system and
setting the private backing field directly. In particular, there is a signature of SetValue
that accepts a parameter of type DependencyPropertyKey. How and where you set this
value programmatically within your application logic will affect how you may wish to set
access on the DependencyPropertyKey created when you first registered the
dependency property. If you handle this logic all within the class you could make it
private, or if you require it to be set from other portions of the assembly you might set it
internal. One approach is to call SetValue within a class event handler of a relevant event
that informs a class instance that the stored property value needs to be changed.
Another approach is to tie dependency properties together by using paired
PropertyChangedCallback and CoerceValueCallback callbacks as part of those
properties' metadata during registration.

Because the DependencyPropertyKey is private, and is not propagated by the property

system outside of your code, a read-only dependency property does have better setting
security than a read-write dependency property. For a read-write dependency property,
the identifying field is explicitly or implicitly public and thus the property is widely
settable. For more specifics, see Dependency Property Security.

See also
Dependency Properties Overview
Custom Dependency Properties
Styling and Templating
Property Value Inheritance
Article • 02/06/2023

Property value inheritance is a feature of the Windows Presentation Foundation (WPF)

property system. Property value inheritance enables child elements in a tree of elements
to obtain the value of a particular property from parent elements, inheriting that value
as it was set anywhere in the nearest parent element. The parent element might also
have obtained its value through property value inheritance, so the system potentially
recurses all the way to the page root. Property value inheritance is not the default
property system behavior; a property must be established with a particular metadata
setting in order to cause that property to initiate property value inheritance on child
elements.

Property Value Inheritance Is Containment

Inheritance
"Inheritance" as a term here is not quite the same concept as inheritance in the context
of types and general object-oriented programming, where derived classes inherit
member definitions from their base classes. That meaning of inheritance is also active in
WPF: properties defined in various base classes are exposed as attributes for derived
XAML classes when used as elements, and exposed as members for code. Property value
inheritance is particularly about how property values can inherit from one element to
another on the basis of the parent-child relationships within a tree of elements. That
tree of elements is most directly visible when nesting elements inside other elements as
you define applications in XAML markup. Trees of objects can also be created
programmatically by adding objects to designated collections of other objects, and
property value inheritance works the same way in the finished tree at run time.

Practical Applications of Property Value

Inheritance
The WPF APIs include several properties that have property inheritance enabled.
Typically, the scenario for these is that they involve a property where it is appropriate
that the property be set only once per page, but where that property is also a member
of one of the base element classes and thus would also exist on most of the child
elements. For example, the FlowDirection property controls which direction flowed
content should be presented and arranged on the page. Typically, you want the text
flow concept to be handled consistently throughout all child elements. If flow direction
were for some reason reset in some level of the element tree by user or environment
action, it should typically be reset throughout. When the FlowDirection property is made
to inherit, the value need only be set or reset once at the level in the element tree that
encompasses the presentation needs of each page in the application. Even the initial
default value will inherit in this way. The property value inheritance model still enables
individual elements to reset the value for the rare cases where having a mix of flow
directions is intentional.

Making a Custom Property Inheritable

By changing a custom property's metadata, you can also make your own custom
properties inheritable. Note, however, that designating a property as inheritable does
have some performance considerations. In cases where that property does not have an
established local value, or a value obtained through styles, templates, or data binding,
an inheritable property provides its assigned property values to all child elements in the
logical tree.

To make a property participate in value inheritance, create a custom attached property,

as described in Register an Attached Property. Register the property with metadata
(FrameworkPropertyMetadata) and specify the "Inherits" option in the options settings
within that metadata. Also make sure that the property has an established default value,
because that value will now inherit. Although you registered the property as attached,
you might also want to create a property "wrapper" for get/set access on the owner
type, just as you would for an "nonattached" dependency property. After doing so, the
inheritable property can either be set by using the direct property wrapper on the owner
type or derived types, or it can be set by using the attached property syntax on any
DependencyObject.

Attached properties are conceptually similar to global properties; you can check for the
value on any DependencyObject and get a valid result. The typical scenario for attached
properties is to set property values on child elements, and that scenario is more
effective if the property in question is an attached property that is always implicitly
present as an attached property on each element (DependencyObject) in the tree.

７ Note

Although property value inheritance might appear to work for nonattached

dependency properties, the inheritance behavior for a nonattached property
through certain element boundaries in the run-time tree is undefined. Always use
RegisterAttached to register properties where you specify Inherits in the metadata.
Inheriting Property Values Across Tree
Boundaries
Property inheritance works by traversing a tree of elements. This tree is often parallel to
the logical tree. However, whenever you include a WPF core-level object in the markup
that defines an element tree, such as a Brush, you have created a discontinuous logical
tree. A true logical tree does not conceptually extend through the Brush, because the
logical tree is a WPF framework-level concept. You can see this reflected in the results
when using the methods of LogicalTreeHelper. However, property value inheritance can
bridge this gap in the logical tree and can still pass inherited values through, so long as
the inheritable property was registered as an attached property and no deliberate
inheritance-blocking boundary (such as a Frame) is encountered.

See also
Dependency Property Metadata
Attached Properties Overview
Dependency Property Value Precedence
Dependency Property Security
Article • 02/06/2023

Dependency properties should generally be considered to be public properties. The

nature of the Windows Presentation Foundation (WPF) property system prevents the
ability to make security guarantees about a dependency property value.

Access and Security of Wrappers and

Dependency Properties
Typically, dependency properties are implemented along with "wrapper" common
language runtime (CLR) properties that simplify getting or setting the property from an
instance. But the wrappers are really just convenience methods that implement the
underlying GetValue and SetValue static calls that are used when interacting with
dependency properties. Thinking of it in another way, the properties are exposed as
common language runtime (CLR) properties that happen to be backed by a dependency
property rather than by a private field. Security mechanisms applied to the wrappers do
not parallel the property system behavior and access of the underlying dependency
property. Placing a security demand on the wrapper will only prevent the usage of the
convenience method but will not prevent calls to GetValue or SetValue. Similarly, placing
protected or private access level on the wrappers does not provide any effective
security.

If you are writing your own dependency properties, you should declare the wrappers
and the DependencyProperty identifier field as public members, so that callers do not
get misleading information about the true access level of that property (because of its
store being implemented as a dependency property).

For a custom dependency property, you can register your property as a read-only
dependency property, and this does provide an effective means of preventing a
property being set by anyone that does not hold a reference to the
DependencyPropertyKey for that property. For more information, see Read-Only
Dependency Properties.

７ Note

Declaring a DependencyProperty identifier field private is not forbidden, and it can

conceivably be used to help reduce the immediately exposed namespace of a
custom class, but such a property should not be considered "private" in the same
sense as the common language runtime (CLR) language definitions define that
access level, for reasons described in the next section.

Property System Exposure of Dependency

Properties
It is not generally useful, and it is potentially misleading, to declare a
DependencyProperty as any access level other than public. That access level setting only
prevents someone from being able to get a reference to the instance from the declaring
class. But there are several aspects of the property system that will return a
DependencyProperty as the means of identifying a particular property as it exists on an
instance of a class or a derived class instance, and this identifier is still usable in a
SetValue call even if the original static identifier is declared as nonpublic. Also,
OnPropertyChanged virtual methods receive information of any existing dependency
property that changed value. In addition, the GetLocalValueEnumerator method returns
identifiers for any property on instances with a locally set value.

Validation and Security

Applying a demand to a ValidateValueCallback and expecting the validation failure on a
demand failure to prevent a property from being set is not an adequate security
mechanism. Set-value invalidation enforced through ValidateValueCallback could also be
suppressed by malicious callers, if those callers are operating within the application
domain.

See also
Custom Dependency Properties
Safe Constructor Patterns for
DependencyObjects
Article • 02/06/2023

Generally, class constructors should not call callbacks such as virtual methods or
delegates, because constructors can be called as base initialization of constructors for a
derived class. Entering the virtual might be done at an incomplete initialization state of
any given object. However, the property system itself calls and exposes callbacks
internally, as part of the dependency property system. As simple an operation as setting
a dependency property value with SetValue call potentially includes a callback
somewhere in the determination. For this reason, you should be careful when setting
dependency property values within the body of a constructor, which can become
problematic if your type is used as a base class. There is a particular pattern for
implementing DependencyObject constructors that avoids specific problems with
dependency property states and the inherent callbacks, which is documented here.

Property System Virtual Methods

The following virtual methods or callbacks are potentially called during the
computations of the SetValue call that sets a dependency property value:
ValidateValueCallback, PropertyChangedCallback, CoerceValueCallback,
OnPropertyChanged. Each of these virtual methods or callbacks serves a particular
purpose in expanding the versatility of the Windows Presentation Foundation (WPF)
property system and dependency properties. For more information on how to use these
virtuals to customize property value determination, see Dependency Property Callbacks
and Validation.

FXCop Rule Enforcement vs. Property System Virtuals

If you use the Microsoft tool FXCop as part of your build process, and you either derive
from certain WPF framework classes calling the base constructor, or implement your
own dependency properties on derived classes, you might encounter a particular FXCop
rule violation. The name string for this violation is:

DoNotCallOverridableMethodsInConstructors

This is a rule that is part of the default public rule set for FXCop. What this rule might be
reporting is a trace through the dependency property system that eventually calls a
dependency property system virtual method. This rule violation might continue to
appear even after following the recommended constructor patterns documented in this
topic, so you might need to disable or suppress that rule in your FXCop rule set
configuration.

Most Issues Come From Deriving Classes, Not Using

Existing Classes
The issues reported by this rule occur when a class that you implement with virtual
methods in its construction sequence is then derived from. If you seal your class, or
otherwise know or enforce that your class will not be derived from, the considerations
explained here and the issues that motivated the FXCop rule do not apply to you.
However, if you are authoring classes in such a way that they are intended to be used as
base classes, for instance if you are creating templates, or an expandable control library
set, you should follow the patterns recommended here for constructors.

Default Constructors Must Initialize All Values Requested

By Callbacks
Any instance members that are used by your class overrides or callbacks (the callbacks
from the list in the Property System Virtuals section) must be initialized in your class
parameterless constructor, even if some of those values are filled by "real" values
through parameters of the nonparameterless constructors.

The following example code (and subsequent examples) is a pseudo-C# example that
violates this rule and explains the problem:

public class MyClass : DependencyObject

{
public MyClass() {}
public MyClass(object toSetWobble)
: this()
{
Wobble = toSetWobble; //this is backed by a DependencyProperty
_myList = new ArrayList(); // this line should be in the default
ctor
}
public static readonly DependencyProperty WobbleProperty =
DependencyProperty.Register("Wobble", typeof(object),
typeof(MyClass));
public object Wobble
{
get { return GetValue(WobbleProperty); }
set { SetValue(WobbleProperty, value); }
}
protected override void
OnPropertyChanged(DependencyPropertyChangedEventArgs e)
{
int count = _myList.Count; // null-reference exception
}
private ArrayList _myList;
}

When application code calls new MyClass(objectvalue) , this calls the parameterless
constructor and base class constructors. Then it sets Property1 = object1 , which calls
the virtual method OnPropertyChanged on the owning MyClass DependencyObject. The
override refers to _myList , which has not been initialized yet.

One way to avoid these issues is to make sure that callbacks use only other dependency
properties, and that each such dependency property has an established default value as
part of its registered metadata.

Safe Constructor Patterns

To avoid the risks of incomplete initialization if your class is used as a base class, follow
these patterns:

Parameterless constructors calling base initialization

Implement these constructors calling the base default:

public MyClass : SomeBaseClass {

public MyClass() : base() {
// ALL class initialization, including initial defaults for
// possible values that other ctors specify or that callbacks need.
}
}

Non-default (convenience) constructors, not matching any base

signatures

If these constructors use the parameters to set dependency properties in the

initialization, first call your own class parameterless constructor for initialization, and
then use the parameters to set dependency properties. These could either be
dependency properties defined by your class, or dependency properties inherited from
base classes, but in either case use the following pattern:

public MyClass : SomeBaseClass {

public MyClass(object toSetProperty1) : this() {
// Class initialization NOT done by default.
// Then, set properties to values as passed in ctor parameters.
Property1 = toSetProperty1;
}
}

Non-default (convenience) constructors, which do match base

signatures
Instead of calling the base constructor with the same parameterization, again call your
own class' parameterless constructor. Do not call the base initializer; instead you should
call this() . Then reproduce the original constructor behavior by using the passed
parameters as values for setting the relevant properties. Use the original base
constructor documentation for guidance in determining the properties that the
particular parameters are intended to set:

public MyClass : SomeBaseClass {

public MyClass(object toSetProperty1) : this() {
// Class initialization NOT done by default.
// Then, set properties to values as passed in ctor parameters.
Property1 = toSetProperty1;
}
}

Must match all signatures

For cases where the base type has multiple signatures, you must deliberately match all
possible signatures with a constructor implementation of your own that uses the
recommended pattern of calling the class parameterless constructor before setting
further properties.

Setting dependency properties with SetValue

These same patterns apply if you are setting a property that does not have a wrapper
for property setting convenience, and set values with SetValue. Your calls to SetValue
that pass through constructor parameters should also call the class' parameterless
constructor for initialization.

See also
Custom Dependency Properties
Dependency Properties Overview
Dependency Property Security
Collection-Type Dependency Properties
Article • 02/06/2023

This topic provides guidance and suggested patterns for how to implement a
dependency property where the type of the property is a collection type.

Implementing a Collection-Type Dependency

Property
For a dependency property in general, the implementation pattern that you follow is
that you define a CLR property wrapper, where that property is backed by a
DependencyProperty identifier rather than a field or other construct. You follow this
same pattern when you implement a collection-type property. However, a collection-
type property introduces some complexity to the pattern whenever the type that is
contained within the collection is itself a DependencyObject or Freezable derived class.

Initializing the Collection Beyond the Default

Value
When you create a dependency property, you do not specify the property default value
as the initial field value. Instead, you specify the default value through the dependency
property metadata. If your property is a reference type, the default value specified in
dependency property metadata is not a default value per instance; instead it is a default
value that applies to all instances of the type. Therefore you must be careful to not use
the singular static collection defined by the collection property metadata as the working
default value for newly created instances of your type. Instead, you must make sure that
you deliberately set the collection value to a unique (instance) collection as part of your
class constructor logic. Otherwise you will have created an unintentional singleton class.

Consider the following example. The following section of the example shows the
definition for a class Aquarium , which contains a flaw with the default value. The class
defines the collection type dependency property AquariumObjects , which uses the
generic List<T> type with a FrameworkElement type constraint. In the Register(String,
Type, Type, PropertyMetadata) call for the dependency property, the metadata
establishes the default value to be a new generic List<T>.

２ Warning
The following code does not behave correctly.

public class Fish : FrameworkElement { }

public class Aquarium : DependencyObject {
private static readonly DependencyPropertyKey
AquariumContentsPropertyKey =
DependencyProperty.RegisterReadOnly(
"AquariumContents",
typeof(List<FrameworkElement>),
typeof(Aquarium),
new FrameworkPropertyMetadata(new List<FrameworkElement>())
);
public static readonly DependencyProperty AquariumContentsProperty =
AquariumContentsPropertyKey.DependencyProperty;

public List<FrameworkElement> AquariumContents

{
get { return
(List<FrameworkElement>)GetValue(AquariumContentsProperty); }
}

// ...
}

However, if you just left the code as shown, that single list default value is shared for all
instances of Aquarium . If you ran the following test code, which is intended to show how
you would instantiate two separate Aquarium instances and add a single different Fish
to each of them, you would see a surprising result:

Aquarium myAq1 = new Aquarium();

Aquarium myAq2 = new Aquarium();
Fish f1 = new Fish();
Fish f2 = new Fish();
myAq1.AquariumContents.Add(f1);
myAq2.AquariumContents.Add(f2);
MessageBox.Show("aq1 contains " + myAq1.AquariumContents.Count.ToString() +
" things");
MessageBox.Show("aq2 contains " + myAq2.AquariumContents.Count.ToString() +
" things");

Instead of each collection having a count of one, each collection has a count of two! This
is because each Aquarium added its Fish to the default value collection, which resulted
from a single constructor call in the metadata and is therefore shared between all
instances. This situation is almost never what you want.
To correct this problem, you must reset the collection dependency property value to a
unique instance, as part of the class constructor call. Because the property is a read-only
dependency property, you use the SetValue(DependencyPropertyKey, Object) method to
set it, using the DependencyPropertyKey that is only accessible within the class.

public Aquarium() : base()

{
SetValue(AquariumContentsPropertyKey, new List<FrameworkElement>());
}

Now, if you ran that same test code again, you could see more expected results, where
each Aquarium supported its own unique collection.

There would be a slight variation on this pattern if you chose to have your collection
property be read-write. In that case, you could call the public set accessor from the
constructor to do the initialization, which would still be calling the nonkey signature of
SetValue(DependencyProperty, Object) within your set wrapper, using a public
DependencyProperty identifier.

Reporting Binding Value Changes from

Collection Properties
A collection property that is itself a dependency property does not automatically report
changes to its subproperties. If you are creating bindings into a collection, this can
prevent the binding from reporting changes, thus invalidating some data binding
scenarios. However, if you use the collection type FreezableCollection<T> as your
collection type, then subproperty changes to contained elements in the collection are
properly reported, and binding works as expected.

To enable subproperty binding in a dependency object collection, create the collection

property as type FreezableCollection<T>, with a type constraint for that collection to
any DependencyObject derived class.

See also
FreezableCollection<T>
XAML and Custom Classes for WPF
Data Binding Overview
Dependency Properties Overview
Custom Dependency Properties
Dependency Property Metadata
XAML Loading and Dependency
Properties
Article • 02/06/2023

The current WPF implementation of its WPF XAML processor uses property system
methods for dependency properties when loading binary XAML and processing
attributes that are dependency properties. This effectively bypasses the property
wrappers. When you implement custom dependency properties, you must account for
this behavior and should avoid placing any other code in your property wrapper other
than the property system methods GetValue and SetValue.

Prerequisites
This topic assumes that you understand dependency properties both as consumer and
author and have read Dependency Properties Overview and Custom Dependency
Properties. You should also have read XAML in WPF and XAML Syntax In Detail.

The WPF XAML Loader Implementation, and

Performance
For implementation reasons, it is computationally less expensive to identify a property
as a dependency property and access the property system SetValue method to set it,
rather than using the property wrapper and its setter. This is because a XAML processor
must infer the entire object model of the backing code based only on knowing the type
and member relationships that are indicated by the structure of the markup and various
strings.

The type is looked up through a combination of xmlns and assembly attributes, but
identifying the members, determining which could support being set as an attribute,
and resolving what types the property values support would otherwise require extensive
reflection using PropertyInfo. Because dependency properties on a given type are
accessible as a storage table through the property system, the WPF implementation of
its XAML processor uses this table and infers that any given property ABC can be more
efficiently set by calling SetValue on the containing DependencyObject derived type,
using the dependency property identifier ABCProperty.
Implications for Custom Dependency
Properties
Because the current WPF implementation of the XAML processor behavior for property
setting bypasses the wrappers entirely, you should not put any additional logic into the
set definitions of the wrapper for your custom dependency property. If you put such
logic in the set definition, then the logic will not be executed when the property is set in
XAML rather than in code.

Similarly, other aspects of the XAML processor that obtain property values from XAML
processing also use GetValue rather than using the wrapper. Therefore, you should also
avoid any additional implementation in the get definition beyond the GetValue call.

The following example is a recommended dependency property definition with

wrappers, where the property identifier is stored as a public static readonly field, and
the get and set definitions contain no code beyond the necessary property system
methods that define the dependency property backing.

public static readonly DependencyProperty AquariumGraphicProperty =

See also
Dependency Properties Overview
XAML in WPF
Dependency Property Metadata
Collection-Type Dependency Properties
Dependency Property Security
Safe Constructor Patterns for DependencyObjects
Properties How-to Topics
Article • 02/06/2023

In This Section
Implement a Dependency Property
Add an Owner Type for a Dependency Property
Register an Attached Property
Override Metadata for a Dependency Property

Reference
DependencyProperty

PropertyMetadata

FrameworkPropertyMetadata

DependencyObject

Related Sections
Properties
How to: Implement a Dependency
Property
Article • 02/06/2023

This example shows how to back a common language runtime (CLR) property with a
DependencyProperty field, thus defining a dependency property. When you define your
own properties and want them to support many aspects of Windows Presentation
Foundation (WPF) functionality, including styles, data binding, inheritance, animation,
and default values, you should implement them as a dependency property.

Example
The following example first registers a dependency property by calling the Register
method. The name of the identifier field that you use to store the name and
characteristics of the dependency property must be the Name you chose for the
dependency property as part of the Register call, appended by the literal string
Property . For instance, if you register a dependency property with a Name of Location ,
then the identifier field that you define for the dependency property must be named
LocationProperty .

In this example, the name of the dependency property and its CLR accessor is State ; the
identifier field is StateProperty ; the type of the property is Boolean; and the type that
registers the dependency property is MyStateControl .

If you fail to follow this naming pattern, designers might not report your property
correctly, and certain aspects of property system style application might not behave as
expected.

You can also specify default metadata for a dependency property. This example registers
the default value of the State dependency property to be false .

public class MyStateControl : ButtonBase

{
public MyStateControl() : base() { }
public Boolean State
{
get { return (Boolean)this.GetValue(StateProperty); }
set { this.SetValue(StateProperty, value); }
}
public static readonly DependencyProperty StateProperty =
DependencyProperty.Register(
"State", typeof(Boolean), typeof(MyStateControl),new
PropertyMetadata(false));
}

For more information about how and why to implement a dependency property, as
opposed to just backing a CLR property with a private field, see Dependency Properties
Overview.

See also
Dependency Properties Overview
How-to Topics
How to: Add an Owner Type for a
Dependency Property
Article • 02/06/2023

This example shows how to add a class as an owner of a dependency property

registered for a different type. By doing this, the WPF XAML reader and property system
are both able to recognize the class as an additional owner of the property. Adding as
owner optionally allows the adding class to provide type-specific metadata.

In the following example, StateProperty is a property registered by the MyStateControl

class. The class UnrelatedStateControl adds itself as an owner of the StateProperty
using the AddOwner method, specifically using the signature that allows for new
metadata for the dependency property as it exists on the adding type. Notice that you
should provide common language runtime (CLR) accessors for the property similar to
the example shown in the Implement a Dependency Property example, as well as re-
expose the dependency property identifier on the class being added as owner.

Without wrappers, the dependency property would still work from the perspective of
programmatic access using GetValue or SetValue. But you typically want to parallel this
property-system behavior with the CLR property wrappers. The wrappers make it easier
to set the dependency property programmatically, and make it possible to set the
properties as XAML attributes.

To find out how to override default metadata, see Override Metadata for a Dependency
Property.

Example
C#

public class MyStateControl : ButtonBase

public class UnrelatedStateControl : Control

{
public UnrelatedStateControl() { }
public static readonly DependencyProperty StateProperty =
MyStateControl.StateProperty.AddOwner(typeof(UnrelatedStateControl), new
PropertyMetadata(true));
public Boolean State
{
get { return (Boolean)this.GetValue(StateProperty); }
set { this.SetValue(StateProperty, value); }
}
}

See also
Custom Dependency Properties
Dependency Properties Overview
How to: Register an Attached Property
Article • 08/10/2023

This example shows how to register an attached property and provide public accessors
so that you can use the property in both XAML and code. Attached properties are a
syntax concept defined by XAML. Most attached properties for WPF types are also
implemented as dependency properties. You can use dependency properties on any
DependencyObject types.

Example
The following example shows how to register an attached property as a dependency
property, by using the RegisterAttached method. The provider class has the option of
providing default metadata for the property that is applicable when the property is used
on another class, unless that class overrides the metadata. In this example, the default
value of the IsBubbleSource property is set to false .

The provider class for an attached property (even if it is not registered as a dependency
property) must provide static get and set accessors that follow the naming convention
Set [AttachedPropertyName] and Get [AttachedPropertyName]. These accessors are

required so that the acting XAML reader can recognize the property as an attribute in
XAML and resolve the appropriate types.

public static readonly DependencyProperty IsBubbleSourceProperty =

See also
DependencyProperty
Dependency Properties Overview
Custom Dependency Properties
How-to Topics
How to: Override Metadata for a
Dependency Property
Article • 06/02/2023

This example shows how to override default dependency property metadata that comes
from an inherited class, by calling the OverrideMetadata method and providing type-
specific metadata.

Example
By defining its PropertyMetadata, a class can define the dependency property's
behaviors, such as its default value and property system callbacks. Many dependency
property classes already have default metadata established as part of their registration
process. This includes the dependency properties that are part of the WPF API. A class
that inherits the dependency property through its class inheritance can override the
original metadata so that the characteristics of the property that can be altered through
metadata will match any subclass-specific requirements.

Overriding metadata on a dependency property must be done prior to that property

being placed in use by the property system (this equates to the time that specific
instances of objects that register the property are instantiated). Calls to
OverrideMetadata must be performed within the static constructors of the type that
provides itself as the forType parameter of OverrideMetadata. If you attempt to change
metadata once instances of the owner type exist, this will not raise exceptions, but will
result in inconsistent behaviors in the property system. Also, metadata can only be
overridden once per type. Subsequent attempts to override metadata on the same type
will raise an exception.

In the following example, the custom class MyAdvancedStateControl overrides the

metadata provided for StateProperty by MyStateControl with new property metadata.
For instance, the default value of the StateProperty is now true when the property is
queried on a newly constructed MyAdvancedStateControl instance.

public class MyStateControl : ButtonBase

public class MyAdvancedStateControl : MyStateControl

{
public MyAdvancedStateControl() : base() { }
static MyAdvancedStateControl()
{

MyStateControl.StateProperty.OverrideMetadata(typeof(MyAdvancedStateControl)
, new PropertyMetadata(true));
}
}

See also
DependencyProperty
Dependency Properties Overview
Custom Dependency Properties
How-to Topics
Events (WPF)
Article • 02/06/2023

Windows Presentation Foundation (WPF) introduces routed events that can invoke
handlers that exist on various listeners in the element tree of an application.

In This Section
Routed Events Overview
Attached Events Overview
Object Lifetime Events
Marking Routed Events as Handled, and Class Handling
Preview Events
Property Change Events
Visual Basic and WPF Event Handling
Weak Event Patterns
How-to Topics

Reference
RoutedEvent

EventManager

RoutingStrategy

Related Sections
WPF Architecture
XAML in WPF
Base Elements
Element Tree and Serialization
Properties
Input
Resources
Styling and Templating
WPF Content Model
Threading Model
Routed Events Overview
Article • 03/17/2022

This topic describes the concept of routed events in Windows Presentation Foundation
(WPF). The topic defines routed events terminology, describes how routed events are
routed through a tree of elements, summarizes how you handle routed events, and
introduces how to create your own custom routed events.

Prerequisites
This topic assumes that you have basic knowledge of the common language runtime
(CLR) and object-oriented programming, as well as the concept of how the relationships
between WPF elements can be conceptualized as a tree. In order to follow the examples
in this topic, you should also understand WPF applications or pages. For more
information, see Walkthrough: My first WPF desktop application and XAML in WPF.

What Is a Routed Event?

You can think about routed events either from a functional or implementation
perspective. Both definitions are presented here, because some people find one or the
other definition more useful.

Functional definition: A routed event is a type of event that can invoke handlers on
multiple listeners in an element tree, rather than just on the object that raised the event.

Implementation definition: A routed event is a CLR event that is backed by an instance

of the RoutedEvent class and is processed by the Windows Presentation Foundation
(WPF) event system.

A typical WPF application contains many elements. Whether created in code or declared
in XAML, these elements exist in an element tree relationship to each other. The event
route can travel in one of two directions depending on the event definition, but
generally the route travels from the source element and then "bubbles" upward through
the element tree until it reaches the element tree root (typically a page or a window).
This bubbling concept might be familiar to you if you have worked with the DHTML
object model previously.

Consider the following simple element tree:

XAML
<Border Height="50" Width="300" BorderBrush="Gray" BorderThickness="1">
<StackPanel Background="LightGray" Orientation="Horizontal"
Button.Click="CommonClickHandler">
<Button Name="YesButton" Width="Auto" >Yes</Button>
<Button Name="NoButton" Width="Auto" >No</Button>
<Button Name="CancelButton" Width="Auto" >Cancel</Button>
</StackPanel>
</Border>

This element tree produces something like the following:

In this simplified element tree, the source of a Click event is one of the Button elements,
and whichever Button was clicked is the first element that has the opportunity to handle
the event. But if no handler attached to the Button acts on the event, then the event will
bubble upwards to the Button parent in the element tree, which is the StackPanel.
Potentially, the event bubbles to Border, and then beyond to the page root of the
element tree (not shown).

In other words, the event route for this Click event is:

Button-->StackPanel-->Border-->...

Top-level Scenarios for Routed Events

The following is a brief summary of the scenarios that motivated the routed event
concept, and why a typical CLR event was not adequate for these scenarios:

Control composition and encapsulation: Various controls in WPF have a rich content
model. For example, you can place an image inside of a Button, which effectively
extends the visual tree of the button. However, the added image must not break the hit-
testing behavior that causes a button to respond to a Click of its content, even if the
user clicks on pixels that are technically part of the image.

Singular handler attachment points: In Windows Forms, you would have to attach the
same handler multiple times to process events that could be raised from multiple
elements. Routed events enable you to attach that handler only once, as was shown in
the previous example, and use handler logic to determine where the event came from if
necessary. For instance, this might be the handler for the previously shown XAML:

C#
private void CommonClickHandler(object sender, RoutedEventArgs e)
{
FrameworkElement feSource = e.Source as FrameworkElement;
switch (feSource.Name)
{
case "YesButton":
// do something here ...
break;
case "NoButton":
// do something ...
break;
case "CancelButton":
// do something ...
break;
}
e.Handled=true;
}

Class handling: Routed events permit a static handler that is defined by the class. This
class handler has the opportunity to handle an event before any attached instance
handlers can.

Referencing an event without reflection: Certain code and markup techniques require a
way to identify a specific event. A routed event creates a RoutedEvent field as an
identifier, which provides a robust event identification technique that does not require
static or run-time reflection.

How Routed Events Are Implemented

A routed event is a CLR event that is backed by an instance of the RoutedEvent class and
registered with the WPF event system. The RoutedEvent instance obtained from
registration is typically retained as a public static readonly field member of the class
that registers and thus "owns" the routed event. The connection to the identically
named CLR event (which is sometimes termed the "wrapper" event) is accomplished by
overriding the add and remove implementations for the CLR event. Ordinarily, the add
and remove are left as an implicit default that uses the appropriate language-specific
event syntax for adding and removing handlers of that event. The routed event backing
and connection mechanism is conceptually similar to how a dependency property is a
CLR property that is backed by the DependencyProperty class and registered with the
WPF property system.

The following example shows the declaration for a custom Tap routed event, including
the registration and exposure of the RoutedEvent identifier field and the add and
remove implementations for the Tap CLR event.
C#

public static readonly RoutedEvent TapEvent =

EventManager.RegisterRoutedEvent(
"Tap", RoutingStrategy.Bubble, typeof(RoutedEventHandler),
typeof(MyButtonSimple));

// Provide CLR accessors for the event

public event RoutedEventHandler Tap
{
add { AddHandler(TapEvent, value); }
remove { RemoveHandler(TapEvent, value); }
}

Routed Event Handlers and XAML

To add a handler for an event using XAML, you declare the event name as an attribute
on the element that is an event listener. The value of the attribute is the name of your
implemented handler method, which must exist in the partial class of the code-behind
file.

XAML

<Button Click="b1SetColor">button</Button>

The XAML syntax for adding standard CLR event handlers is the same for adding routed
event handlers, because you are really adding handlers to the CLR event wrapper, which
has a routed event implementation underneath. For more information about adding
event handlers in XAML, see XAML in WPF.

Routing Strategies
Routed events use one of three routing strategies:

Bubbling: Event handlers on the event source are invoked. The routed event then
routes to successive parent elements until reaching the element tree root. Most
routed events use the bubbling routing strategy. Bubbling routed events are
generally used to report input or state changes from distinct controls or other UI
elements.

Direct: Only the source element itself is given the opportunity to invoke handlers
in response. This is analogous to the "routing" that Windows Forms uses for
events. However, unlike a standard CLR event, direct routed events support class
handling (class handling is explained in an upcoming section) and can be used by
EventSetter and EventTrigger.

Tunneling: Initially, event handlers at the element tree root are invoked. The routed
event then travels a route through successive child elements along the route,
towards the node element that is the routed event source (the element that raised
the routed event). Tunneling routed events are often used or handled as part of
the compositing for a control, such that events from composite parts can be
deliberately suppressed or replaced by events that are specific to the complete
control. Input events provided in WPF often come implemented as a
tunneling/bubbling pair. Tunneling events are also sometimes referred to as
Preview events, because of a naming convention that is used for the pairs.

Why Use Routed Events?

As an application developer, you do not always need to know or care that the event you
are handling is implemented as a routed event. Routed events have special behavior,
but that behavior is largely invisible if you are handling an event on the element where it
is raised.

Where routed events become powerful is if you use any of the suggested scenarios:
defining common handlers at a common root, compositing your own control, or
defining your own custom control class.

Routed event listeners and routed event sources do not need to share a common event
in their hierarchy. Any UIElement or ContentElement can be an event listener for any
routed event. Therefore, you can use the full set of routed events available throughout
the working API set as a conceptual "interface" whereby disparate elements in the
application can exchange event information. This "interface" concept for routed events
is particularly applicable for input events.

Routed events can also be used to communicate through the element tree, because the
event data for the event is perpetuated to each element in the route. One element could
change something in the event data, and that change would be available to the next
element in the route.

Other than the routing aspect, there are two other reasons that any given WPF event
might be implemented as a routed event instead of a standard CLR event. If you are
implementing your own events, you might also consider these principles:

Certain WPF styling and templating features such as EventSetter and EventTrigger
require the referenced event to be a routed event. This is the event identifier
scenario mentioned earlier.

Routed events support a class handling mechanism whereby the class can specify
static methods that have the opportunity to handle routed events before any
registered instance handlers can access them. This is very useful in control design,
because your class can enforce event-driven class behaviors that cannot be
accidentally suppressed by handling an event on an instance.

Each of the above considerations is discussed in a separate section of this topic.

Adding and Implementing an Event Handler for

a Routed Event
To add an event handler in XAML, you simply add the event name to an element as an
attribute and set the attribute value as the name of the event handler that implements
an appropriate delegate, as in the following example.

XAML

<Button Click="b1SetColor">button</Button>

b1SetColor is the name of the implemented handler that contains the code that handles
the Click event. b1SetColor must have the same signature as the RoutedEventHandler
delegate, which is the event handler delegate for the Click event. The first parameter of
all routed event handler delegates specifies the element to which the event handler is
added, and the second parameter specifies the data for the event.

void b1SetColor(object sender, RoutedEventArgs args)

{
//logic to handle the Click event
}

RoutedEventHandler is the basic routed event handler delegate. For routed events that
are specialized for certain controls or scenarios, the delegates to use for the routed
event handlers also might become more specialized, so that they can transmit
specialized event data. For instance, in a common input scenario, you might handle a
DragEnter routed event. Your handler should implement the DragEventHandler
delegate. By using the most specific delegate, you can process the DragEventArgs in the
handler and read the Data property, which contains the clipboard payload of the drag
operation.
For a complete example of how to add an event handler to an element using XAML, see
Handle a Routed Event.

Adding a handler for a routed event in an application that is created in code is

straightforward. Routed event handlers can always be added through a helper method
AddHandler (which is the same method that the existing backing calls for add .)
However, existing WPF routed events generally have backing implementations of add
and remove logic that allow the handlers for routed events to be added by a language-
specific event syntax, which is more intuitive syntax than the helper method. The
following is an example usage of the helper method:

void MakeButton()
{
Button b2 = new Button();
b2.AddHandler(Button.ClickEvent, new RoutedEventHandler(Onb2Click));
}
void Onb2Click(object sender, RoutedEventArgs e)
{
//logic to handle the Click event
}

The next example shows the C# operator syntax (Visual Basic has slightly different
operator syntax because of its handling of dereferencing):

void MakeButton2()
{
Button b2 = new Button();
b2.Click += new RoutedEventHandler(Onb2Click2);
}
void Onb2Click2(object sender, RoutedEventArgs e)
{
//logic to handle the Click event
}

For an example of how to add an event handler in code, see Add an Event Handler
Using Code.

If you are using Visual Basic, you can also use the Handles keyword to add handlers as
part of the handler declarations. For more information, see Visual Basic and WPF Event
Handling.
The Concept of Handled
All routed events share a common event data base class, RoutedEventArgs.
RoutedEventArgs defines the Handled property, which takes a Boolean value. The
purpose of the Handled property is to enable any event handler along the route to mark
the routed event as handled, by setting the value of Handled to true . After being
processed by the handler at one element along the route, the shared event data is again
reported to each listener along the route.

The value of Handled affects how a routed event is reported or processed as it travels
further along the route. If Handled is true in the event data for a routed event, then
handlers that listen for that routed event on other elements are generally no longer
invoked for that particular event instance. This is true both for handlers attached in
XAML and for handlers added by language-specific event handler attachment syntaxes
such as += or Handles . For most common handler scenarios, marking an event as
handled by setting Handled to true will "stop" routing for either a tunneling route or a
bubbling route, and also for any event that is handled at a point in the route by a class
handler.

However, there is a "handledEventsToo" mechanism whereby listeners can still run

handlers in response to routed events where Handled is true in the event data. In other
words, the event route is not truly stopped by marking the event data as handled. You
can only use the handledEventsToo mechanism in code, or in an EventSetter:

In code, instead of using a language-specific event syntax that works for general
CLR events, call the WPF method AddHandler(RoutedEvent, Delegate, Boolean) to
add your handler. Specify the value of handledEventsToo as true .

In an EventSetter, set the HandledEventsToo attribute to be true .

In addition to the behavior that Handled state produces in routed events, the concept of
Handled has implications for how you should design your application and write the
event handler code. You can conceptualize Handled as being a simple protocol that is
exposed by routed events. Exactly how you use this protocol is up to you, but the
conceptual design for how the value of Handled is intended to be used is as follows:

If a routed event is marked as handled, then it does not need to be handled again
by other elements along that route.

If a routed event is not marked as handled, then other listeners that were earlier
along the route have chosen either not to register a handler, or the handlers that
were registered chose not to manipulate the event data and set Handled to true .
(Or, it is of course possible that the current listener is the first point in the route.)
Handlers on the current listener now have three possible courses of action:

Take no action at all; the event remains unhandled, and the event routes to the
next listener.

Execute code in response to the event, but make the determination that the
action taken was not substantial enough to warrant marking the event as
handled. The event routes to the next listener.

Execute code in response to the event. Mark the event as handled in the event
data passed to the handler, because the action taken was deemed substantial
enough to warrant marking as handled. The event still routes to the next
listener, but with Handled= true in its event data, so only handledEventsToo
listeners have the opportunity to invoke further handlers.

This conceptual design is reinforced by the routing behavior mentioned earlier: it is

more difficult (although still possible in code or styles) to attach handlers for routed
events that are invoked even if a previous handler along the route has already set
Handled to true .

For more information about Handled, class handling of routed events, and
recommendations about when it is appropriate to mark a routed event as Handled, see
Marking Routed Events as Handled, and Class Handling.

In applications, it is quite common to just handle a bubbling routed event on the object
that raised it, and not be concerned with the event's routing characteristics at all.
However, it is still a good practice to mark the routed event as handled in the event
data, to prevent unanticipated side effects just in case an element that is further up the
element tree also has a handler attached for that same routed event.

Class Handlers
If you are defining a class that derives in some way from DependencyObject, you can
also define and attach a class handler for a routed event that is a declared or inherited
event member of your class. Class handlers are invoked before any instance listener
handlers that are attached to an instance of that class, whenever a routed event reaches
an element instance in its route.

Some WPF controls have inherent class handling for certain routed events. This might
give the outward appearance that the routed event is not ever raised, but in reality it is
being class handled, and the routed event can potentially still be handled by your
instance handlers if you use certain techniques. Also, many base classes and controls
expose virtual methods that can be used to override class handling behavior. For more
information both on how to work around undesired class handling and on defining your
own class handling in a custom class, see Marking Routed Events as Handled, and Class
Handling.

Attached Events in WPF

The XAML language also defines a special type of event called an attached event. An
attached event enables you to add a handler for a particular event to an arbitrary
element. The element handling the event need not define or inherit the attached event,
and neither the object potentially raising the event nor the destination handling
instance must define or otherwise "own" that event as a class member.

The WPF input system uses attached events extensively. However, nearly all of these
attached events are forwarded through base elements. The input events then appear as
equivalent non-attached routed events that are members of the base element class. For
instance, the underlying attached event Mouse.MouseDown can more easily be handled
on any given UIElement by using MouseDown on that UIElement rather than dealing
with attached event syntax either in XAML or code.

For more information about attached events in WPF, see Attached Events Overview.

Qualified Event Names in XAML

Another syntax usage that resembles typename.eventname attached event syntax but is
not strictly speaking an attached event usage is when you attach handlers for routed
events that are raised by child elements. You attach the handlers to a common parent,
to take advantage of event routing, even though the common parent might not have
the relevant routed event as a member. Consider this example again:

XAML

<Border Height="50" Width="300" BorderBrush="Gray" BorderThickness="1">

<StackPanel Background="LightGray" Orientation="Horizontal"
Button.Click="CommonClickHandler">
<Button Name="YesButton" Width="Auto" >Yes</Button>
<Button Name="NoButton" Width="Auto" >No</Button>
<Button Name="CancelButton" Width="Auto" >Cancel</Button>
</StackPanel>
</Border>

Here, the parent element listener where the handler is added is a StackPanel. However, it
is adding a handler for a routed event that was declared and will be raised by the Button
class (ButtonBase actually, but available to Button through inheritance). Button "owns"
the event, but the routed event system permits handlers for any routed event to be
attached to any UIElement or ContentElement instance listener that could otherwise
attach listeners for a common language runtime (CLR) event. The default xmlns
namespace for these qualified event attribute names is typically the default WPF xmlns
namespace, but you can also specify prefixed namespaces for custom routed events. For
more information about xmlns, see XAML Namespaces and Namespace Mapping for
WPF XAML.

WPF Input Events

One frequent application of routed events within the WPF platform is for input events.
In WPF, tunneling routed events names are prefixed with the word "Preview" by
convention. Input events often come in pairs, with one being the bubbling event and
the other being the tunneling event. For example, the KeyDown event and the
PreviewKeyDown event have the same signature, with the former being the bubbling
input event and the latter being the tunneling input event. Occasionally, input events
only have a bubbling version, or perhaps only a direct routed version. In the
documentation, routed event topics cross-reference similar routed events with
alternative routing strategies if such routed events exist, and sections in the managed
reference pages clarify the routing strategy of each routed event.

WPF input events that come in pairs are implemented so that a single user action from
input, such as a mouse button press, will raise both routed events of the pair in
sequence. First, the tunneling event is raised and travels its route. Then the bubbling
event is raised and travels its route. The two events literally share the same event data
instance, because the RaiseEvent method call in the implementing class that raises the
bubbling event listens for the event data from the tunneling event and reuses it in the
new raised event. Listeners with handlers for the tunneling event have the first
opportunity to mark the routed event handled (class handlers first, then instance
handlers). If an element along the tunneling route marked the routed event as handled,
the already-handled event data is sent on for the bubbling event, and typical handlers
attached for the equivalent bubbling input events will not be invoked. To outward
appearances it will be as if the handled bubbling event has not even been raised. This
handling behavior is useful for control compositing, where you might want all hit-test
based input events or focus-based input events to be reported by your final control,
rather than its composite parts. The final control element is closer to the root in the
compositing, and therefore has the opportunity to class handle the tunneling event first
and perhaps to "replace" that routed event with a more control-specific event, as part of
the code that backs the control class.
As an illustration of how input event processing works, consider the following input
event example. In the following tree illustration, leaf element #2 is the source of both a
PreviewMouseDown and then a MouseDown event:

The order of event processing is as follows:

1. PreviewMouseDown (tunnel) on root element.

2. PreviewMouseDown (tunnel) on intermediate element #1.

3. PreviewMouseDown (tunnel) on source element #2.

4. MouseDown (bubble) on source element #2.

5. MouseDown (bubble) on intermediate element #1.

6. MouseDown (bubble) on root element.

A routed event handler delegate provides references to two objects: the object that
raised the event and the object where the handler was invoked. The object where the
handler was invoked is the object reported by the sender parameter. The object where
the event was first raised is reported by the Source property in the event data. A routed
event can still be raised and handled by the same object, in which case sender and
Source are identical (this is the case with Steps 3 and 4 in the event processing example
list).

Because of tunneling and bubbling, parent elements receive input events where the
Source is one of their child elements. When it is important to know what the source
element is, you can identify the source element by accessing the Source property.

Usually, once the input event is marked Handled, further handlers are not invoked.
Typically, you should mark input events as handled as soon as a handler is invoked that
addresses your application-specific logical handling of the meaning of the input event.

The exception to this general statement about Handled state is that input event
handlers that are registered to deliberately ignore Handled state of the event data
would still be invoked along either route. For more information, see Preview Events or
Marking Routed Events as Handled, and Class Handling.

The shared event data model between tunneling and bubbling events, and the
sequential raising of first tunneling then bubbling events, is not a concept that is
generally true for all routed events. That behavior is specifically implemented by how
WPF input devices choose to raise and connect the input event pairs. Implementing
your own input events is an advanced scenario, but you might choose to follow that
model for your own input events also.

Certain classes choose to class-handle certain input events, usually with the intent of
redefining what a particular user-driven input event means within that control and
raising a new event. For more information, see Marking Routed Events as Handled, and
Class Handling.

For more information on input and how input and events interact in typical application
scenarios, see Input Overview.

EventSetters and EventTriggers

In styles, you can include some pre-declared XAML event handling syntax in the markup
by using an EventSetter. When the style is applied, the referenced handler is added to
the styled instance. You can declare an EventSetter only for a routed event. The
following is an example. Note that the b1SetColor method referenced here is in a code-
behind file.

XAML

<StackPanel
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="SDKSample.EventOvw2"
Name="dpanel2"
Initialized="PrimeHandledToo"
>
<StackPanel.Resources>
<Style TargetType="{x:Type Button}">
<EventSetter Event="Click" Handler="b1SetColor"/>
</Style>
</StackPanel.Resources>
<Button>Click me</Button>
<Button Name="ThisButton" Click="HandleThis">
Raise event, handle it, use handled=true handler to get it anyway.
</Button>
</StackPanel>

The advantage gained here is that the style is likely to contain a great deal of other
information that could apply to any button in your application, and having the
EventSetter be part of that style promotes code reuse even at the markup level. Also, an
EventSetter abstracts method names for handlers one step further away from the
general application and page markup.

Another specialized syntax that combines the routed event and animation features of
WPF is an EventTrigger. As with EventSetter, only routed events may be used for an
EventTrigger. Typically, an EventTrigger is declared as part of a style, but an EventTrigger
can also be declared on page-level elements as part of the Triggers collection, or in a
ControlTemplate. An EventTrigger enables you to specify a Storyboard that runs
whenever a routed event reaches an element in its route that declares an EventTrigger
for that event. The advantage of an EventTrigger over just handling the event and
c