Experimental channel release notes for the Windows App SDK

Important

The experimental channel is not supported for use in production environments, and apps that use the experimental releases cannot be published to the Microsoft Store.

The experimental channel provides releases of the Windows App SDK that include experimental channel features that are in early stages of development. APIs for experimental features have the Experimental attribute. If you call an experimental API in your code, you will receive a build-time warning. All APIs in the experimental channel might have breaking changes in future releases, but experimental APIs are especially subject to change. Experimental features may be removed from the next release, or may never be released.

Important links:

Experimental channel releases:

Version 1.5 Experimental (1.5.0-experimental2)

This is the latest release of the experimental channel. To download, retarget your WinAppSDK NuGet version to 1.5.240124002-experimental2.

Bug fixes

This release includes the following bug fixes:

  • Fixed an issue causing apps to crash on startup when using a custom NavigationViewItem. For more info, see GitHub issue #8814.
  • Fixed a NavigationView issue where the ellipsis button would incorrectly generate an error. For more info, see GitHub issue #8380.
  • Fixed an issue where a SystemBackdrop would not render properly in a multi-window app. For more info, see GitHub issue #8423.
  • Fixed a duplication issue when inserting into the beginning of an ObservableCollection. For more info, see GitHub issue #8370.

New APIs

1.5-experimental2 includes the following new APIs. These APIs are not experimental, but are not yet included in a stable release version of the WinAppSDK.

Microsoft.Graphics.DirectX
 
    DirectXPixelFormat
        A4B4G4R4
Microsoft.UI.Xaml
 
    DebugSettings
        LayoutCycleDebugBreakLevel
        LayoutCycleTracingLevel
 
    LayoutCycleDebugBreakLevel
    LayoutCycleTracingLevel
Microsoft.UI.Xaml.Automation.Peers
 
    SelectorBarItemAutomationPeer
Microsoft.UI.Xaml.Controls
 
    MapControl
    MapControlMapServiceErrorOccurredEventArgs
    MapElement
    MapElementClickEventArgs
    MapElementsLayer
    MapIcon
    MapLayer
    SelectorBar
    SelectorBarItem
    SelectorBarSelectionChangedEventArgs
    WebView2
        EnsureCoreWebView2Async
        EnsureCoreWebView2Async
Microsoft.Windows.Management.Deployment
 
    EnsureReadyOptions
    PackageDeploymentManager
        AddPackageSetAsync
        DeprovisionPackageAsync
        DeprovisionPackageByUriAsync
        DeprovisionPackageSetAsync
        EnsurePackageReadyAsync
        EnsurePackageReadyByUriAsync
        EnsurePackageSetReadyAsync
        IsPackageReady
        IsPackageReadyByUri
        IsPackageRegistrationPending
        IsPackageRegistrationPendingForUser
        ProvisionPackageAsync
        ProvisionPackageByUriAsync
        ProvisionPackageSetAsync
        RegisterPackageAsync
        RegisterPackageByUriAsync
        RegisterPackageSetAsync
        RemovePackageByUriAsync
        RepairPackageAsync
        RepairPackageByUriAsync
        RepairPackageSetAsync
        ResetPackageAsync
        ResetPackageByUriAsync
        ResetPackageSetAsync
        StagePackageAsync
        StagePackageByUriAsync
        StagePackageSetAsync
 
    PackageDeploymentProgress
    PackageDeploymentResult
        Error
        ErrorText
 
    PackageSet
        Items
        PackageUri
 
    PackageVolume
        FindPackageVolumeByName
        FindPackageVolumeByPath
        FindPackageVolumes
        IsRepairNeeded
        Repair
 
    ProvisionPackageOptions
    RegisterPackageOptions
        DependencyPackageFamilyNames
 
    RemovePackageOptions
        FailIfNotFound

Additional Experimental APIs

This release includes the following new and modified experimental APIs:

