Content update - Dependency properties overview (user story 1878471) (#1160)

* Update article and code projects * Further edits * Fix links * Relocate article & snippets to wpf/properties folder * add toc and redirects * Add acrolinx comment and make a minor edit. * minor Co-authored-by: Andy De George (adegeo) <[email protected]>
2026-09-04 00:56:03 +02:00 · 2021-09-27 13:53:44 -07:00
parent bdd178c010
commit 57b6ca1593
22 changed files with 851 additions and 0 deletions
@@ -472,6 +472,14 @@
        {
            "source_path": "dotnet-desktop-guide/framework/wpf/documents/how-to-print-xps-files.md",
            "redirect_url": "/dotnet/desktop/wpf/advanced/how-to-programmatically-print-xps-files?view=netframeworkdesktop-4.8"
+        },
+        {
+            "source_path": "dotnet-desktop-guide/net/wpf/advanced/dependency-properties-overview.md",
+            "redirect_url": "/dotnet/desktop/wpf/properties/dependency-properties-overview?view=netdesktop-5.0"
+        },
+        {
+            "source_path": "dotnet-desktop-guide/framework/wpf/properties/dependency-properties-overview.md",
+            "redirect_url": "/dotnet/desktop/wpf/advanced/dependency-properties-overview?view=netframeworkdesktop-4.8"
        }
    ]
 }
