Latest stable channel release notes for the Windows App SDK
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.
Important links:
- 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.
Stable channel release note archive:
- Stable channel release notes for the Windows App SDK 1.5
- Stable channel release notes for the Windows App SDK 1.4
- Stable channel release notes for the Windows App SDK 1.3
- Stable channel release notes for the Windows App SDK 1.2
- Stable channel release notes for the Windows App SDK 1.1
- Stable channel release notes for the Windows App SDK 1.0
- Stable channel release notes for the Windows App SDK 0.8
- Stable channel release notes for the Windows App SDK 0.5
Note
The Windows App SDK Visual Studio Extensions (VSIX) are no longer distributed as a separate download. They are available in the Visual Studio Marketplace inside Visual Studio.
This is a servicing release of the Windows App SDK that includes critical bug fixes for the 1.6 release.
- Fixed an issue where reading the
AppWindow.ExtendsContentIntoTitleBar
property turns on custom titlebar rendering. For more info, see GitHub issue #9988. - Fixed a potential crash during destruction of a
TextBox
/RichEditBox
. For more info, see GitHub issue #9070. - Fixed an issue where
PackageDeploymentManager.IsPackageReadyOrNewerAvailable()
failed. For more info, see GitHub issue #4817. - Fixed an issue where
ScrollViewer
would leak. - Added detection for a rare scenario where the app stops rendering and never recovers.
- Fixed an issue where
PackageDeploymentManager.RegisterPackageSetAsync()
requires URI when it should be optional to register by PackageFamilyName. - Fixed an issue that prevented apps from being installed or uninstalled. For more info, see GitHub issue #4881.
This release includes the following new APIs which allow for providers of Widgets to incorporate web content in their Widgets:
Microsoft.Windows.Widgets.Providers
IWidgetManager2
IWidgetProviderMessage
IWidgetResourceProvider
WidgetManager
SendMessageToContent
WidgetMessageReceivedArgs
WidgetResourceRequest
WidgetResourceRequestedArgs
WidgetResourceResponse
This is a servicing release of the Windows App SDK that includes critical bug fixes for the 1.6 release.
- Fixed a crash when using FocusVisualKind.Reveal(). For more info, see GitHub issue #9966.
- Fixed noisy C++ exceptions from Bcp47Langs.dll. For more info, see GitHub issue #4691. Note that this fix removes the synchronization with
Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride
. - Fixed an issue where an extra
Unloaded
event was raised immediately after showing aContentDialog
. For more info, see GitHub issue #8402. - Fixed an issue where a CommandBar menu might have incorrectly opened up even when there was room for it to open down.
- Fixed some issues where input to
InputNonClientPointerSource
regions was not handled correctly when the top-level window was running in right-to-left mode. - Fixed the compile-time check for the Windows SDK framework version to handle the slightly different framework name used for .NET 9.
The following sections describe new and updated features and known issues for version 1.6.
In an existing Windows App SDK 1.5 app, you can update your Nuget package to 1.6.240829007 (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.
When updating a C++ project to 1.6, you'll need to add a project reference to the Microsoft.Web.WebView2
package. If you update via NuGet Package Manager in Visual Studio, this dependency will be added for you.
In 1.6, Windows App SDK managed apps require Microsoft.Windows.SDK.NET.Ref *.*.*.38
or later, which can be specified via WindowsSdkPackageVersion in your csproj
file. For example:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
<WindowsSdkPackageVersion>10.0.22621.38</WindowsSdkPackageVersion>
<PropertyGroup>
...
In addition, Windows App SDK managed apps should update to Microsoft.Windows.CsWinRT 2.1.1
(or later).
Note
These manual references will no longer be needed once the next .NET SDK servicing update is released.
The .NET PublishAot
project property is now supported for native Ahead-Of-Time compilation. For details on Native AOT, see Native AOT Deployment. Because AOT builds on Trimming support, much of the following trimming-related guidance applies to AOT as well.
For PublishAot
support and trimming support, in addition to the C# project changes described in the previous section you'll also need a package reference to Microsoft.Windows.CsWinRT 2.1.1
(or later) to enable the source generator from that package until the next .NET SDK servicing update is released when it will no longer be required.
For more info, see the CsWinRT Trimming / AOT support doc and the CsWinRT 2.1.1 Release Notes.
Because the Windows App SDK invokes publishing targets when F5 deploying, we recommend enabling PublishAot
at NuGet restore time by adding this to your csproj
file:
<PublishAot>true</PublishAot>
In this release, the developer is responsible for ensuring that all types are properly rooted to avoid trimming (such as with reflection-based {Binding}
targets). Later releases will enhance both C#/WinRT and the XAML Compiler to automate rooting where possible, alert developers to trimming risks, and provide mechanisms to resolve.
C#/WinRT also includes PublishAot
support in version 2.1.1. To enable a class for AOT publishing with C#/WinRT, it must first be marked partial
. This allows the C#/WinRT AOT source analyzer to attribute the classes for static analysis. Only classes (which contain methods, the targets of trimming) require this attribute.
The CsWinRT source generator might generate code that makes use of unsafe
. If you hit such an error during compilation or a diagnostic warning for it (CS0227 for "Unsafe code may only appear if compiling with /unsafe"), you should set EnableUnsafeBlocks to true. For more info, see GitHub issue CsWinRT #1721.
The WebView2 projections in Microsoft.Web.WebView2
package version 1.0.2651.64 are not yet AOT compatible. This will be fixed in an upcoming release of the Microsoft.Web.WebView2
package, which you can then reference in your project.
To enable AOT compatibility, reflection-based techniques should be replaced with statically typed serialization, AppContext.BaseDirectory, typeof(), etc. For details, see Introduction to trim warnings.
Until full support for {Binding}
is implemented, types may be preserved from trimming as follows:
Given project P
consuming assembly A
with type T
in namespace N
, which is only dynamically referenced (so normally trimmed), T
can be preserved via:
P.csproj
:
<ItemGroup>
<TrimmerRootDescriptor Include="ILLink.Descriptors.xml" />
</ItemGroup>
ILLink.Descriptors.xml
:
<?xml version="1.0" encoding="utf-8"?>
<linker>
<assembly fullname="A">
<type fullname="N.T" preserve="all" />
</assembly>
</linker>
For complete root descriptor XML expression syntax, see Root Descriptors.
Note
Dependency packages that have not yet adopted AOT support may exhibit runtime issues.
The Windows App SDK now consumes the Edge WebView2 SDK as a NuGet reference rather than embedding a hardcoded version of the Edge WebView2 SDK. The new model allows apps to choose a newer version of the Microsoft.Web.WebView2
package instead of being limited to the version with which the Windows App SDK was built. The new model also allows apps to reference NuGet packages which also reference the Edge WebView2 SDK. For more info, see GitHub issue #5689.
The Package Management API has received several enhancements including Is*ReadyOrNewerAvailable*(), EnsureReadyOptions.RegisterNewerIfAvailable, Is*Provisioned*(), IsPackageRegistrationPending(), and several bug fixes. See PackageManagement.md and Pull Request #4453 for more details.
TabView
supports a new CanTearOutTabs
mode which provides an enhanced experience for dragging tabs and dragging out to a new window. When this new option is enabled, tab dragging is very much like the tab drag experience in Edge and Chrome where a new window is immediately created during the drag, allowing the user to drag it to the edge of the screen to maximize or snap the window in one smooth motion. This implementation also doesn't use drag-and-drop APIs, so it isn't impacted by any limitations in those APIs. Notably, tab tear-out is supported in processes running elevated as Administrator.
- Added a new
ColorHelper.ToDisplayName()
API, filling that gap from UWP. - Added a new
Microsoft.Windows.Globalization.ApplicationLanguages
class, which notably includes a newPrimaryLanguageOverride
feature. For more info, see GitHub issue #4523. - Unsealed
ItemsWrapGrid
. This should be a backward-compatible change. PipsPager
supports a new mode where it can wrap between the first and last items.
RatingControl
is now more customizable, by moving some hard-coded style properties to theme resources. This allows apps to override these values to better customize the appearance of RatingControl.
- WinUI 3 has changed to the typographic model for font selection rather than the legacy weight/stretch/style model. The typographic model is required for some newer fonts, including Segoe UI Variable, and enables enhanced font capabilities. Some older fonts which rely on the weight/stretch/style model for selection may not be found with the typographic model.
- If the debugger is set to break on all C++ exceptions, it will break on some noisy exceptions on start-up in the BCP47 (Windows Globalization) code. For more info, see GitHub issue #4691.
- Component library packages which reference the WinAppSDK 1.6 package will not correctly get the referenced WebView2 package contents. For more info, see WebView2Feedback #4743. A workaround is to add a direct reference to the
Microsoft.Web.WebView2
package where needed. - Apps compiled with Native AOT might sometimes experience a hanging issue after page navigation due to a race condition in the .NET runtime's GC thread. For more info, see .NET issue #104582.
- The initial release of 1.6.0 introduced an issue with one of our dependencies that we expect will be resolved in an upcoming release of the .NET SDK. If you experience an error with the version of your Microsoft.Windows.SDK.NET reference, you’ll need to explicitly reference the version of the .NET SDK that is specified by your error message. For example, if the error says you need version 10.0.19041.38, add the following to your
.csproj
file:<WindowsSdkPackageVersion>10.0.19041.38</WindowsSdkPackageVersion>
.
- Fixed a crash when setting
InfoBar.IsOpen
in .xaml. For more info, see GitHub issue #8391. - Fixed an issue where HTML elements would lose pointer capture when the mouse moved outside of the
WebView2
bounds. For more info, see GitHub issue #8677. - Fixed an issue where drag and drop into a flyout with
ShouldConstrainToRootBounds=false
did not work. For more info, see GitHub issue #9276. - Fixed an issue where
ms-appx://
references did not work whenPublishSingleFile
is enabled. For more info, see GitHub issue #9468. - Fixed an issue where debugger symbols weren't working correctly for some binaries. For more info, see GitHub issue #4633.
- Fixed a potential crash when subclassing
NavigationView
. - Fixed an issue where table borders in a
RichEditBox
would not correctly erase when scrolling or reducing the size of the table. - Fixed an issue where flyouts from
MediaTransportControls
had a fully transparent background. - Fixed an issue where dragging into a WebView2 would fail or drop in the wrong location on display scale factors other than 100% or when system text scaling is enabled.
- Fixed an issue where
TextBox
/RichEditBox
would not announce to Accessibility tools when input is blocked due to being at theMaxLength
limit. - Fixed a few issues around handling of custom titlebar scenarios. For more info, see GitHub issues #7629, #9670, #9709 and #8431.
- Fixed an issue where
InfoBadge
icon was not visible. For more info, see GitHub issue #8176. - Fixed an issue with icons sometimes showing in the wrong position in
CommandBarFlyout
. For more info, see GitHub issue #9409. - Fixed an issue with keyboard focus in menus when opening or closing a sub menu. For more info, see GitHub issue #9519.
- Fixed an issue with
TreeView
using the incorrectIsExpanded
state when recycling items. For more info, see GitHub issue #9549. - Fixed an issue when using an ElementName binding in an
ItemsRepeater.ItemTemplate
. For more info, see GitHub issue #9715. - Fixed an issue with the first item in an
ItemsRepeater
sometimes having an incorrect position. For more info, see GitHub issue #9743. - Fixed an issue with
InputNonClientPointerSource
sometimes breaking input to the min/max/close buttons. For more info, see GitHub issue #9749. - Fixed a compile error when using Microsoft.UI.Interop.h with clang-cl. For more info, see GitHub issue #9771.
- Fixed an issue where the
CharacterReceived
event was not working inComboBox
/TextBox
. For more info, see GitHub issue #9786. - Fixed an issue where duplicate
KeyUp
events were raised for arrow and tab keys. For more info, see GitHub issue #9399. - Fixed an issue where the
PowerManager.SystemSuspendStatusChanged
event was unusable to get theSystemSuspendStatus
. For more info, see GitHub issue #2833. - Fixed an issue where initial keyboard focus was not correctly given to a
WebView2
when that was the only control in the window. - Fixed an issue when using
ExtendsContentIntoTitleBar=true
where the Min/Max/Close buttons did not correctly appear in the UI Automation, which prevented Voice Access from showing numbers for those buttons. - Fixed an issue where an app might crash in a lock check due to unexpected reentrancy.
- Fixed an issue where
Hyperlink
colors did not correctly update when switching into a high contrast theme. - Fixed an issue where changing the collection of a
ListView
in a background window may incorrectly move that window to the foreground and take focus. - Fixed an issue where calling
ItemsRepeater.StartBringIntoView
could sometimes cause items to disappear. - Fixed an issue where touching and dragging on a
Button
in aScrollViewer
would leave it in a pressed state. - Updated IntelliSense, which was missing information for many newer types and members.
- Fixed an issue where clicking in an empty area of a
ScrollViewer
would always move focus to the first focusable control in theScrollViewer
and scroll that control into view. For more info, see GitHub issue #597. - Fixed an issue where the
Window.Activated
event sometimes fired multiple times. For more info, see GitHub issue #7343. - Fixed an issue where setting the
NavigationViewItem.IsSelected
property totrue
prevented its children from showing when expanded. For more info, see GitHub issue #7930. - Fixed an issue where
MediaPlayerElement
would not properly display captions withNone
orDropShadow
edge effects. For more info, see GitHub issue #7981. - Fixed an issue where the
Flyout.ShowMode
property was not used when showing the flyout. For more info, see GitHub issue #7987. - Fixed an issue where
NumberBox
would sometimes have rounding errors. For more info, see GitHub issue #8780. - Fixed an issue where using a library compiled against an older version of WinAppSDK could hit an error trying to find a type or property. For more info, see GitHub issue #8810.
- Fixed an issue where initial keyboard focus was not set when launching a window. For more info, see GitHub issue #8816.
- Fixed an issue where
FlyoutShowMode.TransientWithDismissOnPointerMoveAway
didn't work after the first time it was shown. For more info, see GitHub issue #8896. - Fixed an issue where some controls did not correctly template bind
Foreground
andBackground
properties. For more info, see GitHub issue #7070, #9020, #9029, #9083 and #9102. - Fixed an issue where
ThemeResource
s used inVisualStateManager
setters wouldn't update on theme change. This commonly affected controls in flyouts. For more info, see GitHub issue #9198. - Fixed an issue where
WebView
would lose key focus, resulting in extra blur/focus events and other issues. For more info, see GitHub issue #9288. - Fixed an issue where
NavigationView
could show a binding error in debug output. For more info, see GitHub issue #9384. - Fixed an issue where SVG files defining a negative viewbox no longer rendered. For more info, see GitHub issue #9415.
- Fixed an issue where changing
ItemsView.Layout
orientation caused an item to be removed. For more info, see GitHub issue #9422. - Fixed an issue where scrolling a
ScrollView
generated a lot of debug output. For more info, see GitHub issue #9434. - Fixed an issue where
MapContorl.InteractiveControlsVisible
did not work properly. For more info, see GitHub issue #9486. - Fixed an issue where
MapControl.MapElementClick
event didn't properly fire. For more info, see GitHub issue #9487. - Fixed an issue where x:Bind didn't check for null before using a weak reference, which could result in a crash. For more info, see GitHub issue #9551.
- Fixed an issue where changing the
TeachingTip.Target
property didn't correctly update its position. For more info, see GitHub issue #9553. - Fixed an issue where dropdowns did not respond in WebView2. For more info, see GitHub issue #9566.
- Fixed a memory leak when using
GeometryGroup
. For more info, see GitHub issue #9578. - Fixed an issue where scrolling through a very large number of items from an
ItemRepeater
in aScrollView
could cause blank render frames. For more info, see GitHub issue #9643. - Fixed an issue where
SceneVisual
wasn't working.
Version 1.6.0 includes the following new APIs compared to the stable 1.5 release:
Microsoft.UI
ColorHelper
ToDisplayName
Microsoft.UI.Input
EnteredMoveSizeEventArgs
EnteringMoveSizeEventArgs
ExitedMoveSizeEventArgs
InputNonClientPointerSource
EnteredMoveSize
EnteringMoveSize
ExitedMoveSize
WindowRectChanged
WindowRectChanging
MoveSizeOperation
WindowRectChangedEventArgs
WindowRectChangingEventArgs
Microsoft.UI.Xaml
XamlRoot
CoordinateConverter
Microsoft.UI.Xaml.Automation.Peers
ScrollPresenterAutomationPeer
Microsoft.UI.Xaml.Controls
PipsPager
WrapMode
WrapModeProperty
PipsPagerWrapMode
TabView
CanTearOutTabs
CanTearOutTabsProperty
ExternalTornOutTabsDropped
ExternalTornOutTabsDropping
TabTearOutRequested
TabTearOutWindowRequested
TabViewExternalTornOutTabsDroppedEventArgs
TabViewExternalTornOutTabsDroppingEventArgs
TabViewTabTearOutRequestedEventArgs
TabViewTabTearOutWindowRequestedEventArgs
Microsoft.Windows.Globalization
ApplicationLanguages
Microsoft.Windows.Management.Deployment
EnsureReadyOptions
RegisterNewerIfAvailable
PackageDeploymentFeature
PackageDeploymentManager
IsPackageDeploymentFeatureSupported
IsPackageProvisioned
IsPackageProvisionedByUri
IsPackageReadyOrNewerAvailable
IsPackageReadyOrNewerAvailableByUri
IsPackageSetProvisioned
IsPackageSetReadyOrNewerAvailable
PackageReadyOrNewerAvailableStatus
Microsoft.Windows.Storage
ApplicationData
ApplicationDataContainer
ApplicationDataContract
ApplicationDataCreateDisposition
ApplicationDataLocality
Windows developer feedback
Windows developer is an open source project. Select a link to provide feedback: