BindableProperty [PropertyChanged] attribute enhancement

[stephenquan]

Revision History: Original 14 Dec 2025, Rewrite 26 Jan 2026, Rewrite 2 Feb 2026

Introduce new optional attributes: [PropertyChanged], [PropertyChanging], [ValidateValue], [CoerceValue], and [CreateDefaultValue].

The new attributes introduce five optional capabilities. Two of them enable non-static partial methods, and the other three enable non-static methods. These attributes simply give developers the choice to opt into non-static patterns, while still allowing them to use the traditional static methods exactly as before. For convenience, the example below shows what opting in might look like.

public partial class TestClass : View
{
    [BindableProperty(
        DefaultValue = 42,
        ValidateValueMethodName = "ValidateValue",
        PropertyChangedMethodName = "OnPropertyChanged",
        PropertyChangingMethodName = "OnPropertyChanging",
        CoerceValueMethodName = "CoerceValue",
        DefaultValueCreatorMethodName = "CreateDefaultValue")]
     public partial int Value { get; set; }

     // Use [PropertyChanged], [PropertyChanging] attribute with either the single-parameter or two-parameter partial methods (or both) inspired by CommunityToolkit.Mvvm 8.4.0.
     [PropertyChanged]
     partial void OnPropertyChanged(int value) { /* ... */ }
     partial void OnPropertyChanged(int oldValue, int newValue) { /* ... */ }
     [PropertyChanging]
     partial void OnPropertyChanging(int value) { /* ... */ }
     partial void OnPropertyChanging(int oldValue, int newValue) { /* ... */ }
     
     // Alternatively, use [PropertyChanged], [PropertyChanging] attribute with regular methods.
     [PropertyChanged]
     void OnPropertyChanged(int oldValue, int newValue) { /* ... */ }
     [PropertyChanging]
     void OnPropertyChanging(int oldValue, int newValue) { /* ... */ }
     
     // For [ValidateValue], [CoerceValue] and [CreateDefaultValue] we only offer regular methods.
     [ValidateValue]
     bool ValidateValue(int value) { /* ... */ return true; }
     [CoerceValue]
     int CoerceValue(int value) { /* ... */ return value; }
     [CreateDefaultValue]
     int CreateDefaultValue() { /* ...*/ return 0; }
}

If [PropertyChanged]/[PropertyChanging] are attached to partial methods, then the source generator will generate the static method and invoke those partial methods:

public partial class TestClass
{
    static void OnPropertyChanged(BindableObject bindable, object oldValue, object newValue)
    {
        ((TestCase)b).OnPropertyChanged((int)newValue);
        ((TestCase)b).OnPropertyChanged((int)oldValue, (int) newValue);
    }
    partial void OnPropertyChanged(int value);
    partial void OnPropertyChanged(int oldValue, int newValue);
    static void OnPropertyChanging(BindableObject bindable, object oldValue, object newValue)
    {
        ((TestCase)b).OnPropertyChanging((int)newValue);
        ((TestCase)b).OnPropertyChanging((int)oldValue, (int) newValue);
    }
    partial void OnPropertyChanging(int value);
    partial void OnPropertyChanging(int oldValue, int newValue);
}

If [PropertyChanged]/[PropertyChanging] are attached to regular methods, then the source generator will create the static to non-static wrappers:

public partial class TestClass
{
    static void OnPropertyChanged(BindableObject b, object o, object n) => ((TestCase)b).OnPropertyChanged((int)o, (int)n);
    static void OnPropertyChanging(BindableObject b, object o, object n) => ((TestCase)b).OnPropertyChanging((int)o, (int)n);
}

For [ValidateValue], [CoerceValue], [CreateDefaultValue] the source generator will create static to non-static wrappers:

public partial class TestClass
{
    static bool ValidateValue(BindableObject b, object v) => ((TestCase)b).ValidateValue((int)v);
    static void object CoerceValue(BindableObject b, object v) => ((TestCase)b).CoerceValue((int)v);
    static void object CreateDefaultValue(BindableObject b) => ((TestCase)b).CreateDefaultValue();
}

Redacted original proposal

Instead of asking developers to write static methods for source generators, we could make things easier by letting them use regular instance methods. The benefit is that the methods are simpler, requiring no BindableProperty parameter or manual casting to the class type, since the source generator handles this automatically.

For example:

