Stable channel release notes for the Windows App SDK

Article
02/29/2024

The stable channel provides releases of the Windows App SDK that are supported for use by apps in production environments. Apps that use the stable release of the Windows App SDK can also be published to the Microsoft Store.

The following releases of the stable channel are currently available:

Version 1.5
Version 1.4
Version 1.3
Version 1.2
Version 1.1
Version 1.0
Version 0.8
Version 0.5

If you'd like to upgrade an existing app from an older version of the Windows App SDK to a newer version, see Update existing projects to the latest release of the Windows App SDK.

Downloads for Windows App SDK

Note

The Windows App Visual Studio Extensions (VSIX) are no longer distributed as a separate download. They are available in the Visual Studio Marketplace inside Visual Studio.

Version 1.5

Version 1.5.2 (1.5.240404000)

This is a servicing release of the Windows App SDK that includes critical bug fixes for the 1.5 release and a new feature for Widget feed providers.

Feed providers are now able to show announcements in the Widgets Dashboard:
- The new FeedManager.TryShowAnnouncement API allows a Feed Provider to request that the Widget Dashboard show their announcements. To show your announcement, create a FeedAnnouncement object and call the FeedManager.TryShowAnnouncement API.
- Feed announcements will have their own badges displayed in the taskbar that can be customized using the FeedAnnouncement API.
Feed providers can now opt in to receive Analytics and Error Reports information about their provider as a user interacts with it. To opt in, implement the IFeedProviderAnalytics and/or IFeedProviderErrors interfaces by your provider.

The feed provider updates includes the following new APIs:

Microsoft.Windows.Widgets.Feeds.Providers
 
    FeedAnalyticsInfoReportedArgs
    FeedErrorInfoReportedArgs
    FeedManager
        SendMessageToContent
        TryShowAnnouncement
 
    FeedMessageReceivedArgs
    FeedResourceRequest
    FeedResourceRequestedArgs
    FeedResourceResponse
    IFeedAnnouncementInvokedTarget
    IFeedManager2
    IFeedProviderAnalytics
    IFeedProviderErrors
    IFeedProviderMessage
    IFeedResourceProvider

Microsoft.Windows.Widgets.Notifications
 
    AnnouncementActionKind
    AnnouncementTextColor
    FeedAnnouncement
    FeedAnnouncementInvokedArgs

Bug fixes

Fixed an issue where DispatcherTimer would not fire at the correct time if the primary display wasn't running at 60 Hz.
Fixed an issue where a textbox input method editor (IME) window would be incorrectly positioned when running at a scale factor other than 100%. For more info, see GitHub issue #9382.
Fixed an issue where a drag-and-drop operation started from another app might not allow the correct Copy/Move/Link drop operations.
Fixed a potential crash when a ListView's ItemsSource is reset and given focus right away.
Fixed a problem where ShouldConstrainToRootBounds="false" popups/flyouts don't apply any inherited scale transform. For more info, see GitHub issues #9118 and #9433.
Fixed a potential crash when a Composition object is destroyed with an animation still running.
Fixed a potential crash on shutdown in NavigationView::RevokeNavigationViewItemRevokers.

Version 1.5.1 (1.5.240311000)

This is a servicing release of the Windows App SDK that includes critical bug fixes for the 1.5 release.

Fixed an issue where self-contained apps may fail to build due to not being able to copy "map.html".
Fixed an issue where MapControl would fail to initialize due to rejecting valid tokens. For more info, see GitHub issue #9324.
Fixed an issue where MapControl loaded with a blue background. For more info, see GitHub issue #9377.
Fixed an issue where clicking on the chevron of a NavigationViewItem did not correctly expand or collapse on a single click. This also caused menus to show as blank when clicking the chevron in PaneDisplayMode="Top" mode. For more info, see GitHub issues #9423 and #9426.
Fixed an issue where tapping on a NavigationViewItem with touch or pen would prevent the item from responding to any future input. For more info, see GitHub issue #9429.
Fixed a crash when clicking on an item in the NavigationView.PaneFooter area. For more info, see GitHub issue #9396.
Fixed an issue where icons in menus were sometimes showing in the wrong place. For more info, see GitHub issue #9409.
Fixed an issue where acrylic does not show on menus until switching away from the window and back. For more info, see GitHub issue #9406.
Fixed a crash which could occur during TextBox/RichEditBox initialization. For more info, see GitHub issue #9216.
Fixed some noisy exceptions which NavigationView threw and caught on destruction.
Fixed an issue where a "pinch to zoom" gesture would sometimes show up as a pan or tap due to an incorrect PointerCaptureLost message firing.

Version 1.5

The following sections describe new and updated features and known issues for version 1.5.

In an existing Windows App SDK 1.4 app, you can update your Nuget package to 1.5.240227000 (see the Update a package section in Install and manage packages in Visual Studio using the NuGet Package Manager).

For the updated runtime and MSIX, see Downloads for the Windows App SDK.

XAML Islands runtime and shutdown updates

There is a behavioral difference between WinAppSDK 1.4 and WinAppSDK 1.5 for XAML Islands-based apps when the last XAML Window on any thread is closed.

