github CommunityToolkit/Maui 17.0.0
v17.0.0: Update to .NET 11
on GitHub

latest releases: 12.0.0-mediaelement, 8.0.0-camera
3 hours ago

This release updates CommunityToolkit.Maui to .NET 11.

It also enables Runtime Async only on the net11.0-windows TFM. Runtime Async is not enabled on the Mono Runtime and is not recommended for any NuGet library that may be consumed by an app using the Mono Runtime.

We have removed code supporting the Tizen TFM as Tizen was no longer supported in .NET MAUI starting with .NET 10.

We have also removed code supporting CommunityToolkit.Maui.Maps. See the Release Notes for CommunityToolkit.Maui.Maps v5.0.0 for more information.

Breaking Changes

The update to .NET 11 required us to modify some APIs and their underlying behavior. Please find the features you use, below, and update your apps accordingly.

All packages
API
  • Minimum OS versions in the API. The AppBuilderExtensions classes declare [SupportedOSPlatform] iOS 15.0, Mac Catalyst 17.0 and Android 24.0 (MediaElement: Android 26.0), the .NET MAUI 11 minimums. Attributes that only restated a version below these minimums are removed or made versionless; this only relaxes the analyzer. Feature-specific changes are in the CameraView, FileSaver and FolderPicker, MediaElement, NavigationBar (Android), SemanticOrderView, and StatusBar and StatusBarBehavior sections.
  • No Tizen API surface. The Tizen [SupportedOSPlatform] and [UnsupportedOSPlatform] attributes and the Tizen code paths are removed.
Behavior
  • Converters use the culture the binding passes. With no ConverterCulture, .NET MAUI passes CultureInfo.CurrentUICulture, as .NET MAUI 10 did.
    • These converters used the thread's CurrentCulture instead: ColorToCmykStringConverter, ColorToHslStringConverter, ColorToHslaStringConverter, CompareConverter, IsInRangeConverter, ListToStringConverter, MathExpressionConverter and MultiMathExpressionConverter.
    • Their output changes only when ConverterCulture is set or when an app's UI language differs from its regional format.
    • TextCaseConverter always used invariant casing instead, so its output also changes when the binding's culture is Turkish or Azerbaijani (see its section).
    • A null culture (calling a converter directly) keeps the previous behavior.
    • Each converter's section says what it does with the culture. ColorToRgbaStringConverter, DateTimeOffsetConverter and DoubleToIntConverter have separate changes, also in their sections.
Setup
  • .NET 11 only. The libraries target net11.0 and its platforms; .NET 10 apps should stay on the last .NET 10 releases (CommunityToolkit.Maui 15.x, CommunityToolkit.Maui.Camera 6.x, CommunityToolkit.Maui.MediaElement 10.x). The minimum OS versions are .NET MAUI 11's: iOS 15.0, Mac Catalyst 17.0 (macOS 14), Android 7.0 (API 24), Windows 10 1809 (10.0.17763); CommunityToolkit.Maui.MediaElement still requires Android 8.0 (API 26). .NET MAUI 11 itself no longer supports the older versions.
  • Tizen is no longer supported. The packages already shipped no Tizen target; .NET MAUI 11 dropped Tizen.
  • Dependencies: the libraries reference .NET MAUI 11 (Microsoft.Maui.Controls 11.0.0), and CommunityToolkit.Maui.Core references System.Speech 11.0.0 on Windows (pending: RC versions until the last commit).
Smaller changes
  • Windows: the async methods of the net11.0-windows assemblies are runtime async. No API or functional change: the compiler no longer generates async state machines for these methods (except async void ones), and the runtime handles their suspension instead.
  • Informational, from .NET MAUI 11: on iOS and Mac Catalyst, .NET MAUI 11 skips animations while the system's Reduce Motion setting is on, so the toolkit's animations (TouchBehavior, FadeAnimation, the animation behaviors) finish at once for those users. The toolkit doesn't change this.
CameraView
API
  • CommunityToolkit.Maui.Camera declares [SupportedOSPlatform] Windows 10.0.17763 (was 10.0.10240), like the other libraries.