public partial class TestClass : View
{
    [BindableProperty(
        DefaultValue = 42,
        ValidateValueMethodName = "ValidateValue",
        PropertyChangedMethodName = "OnPropertyChanged",
        PropertyChangingMethodName = "OnPropertyChanging",
        CoerceValueMethodName = "CoerceValue",
        DefaultValueCreatorMethodName = "CreateDefaultValue")]
     public partial int Value { get; set; }

     bool ValidateValue(object value) => true;
     void OnPropertyChanged(object oldValue, object newValue) { }
     void OnPropertyChanging(object oldValue, object newValue) { }
     object CoerceValue(object value) => value;
     object CreateDefaultValue() => 0;
}

Would generate a wrapper that includes the BindableObject bindable property:

public partial class TestClassName
{
    /// <summary>
    /// Backing BindableProperty for the <see cref = "Value"/> property.
    /// </summary>
    public static readonly global::Microsoft.Maui.Controls.BindableProperty ValueProperty = global::Microsoft.Maui.Controls.BindableProperty.Create(
       "Value",
       typeof(int),
       typeof(TestNamespace.TestClassName),
       (int)42,
       (Microsoft.Maui.Controls.BindingMode)1,
       (b,v) => ((TestClassName)b).ValidateValue(v),
       (b,o,n) => ((TestClassName)b).OnPropertyChanged(o,n),
       (b,o,n) => ((TestClassName)b).OnPropertyChanging(o,n),
       (b,v) => ((TestClassName)b).CoerceValue(v),
       (b) => ((TestClassName)b).CreateDefaultValue());
    public partial int Value {
        get => (int)GetValue(ValueProperty);
        set => SetValue(ValueProperty, value);
    }
}

Alternatives

There’s merit in revisiting whether some of these behaviors should be default for BindableProperty. Given how often PropertyChanged and PropertyChanging are used, we might want to always generate the partial property wrappers.

**Al
Tentative PR

• BindableProperty non-static method name enhancement #3002

[TheCodeTraveler]

Hey Stephen! I plan on creating an Analyzer that will generate a compiler error if a developer supplies a method name that is using an invalid method signature.

This analyzer will ensure that developers always use the correct return type and parameter types, and it'll also ensure the method is static, providing a helpful message telling them what's required.

The Analyzer should cover scenarios where a developer forgets to supply a static method to [BindableProperty].

[stephenquan]

Hi Brandon - thanks for the rapid response! An Analyzer would definitely be useful for catching mistakes with the current static method setup. What I'm suggesting, though, is a shift away from requiring static methods altogether. In my proposed generator changes, a static wrapper would handle casting the bindable object to the right type, so developers can just write normal instance methods and let the generator take care of the rest.

[stephenquan]

I have an evolution of this idea that I posted in the PR comments #3002 (comment)

[stephenquan]

Redacted comment (it is copied/moved to root comment)

Because `PropertyChanged` and `PropertyChanging` are void methods, we can treat them similarly to the partial methods in `CommunityToolkit.Mvvm 8.4.0`. e.g.

public partial class TestClass : View
{
    [BindableProperty(
        DefaultValue = 42,
        PropertyChangedMethodName = "OnPropertyChanged",
        PropertyChangingMethodName = "OnPropertyChanging")]
    public partial int Value { get; set; }
     
    [PropertyChanged]
    partial void OnPropertyChanged(int value) { }
    partial void OnPropertyChanged(int oldValue, int newValue) { }
    [PropertyChanging]
    partial void OnPropertyChanging(int value) { }
    partial void OnPropertyChanging(int oldValue, int newValue) { }
}

The [PropertyChanged]/[PropertyChanging] can be attached to either 1 or 2 partial methods. The source generator will look at the method name and the method's argument type(s). Based on that, it has enough information to generate the static wrappers and matching partial methods.

public partial class TestClass
{
    static void OnPropertyChanged(BindableObject bindable, object oldValue, object newValue)
    {
        ((TestCase)b).OnPropertyChanged((int)newValue);
        ((TestCase)b).OnPropertyChanged((int)oldValue, (int) newValue);
    }
    partial void OnPropertyChanged(int value);
    partial void OnPropertyChanged(int oldValue, int newValue);
    static void OnPropertyChanging(BindableObject bindable, object oldValue, object newValue)
    {
        ((TestCase)b).OnPropertyChanging((int)newValue);
        ((TestCase)b).OnPropertyChanging((int)oldValue, (int) newValue);
    }
    partial void OnPropertyChanging(int value);
    partial void OnPropertyChanging(int oldValue, int newValue);
}