Microsoft.UI.Xaml
 
    Application
        DispatcherShutdownMode
 
    DispatcherShutdownMode
    XamlIsland
        SystemBackdrop
Microsoft.UI.Xaml.Hosting
 
    WindowsXamlManager
        IsXamlRunningOnCurrentThread
        XamlShutdownCompletedOnThread
 
    XamlShutdownCompletedOnThreadEventArgs
Microsoft.Windows.System.Workloads
 
    IWorkloadHandler
    Workload
    WorkloadManager
    WorkloadProgress
    WorkloadProgressStatus
    WorkloadResult
    WorkloadsContract
    WorkloadStatus

Version 1.5 Experimental (1.5.0-experimental1)

This is the latest release of the experimental channel. To download, retarget your WinAppSDK NuGet version to 1.5.231202003-experimental1.

New APIs

1.5-experimental1 includes the following new APIs. These APIs are not experimental, but are not yet included in a stable release version of the WinAppSDK.

Microsoft.Windows.Widgets.Feeds.Providers
    CustomQueryParametersRequestedArgs
    CustomQueryParametersUpdateOptions
    FeedDisabledArgs
    FeedEnabledArgs
    FeedManager
    FeedProviderDisabledArgs
    FeedProviderEnabledArgs
    FeedProviderInfo
    IFeedManager
    IFeedProvider

Additional Experimental APIs

This release includes the following new and modified experimental APIs:

Microsoft.UI.Content
 
    ContentIsland
        ConnectionInfo
        ConnectRemoteEndpoint
        IsRemoteEndpointConnected
 
    ContentIslandEnvironment
        CurrentOrientation
        DisplayScale
        NativeOrientation
        ThemeChanged
 
    ContentSiteEnvironment
        CurrentOrientation
        DisplayScale
        NativeOrientation
        NotifyThemeChanged
 
    DesktopChildSiteBridge
        AcceptRemoteEndpoint
        ConnectionInfo
        IsRemoteEndpointConnected
        RemoteEndpointConnecting
        RemoteEndpointDisconnected
        RemoteEndpointRequestedStateChanged
 
    EndpointConnectionEventArgs
    EndpointRequestedStateChangedEventArgs
    IContentIslandEndpointConnectionPrivate
    IContentSiteBridgeEndpointConnectionPrivate
    ProcessStarter
    SystemVisualSiteBridge
        IsClosed
Microsoft.UI.Input
 
    FocusNavigationReason
    FocusNavigationRequest
    FocusNavigationRequestEventArgs
    FocusNavigationResult
    InputFocusController
        DepartFocus
        NavigateFocusRequested
 
    InputFocusNavigationHost
Microsoft.UI.Xaml
 
    DebugSettings
        LayoutCycleDebugBreaks
        LayoutCycleTracing
 
    LayoutCycleDebugBreakLevel
    LayoutCycleTracingLevel
    XamlIsland
Microsoft.UI.Xaml.Controls
 
    SelectionModel
        SelectAllFlat
Microsoft.UI.Xaml.Core.Direct
 
    XamlPropertyIndex
        FlyoutBase_SystemBackdrop
        Popup_SystemBackdrop
Microsoft.Windows.Management.Deployment
 
    AddPackageOptions
    AddPackageSetOptions
    DeploymentPriority
    DeploymentProcessingModel
    EnsureIsReadyOptions
    FindPackageSetOptions
    PackageDeploymentContract
    PackageDeploymentManager
    PackageDeploymentProgress
    PackageDeploymentProgressStatus
    PackageDeploymentResult
    PackageDeploymentStatus
    PackageRuntimeManager
    PackageSet
    PackageSetItem
    PackageSetItemRuntimeDisposition
    PackageSetManager
    PackageSetRuntimeDisposition
    PackageVolume
    PackageVolumeManager
    PackageVolumeStatus
    RegisterPackageOptions
    RemovePackageOptions
    StagePackageOptions
    StubPackageOption

Version 1.4 Experimental (1.4.0-experimental1)