ColorConversionExtensions
API
  • New ToCmykString(CultureInfo?) and ToHslString(CultureInfo?) overloads. A null culture uses CurrentCulture.
Behavior
  • ToHslaString(CultureInfo?) formats the hue, saturation and lightness with the given culture too, not only the alpha, so the string no longer mixes two cultures. A null culture still uses CurrentCulture.
ColorToCmykStringConverter, ColorToHslStringConverter and ColorToHslaStringConverter
Behavior
  • Percentages are formatted with the culture the binding passes (see All packages).
  • ColorToHslaStringConverter: the string no longer mixes two cultures (see ColorConversionExtensions).
ColorToRgbaStringConverter
Behavior
  • Converts back its own output in comma-decimal cultures; before, RGBA(255,0,0,0,5) under de-DE converted back to Transparent. A direct call with a null culture uses CurrentCulture both ways. (The HSLA and CMYKA converters are one-way.)
CompareConverter
Behavior
  • Strings are compared with the culture's collation, using the culture the binding passes (see All packages).
DateTimeOffsetConverter
Behavior
  • No longer applies the culture's calendar to the date: it produced wrong years under th-TH and fa-IR and threw under ar-SA. It also keeps sub-microsecond ticks.
DoubleToIntConverter
Behavior
  • Parses a string ConverterParameter with the invariant culture first, so ConverterParameter=2.5 means 2.5 for every user, and falls back to the binding's culture, so 2,5 still works in comma-decimal cultures.
  • A parameter with only . separators is now always a decimal: 1.000 under de-DE means 1 (it meant 1000).
DrawingView
Behavior
  • On iOS and Mac Catalyst, exporting an image off the main thread no longer risks a crash on .NET 11's CoreCLR (the CGColor of a temporary UIColor could be freed while it was read).
EventToCommandBehavior
API
  • New EventToCommandBehavior.EventArgsConverterCulture property (CultureInfo?, default null = CultureInfo.InvariantCulture, the previous behavior).
FileSaver and FolderPicker
API
  • The [SupportedOSPlatform] attributes iOS14.0/MacCatalyst14.0 on FileSaver and FolderPicker are now iOS/MacCatalyst (see All packages).
Behavior
  • On Windows (.NET 11):
    • With no visible app window they fail with FileSaveException / FolderPickerException ("No active window found") as on .NET 10, instead of opening a dialog over a hidden window.
    • An app with no windows no longer gets an ArgumentOutOfRangeException, and .NET MAUI embedded in a WinUI app no longer gets a false "No active window found".
    • Canceling the CancellationToken closes the open save or folder dialog and returns a canceled result, as on .NET 10, instead of waiting until the person closes the dialog. If the person has the "Confirm Save As" prompt open, the save ends canceled once they answer it, and nothing is written.
    • Picks on the same window now take turns: a pick that starts while another FileSaver or FolderPicker dialog is open on that window waits until that dialog closes, and canceling its token ends the wait with a canceled result.
    • A cancel can still close a dialog that other code opened on the same window during the canceled pick, such as the app's own message box, because nothing marks a picker dialog as the toolkit's.
GravatarImageSource
Behavior
  • The default-image keyword sent to Gravatar is lowercased with the invariant culture. Under Turkish and Azerbaijani cultures identicon and monsterid were sent as ıdenticon and monsterıd, which Gravatar doesn't recognize.
IsInRangeConverter
Behavior
  • Strings are compared with the culture's collation, using the culture the binding passes (see All packages).
ListToStringConverter
Behavior
  • Numbers and dates in the list are formatted with the culture the binding passes (see All packages).
  • A custom item type whose ToString() differs from its IFormattable.ToString(null, provider) changes output even without a culture.
Maps
API
  • CommunityToolkit.Maui.Maps is removed. There is no .NET 11 version of the package; UseMauiCommunityToolkitMaps, its AppBuilderExtensions and MapHandlerWindows no longer exist. See Setup below.
