14.0.0: Introducing Bindable Property Source Generators!

[TheCodeTraveler]

CommunityToolkit.Maui v14.0.0

I am excited to debut two new source generators!

• [BindableProperty]
• [AttachedBindableProperty<T>]

These new source generators make it easier than ever to create a BindableProperty for your .NET MAUI apps by allowing us to write all the associated boiler-plate code for you. In fact, all Bindable Properties in CommunityToolkit.Maui are now automatically generated using these new source generators!

For an in-depth overview of both [BindableProperty] and [AttachedBindableProperty<T>], check out my comprehensive write-up:
👉 https://codetraveler.io/introducing-bindable-property-source-generators/

Bug Fixes

Alongside the new Source Generators, this Release also brings important bug fixes:

• StatusBar
  • Fixes StatusBar on Android 35+
• Popup
  • Add extension method for NavigatedFromEventArgs
  • Fixes tapping issues when using a CollectionView in Popup
  • Fixes memory leaks

Introducing Bindable Property Source Generators

Opt-into this Experimental Feature

We have decided to release this feature using the [Experimental] attribute. This allows us to let you try out its features and provide feedback while giving us the flexibility to update it with your feedback over the next few releases.

In the csproj file of your .NET MAUI app, add the following code:

<!-- Opt into Binbdable Property Source Generators -->
<PropertyGroup>
    <NoWarn>MCTEXP001</NoWarn>
</PropertyGroup>

In the mean-time, we will be writing more comprehensive documentation and writing Analyzers, similar to CommunityToolkit.MVVM, to help provide you the best coding experience!

Using [BindableProperty]

To leverage the Bindable Property Source Generator, first ensure you using a partial class. Then, add the partial keyword and attach the [BindableProperty] attribute to your property:

1. Add the partial keyword to the class
2. Add the partial keyword the Property for which to generate an associated Bindable Property
3. Add the [BindableProperty] attribute to the property to make it bindable

using CommunityToolkit.Maui;

namespace BindablePropertySourceGeneratorSample;

public partial class CustomButton : Button
{
    [CommunityToolkit.Maui.BindableProperty] 
    public partial int? Number { get; set; }
}

The above example generates the following Bindable Property:

public partial class CustomButton
{
    /// <summary>
    /// BindableProperty for the <see cref = "Number"/> property.
    /// </summary>
    public static readonly global::Microsoft.Maui.Controls.BindableProperty NumberProperty = global::Microsoft.Maui.Controls.BindableProperty.Create("Number", typeof(int?), typeof(BindablePropertySourceGeneratorSample.CustomButton), null, Microsoft.Maui.Controls.BindingMode.OneWay, null, null, null, null, null);
    public partial int? Number { get => (int)GetValue(NumberProperty); set => SetValue(NumberProperty, value); }
}

For more in-depth examples see my comprehensive write-up on [BindableProperty]:
👉 https://codetraveler.io/introducing-bindable-property-source-generators/

Using [AttachedBindableProperty<T>]

Using [AttachedBindableProperty] is a bit different. This attribute is applied to either the Class or the Constructor, not a Property, as Attached Properties are not required to have an associated Property:

.NET Multi-platform App UI (.NET MAUI) attached properties enable an object to assign a value for a property that its own class doesn't define

To leverage the Attached Bindable Property Source Generator, first ensure you using a partial class. Then, add [AttachedBindableProperty<T>] attribute to either the class or constructor:

1. Add the partial keyword to the class
2. Add the [AttachedBindableProperty<T>] attribute to the class or constructor for which to generate an associated Attached Property

namespace BindablePropertySourceGeneratorSample;

[CommunityToolkit.Maui.AttachedBindableProperty<int>("Number")] 
public partial class CustomButton : Button
{
  public CustomButton()
  {
  }
}

Alternatively, the attribute can be attached to the constructor:

namespace BindablePropertySourceGeneratorSample;
 
public partial class CustomButton : Button
{
  [CommunityToolkit.Maui.AttachedBindableProperty<int>("Number")]
  public CustomButton()
  {
  }
}

Both examples above generate the following Attached Property along with its associated Get/Set methods:

public partial class CustomButton
{
    /// <summary>
    /// Attached BindableProperty for the Number property.
    /// </summary>
    public static readonly global::Microsoft.Maui.Controls.BindableProperty NumberProperty = global::Microsoft.Maui.Controls.BindableProperty.CreateAttached("Number", typeof(int), typeof(BindablePropertySourceGeneratorSample.CustomButton), null, (global::Microsoft.Maui.Controls.BindingMode)0, null, null, null, null, null);
    /// <summary>
    /// Gets Number for the <paramref name = "bindable"/> child element.
    /// </summary>
    public static int GetNumber(global::Microsoft.Maui.Controls.BindableObject bindable) => (int)bindable.GetValue(NumberProperty);
    /// <summary>
    /// Sets Number for the <paramref name = "bindable"/> child element.
    /// </summary>
    public static void SetNumber(global::Microsoft.Maui.Controls.BindableObject bindable, int value) => bindable.SetValue(NumberProperty, value);
}

