Add article, code projects, toc, and redirects (#1180)

Co-authored-by: Andy (Steve) De George <[email protected]>

.openpublishing.redirection.json

@@ -489,6 +489,14 @@
             "source_path": "dotnet-desktop-guide/framework/wpf/properties/dependency-property-value-precedence.md",
             "redirect_url": "/dotnet/desktop/wpf/advanced/dependency-property-value-precedence?view=netframeworkdesktop-4.8"
         },
+        {
+            "source_path": "dotnet-desktop-guide/net/wpf/advanced/how-to-implement-a-dependency-property.md",
+            "redirect_url": "/dotnet/desktop/wpf/properties/how-to-implement-a-dependency-property?view=netdesktop-5.0"
+        },
+        {
+            "source_path": "dotnet-desktop-guide/framework/wpf/properties/how-to-implement-a-dependency-property.md",
+            "redirect_url": "/dotnet/desktop/wpf/advanced/how-to-implement-a-dependency-property?view=netframeworkdesktop-4.8"
+        },
         {
             "source_path": "dotnet-desktop-guide/net/wpf/advanced/attached-properties-overview.md",
             "redirect_url": "/dotnet/desktop/wpf/properties/attached-properties-overview?view=netdesktop-5.0"

dotnet-desktop-guide/net/wpf/properties/how-to-implement-a-dependency-property.md

@@ -0,0 +1,36 @@
+---
+title: "How to implement a dependency property"
+description: "Define a dependency property in Windows Presentation Foundation (WPF), by backing a common language runtime property with a DependencyProperty field."
+ms.date: "10/15/2021"
+dev_langs: 
+  - "csharp"
+  - "vb"
+helpviewer_keywords: 
+  - "dependency properties [WPF], backing properties with"
+  - "properties [WPF], backing with dependency properties"
+---
+<!-- The acrolinx score was 96 on 10/15/2021-->
+
+# How to implement a dependency property (WPF .NET)
+
+This article describes how to implement a dependency property by using a <xref:System.Windows.DependencyProperty> field to back a common language runtime (CLR) property. Dependency properties support several advanced Windows Presentation Foundation (WPF) property system features. These features include styles, data binding, inheritance, animation, and default values. If you want properties that you define to support those features, then implement your properties as a dependency property.
+  
+## Example  
+
+The following example shows how to register a dependency property, by calling the <xref:System.Windows.DependencyProperty.Register%2A> method. The `Register` method returns a <xref:System.Windows.DependencyProperty> instance called a *dependency property identifier*. The identifier is stored in a `static readonly` field, and holds the name and characteristics of a dependency property.
+
+The identifier field must follow the naming convention `<property name>Property`. For instance, if you register a dependency property with the name `Location`, then the identifier field should be named `LocationProperty`. If you fail to follow this naming pattern, then WPF designers might not report your property correctly, and aspects of the property system style application might not behave as expected.
+
+In the following example, the [name](<xref:System.Windows.DependencyProperty.Name>) of the dependency property and its CLR accessor is `HasFish`, so the identifier field is named `HasFishProperty`. The dependency property type is <xref:System.Boolean> and the owner type that registers the dependency property is `Aquarium`.  
+
+You can specify default [metadata](<xref:System.Windows.FrameworkPropertyMetadata>) for a dependency property. This example sets a default value of `false` for the `HasFish` dependency property.
+
+:::code language="csharp" source="./snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml.cs" id="DefineDependencyProperty":::
+:::code language="vb" source="./snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml.vb" id="DefineDependencyProperty":::  
+
+For more information about how and why to implement a dependency property, rather than just backing a CLR property with a private field, see [Dependency properties overview](dependency-properties-overview.md).
+
+## See also
+
+- [Dependency properties overview](dependency-properties-overview.md)
+- [How-to topics](/dotnet/desktop/wpf/advanced/properties-how-to-topics?view=netframeworkdesktop-4.8&preserve-view=true)

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml

@@ -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>

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml.cs

@@ -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
+    {
+    }
+}

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/AssemblyInfo.cs

@@ -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)
+)]

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/CodeSampleCsharp.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net5.0-windows</TargetFramework>
+    <UseWPF>true</UseWPF>
+  </PropertyGroup>
+
+  <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>

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml

@@ -0,0 +1,3 @@
+<Window x:Class="CodeSampleCsharp.MainWindow"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" />

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml.cs

@@ -0,0 +1,30 @@
+using System.Windows;
+
+namespace CodeSampleCsharp
+{
+    /// <summary>
+    /// Interaction logic for MainWindow.xaml.
+    /// </summary>
+    public partial class MainWindow : Window
+    {
+        public MainWindow() => InitializeComponent();
+    }
+
+    // <DefineDependencyProperty>
+    public class Aquarium : DependencyObject
+    {
+        public static readonly DependencyProperty HasFishProperty =
+            DependencyProperty.Register(
+                name: "HasFish",
+                propertyType: typeof(bool),
+                ownerType: typeof(Aquarium),
+                typeMetadata: new FrameworkPropertyMetadata(defaultValue: false));
+
+        public bool HasFish
+        {
+            get => (bool)GetValue(HasFishProperty);
+            set => SetValue(HasFishProperty, value);
+        }
+    }
+    // </DefineDependencyProperty>
+}

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.Designer.cs

@@ -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;
+            }
+        }
+    }
+}

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.resx

@@ -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>

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml

@@ -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>

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml.vb

@@ -0,0 +1,6 @@
+Class Application
+
+    ' Application-level events, such as Startup, Exit, and DispatcherUnhandledException
+    ' can be handled in this file.
+
+End Class

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/AssemblyInfo.vb

@@ -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)>

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/CodeSampleVb.vbproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net5.0-windows</TargetFramework>
+    <RootNamespace>CodeSampleVb</RootNamespace>
+    <UseWPF>true</UseWPF>
+  </PropertyGroup>
+
+  <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>

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml

@@ -0,0 +1,3 @@
+<Window x:Class="CodeSampleVb.MainWindow"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" />

dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml.vb

@@ -0,0 +1,32 @@
+Namespace CodeSampleVb
+    Partial Public Class MainWindow
+        Inherits Window
+
+        Public Sub New()
+            InitializeComponent()
+        End Sub
+
+        ' <DefineDependencyProperty>
+        Public Class Aquarium
+            Inherits DependencyObject
+
+            Public Shared ReadOnly HasFishProperty As DependencyProperty =
+            DependencyProperty.Register(
+                name:="HasFish",
+                propertyType:=GetType(Boolean),
+                ownerType:=GetType(Aquarium),
+                typeMetadata:=New FrameworkPropertyMetadata(defaultValue:=False))
+
+            Public Property HasFish As Boolean
+                Get
+                    Return GetValue(HasFishProperty)
+                End Get
+                Set(value As Boolean)
+                    SetValue(HasFishProperty, value)
+                End Set
+            End Property
+
+        End Class
+        ' </DefineDependencyProperty>
+    End Class
+End Namespace

dotnet-desktop-guide/net/wpf/toc.yml

@@ -84,14 +84,16 @@ items:
       href: properties/dependency-properties-overview.md
     - name: Dependency property value precedence
       href: properties/dependency-property-value-precedence.md
-    - name: Register an attached property
+    - name: Attached properties
-      href: properties/how-to-register-an-attached-property.md
+      href: properties/attached-properties-overview.md
     - name: Collection-type dependency properties
       href: properties/collection-type-dependency-properties.md
     - name: Common tasks
       items:
-      - name: Attached properties
+      - name: Implement a dependency property
-        href: properties/attached-properties-overview.md
+        href: properties/how-to-implement-a-dependency-property.md
+      - name: Register an attached property
+        href: properties/how-to-register-an-attached-property.md
   - name: Resources
     items:
     - name: Overview

redirects_generator/definitions.json

@@ -344,6 +344,11 @@
             "SourceUrl": "/dotnet/desktop/wpf/advanced/how-to-register-an-attached-property?view=netframeworkdesktop-4.8",
             "TargetUrl": "/dotnet/desktop/wpf/properties/how-to-register-an-attached-property?view=netdesktop-5.0"
         },
+        {
+            "Redirect": "TwoWay",
+            "SourceUrl": "/dotnet/desktop/wpf/advanced/how-to-implement-a-dependency-property?view=netframeworkdesktop-4.8",
+            "TargetUrl": "/dotnet/desktop/wpf/properties/how-to-implement-a-dependency-property?view=netdesktop-5.0"
+        },
 
         // Systems - XAML
         {