@@ -0,0 +1,230 @@
+---
+title: "Dependency properties overview"
+description: Learn about the WPF property system and the capabilities of a dependency property, which is a property that's backed by the WPF property system.
+ms.date: "09/23/2021"
+ms.topic: overview
+dev_langs: 
+  - "csharp"
+  - "vb"
+helpviewer_keywords: 
+  - "properties [WPF], attached"
+  - "properties [WPF], overview"
+  - "styles [WPF]"
+  - "attached properties [WPF]"
+  - "data binding [WPF]"
+  - "dependency properties [WPF]"
+  - "resources [WPF], references to"
+---
+<!-- The acrolinx score was 94 on 09/23/2021-->
+
+# Dependency properties overview (WPF .NET)
+
+Windows Presentation Foundation (WPF) provides a set of services that can be used to extend the functionality of a type's [property](/dotnet/standard/base-types/common-type-system#properties). Collectively, these services are referred to as the WPF property system. A property that's 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, including 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.
+
+[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)]
+
+## Prerequisites
+
+This article assumes basic knowledge of the .NET type system and object-oriented programming. To follow the examples in this article, it helps to understand XAML and know how to write WPF applications. For more information, see [Walkthrough: My first WPF desktop application](/dotnet/desktop/wpf/get-started/create-app-visual-studio).
+
+## Dependency properties and CLR properties
+
+WPF properties are typically exposed as standard .NET [properties](/dotnet/standard/base-types/common-type-system#properties). You might interact with these properties at a basic level and never know that they're implemented as a dependency property. However, familiarity with some or all of the features of the WPF property system, will help you take advantage of those 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, such as:
+
+- 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.
+- Values known through parent-child relationships with other elements in the element tree.
+
+Also, a dependency property can provide:
+
+- Self-contained validation.
+- Default values.
+- Callbacks that monitor changes to other properties.
+- A system that can coerce property values based on runtime information.
+
+Derived classes can change some characteristics of an existing property by overriding the metadata of a dependency property, rather than overriding the actual implementation of existing properties or creating new properties.
+
+In the SDK reference, you can identify a dependency property by the presence of a Dependency Property Information section on the managed reference page for that property. The Dependency Property Information section includes a link to the <xref:System.Windows.DependencyProperty> identifier field for that dependency property. It also includes the list of metadata options 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 to the standard pattern of backing a property with a private field. The name of this type is <xref:System.Windows.DependencyProperty>. The other important type that defines the WPF property system is <xref:System.Windows.DependencyObject>, which defines the base class that can register and own a dependency property.
+
+Here's some commonly used terminology:
+
+- **Dependency property**, which is a property that's backed by a <xref:System.Windows.DependencyProperty>.
+
+- **Dependency property identifier**, which is a `DependencyProperty` instance obtained as a return value when registering a dependency property, and then stored as a static member of a class. Many of the APIs that interact with the WPF property system use the dependency property identifier as a parameter.
+
+- **CLR "wrapper"**, which is the `get` and `set` implementations for the property. These implementations incorporate the dependency property identifier by using it in the <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> calls. In this way, the WPF property system provides the backing for the property.
+
+The following example defines the `IsSpinning` dependency property to show the relationship of the `DependencyProperty` identifier to the property that it backs.
+
+:::code language="csharp" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml.cs" id="DefineDependencyProperty":::
+:::code language="vb" source="./snippets/dependency-properties-overview/vb/MainWindow.xaml.vb" id="DefineDependencyProperty":::
+
+The naming convention of the property and its backing <xref:System.Windows.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](/dotnet/desktop/wpf/advanced/custom-dependency-properties?view=netframeworkdesktop-4.8&preserve-view=true).
+
+## Setting property values
+
+You can set properties either in code or in XAML.
+
+### Setting property values in XAML
+
+The following XAML example sets the background color of a button to red. The string value for the XAML attribute is type-converted by the WPF XAML parser into a WPF type. In the generated code, the WPF type is a <xref:System.Windows.Media.Color>, by way of a <xref:System.Windows.Media.SolidColorBrush>.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="BasicPropertySyntax":::
+
+XAML supports several syntax forms for setting properties. Which syntax to use for a particular property depends on the value type that a property uses, and other factors, such as the presence of a type converter. For more information on XAML syntax for setting properties, see [XAML in WPF](/dotnet/desktop/wpf/xaml/) and [XAML syntax In detail](/dotnet/desktop/wpf/advanced/xaml-syntax-in-detail?view=netframeworkdesktop-4.8&preserve-view=true).
+
+The following XAML example shows another button background that uses property element syntax instead of attribute syntax. Rather than setting a simple solid color, the XAML sets the button `Background` property to an image. An element represents that image, and an attribute of the nested element specifies the source of the image.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="PropertyElementSyntax":::
+
+### Setting properties in code
+
+Setting dependency property values in code is typically just a call to the `set` implementation exposed by the CLR "wrapper":
+
+:::code language="csharp" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml.cs" id="ProceduralPropertySet":::
+:::code language="vb" source="./snippets/dependency-properties-overview/vb/MainWindow.xaml.vb" id="ProceduralPropertySet":::
+
+Getting a property value is essentially a call to the `get` "wrapper" implementation:
+
+:::code language="csharp" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml.cs" id="ProceduralPropertyGet":::
+:::code language="vb" source="./snippets/dependency-properties-overview/vb/MainWindow.xaml.vb" id="ProceduralPropertyGet":::
+
+You can also call the property system APIs <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> directly. Calling the APIs directly is appropriate for some scenarios, but usually not when you're using existing properties. Typically, wrappers are more convenient, and provide better exposure of the property for developer tools.
+
+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](/dotnet/desktop/wpf/advanced/code-behind-and-xaml-in-wpf?view=netframeworkdesktop-4.8&preserve-view=true).
+
+## Property functionality provided by a dependency property
+
+Unlike a property that's backed by a field, a dependency property extends the functionality of a property. Often, the added functionality represents or supports one of these features:
+
+- [Resources](#resources)
+
+- [Data binding](#data-binding)
+
+- [Styles](#styles)
+
+- [Animations](#animations)
+
+- [Metadata overrides](#metadata-overrides)
+
+- [Property value inheritance](#property-value-inheritance)
+
+- [WPF Designer integration](#wpf-designer-integration)
+
+### Resources
+
+You can set a dependency property value by referencing a resource. Resources are typically specified as the `Resources` property value of a page root element, or of the application, since these locations offer convenient access to the resource. In this example, we define a <xref:System.Windows.Media.SolidColorBrush> resource:
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="Resource":::
+
+Now that the resource is defined, we can reference the resource to provide a value for the `Background` property:
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="ResourceReference":::
+
+In WPF XAML, you can use either a static or dynamic resource reference. This particular resource is referenced as a [DynamicResource](/dotnet/desktop/wpf/advanced/dynamicresource-markup-extension?view=netframeworkdesktop-4.8&preserve-view=true). A dynamic resource reference can only be used to set a dependency property, so it's specifically the dynamic resource reference usage that's enabled by the WPF property system. For more information, see [XAML resources](/dotnet/desktop/wpf/systems/xaml-resources-overview).
+
+> [!NOTE]
+> Resources are treated as a local value, which means that if you set another local value, you'll eliminate the resource reference. For more information, see [Dependency property value precedence](/dotnet/desktop/wpf/advanced/dependency-property-value-precedence?view=netframeworkdesktop-4.8&preserve-view=true).
+
+### 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 <xref:System.Windows.Data.Binding> object in code. With data binding, determination of the final property value is deferred until run time, at which time the value is obtained from a data source.
+
+The following example sets the <xref:System.Windows.Controls.ContentControl.Content%2A> property for a <xref:System.Windows.Controls.Button>, by using a binding declared in XAML. The binding uses an inherited data context and an <xref:System.Windows.Data.XmlDataProvider> data source (not shown). The binding itself specifies the source property within the data source by <xref:System.Windows.Data.Binding.XPath%2A>.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="BasicInlineBinding":::
+
+> [!NOTE]
+> Bindings are treated as a local value, which means that if you set another local value, you'll eliminate the binding. For details, see [Dependency property value precedence](/dotnet/desktop/wpf/advanced/dependency-property-value-precedence?view=netframeworkdesktop-4.8&preserve-view=true).
+
+Dependency properties, or the <xref:System.Windows.DependencyObject> class, don't natively support <xref:System.ComponentModel.INotifyPropertyChanged> for notification of changes in `DependencyObject` source property value for data binding operations. For more about how to create properties for use in data binding that can report changes to a data binding target, see [Data binding overview](/dotnet/desktop/wpf/data/data-binding-overview?view=netframeworkdesktop-4.8&preserve-view=true).
+
+### Styles
+
+Styles and templates are compelling reasons to use dependency properties. Styles are particularly useful for setting properties that define the application UI. Styles are typically defined as resources in XAML. Styles interact with the property system because they typically contain "setters" for particular properties, and "triggers" that change a property value based on the runtime value for another property.
+
+The following example creates a simple style, which would be defined inside a <xref:System.Windows.FrameworkElement.Resources%2A> dictionary (not shown). Then that style is applied directly to the <xref:System.Windows.FrameworkElement.Style%2A> property for a <xref:System.Windows.Controls.Button>. The setter within the style sets the <xref:System.Windows.Controls.Control.Background%2A> property for a styled `Button` to green.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="SimpleStyleDefinition":::
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="SimpleStyle":::
+
+For more information, see [Styling and templating](/dotnet/desktop/wpf/controls/styles-templates-overview?view=netdesktop-5.0).
+
+### Animations
+
+Dependency properties can be animated. When an applied animation runs, the animated value has higher precedence than any other property value, including a local value.
+
+The following example animates the <xref:System.Windows.Controls.Control.Background%2A> property of a <xref:System.Windows.Controls.Button>. Technically, the property element syntax sets a blank <xref:System.Windows.Media.SolidColorBrush> as the `Background`, and the <xref:System.Windows.Media.SolidColorBrush.Color%2A> property of the `SolidColorBrush` is animated.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="Animate":::
+
+For more about animating properties, see [Animation overview](/dotnet/desktop/wpf/graphics-multimedia/animation-overview?view=netframeworkdesktop-4.8&preserve-view=true) and [Storyboards overview](/dotnet/desktop/wpf/graphics-multimedia/storyboards-overview?view=netframeworkdesktop-4.8&preserve-view=true).
+
+### Metadata overrides
+
+You can change specific behaviors of a dependency property by overriding its metadata when you derive from the class that originally registered the dependency property. Overriding metadata relies on the <xref:System.Windows.DependencyProperty> identifier and doesn't require reimplementing the property. The metadata change is handled natively by the property system. Each class potentially holds individual metadata for all properties inherited from base classes, on a per-type basis.
+
+The following example overrides metadata for a <xref:System.Windows.FrameworkElement.DefaultStyleKey%2A> dependency property. Overriding metadata for this particular dependency property is part of an implementation pattern for creating controls that can use default styles from themes.
+
+:::code language="csharp" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml.cs" id="overridemetadata":::
+:::code language="vb" source="./snippets/dependency-properties-overview/vb/MainWindow.xaml.vb" id="overridemetadata":::
+
+For more about overriding or accessing metadata for dependency properties, see [Override metadata for a dependency property](/dotnet/desktop/wpf/advanced/how-to-override-metadata-for-a-dependency-property?view=netframeworkdesktop-4.8&preserve-view=true).
+
+### 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 isn't globally enabled for all dependency properties, because the calculation time for inheritance affects performance. Property value inheritance is typically only enabled in scenarios that suggest applicability. You can check 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 that includes the <xref:System.Windows.FrameworkElement.DataContext%2A> property to specify the source of the binding. So, bindings in child objects don't need to specify the source and can use the inherited value from `DataContext` in the parent <xref:System.Windows.Controls.StackPanel> object. Or, a child object can directly specify its own `DataContext` or a <xref:System.Windows.Data.Binding.Source%2A> in the <xref:System.Windows.Data.Binding>, and not use the inherited value.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="InheritanceBindingContext":::
+
+For more information, see [Property value inheritance](/dotnet/desktop/wpf/advanced/property-value-inheritance?view=netframeworkdesktop-4.8&preserve-view=true).
+
+### WPF designer integration
+
+Custom controls with properties implemented as dependency properties integrate well with WPF Designer for Visual Studio. One example is the ability to edit direct and attached dependency properties in the **Properties** window. For more information, see [Control authoring overview](/dotnet/desktop/wpf/controls/control-authoring-overview?view=netframeworkdesktop-4.8&preserve-view=true).
+
+## Dependency property value precedence
+
+Any of the property-based inputs within the WPF property system can set the value of a dependency property. [Dependency property value precedence](/dotnet/desktop/wpf/advanced/dependency-property-value-precedence?view=netframeworkdesktop-4.8&preserve-view=true) exists so that the various scenarios for how properties obtain their values interact in a predictable way.
+
+> [!NOTE]
+> The SDK documentation sometimes uses the term "local value" or "locally set value" when discussing dependency properties. A locally set value is a property value that's set directly on an object instance in code, or as an element attribute in XAML.
+
+The next example includes a style that applies to the <xref:System.Windows.Controls.Control.Background%2A> property of any button, but specifies one button with a locally set `Background` property. Technically, that button has its `Background` property set twice, although only one value applies&mdash;the value with the highest precedence. A locally set value has the highest precedence, except for a running animation, which doesn't exist here. So, the first button uses the locally set value for the `Background` property, instead of the style setter value. The second button has no local value, or other value with higher precedence than a style setter, and so uses the style setter value for the `Background` property.
+
+:::code language="xaml" source="./snippets/dependency-properties-overview/csharp/MainWindow.xaml" id="PropertyValuePrecedence":::
+
+### Why does dependency property precedence exist?
+
+Locally set values have precedence over style setter values, which supports local control of element properties. For details, see [Dependency property value precedence](/dotnet/desktop/wpf/advanced/dependency-property-value-precedence?view=netframeworkdesktop-4.8&preserve-view=true).
+
+> [!NOTE]
+> A number of properties defined on WPF elements aren't dependency properties, because dependency properties were typically implemented only when a feature of the WPF property system was required. The features include data binding, styling, animation, default value support, inheritance, attached properties, and invalidation.
+
+## Learning more about dependency properties
+
+- Component developers or application developers might wish to create their own dependency property to add capabilities, such as data binding or styles support, or invalidation and value coercion support. For more information, see [Custom dependency properties](/dotnet/desktop/wpf/advanced/custom-dependency-properties?view=netframeworkdesktop-4.8&preserve-view=true).
+
+- Consider dependency properties to be public properties, accessible or discoverable by any caller with access to an instance. For more information, see [Dependency property security](/dotnet/desktop/wpf/advanced/dependency-property-security?view=netframeworkdesktop-4.8&preserve-view=true).
+
+- An attached property is a type of property that supports a specialized syntax in XAML. An attached property often doesn't have a 1:1 correspondence with a common language runtime property and isn't necessarily a dependency property. The main 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 don't include that property as part of the class members listings. One primary scenario is to enable a child element to inform parent elements how to present them in the UI. For examples, see <xref:System.Windows.Controls.DockPanel.Dock%2A> and <xref:System.Windows.Controls.Canvas.Left%2A>. For more information, see [Attached properties overview](/dotnet/desktop/wpf/advanced/attached-properties-overview?view=netframeworkdesktop-4.8&preserve-view=true).
+
+## See also
+
+- [Custom dependency properties](/dotnet/desktop/wpf/advanced/custom-dependency-properties?view=netframeworkdesktop-4.8&preserve-view=true)
+- [Read-only dependency properties](/dotnet/desktop/wpf/advanced/read-only-dependency-properties?view=netframeworkdesktop-4.8&preserve-view=true)
+- [XAML in WPF](/dotnet/desktop/wpf/xaml/)
+- [WPF architecture](/dotnet/desktop/wpf/advanced/wpf-architecture?view=netframeworkdesktop-4.8&preserve-view=true)
@@ -0,0 +1,9 @@
+<Application x:Class="CodeSampleCsharp.App"
+             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             xmlns:local="clr-namespace:CodeSampleCsharp"
+             StartupUri="MainWindow.xaml">
+    <Application.Resources>
+         
+    </Application.Resources>
+</Application>
@@ -0,0 +1,17 @@
+using System;
+using System.Collections.Generic;
+using System.Configuration;
+using System.Data;
+using System.Linq;
+using System.Threading.Tasks;
+using System.Windows;
+
+namespace CodeSampleCsharp
+{
+    /// <summary>
+    /// Interaction logic for App.xaml
+    /// </summary>
+    public partial class App : Application
+    {
+    }
+}
@@ -0,0 +1,10 @@
+using System.Windows;
+
+[assembly: ThemeInfo(
+    ResourceDictionaryLocation.None, //where theme specific resource dictionaries are located
+                                     //(used if a resource is not found in the page,
+                                     // or application resource dictionaries)
+    ResourceDictionaryLocation.SourceAssembly //where the generic resource dictionary is located
+                                              //(used if a resource is not found in the page,
+                                              // app, or any theme specific resource dictionaries)
+)]
@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net5.0-windows</TargetFramework>
+    <UseWPF>true</UseWPF>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Remove="stripes.jpg" />
+    <None Remove="test.xml" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="stripes.jpg">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+    <Content Include="test.xml">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+
+  <ItemGroup>
+    <Compile Update="Properties\Resources.Designer.cs">
+      <DesignTime>True</DesignTime>
+      <AutoGen>True</AutoGen>
+      <DependentUpon>Resources.resx</DependentUpon>
+    </Compile>
+  </ItemGroup>
+
+  <ItemGroup>
+    <EmbeddedResource Update="Properties\Resources.resx">
+      <Generator>ResXFileCodeGenerator</Generator>
+      <LastGenOutput>Resources.Designer.cs</LastGenOutput>
+    </EmbeddedResource>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,90 @@
+<Window x:Class="CodeSampleCsharp.MainWindow"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d"
+    Title="Dependency Properties" Height="220" Width="300">
+    <Window.Resources>
+        <XmlDataProvider x:Key="TestData" Source="test.xml" XPath="tests"/>
+
+        <!--<SimpleStyleDefinition>-->
+        <Style x:Key="GreenButtonStyle">
+            <Setter Property="Control.Background" Value="Green"/>
+        </Style>
+        <!--</SimpleStyleDefinition>-->
+
+    </Window.Resources>
+    <StackPanel>
+
+        <!--<Resource>-->
+        <StackPanel.Resources>
+            <SolidColorBrush x:Key="MyBrush" Color="Gold"/>
+        </StackPanel.Resources>
+        <!--</Resource>-->
+
+        <!--<BasicPropertySyntax>-->
+        <Button Content="I am red" Background="Red"/>
+        <!--</BasicPropertySyntax>-->
+
+        <!--<PropertyElementSyntax>-->
+        <Button Content="I have an image background">
+            <Button.Background>
+                <ImageBrush ImageSource="stripes.jpg"/>
+            </Button.Background>
+        </Button>
+        <!--</PropertyElementSyntax>-->
+
+        <!--<ResourceReference>-->
+        <Button Background="{DynamicResource MyBrush}" Content="I am gold" />
+        <!--</ResourceReference>-->
+
+        <!--<BasicInlineBinding>-->
+        <Button Content="{Binding Source={StaticResource TestData}, XPath=test[1]/@text}"/>
+        <!--</BasicInlineBinding>-->
+
+        <!--<SimpleStyle>-->
+        <Button Style="{StaticResource GreenButtonStyle}" Content="I am green"/>
+        <!--</SimpleStyle>-->
+
+        <!--<Animate>-->
+        <Button Content="I am animated">
+            <Button.Background>
+                <SolidColorBrush x:Name="AnimBrush"/>
+            </Button.Background>
+            <Button.Triggers>
+                <EventTrigger RoutedEvent="FrameworkElement.Loaded">
+                    <BeginStoryboard>
+                        <Storyboard>
+                            <ColorAnimation
+                                Storyboard.TargetName="AnimBrush" 
+                                Storyboard.TargetProperty="(SolidColorBrush.Color)"
+                                From="Blue" To="White" Duration="0:0:1" 
+                                AutoReverse="True" RepeatBehavior="Forever" />
+                        </Storyboard>
+                    </BeginStoryboard>
+                </EventTrigger>
+            </Button.Triggers>
+        </Button>
+        <!--</Animate>-->
+
+        <!--<InheritanceBindingContext>-->
+        <StackPanel Canvas.Top="50" DataContext="{Binding Source={StaticResource TestData}}">
+            <Button Content="{Binding XPath=test[2]/@text}"/>
+        </StackPanel>
+        <!--</InheritanceBindingContext>-->
+
+        <!--<PropertyValuePrecedence>-->
+        <StackPanel>
+            <StackPanel.Resources>
+                <Style x:Key="{x:Type Button}" TargetType="{x:Type Button}">
+                    <Setter Property="Background" Value="Orange"/>
+                </Style>
+            </StackPanel.Resources>
+            <Button>I am styled orange</Button>
+            <Button Background="Pink">I am locally set to pink (not styled orange)</Button>
+        </StackPanel>
+        <!--</PropertyValuePrecedence>-->
+        
+    </StackPanel>
+</Window>
@@ -0,0 +1,48 @@
+using System.Windows;
+using System.Windows.Controls;
+
+namespace CodeSampleCsharp
+{
+    /// <summary>
+    /// Interaction logic for MainWindow.xaml.
+    /// </summary>
+    public partial class MainWindow : Window
+    {
+        public MainWindow()
+        {
+            InitializeComponent();
+
+            // <ProceduralPropertySet>
+            Button myButton = new();
+            myButton.Width = 200.0;
+            // </ProceduralPropertySet>
+
+            // <ProceduralPropertyGet>
+            double whatWidth = myButton.Width;
+            // </ProceduralPropertyGet>
+        }
+
+        // <DefineDependencyProperty>
+        public static readonly DependencyProperty IsSpinningProperty = DependencyProperty.Register(
+            "IsSpinning", typeof(bool),
+            typeof(MainWindow)
+            );
+
+        public bool IsSpinning
+        {
+            get => (bool)GetValue(IsSpinningProperty);
+            set => SetValue(IsSpinningProperty, value);
+        }
+        // </DefineDependencyProperty>
+    }
+
+    // <OverrideMetadata>
+    public class SpinnerControl : ItemsControl
+    {
+        static SpinnerControl() => DefaultStyleKeyProperty.OverrideMetadata(
+                typeof(SpinnerControl),
+                new FrameworkPropertyMetadata(typeof(SpinnerControl))
+            );
+    }
+    // </OverrideMetadata>
+}
@@ -0,0 +1,63 @@
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This code was generated by a tool.
+//     Runtime Version:4.0.30319.42000
+//
+//     Changes to this file may cause incorrect behavior and will be lost if
+//     the code is regenerated.
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+namespace CodeSampleCsharp.Properties {
+    using System;
+    
+    
+    /// <summary>
+    ///   A strongly-typed resource class, for looking up localized strings, etc.
+    /// </summary>
+    // This class was auto-generated by the StronglyTypedResourceBuilder
+    // class via a tool like ResGen or Visual Studio.
+    // To add or remove a member, edit your .ResX file then rerun ResGen
+    // with the /str option, or rebuild your VS project.
+    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("System.Resources.Tools.StronglyTypedResourceBuilder", "16.0.0.0")]
+    [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
+    [global::System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
+    internal class Resources {
+        
+        private static global::System.Resources.ResourceManager resourceMan;
+        
+        private static global::System.Globalization.CultureInfo resourceCulture;
+        
+        [global::System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")]
+        internal Resources() {
+        }
+        
+        /// <summary>
+        ///   Returns the cached ResourceManager instance used by this class.
+        /// </summary>
+        [global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)]
+        internal static global::System.Resources.ResourceManager ResourceManager {
+            get {
+                if (object.ReferenceEquals(resourceMan, null)) {
+                    global::System.Resources.ResourceManager temp = new global::System.Resources.ResourceManager("CodeSampleCsharp.Properties.Resources", typeof(Resources).Assembly);
+                    resourceMan = temp;
+                }
+                return resourceMan;
+            }
+        }
+        
+        /// <summary>
+        ///   Overrides the current thread's CurrentUICulture property for all
+        ///   resource lookups using this strongly typed resource class.
+        /// </summary>
+        [global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)]
+        internal static global::System.Globalization.CultureInfo Culture {
+            get {
+                return resourceCulture;
+            }
+            set {
+                resourceCulture = value;
+            }
+        }
+    }
+}
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="utf-8"?>
+<root>
+  <!-- 
+    Microsoft ResX Schema 
+    
+    Version 2.0
+    
+    The primary goals of this format is to allow a simple XML format 
+    that is mostly human readable. The generation and parsing of the 
+    various data types are done through the TypeConverter classes 
+    associated with the data types.
+    
+    Example:
+    
+    ... ado.net/XML headers & schema ...
+    <resheader name="resmimetype">text/microsoft-resx</resheader>
+    <resheader name="version">2.0</resheader>
+    <resheader name="reader">System.Resources.ResXResourceReader, System.Windows.Forms, ...</resheader>
+    <resheader name="writer">System.Resources.ResXResourceWriter, System.Windows.Forms, ...</resheader>
+    <data name="Name1"><value>this is my long string</value><comment>this is a comment</comment></data>
+    <data name="Color1" type="System.Drawing.Color, System.Drawing">Blue</data>
+    <data name="Bitmap1" mimetype="application/x-microsoft.net.object.binary.base64">
+        <value>[base64 mime encoded serialized .NET Framework object]</value>
+    </data>
+    <data name="Icon1" type="System.Drawing.Icon, System.Drawing" mimetype="application/x-microsoft.net.object.bytearray.base64">
+        <value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value>
+        <comment>This is a comment</comment>
+    </data>
+                
+    There are any number of "resheader" rows that contain simple 
+    name/value pairs.
+    
+    Each data row contains a name, and value. The row also contains a 
+    type or mimetype. Type corresponds to a .NET class that support 
+    text/value conversion through the TypeConverter architecture. 
+    Classes that don't support this are serialized and stored with the 
+    mimetype set.
+    
+    The mimetype is used for serialized objects, and tells the 
+    ResXResourceReader how to depersist the object. This is currently not 
+    extensible. For a given mimetype the value must be set accordingly:
+    
+    Note - application/x-microsoft.net.object.binary.base64 is the format 
+    that the ResXResourceWriter will generate, however the reader can 
+    read any of the formats listed below.
+    
+    mimetype: application/x-microsoft.net.object.binary.base64
+    value   : The object must be serialized with 
+            : System.Runtime.Serialization.Formatters.Binary.BinaryFormatter
+            : and then encoded with base64 encoding.
+    
+    mimetype: application/x-microsoft.net.object.soap.base64
+    value   : The object must be serialized with 
+            : System.Runtime.Serialization.Formatters.Soap.SoapFormatter
+            : and then encoded with base64 encoding.
+
+    mimetype: application/x-microsoft.net.object.bytearray.base64
+    value   : The object must be serialized into a byte array 
+            : using a System.ComponentModel.TypeConverter
+            : and then encoded with base64 encoding.
+    -->
+  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
+    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
+    <xsd:element name="root" msdata:IsDataSet="true">
+      <xsd:complexType>
+        <xsd:choice maxOccurs="unbounded">
+          <xsd:element name="metadata">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" />
+              </xsd:sequence>
+              <xsd:attribute name="name" use="required" type="xsd:string" />
+              <xsd:attribute name="type" type="xsd:string" />
+              <xsd:attribute name="mimetype" type="xsd:string" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="assembly">
+            <xsd:complexType>
+              <xsd:attribute name="alias" type="xsd:string" />
+              <xsd:attribute name="name" type="xsd:string" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="data">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
+              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
+              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="resheader">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" />
+            </xsd:complexType>
+          </xsd:element>
+        </xsd:choice>
+      </xsd:complexType>
+    </xsd:element>
+  </xsd:schema>
+  <resheader name="resmimetype">
+    <value>text/microsoft-resx</value>
+  </resheader>
+  <resheader name="version">
+    <value>2.0</value>
+  </resheader>
+  <resheader name="reader">
+    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <resheader name="writer">
+    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+</root>
@@ -0,0 +1,4 @@
+<tests>
+    <test text="I have data binding content"/>
+    <test text="I have inherited data binding content"/>
+</tests>
@@ -0,0 +1,9 @@
+<Application x:Class="Application"
+             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             xmlns:local="clr-namespace:CodeSampleVb"
+             StartupUri="MainWindow.xaml">
+    <Application.Resources>
+         
+    </Application.Resources>
+</Application>
@@ -0,0 +1,6 @@
+Class Application
+
+    ' Application-level events, such as Startup, Exit, and DispatcherUnhandledException
+    ' can be handled in this file.
+
+End Class
@@ -0,0 +1,11 @@
+Imports System.Windows
+
+'The ThemeInfo attribute describes where any theme specific and generic resource dictionaries can be found.
+'1st parameter: where theme specific resource dictionaries are located
+'(used if a resource is not found in the page,
+' or application resource dictionaries)
+
+'2nd parameter: where the generic resource dictionary is located
+'(used if a resource is not found in the page,
+'app, and any theme specific resource dictionaries)
+<Assembly: ThemeInfo(ResourceDictionaryLocation.None, ResourceDictionaryLocation.SourceAssembly)>
@@ -0,0 +1,36 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net5.0-windows</TargetFramework>
+    <RootNamespace>CodeSampleVb</RootNamespace>
+    <UseWPF>true</UseWPF>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Remove="stripes.jpg" />
+    <None Remove="test.xml" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="stripes.jpg">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+    <Content Include="test.xml">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+
+  <ItemGroup>
+    <Import Include="System.Windows" />
+    <Import Include="System.Windows.Controls" />
+    <Import Include="System.Windows.Data" />
+    <Import Include="System.Windows.Documents" />
+    <Import Include="System.Windows.Input" />
+    <Import Include="System.Windows.Media" />
+    <Import Include="System.Windows.Media.Imaging" />
+    <Import Include="System.Windows.Navigation" />
+    <Import Include="System.Windows.Shapes" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,90 @@
+<Window x:Class="CodeSampleVb.MainWindow"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d"
+    Title="Dependency Properties" Height="220" Width="300">
+    <Window.Resources>
+        <XmlDataProvider x:Key="TestData" Source="test.xml" XPath="tests"/>
+
+        <!--<SimpleStyleDefinition>-->
+        <Style x:Key="GreenButtonStyle">
+            <Setter Property="Control.Background" Value="Green"/>
+        </Style>
+        <!--</SimpleStyleDefinition>-->
+
+    </Window.Resources>
+    <StackPanel>
+
+        <!--<Resource>-->
+        <StackPanel.Resources>
+            <SolidColorBrush x:Key="MyBrush" Color="Gold"/>
+        </StackPanel.Resources>
+        <!--</Resource>-->
+
+        <!--<BasicPropertySyntax>-->
+        <Button Content="I am red" Background="Red"/>
+        <!--</BasicPropertySyntax>-->
+
+        <!--<PropertyElementSyntax>-->
+        <Button Content="I have an image background">
+            <Button.Background>
+                <ImageBrush ImageSource="stripes.jpg"/>
+            </Button.Background>
+        </Button>
+        <!--</PropertyElementSyntax>-->
+
+        <!--<ResourceReference>-->
+        <Button Background="{DynamicResource MyBrush}" Content="I am gold" />
+        <!--</ResourceReference>-->
+
+        <!--<BasicInlineBinding>-->
+        <Button Content="{Binding Source={StaticResource TestData}, XPath=test[1]/@text}"/>
+        <!--</BasicInlineBinding>-->
+
+        <!--<SimpleStyle>-->
+        <Button Style="{StaticResource GreenButtonStyle}" Content="I am green"/>
+        <!--</SimpleStyle>-->
+
+        <!--<Animate>-->
+        <Button Content="I am animated">
+            <Button.Background>
+                <SolidColorBrush x:Name="AnimBrush"/>
+            </Button.Background>
+            <Button.Triggers>
+                <EventTrigger RoutedEvent="FrameworkElement.Loaded">
+                    <BeginStoryboard>
+                        <Storyboard>
+                            <ColorAnimation
+                                Storyboard.TargetName="AnimBrush" 
+                                Storyboard.TargetProperty="(SolidColorBrush.Color)"
+                                From="Blue" To="White" Duration="0:0:1" 
+                                AutoReverse="True" RepeatBehavior="Forever" />
+                        </Storyboard>
+                    </BeginStoryboard>
+                </EventTrigger>
+            </Button.Triggers>
+        </Button>
+        <!--</Animate>-->
+
+        <!--<InheritanceBindingContext>-->
+        <StackPanel Canvas.Top="50" DataContext="{Binding Source={StaticResource TestData}}">
+            <Button Content="{Binding XPath=test[2]/@text}"/>
+        </StackPanel>
+        <!--</InheritanceBindingContext>-->
+
+        <!--<PropertyValuePrecedence>-->
+        <StackPanel>
+            <StackPanel.Resources>
+                <Style x:Key="{x:Type Button}" TargetType="{x:Type Button}">
+                    <Setter Property="Background" Value="Orange"/>
+                </Style>
+            </StackPanel.Resources>
+            <Button>I am styled orange</Button>
+            <Button Background="Pink">I am locally set to pink (not styled orange)</Button>
+        </StackPanel>
+        <!--</PropertyValuePrecedence>-->
+
+    </StackPanel>
+</Window>
@@ -0,0 +1,45 @@
+Namespace CodeSampleVb
+    Partial Public Class MainWindow
+        Inherits Window
+
+        Public Sub New()
+            InitializeComponent()
+
+            ' <ProceduralPropertySet>
+            Dim myButton As New Button With {
+                .Width = 200.0
+            }
+            ' </ProceduralPropertySet>
+
+            ' <ProceduralPropertyGet>
+            Dim whatWidth As Double = myButton.Width
+            ' </ProceduralPropertyGet>
+
+        End Sub
+
+        ' <DefineDependencyProperty>
+        Public Shared ReadOnly IsSpinningProperty As DependencyProperty =
+            DependencyProperty.Register("IsSpinning", GetType(Boolean), GetType(MainWindow))
+
+        Public Property IsSpinning As Boolean
+            Get
+                Return GetValue(IsSpinningProperty)
+            End Get
+            Set(value As Boolean)
+                SetValue(IsSpinningProperty, value)
+            End Set
+        End Property
+        ' </DefineDependencyProperty>
+
+    End Class
+
+    ' <OverrideMetadata>
+    Public Class SpinnerControl
+        Inherits ItemsControl
+        Shared Sub New()
+            DefaultStyleKeyProperty.OverrideMetadata(GetType(SpinnerControl), New FrameworkPropertyMetadata(GetType(SpinnerControl)))
+        End Sub
+    End Class
+    ' </OverrideMetadata>
+
+End Namespace
@@ -0,0 +1,4 @@
+<tests>
+    <test text="I have data binding content"/>
+    <test text="I have inherited data binding content"/>
+</tests>
@@ -38,6 +38,7 @@ items:
  - name: Controls
    items:
    - name: Styles and templates
+      expanded: true
      items:
      - name: Overview
        href: controls/styles-templates-overview.md
@@ -77,6 +78,10 @@ items:
 - name: Systems
  expanded: true
  items:
+  - name: Properties
+    items:
+    - name: Dependency properties
+      href: properties/dependency-properties-overview.md
  - name: Resources
    items:
    - name: Overview
@@ -93,6 +98,7 @@ items:
        href: systems/xaml-resources-how-to-use-application.md
      - name: Use system resources
        href: systems/xaml-resources-how-to-use-system.md
+
 - name: XAML with WPF
  items:
  - name: Overview
@@ -318,6 +318,13 @@
            "TargetUrl": "/dotnet/desktop/wpf/documents/how-to-print-xps-files?view=netdesktop-5.0"
        },

+        // Systems - Properties
+        {
+            "Redirect": "TwoWay",
+            "SourceUrl": "/dotnet/desktop/wpf/advanced/dependency-properties-overview?view=netframeworkdesktop-4.8",
+            "TargetUrl": "/dotnet/desktop/wpf/properties/dependency-properties-overview?view=netdesktop-5.0"
+        },
+
        // Systems - XAML
        {
            "Redirect": "TwoWay",