This is the latest release of the experimental channel. To download, retarget your WinAppSDK NuGet version to 1.4.230518007-experimental1.

Bug fixes

This release contains miscellaneous fixes, including the following:

  • Fixed an issue where enabling the debug settings framerate counter in a new WinUI desktop application caused an access violation. For more information, see issue 2835 on GitHub.
  • Fixed an issue where horizontal scrolling on a touchpad did not work in a WebView2 web page. For more information, see issue 7772 on GitHub.

Additional Experimental APIs

This release includes the following new and modified experimental APIs:

Microsoft.UI

   IClosableNotifier
Microsoft.UI.Composition.SystemBackdrops

   DesktopAcrylicController
       Closed
       FrameworkClosed
       Kind

   DesktopAcrylicKind
   MicaController
       Closed
       FrameworkClosed
Microsoft.UI.Content

   ContentAppWindowBridge
       SettingChanged

   ContentEnvironmentSettingChangedEventArgs
   ContentExternalBackdropLink
   ContentExternalOutputLink
       ExternalOutputBorderMode

   ContentIsland
       FrameworkClosed

   ContentIslandWindow
       SettingChanged

   ContentSite
       FrameworkClosed

   ContentSiteWindow
       NotifySettingChanged
       SettingChanged

   CoreWindowTopLevelWindowBridge
       SettingChanged

   DesktopSiteBridge
       Closed
       FrameworkClosed

   IContentWindow
       SettingChanged

   SystemVisualSiteBridge
       Closed
       FrameworkClosed
Microsoft.UI.Input

   InputLayoutPolicy
   InputNonClientPointerSource
       ConfigurationChanged
       GetForWindowId

   NonClientRegionConfigurationChangedEventArgs
Microsoft.UI.System

   ThemeSettings
Microsoft.UI.Windowing

   DisplayArea
       GetMetricsFromWindowId
Microsoft.UI.Xaml

   XamlRoot
       ContentWindow
Microsoft.UI.Xaml.Controls

   ItemContainer
       Child
       ChildProperty

   ItemContainerMultiSelectMode
       Extended

   ItemsView
       Animator
       AnimatorProperty

   MenuFlyoutPresenter
       SystemBackdrop
       SystemBackdropProperty

   RiverFlowLayout
       InvalidateItemsInfo
       RequestedRangeCount
       RequestedRangeStartIndex

   RiverFlowLayoutElementAnimator
Microsoft.UI.Xaml.Controls.Primitives

   CommandBarFlyoutCommandBar
       SystemBackdrop
       SystemBackdropProperty
Microsoft.UI.Xaml.Input

   AccessKeyManager
       EnterDisplayMode

Version 1.3 Experimental (1.3.0-experimental1)

This is the latest release of the experimental channel. To download, retarget your WinAppSDK NuGet version to 1.3.230202101-experimental1.

XAML Backdrop APIs

With properties built in to the XAML Window, Mica & Background Acrylic backdrops are now easier to use in your WinUI 3 app. See the Xaml Backdrop API spec on GitHub for more information about the Window.SystemBackdrop property.

Of note in this release, you're able to set the backdrop only in code-behind, as below. Setting <Window.SystemBackdrop> in markup results in a compile error. Additionally, the Xaml Backdrop APIs are currently missing an 'experimental' tag as they are under active development.

public MainWindow()
{
    this.InitializeComponent();

    this.SystemBackdrop = new MicaBackdrop();
}

Window.AppWindow

Replacing several lines of boilerplate code, you're now able to use AppWindow APIs directly from an Window through Window.AppWindow. See the Window.AppWindow API spec on GitHub for additional background and usage information.