For more in-depth examples see my comprehensive write-up on [AttachedBindableProperty<T>]:
👉 https://codetraveler.io/introducing-bindable-property-source-generators/

What's Changed

• Fix StatusBar on Android 35+ by @TheCodeTraveler in Fix StatusBar on Android 35+ #2939
• [CameraView][iOS] Favor Photo Formats During Default Resolution Selection by @phunkeler in [CameraView][iOS] Favor Photo Formats During Default Resolution Selection #2941
• Fixes Obsolete Warnings and NuGet Package Dependency Warnings by @VladislavAntonyuk in Fixes Obsolete Warnings and NuGet Package Dependency Warnings #2944
• Update ColorConversionExtensions.shared.cs by @stephenquan in Update ColorConversionExtensions.shared.cs #2945
• Improve CameraView Performance by @zhitaop in Improve CameraView Performance #2909
• Add popup related navigation extension methods by @jamesbrooksbank in Add popup related navigation extension methods #2955
• [Housekeeping] Add ReferenceAssembliesExtensions extension for ReferenceAssemblies.Net.Net100 by @TheCodeTraveler in [Housekeeping] Add ReferenceAssembliesExtensions extension for ReferenceAssemblies.Net.Net100 #2956
• Update [BindableProperty] Support for Additional Scenarios, Add CommunityToolkit.Maui.SourceGenerators.Internal.UnitTests, Implement [BindableProperty] for Behaviors by @TheCodeTraveler in Update [BindableProperty] Support for Additional Scenarios, Add CommunityToolkit.Maui.SourceGenerators.Internal.UnitTests, Implement [BindableProperty] for Behaviors #2932
• Add CommunityToolkit.Maui.SourceGenerator.Benchmarks, Reduce Memory Allocations on [BindableProperty] Source Generator by @TheCodeTraveler in Add CommunityToolkit.Maui.SourceGenerator.Benchmarks, Reduce Memory Allocations on [BindableProperty] Source Generator #2960
• Use [BindableProperty] for RatingView by @CliffAgius in Use [BindableProperty] for RatingView #2964
• Cleanup Popup Resources When Closed by @AlejoTorresLeon in Cleanup Popup Resources When Closed #2971
• Fix camera view regression by @zhitaop in Fix camera view regression  #2951
• Implement [BindableProperty] for MediaElement by @ne0rrmatrix in Implement [BindableProperty] for MediaElement #2933
• Bindable property for camera view by @ne0rrmatrix in Bindable property for camera view #2974
• Add missing AudioSessionIdChanged stub to android MediaElement by @ne0rrmatrix in Add missing AudioSessionIdChanged stub to android MediaElement #2992
• Add [Experimental] To [BindableProperty] by @TheCodeTraveler in Add [Experimental] To [BindableProperty] #2990
• Extend BindableProperty source gen to handle partial property initializers by @stephenquan in Extend BindableProperty source gen to handle partial property initializers #2987
• Add BoxView behind the Popup content to safely handle touch interaction by @bijington in Add BoxView behind the Popup content to safely handle touch interaction #2997
• Bindable property for Popup by @ne0rrmatrix in Bindable property for Popup #2991
• Remove BindablePropertyAttribute.DefaultValue by @TheCodeTraveler in Remove BindablePropertyAttribute.DefaultValue #2995
• Refactor Animations to use [BindableProperty] partial properties by @ne0rrmatrix in Refactor Animations to use [BindableProperty] partial properties #3013
• Refactor Views to use [BindableProperties] partial properties by @ne0rrmatrix in Refactor Views to use [BindableProperties] partial properties #3017
• Implement [BindableProperty] for Converters by @TheCodeTraveler in Implement [BindableProperty] for Converters #3018
• Implement [BindableProperty] for ImageSources, Add [BindableProperty] Support for internal Properties by @TheCodeTraveler in Implement [BindableProperty] for ImageSources, Add [BindableProperty] Support for internal Properties #3019
• Use Copy instead of Move in FileSaver UI on iOS by @matt-goldman in Use Copy instead of Move in FileSaver UI on iOS #2981
• Fix MediaElement windows fails to playback by @ne0rrmatrix in Fix MediaElement windows fails to playback #2915
• Support null values in NumericValidationBehavior by @reck1610 in Support null values in NumericValidationBehavior #2886
• Refactor Layouts to use [BindableProperty] partial properties by @ne0rrmatrix in Refactor Layouts to use [BindableProperty] partial properties #3016
• Implement [BindableProperty] for ValidationBehaviors by @TheCodeTraveler in Implement [BindableProperty] for ValidationBehaviors #3000
• Remove ReferenceAssembliesExtensions by @TheCodeTraveler in Remove ReferenceAssembliesExtensions #3038
• Create [AttachedBindableProperty<T>] by @TheCodeTraveler in Create [AttachedBindableProperty<T>] #3024
• Fix memory leak on snackbar by @pictos in Fix memory leak on snackbar #3034
• Fix Windows Picker Initial Path is not set by @VladislavAntonyuk in Fix Windows Picker Initial Path is not set #3030
• Fix clicking on notification does not restore activity by @ne0rrmatrix in Fix clicking on notification does not restore activity #2979
• Prepare [AttachedBindableProperty<T>] and [BindableProperty] for Release by @TheCodeTraveler in Prepare [AttachedBindableProperty<T>] and [BindableProperty] for Release #3047
• Fix memory leak by changing now playing artwork request handler by @MarcelStommel in Fix memory leak by changing now playing artwork request handler #3051
• Add support to make AndroidForegroundService optional to MediaElement by @ne0rrmatrix in Add support to make AndroidForegroundService optional to MediaElement #2658