In WinAppSDK 1.4, the XAML runtime always exits the thread's event loop when the last XAML window on a thread is closed.
In WinAppSDK 1.5:
- If your app is a WinUI Desktop app, the default behavior is still the same as in WinAppSDK 1.4.
- If you're using XAML for the DesktopWindowXamlSource ("XAML Islands") API, the default behavior is now that XAML does not automatically exit the thread's event loop.
- In both modes, you can change this behavior by setting the Application.DispatcherShutdownMode property.

For more information, see the documentation for the Application.DispatcherShutdownMode property when available. This completes GitHub proposal #8492.

There is a behavioral difference between WinAppSDK 1.4 and WinAppSDK 1.5 for XAML Islands-based apps in the lifetime of the XAML runtime:

In WinAppSDK 1.4, the XAML runtime shuts down on a thread if either all WindowsXamlManager and DesktopWindowXamlSource objects on a given thread are closed or shut down, or the DispatcherQueue running on that thread is shut down (in this case, the XAML runtime shuts down during the DispatcherQueue.FrameworkShutdownStarting stage).
In WinAppSDK 1.5, the XAML runtime shuts down on a thread only when the DispatcherQueue running on that thread is shut down (the Xaml runtime always shuts down during the DispatcherQueue.FrameworkShutdownStarting stage).

For more information, see the documentation for the WindowsXamlManager class when available.

There is a behavioral difference in WindowsXamlManager.InitializeForCurrentThread():

In WinAppSDK 1.4, WindowsXamlManager.InitializeForCurrentThread() returns a unique instance of a WindowsXamlManager object with each call.
In WinAppSDK 1.5, WindowsXamlManager.InitializeForCurrentThread() returns an existing instance if one already exists on the thread. Close/Dispose() is now ignored.

WinUI Maps control

The WinUI Maps control is now available! This control is powered by WebView2 and Azure Maps, providing the following features:

Panning and zooming with either the map buttons or touch.
Changing the style of the map to satellite, terrain, or street view.
Programatically adding interactable pins with developer-customizable icons to the map.
Developer customization for where the map is centered on initial load.
Control for developers over hiding or showing the buttons for panning, zooming, and map styles.

WinUI 3 Maps Control

Note

To use the Maps control, you'll need an Azure Maps key. To create the key, see the Azure Maps documentation page for creating a web app.

The Maps control is entirely new and we welcome your feedback to evaluate its future direction!

New SelectorBar control

In 1.5, we've added a new SelectorBar control for enabling users to switch between multiple views of data. This control was previously known as "SegmentedControl" on our 1.5 roadmap.

WinUI 3 SelectorBar Control

Labels in the CommandBarFlyout primary commands

The visuals of the CommandBarFlyout have been updated to display a text label for the items in the primary commands area if the Label property has been set on the AppBarButton. Previously, the primary commands in the CommandBarFlyout area only displayed an icon, but now they can show both an icon and a label for improved usability.

WinUI 3 CommandBarFlyout Labels

WebView2 support for custom environment/options

The WinUI WebView2 control now exposes the ability to customize the underlying CoreWebView2 object with a custom CoreWebView2Environment and CoreWebView2ControllerOptions. This enables the app author to specify an alternate path from which to load the WebView2Runtime, choose to use a different UserDataFolder, or set options such as IsPrivateModeEnabled and ScriptLocale.

Suppport for .NET 8

We added support for .NET 8 in a recent 1.4 servicing release, but that still kept the warning for the use of platform-specific RIDs. In 1.5, we completed that work so that the warning is no longer present.

Improved debugging and source availability

We now inject Github source server information for code in the microsoft-ui-xaml repo into our public symbols, allowing debuggers to automatically download source code. We also made other fixes and improvements to our symbols across the entire WinAppSDK to improve the debugging experience.

Improved functionality for debugging layout cycles

Debugging layout cycles in a WinUI app can be a challenge, so in 1.5 the DebugSettings object now exposes options to enable improved logging and breakpoints for the layout process to make it easier to debug and fix layout cycles in the app.

Other new features from across the WinAppSDK

Added support for the PublishSingleFile deployment model. For more info about PublishSingleFile, see the Single-file deployment documentation.
Added improvements to screen reader support, text scaling support, and other accessibility features.
Various stability and performance improvements based on our prioritized GitHub bug backlog.

New features being released separately

New versions of the WinAppSDK Visual Studio Templates for C# and C++ are being released through the Visual Studio Marketplace and they will appear a few weeks after the release of 1.5. With the new version, the templates may now be released independently of WinAppSDK releases, giving us much more flexibility in getting updates to customers.

Other previously planned features

In 1.5, we made progress on the following features that we announced on our roadmap, but did not complete them. They will continue into the 1.6 timeframe.

Tabbed windows
Drag-n-drop support for WebView2
Investigations into the table view and ink controls

Dynamic lighting has been removed from the roadmap for the time being.

Known issues

When using libraries which contain resources such as .xaml files, you may hit an error message at runtime indicating that those resources cannot be found. In this case, it might be necessary to insert <ShouldComputeInputPris>true</ShouldComputeInputPris> in the project file to ensure those resources get included.
Clicking on the chevron of a NavigationViewItem no longer correctly expands or collapses on a single click. Double-clicking still works, as does clicking elsewhere on the NavigationViewItem.