New features from across WinAppSDK

  • ApplicationModel.DynamicDependency: PackageDependency.PackageGraphRevisionId that replaces the deprecated MddGetGenerationId.
  • Environment Manager: EnvironmentManager.AreChangesTracked to inform you whether changes to the environment manager are able to be tracked in your application. See the Environment Manager API spec on GitHub for more information.
  • MRT Core: A new event, Application.ResourceManagerInitializing allows your app to provide its own implementation of the IResourceManager interface, and gives you access to the ResourceManager that WinUI uses to resolve resource URIs.
  • With the latest experimental VSIX, you're now able to convert your app between unpackaged and packaged through the Visual Studio menu instead of in your project file.
  • A new event, DebugSettings.XamlResourceReferenceFailed is now raised when a referenced Static/ThemeResource lookup can't be resolved. This event gives access to a trace that details where the framework searched for that key in order to better enable you to debug Static & ThemeResource lookup failures. For more information, see issues 4972, 2350, and 6073 on GitHub.

Bug fixes

  • Fixed issues with touch input causing the soft keyboard to not appear on text boxes. For more information, see issue 6291 on GitHub.
  • Fixed issue causing an ItemsRepeater with an IElementFactory as its ItemTemplate to throw an ArgumentException. For more info, see issue 4705 on GitHub.

Additional Experimental APIs

This release also includes several APIs that are in early development.

The list below details the APIs introduced in this experimental release that we don't plan to ship in the 1.3.0 stable release.

**Microsoft.UI.Content**

    DesktopSiteBridge
        GetInputEnabledToRoot
        GetVisibleToRoot
        InputEnabled
**Microsoft.UI.Dispatching**

    DispatcherQueue
        FrameworkShutdownStarting
**Microsoft.UI.Input**

    InputLightDismissAction
        GetForIsland

    InputNonClientPointerSource
    InputPointerActivationBehavior
    InputPointerSource
        ActivationBehavior

    NonClientRegionCaptionTappedEventArgs
    NonClientRegionHoverEventArgs
    NonClientRegionKind
**Microsoft.UI.Input.DragDrop**

    DragDropManager
    DragDropModifiers
    DragInfo
    DragOperation
    DragUIContentMode
    DragUIOverride
    DropOperationTargetRequestedEventArgs
    IDropOperationTarget
**Microsoft.UI.Xaml.Automation.Peers**

    ItemContainerAutomationPeer
    ItemsViewAutomationPeer
**Microsoft.UI.Xaml.Controls**

    AnnotatedScrollBar
    AnnotatedScrollBarLabel
    AnnotatedScrollBarScrollEventArgs
    AnnotatedScrollBarScrollEventType
    AnnotatedScrollBarScrollOffsetRequestedEventArgs
    AnnotatedScrollBarSubLabelRequestedEventArgs
    AnnotatedScrollBarValueRequestedEventArgs
    ElementFactory
        GetElement
        GetElementCore
        RecycleElement
        RecycleElementCore

    IndexBasedLayoutOrientation
    ItemContainer
    ItemContainerInteractionTrigger
    ItemContainerInvokedEventArgs
    ItemContainerMultiSelectMode
    ItemContainerUserInvokeMode
    ItemContainerUserSelectMode
    ItemsView
    ItemsViewItemInvokedEventArgs
    ItemsViewItemInvokeMode
    ItemsViewSelectionMode
    Layout
        IndexBasedLayoutOrientation

    NonVirtualizingLayout
        IndexBasedLayoutOrientationCore

    RiverFlowLayout
    RiverFlowLayoutItemsInfoRequestedEventArgs
    RiverFlowLayoutItemsJustification
    RiverFlowLayoutItemsStretch
    VirtualizingLayout
        IndexBasedLayoutOrientationCore

    VirtualizingLayoutContext
        VisibleRect
        VisibleRectCore
**Microsoft.Graphics.Display**

    DisplayInformation
        AngularOffsetFromNativeOrientation
        DpiChanged
        OrientationChanged
        RawDpi
        RawPixelsPerViewPixel

    DisplayOrientation
**Microsoft.UI.Xaml.Hosting**

    DesktopWindowXamlSource
        CreateSiteBridge
        SiteBridge
        SystemBackdrop