Setup
  • Change the package and the startup call. Remove the CommunityToolkit.Maui.Maps package, its using CommunityToolkit.Maui.Maps; directives and the UseMauiCommunityToolkitMaps call; reference the Microsoft.Maui.Controls.Maps package directly (the toolkit package referenced it for you) and call builder.UseMauiMaps() on every platform.
  • On Windows also call builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY")), because there the map is the WinUI 3 MapControl backed by Azure Maps and shows no map data without a valid key.
  • On Windows, .NET MAUI's Map has no IsShowingUser, no polygons, polylines or circles in MapElements, no pin labels or info windows, and no MapClicked; MoveToRegion, the Street, Satellite and Hybrid map types, traffic, scrolling, zooming and pins work.
  • See https://learn.microsoft.com/dotnet/maui/user-interface/controls/map?view=net-maui-10.0 and #3190.
MathExpressionConverter and MultiMathExpressionConverter
Behavior
  • The expression syntax is culture-invariant. Numbers in the expression always use . and every function name works in every culture; before, 3.5 meant 35 under de-DE and threw under fr-FR, and names containing I (PI, IF, MIN, SIN, INT, CEILING, ...) failed under tr-TR and az.
  • String inputs and str()/len() use the culture the binding passes (see All packages).
  • Quoted strings in the expression are values: they convert with the binding's culture, like the bound inputs, and are lowercased with invariant rules (under tr-TR "I" becomes "i", not "ı").
MediaElement
API
  • maccatalyst16.1, which only restated a version below the new minimums, is removed from MediaElement's iOS members, where #3222 added it after MediaElement 10.0.0 (see All packages).
NavigationBar (Android)
API
  • android23.0 is removed from NavigationBar. This only relaxes the analyzer: NavigationBar is no longer marked Android-only for code built for other platforms, where its platform-specific properties do nothing.
SemanticOrderView
API
  • Android22.0, which only restated a version below the new minimums, is removed from MauiSemanticOrderView (see All packages).
Source generators
Smaller changes
  • [BindableProperty] and [AttachedBindableProperty]: the generated code no longer depends on the build machine's culture. On a Turkish or Azerbaijani machine an internal class generated ınternal partial class and a read-only IsBusy generated ısBusyPropertyKey; in comma-decimal and some other cultures, numeric default values generated invalid literals such as 3,1400000000000001 or −1 (U+2212). All of these broke the app's build. Documentation comments in the generated code also use CRLF on every build machine.
StatusBar and StatusBarBehavior
API
  • android23.0 is removed from StatusBar, and from StatusBarBehavior, where #3344 added it. This only relaxes the analyzer.
Smaller changes
  • StatusBar outside iOS and Android: the NotSupportedException message now reads "... is only supported on iOS and Android" (it said "Android 23 and later").
TextCaseConverter
Behavior
  • Casing uses the culture the binding passes (see All packages); before, it was always invariant. Only Turkish and Azerbaijani dotted and dotless I differ, so the output changes for apps whose UI language or ConverterCulture is Turkish or Azerbaijani: Upper turns istanbul into İSTANBUL (it was ISTANBUL). A null culture keeps the invariant casing.

What's Changed

Housekeeping

  • Bump actions/setup-java from 6.1.0 to 6.2.0 by @dependabot[bot] in #3376
  • [housekeeping] Automated PR to fix formatting errors by @github-actions[bot] in #3386
  • Bump actions/setup-dotnet from 6.0.0 to 6.1.0 by @dependabot[bot] in #3377
  • Bump the dotnet-tools group with 3 updates by @dependabot[bot] in #3379
  • Bump Microsoft.Extensions.Logging.Console from 10.0.11 to 10.0.14 by @dependabot[bot] in #3382
  • Bump PolySharp from 1.16.0 to 1.17.0 by @dependabot[bot] in #3389
  • Bump xunit.v3 from 4.0.2 to 4.0.3 by @dependabot[bot] in #3390

Full Changelog: 16.0.0...17.0.0

Check out latest releases or
releases around CommunityToolkit/Maui 17.0.0

Don't miss a new Maui release

NewReleases is sending notifications on new releases.

Get notifications