diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 8c307c9..0d4f202 100644 --- a/.openpublishing.redirection.json +++ b/.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" diff --git a/dotnet-desktop-guide/net/wpf/properties/how-to-implement-a-dependency-property.md b/dotnet-desktop-guide/net/wpf/properties/how-to-implement-a-dependency-property.md new file mode 100644 index 0000000..afe80eb --- /dev/null +++ b/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" +--- + + +# How to implement a dependency property (WPF .NET) + +This article describes how to implement a dependency property by using a 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 method. The `Register` method returns a 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`. 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]() of the dependency property and its CLR accessor is `HasFish`, so the identifier field is named `HasFishProperty`. The dependency property type is and the owner type that registers the dependency property is `Aquarium`. + +You can specify default [metadata]() 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) diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml new file mode 100644 index 0000000..867d2f0 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml @@ -0,0 +1,9 @@ + + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/App.xaml.cs new file mode 100644 index 0000000..3128552 --- /dev/null +++ b/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 +{ + /// + /// Interaction logic for App.xaml + /// + public partial class App : Application + { + } +} diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/AssemblyInfo.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/AssemblyInfo.cs new file mode 100644 index 0000000..8b5504e --- /dev/null +++ b/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) +)] diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/CodeSampleCsharp.csproj b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/CodeSampleCsharp.csproj new file mode 100644 index 0000000..8824b2f --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/CodeSampleCsharp.csproj @@ -0,0 +1,24 @@ + + + + WinExe + net5.0-windows + true + + + + + True + True + Resources.resx + + + + + + ResXFileCodeGenerator + Resources.Designer.cs + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml new file mode 100644 index 0000000..4746ae7 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml @@ -0,0 +1,3 @@ + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/MainWindow.xaml.cs new file mode 100644 index 0000000..d1bccdc --- /dev/null +++ b/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 +{ + /// + /// Interaction logic for MainWindow.xaml. + /// + public partial class MainWindow : Window + { + public MainWindow() => InitializeComponent(); + } + + // + 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); + } + } + // +} diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.Designer.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.Designer.cs new file mode 100644 index 0000000..64552f9 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.Designer.cs @@ -0,0 +1,63 @@ +//------------------------------------------------------------------------------ +// +// 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. +// +//------------------------------------------------------------------------------ + +namespace CodeSampleCsharp.Properties { + using System; + + + /// + /// A strongly-typed resource class, for looking up localized strings, etc. + /// + // 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() { + } + + /// + /// Returns the cached ResourceManager instance used by this class. + /// + [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; + } + } + + /// + /// Overrides the current thread's CurrentUICulture property for all + /// resource lookups using this strongly typed resource class. + /// + [global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Advanced)] + internal static global::System.Globalization.CultureInfo Culture { + get { + return resourceCulture; + } + set { + resourceCulture = value; + } + } + } +} diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.resx b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.resx new file mode 100644 index 0000000..1af7de1 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/csharp/Properties/Resources.resx @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + text/microsoft-resx + + + 2.0 + + + System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + + System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + \ No newline at end of file diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml new file mode 100644 index 0000000..f225972 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml @@ -0,0 +1,9 @@ + + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml.vb b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/Application.xaml.vb new file mode 100644 index 0000000..084cbe9 --- /dev/null +++ b/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 diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/AssemblyInfo.vb b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/AssemblyInfo.vb new file mode 100644 index 0000000..025ee72 --- /dev/null +++ b/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) + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/CodeSampleVb.vbproj b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/CodeSampleVb.vbproj new file mode 100644 index 0000000..c7ae1cc --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/CodeSampleVb.vbproj @@ -0,0 +1,22 @@ + + + + WinExe + net5.0-windows + CodeSampleVb + true + + + + + + + + + + + + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml new file mode 100644 index 0000000..b255c55 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml @@ -0,0 +1,3 @@ + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml.vb b/dotnet-desktop-guide/net/wpf/properties/snippets/how-to-implement-a-dependency-property/vb/MainWindow.xaml.vb new file mode 100644 index 0000000..cc7fcc7 --- /dev/null +++ b/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 + + ' + 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 + ' + End Class +End Namespace diff --git a/dotnet-desktop-guide/net/wpf/toc.yml b/dotnet-desktop-guide/net/wpf/toc.yml index e28eb0d..180eac4 100644 --- a/dotnet-desktop-guide/net/wpf/toc.yml +++ b/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 - href: properties/how-to-register-an-attached-property.md + - name: Attached properties + 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 - href: properties/attached-properties-overview.md + - name: Implement a dependency property + 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 diff --git a/redirects_generator/definitions.json b/redirects_generator/definitions.json index f6cc73c..3dd161b 100644 --- a/redirects_generator/definitions.json +++ b/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 {