Version 1.2 Experimental (1.2.0-experimental2)

This is the latest release of the experimental channel. It supports all experimental channel features and features from 1.2.0-preview 1.

To download, retarget your WinAppSDK NuGet version to 1.2.220909.2-experimental2.

Fixed issue

In upcoming Windows Insider Preview builds, applications using Windows App SDK would fail to launch.

Version 1.2 Experimental (1.2.0-experimental1)

This is the latest release of the experimental channel. It supports all experimental channel features.

To download, retarget your WinAppSDK NuGet version to 1.2.220727.1-experimental1.

Input & Composition

First introduced in Windows App SDK 0.8, there are several experimental classes in the Microsoft.UI.Input.Experimental & Microsoft.UI.Composition.Experimental namespaces.

New to this release:

Content

New to this release, the experimental classes in the Microsoft.UI.Content namespace provide the building blocks of interactive content. These are low level primitives that can be assembled into content to provide the interactive experience for an end user. The content defines the structure for: rendering output with animations, processing input on different targets, providing accessibility representation, and handling host state changes.

Notable APIs:

  • ContentIsland - brings together Output, Input, and Accessibility and provides the abstraction for interactive content. A custom visual tree can be constructed and made interactive with these APIs.
  • DesktopChildSiteBridge - enables a ContentIsland to be connected into a HWND-based hierarchy.

Check out the sample on GitHub for more information.

Dispatching

DispatcherQueue now dispatches as reentrant. Previously, no more than a single DispatcherQueueHandler callback could be active on a single thread at a time. Now, if a handler starts a nested message pump, additional callbacks dispatch as reentrant. This matches Win32 behavior around window messages and nested message pumps.

Notifications

Registering app display name and icon for app notification is now supported. Check out the spec on GitHub for additional information.

WinUI 3

  • Controls and styles are up to date with the WinUI 2.8 release.
  • UWP is no longer supported in the experimental releases.

Other limitations and known issues

  • Apps need to be rebuilt after updating to Windows App SDK 1.2-experimental1 due to a breaking change introduced in the ABI.
  • Apps that reference a package that depends on WebView2 (like Microsoft.Identity.Client) fail to build. This is caused by conflicting binaries at build time. See issue 2492 on GitHub for more information.
  • Using dotnet build with a WinAppSDK C# class library project may see a build error "Microsoft.Build.Packaging.Pri.Tasks.ExpandPriContent task could not be loaded". To resolve this issue set <EnableMsixTooling>true</EnableMsixTooling> in your project file.
  • The default WinAppSDK templates note that the MaxVersionTested="10.0.19041.0" when it should be "10.0.22000.0". For full support of some features, notably UnlockedDEHs, update the MaxVersionTested to "10.0.22000.0" in your project file.

Version 1.0 Experimental (1.0.0-experimental1)

This release supports all experimental channel features.

The following sections describe new and updated features, limitations, and known issues for this release.

WinUI 3

This release of WinUI 3 is focused on building towards new features for 1.0 stable and fixing bugs.

  • New features: Support for showing a ContentDialog per window rather than per thread.
  • Bugs: For the full list of bugs addressed in this release, see our GitHub repo.
  • Samples: To see WinUI 3 controls and features in action, you can clone and build the WinUI 3 Gallery app from GitHub, or download the app from the Microsoft Store.

For more information or to get started developing with WinUI, see:

Push notifications (experimental feature)

This release introduces a push notifications API that can be used by packaged desktop apps with Azure app registration-based identities. To use this feature, you must sign up for our private preview.

Important limitations:

  • Push notifications are only supported in MSIX packaged apps that are running on Windows 10 version 2004 (build 19041) or later releases.
  • Microsoft reserves the right to disable or revoke apps from push notifications during the private preview.
  • Microsoft does not guarantee the reliability or latency of push notifications.
  • During the private preview, push notification volume is limited to 1 million per month.

