From 048ceebd5dfd4df33f9159854375cd8333f335c1 Mon Sep 17 00:00:00 2001 From: Tris Shores <86677757+v-trisshores@users.noreply.github.com> Date: Tue, 7 Dec 2021 17:15:29 -0600 Subject: [PATCH 1/2] Add article, snippets, toc, and redirects (#1233) --- .openpublishing.redirection.json | 8 ++ .../dependency-property-security.md | 61 +++++++++ .../csharp/App.xaml.cs | 17 +++ .../csharp/AssemblyInfo.cs | 10 ++ .../csharp/CodeSampleCsharp.csproj | 24 ++++ .../csharp/MainWindow.xaml | 5 + .../csharp/MainWindow.xaml.cs | 100 +++++++++++++++ .../csharp/Properties/Resources.Designer.cs | 63 +++++++++ .../csharp/Properties/Resources.resx | 120 ++++++++++++++++++ .../csharp/app.xaml | 9 ++ .../vb/Application.xaml | 9 ++ .../vb/Application.xaml.vb | 6 + .../vb/AssemblyInfo.vb | 11 ++ .../vb/CodeSampleVb.vbproj | 22 ++++ .../vb/MainWindow.xaml | 5 + .../vb/MainWindow.xaml.vb | 100 +++++++++++++++ dotnet-desktop-guide/net/wpf/toc.yml | 2 + redirects_generator/definitions.json | 4 + 18 files changed, 576 insertions(+) create mode 100644 dotnet-desktop-guide/net/wpf/properties/dependency-property-security.md create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/App.xaml.cs create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/AssemblyInfo.cs create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/CodeSampleCsharp.csproj create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml.cs create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/Properties/Resources.Designer.cs create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/Properties/Resources.resx create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/app.xaml create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml.vb create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/AssemblyInfo.vb create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/CodeSampleVb.vbproj create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml create mode 100644 dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml.vb diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 02c81da..2ba5164 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -564,6 +564,14 @@ { "source_path": "dotnet-desktop-guide/framework/wpf/properties/read-only-dependency-properties.md", "redirect_url": "/dotnet/desktop/wpf/advanced/read-only-dependency-properties?view=netframeworkdesktop-4.8" + }, + { + "source_path": "dotnet-desktop-guide/net/wpf/advanced/dependency-property-security.md", + "redirect_url": "/dotnet/desktop/wpf/properties/dependency-property-security?view=netdesktop-6.0" + }, + { + "source_path": "dotnet-desktop-guide/framework/wpf/properties/dependency-property-security.md", + "redirect_url": "/dotnet/desktop/wpf/advanced/dependency-property-security?view=netframeworkdesktop-4.8" } ] } diff --git a/dotnet-desktop-guide/net/wpf/properties/dependency-property-security.md b/dotnet-desktop-guide/net/wpf/properties/dependency-property-security.md new file mode 100644 index 0000000..3592823 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/dependency-property-security.md @@ -0,0 +1,61 @@ +--- +title: "Dependency property security" +description: Learn about the dependency property accessibility and security in Windows Presentation Foundation (WPF). +ms.date: "12/03/2021" +dev_langs: + - "csharp" + - "vb" +helpviewer_keywords: + - "wrappers [WPF], access" + - "wrappers [WPF], security" + - "dependency properties [WPF], security" + - "security [WPF], wrappers" + - "validation [WPF], dependency properties" + - "dependency properties [WPF], access" + - "security [WPF], dependency properties" +--- + + +# Dependency property security (WPF .NET) + +The accessibility of read-write dependency properties through the Windows Presentation Foundation (WPF) property system effectively makes them public properties. As a result, it's not possible to make security guarantees about read-write dependency property values. The WPF property system provides more security for read-only dependency properties so that you can restrict write access. + +[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)] + +## Access and security of property wrappers + +A common language runtime (CLR) property wrapper is usually included in read-write dependency property implementations to simplify getting or setting property values. If included, the CLR property wrapper is a convenience method that implements the and static calls that interact with the underlying dependency property. Essentially, a CLR property wrapper exposes a dependency property as a CLR property backed by a dependency property rather than a private field. + +Applying security mechanisms and restricting access to the CLR property wrapper might prevent usage of the convenience method, but those techniques won't prevent direct calls to `GetValue` or `SetValue`. In other words, a read-write dependency property is always accessible through the WPF property system. If you're implementing a read-write dependency property, avoid restricting access to the CLR property wrapper. Instead, declare the CLR property wrapper as a public member so callers are aware of the true access level of the dependency property. + +## Property system exposure of dependency properties + +The WPF property system provides access to a read-write dependency property through its identifier. The identifier is usable in and calls. Even if the static identifier field is non-public, several aspects of the property system will return a `DependencyProperty` as it exists on an instance of a class or derived class. For example, the method returns identifiers for dependency property instances with a locally set value. Also, you can override the virtual method to receive event data that will report the `DependencyProperty` identifier for dependency properties that have changed value. To make callers aware of the true access level of a read-write dependency property, declare its identifier field as a public member. + +> [!NOTE] +> Although declaring a dependency property identifier field as `private` reduces the number of ways that a read-write dependency property is accessible, the property won't be [private](/dotnet/csharp/language-reference/keywords/private) according to the CLR language definition. + +### Validation security + +Applying a to a and expecting validation to fail on `Demand` failure, isn't an adequate security mechanism for restricting property value changes. Also, new value invalidation enforced through `ValidateValueCallback` can be suppressed by malicious callers, if those callers are operating within the application domain. + +## Access to read-only dependency properties + +To restrict access, register your property as a read-only dependency property by calling the method. The `RegisterReadOnly` method returns a , which you can assign to a non-public class field. For read-only dependency properties, the WPF property system will only provide write access to those who have a reference to the `DependencyPropertyKey`. To illustrate this behavior, the following test code: + +- Instantiates a class that implements both read-write and read-only dependency properties. +- Assigns a `private` access modifier to each identifier. +- Only implements `get` accessors. +- Uses the method to access the underlying dependency properties through the WPF property system. +- Calls and to test access to each dependency property value. + +:::code language="csharp" source="./snippets/dependency-property-security/csharp/MainWindow.xaml.cs" id="DependencyPropertyAccessTests"::: +:::code language="vb" source="./snippets/dependency-property-security/vb/MainWindow.xaml.vb" id="DependencyPropertyAccessTests"::: + +## See also + +- +- +- +- [Custom dependency properties](custom-dependency-properties.md) +- [Implement a Dependency property](how-to-implement-a-dependency-property.md) diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/App.xaml.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/App.xaml.cs new file mode 100644 index 0000000..3128552 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/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/dependency-property-security/csharp/AssemblyInfo.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/AssemblyInfo.cs new file mode 100644 index 0000000..8b5504e --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/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/dependency-property-security/csharp/CodeSampleCsharp.csproj b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/CodeSampleCsharp.csproj new file mode 100644 index 0000000..22d78ee --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/CodeSampleCsharp.csproj @@ -0,0 +1,24 @@ + + + + WinExe + net6.0-windows + true + + + + + True + True + Resources.resx + + + + + + ResXFileCodeGenerator + Resources.Designer.cs + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml new file mode 100644 index 0000000..40e5615 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml @@ -0,0 +1,5 @@ + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml.cs new file mode 100644 index 0000000..c4ef0c5 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/MainWindow.xaml.cs @@ -0,0 +1,100 @@ +using System; +using System.Diagnostics; +using System.Windows; + +namespace CodeSampleCsharp +{ + /// + /// Interaction logic for MainWindow.xaml. + /// + public partial class MainWindow : Window + { + public MainWindow() + { + InitializeComponent(); + + DependencyPropertyAccessTests(); + } + + // + /// + /// Test get/set access to dependency properties exposed through the WPF property system. + /// + public static void DependencyPropertyAccessTests() + { + // Instantiate a class that implements read-write and read-only dependency properties. + Aquarium _aquarium = new(); + // Access each dependency property using the LocalValueEnumerator method. + LocalValueEnumerator localValueEnumerator = _aquarium.GetLocalValueEnumerator(); + while (localValueEnumerator.MoveNext()) + { + DependencyProperty dp = localValueEnumerator.Current.Property; + string dpType = dp.ReadOnly ? "read-only" : "read-write"; + // Test read access. + Debug.WriteLine($"Attempting to get a {dpType} dependency property value..."); + Debug.WriteLine($"Value ({dpType}): {(int)_aquarium.GetValue(dp)}"); + // Test write access. + try + { + Debug.WriteLine($"Attempting to set a {dpType} dependency property value to 2..."); + _aquarium.SetValue(dp, 2); + } + catch (InvalidOperationException e) + { + Debug.WriteLine(e.Message); + } + finally + { + Debug.WriteLine($"Value ({dpType}): {(int)_aquarium.GetValue(dp)}"); + } + } + + // Test output: + + // Attempting to get a read-write dependency property value... + // Value (read-write): 1 + // Attempting to set a read-write dependency property value to 2... + // Value (read-write): 2 + + // Attempting to get a read-only dependency property value... + // Value (read-only): 1 + // Attempting to set a read-only dependency property value to 2... + // 'FishCountReadOnly' property was registered as read-only + // and cannot be modified without an authorization key. + // Value (read-only): 1 + } + } + + public class Aquarium : DependencyObject + { + public Aquarium() + { + // Assign locally-set values. + SetValue(FishCountProperty, 1); + SetValue(FishCountReadOnlyPropertyKey, 1); + } + + // Failed attempt to restrict write-access by assigning the + // DependencyProperty identifier to a non-public field. + private static readonly DependencyProperty FishCountProperty = + DependencyProperty.Register( + name: "FishCount", + propertyType: typeof(int), + ownerType: typeof(Aquarium), + typeMetadata: new PropertyMetadata()); + + // Successful attempt to restrict write-access by assigning the + // DependencyPropertyKey to a non-public field. + private static readonly DependencyPropertyKey FishCountReadOnlyPropertyKey = + DependencyProperty.RegisterReadOnly( + name: "FishCountReadOnly", + propertyType: typeof(int), + ownerType: typeof(Aquarium), + typeMetadata: new PropertyMetadata()); + + // Declare public get accessors. + public int FishCount => (int)GetValue(FishCountProperty); + public int FishCountReadOnly => (int)GetValue(FishCountReadOnlyPropertyKey.DependencyProperty); + } + // +} diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/Properties/Resources.Designer.cs b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/Properties/Resources.Designer.cs new file mode 100644 index 0000000..64552f9 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/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/dependency-property-security/csharp/Properties/Resources.resx b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/Properties/Resources.resx new file mode 100644 index 0000000..1af7de1 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/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/dependency-property-security/csharp/app.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/app.xaml new file mode 100644 index 0000000..867d2f0 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/csharp/app.xaml @@ -0,0 +1,9 @@ + + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml new file mode 100644 index 0000000..f225972 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml @@ -0,0 +1,9 @@ + + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml.vb b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/Application.xaml.vb new file mode 100644 index 0000000..084cbe9 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/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/dependency-property-security/vb/AssemblyInfo.vb b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/AssemblyInfo.vb new file mode 100644 index 0000000..025ee72 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/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/dependency-property-security/vb/CodeSampleVb.vbproj b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/CodeSampleVb.vbproj new file mode 100644 index 0000000..34db9b0 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/CodeSampleVb.vbproj @@ -0,0 +1,22 @@ + + + + WinExe + net6.0-windows + CodeSampleVb + true + + + + + + + + + + + + + + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml new file mode 100644 index 0000000..30392c0 --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml @@ -0,0 +1,5 @@ + + diff --git a/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml.vb b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml.vb new file mode 100644 index 0000000..3d1271c --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/snippets/dependency-property-security/vb/MainWindow.xaml.vb @@ -0,0 +1,100 @@ +Namespace CodeSampleVb + + ' + ' Interaction logic for MainWindow.xaml. + ' + Partial Public Class MainWindow + Inherits Window + + Public Sub New() + InitializeComponent() + DependencyPropertyAccessTests() + End Sub + + ' + ''' + ''' ' Test get/set access to dependency properties exposed through the WPF property system. + ''' + Public Shared Sub DependencyPropertyAccessTests() + ' Instantiate a class that implements read-write and read-only dependency properties. + Dim _aquarium As New Aquarium() + ' Access each dependency property using the LocalValueEnumerator method. + Dim localValueEnumerator As LocalValueEnumerator = _aquarium.GetLocalValueEnumerator() + While localValueEnumerator.MoveNext() + Dim dp As DependencyProperty = localValueEnumerator.Current.[Property] + Dim dpType As String = If(dp.[ReadOnly], "read-only", "read-write") + ' Test read access. + Debug.WriteLine($"Attempting to get a {dpType} dependency property value...") + Debug.WriteLine($"Value ({dpType}): {CInt(_aquarium.GetValue(dp))}") + ' Test write access. + Try + Debug.WriteLine($"Attempting to set a {dpType} dependency property value to 2...") + _aquarium.SetValue(dp, 2) + Catch e As InvalidOperationException + Debug.WriteLine(e.Message) + Finally + Debug.WriteLine($"Value ({dpType}): {CInt(_aquarium.GetValue(dp))}") + End Try + End While + + ' Test output + + ' Attempting to get a read-write dependency property value... + ' Value (read-write): 1 + ' Attempting to set a read-write dependency property value to 2... + ' Value (read-write): 2 + + ' Attempting to get a read-only dependency property value... + ' Value (read-only): 1 + ' Attempting to set a read-only dependency property value to 2... + ' 'FishCountReadOnly' property was registered as read-only + ' and cannot be modified without an authorization key. + ' Value (read-only): 1 + End Sub + + End Class + + Public Class Aquarium + Inherits DependencyObject + + Public Sub New() + ' Assign locally-set values. + SetValue(FishCountProperty, 1) + SetValue(FishCountReadOnlyPropertyKey, 1) + End Sub + + ' Failed attempt to restrict write-access by assigning the + ' DependencyProperty identifier to a non-public field. + Private Shared ReadOnly FishCountProperty As DependencyProperty = + DependencyProperty.Register( + name:="FishCount", + propertyType:=GetType(Integer), + ownerType:=GetType(Aquarium), + typeMetadata:=New PropertyMetadata()) + + ' Successful attempt to restrict write-access by assigning the + ' DependencyPropertyKey to a non-public field. + Private Shared ReadOnly FishCountReadOnlyPropertyKey As DependencyPropertyKey = + DependencyProperty.RegisterReadOnly( + name:="FishCountReadOnly", + propertyType:=GetType(Integer), + ownerType:=GetType(Aquarium), + typeMetadata:=New PropertyMetadata()) + + ' Declare public get accessors. + Public ReadOnly Property FishCount As Integer + Get + Return GetValue(FishCountProperty) + End Get + End Property + + Public ReadOnly Property FishCountReadOnly As Integer + Get + Return GetValue(FishCountReadOnlyPropertyKey.DependencyProperty) + End Get + End Property + + End Class + ' + +End Namespace diff --git a/dotnet-desktop-guide/net/wpf/toc.yml b/dotnet-desktop-guide/net/wpf/toc.yml index b5d70db..a737976 100644 --- a/dotnet-desktop-guide/net/wpf/toc.yml +++ b/dotnet-desktop-guide/net/wpf/toc.yml @@ -96,6 +96,8 @@ items: href: properties/dependency-property-callbacks-and-validation.md - name: Read-only dependency properties href: properties/read-only-dependency-properties.md + - name: Dependency property security + href: properties/dependency-property-security.md - name: Common tasks items: - name: Implement a dependency property diff --git a/redirects_generator/definitions.json b/redirects_generator/definitions.json index 8f8622e..6c8db5d 100644 --- a/redirects_generator/definitions.json +++ b/redirects_generator/definitions.json @@ -383,6 +383,10 @@ "SourceUrl": "/dotnet/desktop/wpf/advanced/read-only-dependency-properties?view=netframeworkdesktop-4.8", "TargetUrl": "/dotnet/desktop/wpf/properties/read-only-dependency-properties?view=netdesktop-6.0" }, + { + "SourceUrl": "/dotnet/desktop/wpf/advanced/dependency-property-security?view=netframeworkdesktop-4.8", + "TargetUrl": "/dotnet/desktop/wpf/properties/dependency-property-security?view=netdesktop-6.0" + }, // Systems - XAML { From 3bac863f4348ae4f4525c5131fa96a8a241f8d81 Mon Sep 17 00:00:00 2001 From: Tris Shores <86677757+v-trisshores@users.noreply.github.com> Date: Tue, 7 Dec 2021 17:20:09 -0600 Subject: [PATCH 2/2] Content update - Framework property metadata (user story 1878471) (#1223) * Add article, snippets, toc, and redirects * Minor edits * Make reviewer requested changes * Section header edit Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --- .openpublishing.redirection.json | 8 ++ .../dependency-property-metadata.md | 2 +- .../properties/framework-property-metadata.md | 79 +++++++++++++++++++ dotnet-desktop-guide/net/wpf/toc.yml | 2 + redirects_generator/definitions.json | 4 + 5 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 dotnet-desktop-guide/net/wpf/properties/framework-property-metadata.md diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 2ba5164..12db5a0 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -565,6 +565,14 @@ "source_path": "dotnet-desktop-guide/framework/wpf/properties/read-only-dependency-properties.md", "redirect_url": "/dotnet/desktop/wpf/advanced/read-only-dependency-properties?view=netframeworkdesktop-4.8" }, + { + "source_path": "dotnet-desktop-guide/net/wpf/advanced/framework-property-metadata.md", + "redirect_url": "/dotnet/desktop/wpf/properties/framework-property-metadata?view=netdesktop-6.0" + }, + { + "source_path": "dotnet-desktop-guide/framework/wpf/properties/framework-property-metadata.md", + "redirect_url": "/dotnet/desktop/wpf/advanced/framework-property-metadata?view=netframeworkdesktop-4.8" + }, { "source_path": "dotnet-desktop-guide/net/wpf/advanced/dependency-property-security.md", "redirect_url": "/dotnet/desktop/wpf/properties/dependency-property-security?view=netdesktop-6.0" diff --git a/dotnet-desktop-guide/net/wpf/properties/dependency-property-metadata.md b/dotnet-desktop-guide/net/wpf/properties/dependency-property-metadata.md index f036e6b..bff2d7f 100644 --- a/dotnet-desktop-guide/net/wpf/properties/dependency-property-metadata.md +++ b/dotnet-desktop-guide/net/wpf/properties/dependency-property-metadata.md @@ -75,7 +75,7 @@ Since most existing dependency properties aren't virtual properties, their inher - For a , the new value will replace the existing default value. If you don't specify a `DefaultValue` in the override metadata, the value comes from the nearest ancestor that specified `DefaultValue` in metadata. -- For a , the default merge logic stores all `PropertyChangedCallback` values in a table, and all are invoked on a property change. The callback order is determined by class depth, where the callback registered by the base class in the hierarchy runs first. +- For a , the default merge logic stores all `PropertyChangedCallback` values in a table, and all are invoked on a property change. The callback order is determined by class depth, where a callback registered by the base class in the hierarchy would run first. - For a , the new value will replace the existing `CoerceValueCallback` value. If you don't specify a `CoerceValueCallback` in the override metadata, the value comes from the nearest ancestor that specified `CoerceValueCallback` in metadata. diff --git a/dotnet-desktop-guide/net/wpf/properties/framework-property-metadata.md b/dotnet-desktop-guide/net/wpf/properties/framework-property-metadata.md new file mode 100644 index 0000000..c4c01aa --- /dev/null +++ b/dotnet-desktop-guide/net/wpf/properties/framework-property-metadata.md @@ -0,0 +1,79 @@ +--- +title: "Framework property metadata" +description: Learn how to set framework property metadata for a dependency property in Windows Presentation Foundation (WPF). +ms.date: "11/20/2021" +helpviewer_keywords: + - "metadata [WPF], framework properties" + - "framework property metadata [WPF]" +--- + + +# Framework property metadata (WPF .NET) + +You can set framework property metadata options for dependency properties at the Windows Presentation Foundation (WPF) framework level. The WPF framework level designation applies when WPF presentation APIs and executables handle rendering and data binding. Presentation APIs and executables query the of a dependency property. + +[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)] + +## Prerequisites + +The article assumes a basic knowledge of dependency properties, and that you've read [Dependency properties overview](dependency-properties-overview.md). To follow the examples in this article, it helps if you're familiar with Extensible Application Markup Language (XAML) and know how to write WPF applications. + +## Framework property metadata categories + + falls into these categories: + +- Metadata that affects the layout of an element, specifically the , , and metadata flags. You might set those flags if your dependency property implementation affects a visual aspect and you're implementing or in your class. The `MeasureOverride` and `ArrangeOverride` methods provide implementation-specific behavior and rendering information to the layout system. When `AffectsArrange`, `AffectsMeasure`, or `AffectsRender` are set to `true` in the metadata of a dependency property and its effective value changes, the WPF property system will initiate a request to invalidate the element's visuals to trigger a redraw. + +- Metadata that affects the layout of the parent element of an element, specifically the and metadata flags. Examples of WPF dependency properties that set these flags are and . + +- Property value inheritance metadata, specifically the and metadata flags. By default, dependency properties don't inherit values. allows the pathway of inheritance to also travel into a visual tree, which is necessary for some control compositing scenarios. For more information, see [Property value inheritance](/dotnet/desktop/wpf/advanced/property-value-inheritance?view=netframeworkdesktop-4.8&preserve-view=true). + + > [!NOTE] + > The term "inherits" in the context of property values is specific to dependency properties, and doesn't directly relate to managed code types and member inheritance through derived types. In the context of dependency properties, it means that child elements can inherit dependency property values from parent elements. + +- Data binding metadata, specifically the and metadata flags. By default, dependency properties in the WPF framework support one-way binding. Consider setting two-way binding as the default for properties that report state *and* are modifiable by user action, for example . Also, consider setting two-way binding as the default when users of a control expect a property to implement it, for example [TextBox.Text](). `BindsTwoWayByDefault` only affects the default binding mode. To edit the data flow direction of a binding, set [Binding.Mode](). You can use `IsNotDataBindable` to disable data binding when there's no use case for it. For more information on data bindings, see [Data binding overview](/dotnet/desktop/wpf/advanced/data-binding-overview?view=netframeworkdesktop-4.8&preserve-view=true). + +- Journaling metadata, specifically the metadata flag. The default value of the `Journal` flag is only `true` for a some dependency properties, such as . User input controls should set the `Journal` flag for properties whose values hold user selections that need to be stored. The `Journal` flag is read by applications or services that support journaling, including WPF journaling services. For information on storing navigation steps, see [Navigation overview](/dotnet/desktop/wpf/app-development/navigation-overview?view=netframeworkdesktop-4.8&preserve-view=true). + + derives directly from , and implements the flags discussed here. Unless specifically set, `FrameworkPropertyMetadata` flags have a default value of `false`. + +## Reading FrameworkPropertyMetadata + +To retrieve metadata for a dependency property, call on the identifier. The `GetMetadata` call returns a `PropertyMetadata` object. If you need to query framework metadata values cast `PropertyMetadata` to . + +## Specifying FrameworkPropertyMetadata + +When you register a dependency property, you have the option to create and assign metadata to it. The metadata object that you assign can be or one of its derived classes, like . Choose `FrameworkPropertyMetadata` for dependency properties that rely on WPF presentation APIs and executables for rendering and data binding. A more advanced option is to derive from `FrameworkPropertyMetadata` to create a custom metadata reporting class with more flags. Or, you might use for non-framework properties that affect UI rendering. + +Although metadata options are typically set during registration of a new dependency property, you can respecify them in or calls. When overriding metadata, always override with the same metadata type that was used during property registration. + +The property characteristics that are exposed by `FrameworkPropertyMetadata` are sometimes referred to as *flags*. If you're creating a `FrameworkPropertyMetadata` instance, there are two ways to populate flag values: + +1. Set the flags on an instance of the enumeration type. `FrameworkPropertyMetadataOptions` lets you specify metadata flags in bitwise OR combination. Then, instantiate `FrameworkPropertyMetadata` using a constructor that has a `FrameworkPropertyMetadataOptions` parameter, and pass in your `FrameworkPropertyMetadataOptions` instance. To change metadata flags after passing `FrameworkPropertyMetadataOptions` into the constructor, change the corresponding property on the new `FrameworkPropertyMetadata` instance. For example, if you set the flag, you can undo that by setting to `false`. + +1. Instantiate `FrameworkPropertyMetadata` using a constructor that doesn't have a `FrameworkPropertyMetadataOptions` parameter, and then set the applicable flags on `FrameworkPropertyMetadata`. Set flag values before associating your `FrameworkPropertyMetadata` instance with a dependency property, otherwise you'll get an . + +## Metadata override behavior + +When you override framework property metadata, changed metadata values either replace or are merged with the original values: + +- For a , the default merge logic retains previous `PropertyChangedCallback` values in a table, and all are invoked on a property change. The callback order is determined by class depth, where a callback registered by the base class in the hierarchy would run first. Inherited callbacks run only once, and are owned by the class that added them into metadata. + +- For a , the new value will replace the existing default value. If you don't specify a `DefaultValue` in the override metadata and if the existing has the `Inherits` flag set, then the default value comes from the nearest ancestor that specified `DefaultValue` in metadata. + +- For a , the new value will replace an existing `CoerceValueCallback` value. If you don't specify a `CoerceValueCallback` in the override metadata, the value comes from the nearest ancestor in the inheritance chain that specified a `CoerceValueCallback`. + +- For `FrameworkPropertyMetadata` non-inherited flags, you can override the default `false` value with a `true` value. However, you can only override a `true` value with a `false` value for , , , and . + +> [!NOTE] +> The default merge logic is implemented by the method. You can specify custom merge logic in a derived class that inherits a dependency property, by overriding `Merge` in that class. + +## See also + +- +- +- +- +- [Dependency Property Metadata](dependency-property-metadata.md) +- [Dependency Properties Overview](dependency-properties-overview.md) +- [Custom Dependency Properties](custom-dependency-properties.md) diff --git a/dotnet-desktop-guide/net/wpf/toc.yml b/dotnet-desktop-guide/net/wpf/toc.yml index a737976..8e1cec1 100644 --- a/dotnet-desktop-guide/net/wpf/toc.yml +++ b/dotnet-desktop-guide/net/wpf/toc.yml @@ -96,6 +96,8 @@ items: href: properties/dependency-property-callbacks-and-validation.md - name: Read-only dependency properties href: properties/read-only-dependency-properties.md + - name: Framework-property-metadata + href: properties/framework-property-metadata.md - name: Dependency property security href: properties/dependency-property-security.md - name: Common tasks diff --git a/redirects_generator/definitions.json b/redirects_generator/definitions.json index 6c8db5d..31c5ee7 100644 --- a/redirects_generator/definitions.json +++ b/redirects_generator/definitions.json @@ -383,6 +383,10 @@ "SourceUrl": "/dotnet/desktop/wpf/advanced/read-only-dependency-properties?view=netframeworkdesktop-4.8", "TargetUrl": "/dotnet/desktop/wpf/properties/read-only-dependency-properties?view=netdesktop-6.0" }, + { + "SourceUrl": "/dotnet/desktop/wpf/advanced/framework-property-metadata?view=netframeworkdesktop-4.8", + "TargetUrl": "/dotnet/desktop/wpf/properties/framework-property-metadata?view=netdesktop-6.0" + }, { "SourceUrl": "/dotnet/desktop/wpf/advanced/dependency-property-security?view=netframeworkdesktop-4.8", "TargetUrl": "/dotnet/desktop/wpf/properties/dependency-property-security?view=netdesktop-6.0"