New Contributors

• @jamesbrooksbank made their first contribution in Add popup related navigation extension methods #2955
• @AlejoTorresLeon made their first contribution in Cleanup Popup Resources When Closed #2971
• @matt-goldman made their first contribution in Use Copy instead of Move in FileSaver UI on iOS #2981
• @reck1610 made their first contribution in Support null values in NumericValidationBehavior #2886
• @MarcelStommel made their first contribution in Fix memory leak by changing now playing artwork request handler #3051

Full Changelog: 13.0.0...14.0.0

---

This discussion was created from the release 14.0.0: Introducing Bindable Property Source Generators!.

[matt-goldman]

Hey @TheCodeTraveler, thanks so, so much for this! The bindable property source generator is going to be an absolute game changer.

I've been playing with it and I've noticed a couple of problems. I've got a repo here: https://github.com/matt-goldman/MCTBPSG

Should I open an issue (or issue) for these? Or discuss here or in a new discussion? Just want to check because it's still experimental, and your blog post specifically mentions using discussions.

[ne0rrmatrix]

I looked at your sample and I think I figured out the issue. You need to use ContentView and not a ContentPage for the controls when you add the BindableProperty in BindableView.xaml and that will resolve the error.

[ne0rrmatrix]

Also set android to min version 26 will fix another issue

[matt-goldman]

Urgh....that's annoying. That ContentPage/ContentView thing is a bad habit I seem to have only picked up over the past 2 months. Anyway I actually noticed the issue in another project where I was using ContentView, I just created this as a sample. Fixing that solved the crash on Windows, thanks!

I didn't notice any other issues, but updated android min to 26 anyway. But I still get the warning.

Edit to add: I mean I don't notice any other errors. The two issues in my repo that I noted were the Windows crash (solved, PEBKAC), and the compiler warning.

[ne0rrmatrix]

I have passed on the message about the warning. I saw it too.

[TheCodeTraveler]

CS0436 Warning Fixed in #3073

[juan-ibanez-incontrol]

Hello @TheCodeTraveler,

Thank you so much for this feature — it's really cool! 🙌
In my current project I'm using:

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

and I had to add CS0436 to the NoWarn list to make everything build cleanly.

<NoWarn>MCTEXP001,CS0436</NoWarn>

Just wanted to share — thanks again for the great work!

[TheCodeTraveler]

Thanks! I'm on it 🫡

The CS0436 warning is a bug I'll fix in the next release.

[TheCodeTraveler]

CS0436 Warning Fixed in #3073

[kobbok]

Any reason why CommunityToolkit.Maui.MediaElement v8.0.0 was not deployed to Nuget yet?
Both CommunityToolkit.Maui v14 and CommunityToolkit.Maui.Camera v6 seem to be deployed?

[TheCodeTraveler]

Good catch! Those should've been published last week.

@jfversluis Are you able to publish CommunityToolkit.Maui.MediaElement v8.0.0 and CommunityToolkit.Maui.Camera v6.0.0 to NuGet this week? I created the GitHub Release for both last week alongside CommunityToolkit.Maui v14.0.0.

[kobbok]

@TheCodeTraveler CommunityToolkit.Maui.Camera v6.0.0 is on nuget: https://www.nuget.org/packages/CommunityToolkit.Maui.Camera/6.0.0

It's just MediaElement that's missing for some reason.

[TheCodeTraveler]

Thanks for confirming 🙌

[jfversluis]

MediaElement has been released! The build failed because of a flaky unit test, retriggered it and released to NuGet now, thanks!

[stephenquan]

The [BindableProperty] source generator makes it easier to post code snippets answers, e.g. dotnet/maui#20406 (comment) 😊

[zwikk]

The [BindableProperty] source generator is excellent, love it! I did notice, however, an issue when applying styling through the source‑generated XAML inflator. See #3070

[robin-juette]

The [BindableProperty] sg sounds awesome, can't wait to try it.

But please don't release this as a regular update if it depends on prerelease-libraries!

The dependency on Microsoft.WindowsAppSDK >= 2.0.0-experimental3 breaks publish in a way that was (for me) pretty hard to detect.

Still thanks for all the great work you do with this toolkit!

[TheCodeTraveler]

Fixed #3076