For more information, see Push notifications.

Windowing

This release includes updates to the windowing APIs. These are a set of high-level windowing APIs, centered around the AppWindow class, which allows for easy-to-use windowing scenarios that integrates well with the Windows user experience and other apps. This is similar to, but not the same as, the UWP AppWindow.

Important limitations:

  • This release of AppWindow is currently available only to Win32 apps (both packaged and unpackaged).
  • The Windows App SDK does not currently provide methods for attaching UI framework content to an AppWindow; you're limited to using the HWND interop access methods.
  • The Windowing API's will currently not work on Windows version 1809 and 1903 for AMD64.

For more information, see Manage app windows.

Deployment for unpackaged apps

This release introduces updates to the dynamic dependencies feature, including the bootstrapper API.

Important limitations:

  • The dynamic dependencies feature is only supported for unpackaged apps.
  • Elevated callers aren't supported.

For more information, see the following articles:

Other limitations and known issues

  • No support for Any CPU build configuration: The Windows App SDK is written in native code and thus does not support Any CPU build configurations. The WinUI 3 templates in Visual Studio only allow architecture-specific builds. When adding the Windows App SDK to an existing .NET application or component that supports Any CPU, you must specify the desired architecture: x86, x64 or arm64.
  • .NET apps must target build 18362 or later: Your TFM must be set to net6.0-windows10.0.18362 or later, and your packaging project's <TargetPlatformVersion> must be set to 18362 or later. For more info, see the known issue on GitHub.
  • C# apps using 1.0 Experimental must use one of the following .NET SDKs:

Version 0.8 Preview (0.8.0-preview)

This release supports all experimental channel features.

The following sections describe new and updated features, limitations, and known issues for this release.

WinUI 3

This release introduces critical bug fixes (including those fixed in 0.5 servicing releases) and other changes for WinUI. For a complete list, see the WinUI 3 - Windows App SDK 0.8 release notes.

App lifecycle (experimental feature)

This release introduces new experimental features related to managing the app lifecycle of your app.

  • All apps (packaged and unpackaged) can use GetActivatedEventArgs (although packaged apps can already use the implementation of this in the platform).
  • Only unpackaged apps can use the RegisterForXXXActivation functions.
  • Packaged desktop apps can use app lifecycle instancing.

For more information, see App instancing and Rich activation.

Deployment for unpackaged apps (experimental feature)

This release introduces new experimental deployment features for unpackaged apps. Unpackaged apps can now dynamically take a dependency on the Windows App SDK runtime packages so you can continue using your existing MSI or setup program for app deployment. This is available through the following features:

  • Standalone installer for Windows App SDK.
  • MSIX package bundle that includes dynamic dependencies functionality.

For more info, see Windows App SDK deployment guide for framework-dependent apps packaged with external location or unpackaged.

DWriteCore

This release adds the following features:

  • Text decorations (underline and strikethrough in the text layout API)
  • Vertical text layout
  • Font face kerning API
  • Experimental support for unpackaged apps

For more information, see Render text with DWriteCore.

MRT Core

This release adds the following features:

  • The build action for resources is now automatically set, reducing the need for manual project configuration.
  • Experimental support for unpackaged apps.

For more information, see Manage resources with MRT Core.

Limitations and known issues

  • No support for Any CPU build configuration: The Windows App SDK is written in native code and thus does not support Any CPU build configurations. The WinUI 3 templates in Visual Studio only allow architecture-specific builds. When adding the Windows App SDK to an existing .NET application or component that supports Any CPU, you must specify the desired architecture: x86, x64 or arm64.
  • .NET apps must target build 18362 or later: Your TFM must be set to net6.0-windows10.0.18362 or later, and your packaging project's <TargetPlatformVersion> must be set to 18362 or later. For more info, see the known issue on GitHub.

Samples

The Windows App SDK samples do not yet work with this release. New and updated samples, including samples that demonstrate new features such as unpackaged app deployment, are coming soon.