Stable channel release notes for the Windows App SDK 1.0

  • Article

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:

Latest stable channel release:

Downloads for the Windows App SDK

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.

Version 1.0.4

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

Bug fixes (1.0.4)

  • Fixed issue causing AppBars, when used as Page.TopAppBar or Page.BottomAppBar to not render on screen.
  • Fixed issue where apps with a package name of 12 characters or less that use a WinUI control from MUXControls.dll will immediately crash. For more information, see issue 6360 on GitHub.
  • Fixed touch input issues causing problems with keyboard shortcuts and other scenarios. For more information, see issue 6291 on GitHub.
  • Fixed issue causing apps packaged with MSIX or deployed as self-contained to fail to deploy.
  • Fixed issue causing apps to sometimes crash during a drag and drop operation. For more information see issue 7002 on GitHub.

Version 1.0.3

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

Bug fixes (1.0.3)

  • Fixed issue causing C# apps with WebView2 to crash on launch when the C/C++ Runtime (CRT) isn't installed.
  • Fixed touch input issues causing problems with keyboard shortcuts and other scenarios. For more information, see issue 6291 on GitHub.

Note: We don't usually add functionality in a servicing release, but this release's WebView2 fix required us to update to the latest version of the WebView2 SDK (1020.46 to 1185.39). See Release Notes for the WebView2 SDK for additional information on WebView2 1.0.1185.39 and Distribute your app and the WebView2 Runtime for additional information on the WebView2 Runtime.

Version 1.0.2

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

Bug fixes (1.0.2)

  • Fixed layout cycle issue causing an app to crash when scrolling to the end of a ListView. For more information see issue 6218 on GitHub.
  • Fixed issue causing C# apps to crash on launch when the C/C++ Runtime (CRT) isn't installed. However, the CRT is still required for C# apps using WebView2. For more information see issue 2117 on GitHub.
  • Fixed issue where applications with Single-project MSIX did not generate a .appinstaller file. For more information see issue 1821 on GitHub.
  • Fixed issue where WinUI applications did not support .NET 6 dotnet build.

Version 1.0.1

This is a servicing release of the Windows App SDK that includes critical bug fixes and multi-window support for the 1.0 release.

Bug fixes (1.0.1)

  • Fixed issue causing the MddBootstrapAutoinitializer to not compile with enabled ImplicitUsings. For more information see issue 1686 on GitHub.
  • Fixed issue where focus in WebView2 would be unexpectedly lost causing input and selection issues. For more information, see issue 5615 & issue 5570 on GitHub.
  • Fixed issue causing the in-app toolbar in Visual Studio to be unclickable when using a custom title bar in a WinUI 3 app.
  • Fixed issue causing Snap Layout to not appear when using a custom title bar in a WinUI 3 app. For more information, see issue 6333 & issue 6246 on GitHub.
  • Fixed issue causing an exception when setting Window.ExtendsContentIntoTitleBar property when Window.SetTitlebar has been called with a still-loading UIElement.
  • Fixed issue where Single-project MSIX apps did not support dotnet build.
  • Fixed issue causing unpackaged apps to not install after installing a packaged app. For more information, see issue 1871 on GitHub.
  • Fixed issue reducing performance during mouse drag operations.
  • Fixed crash when calling GetWindowIdFromWindow() in unpackaged apps. For more information, see discussion 1891 on GitHub.

The limitations and known issues for version 1.0 also apply to version 1.0.1.

Additionally, for apps with custom title bars, we have made changes in this release (and fixed numerous issues) that include fixes to the glass window used for drag&drop operations. The recommendation is to use the default values and behaviors (give them a try!). If your title bar used margins so that the default caption buttons were interactive, we recommend visualizing your drag region by setting the background of your title bar to red and then adjusting the margins to extend the drag region to the caption controls.

New features

We have stabilized and enabled the creation of multiple windows on the same thread in WinUI 3 applications. See issue 5918 for more information.

Version 1.0

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

WinUI 3

WinUI 3 is the native user experience (UX) framework for Windows App SDK. In this release we've added multiple new features from Windows App SDK 0.8 and stabilized issues from 1.0 Preview releases.

New features and updates:

  • We've added new controls (PipsPager, Expander, BreadcrumbBar) and updated existing controls to reflect the latest Windows styles from WinUI 2.6.
  • Single-project MSIX packaging is supported in WinUI by creating a new application using the "Blank App, Packaged…" template.
  • We now support deploying WinUI 3 apps that aren't packaged on Windows versions 1809 and above. Please view Create your first WinUI 3 (Windows App SDK) project for additional information.
  • WinUI 3 projects can now set their target version down to Windows 10, version 1809. Previously, they could only be set as low as version 1903.
  • In-app toolbar, Hot Reload, & Live Visual Tree for WinUI packaged apps are supported in Visual Studio 2022 Preview 5 and GA.

Important limitations:

  • Known issues for both packaged and unpackaged WinUI applications:

    • Run-time error in C++ or C# apps that reference a C++ Windows Runtime Component:

      • To resolve, add the below target to the end of the Windows Runtime Component's .vcxproj:
      <Target Name="GetPriIndexName">
<PropertyGroup>
    <!-- Winmd library targets use the default root namespace of the project for the App package name -->
    <PriIndexName Condition="'$(RootNamespace)' != ''">$(RootNamespace)</PriIndexName>
    <!-- If RootNamespace is empty fall back to TargetName -->
    <PriIndexName Condition="$(PriIndexName) == ''">$(TargetName)</PriIndexName>
</PropertyGroup>
</Target>
      • The expected error will be similar to WinRT originate error - 0x80004005 : 'Cannot locate resource from 'ms-appx:///BlankPage.xaml'.'.

  • Known issues for WinUI applications with Single-project MSIX (Blank App, Packaged template):

    • Missing Package & Publish menu item until you restart Visual Studio: When creating a new app with Single-project MSIX in both Visual Studio 2019 and Visual Studio 2022 using the Blank App, Packaged (WinUI 3 in Desktop) project template, the command to publish the project doesn't appear in the menu until you close and re-open Visual Studio.
    • A C# app with Single-project MSIX will not compile without the "C++ (v14x) Universal Windows Platform Tools" optional component installed. See Install tools for the Windows App SDK for additional information.
    • Potential run-time error in an app with Single-project MSIX that consumes types defined in a referenced Windows Runtime Component: To resolve, manually add activatable class entries to the appxmanifest.xml.
      • The expected error in C# applications is "COMException: Class not registered (0x80040154 (REGDB_E_CLASSNOTREG)).
      • The expected error in C++/WinRT applications is "winrt::hresult_class_not_registered".

  • Known issues for WinUI 3 apps that aren't packaged (unpackaged apps):

  • Known issues for packaging and deploying WinUI applications:

    • The Package command is not supported in WinUI apps with Single-project MSIX (Blank App, Packaged template). Instead, use the Package & Publish command to create an MSIX package.
    • To create a NuGet package from a C# Class Library with the Pack command, ensure the active Configuration is Release.
    • The Pack command is not supported in C++ Windows Runtime Components to create a NuGet package.

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

Windowing

The Windows App SDK provides an AppWindow class that evolves the previous easy-to-use Windows.UI.WindowManagement.AppWindow preview class and makes it available to all Windows apps, including Win32, WPF, and WinForms.

New Features:

  • AppWindow is a high-level windowing API that allows for easy-to-use windowing scenarios that integrates well with the Windows user experience and with other apps. Represents a high-level abstraction of a system-managed container of the content of an app. This is the container in which your content is hosted, and represents the entity that users interact with when they resize and move your app on screen. For developers familiar with Win32, the AppWindow can be seen as a high-level abstraction of the HWND.
  • DisplayArea represents a high-level abstraction of a HMONITOR, follows the same principles as AppWindow.
  • DisplayAreaWatcher allows a developer to observe changes in the display topology and enumerate DisplayAreas currently defined in the system.

For more info, see Manage app windows (Windows App SDK).

Input

These are the input APIs that support WinUI and provide a lower level API surface for developers to achieve more advanced input interactions.

New Features:

Important limitations:

  • All PointerPoint static factory functions have been removed: GetCurrentPoint, GetCurrentPointTransformed, GetIntermediatePoints, and GetIntermediatePointsTransformed.
  • The Windows App SDK doesn't support retrieving PointerPoint objects with pointer IDs. Instead, you can use the PointerPoint member function GetTransformedPoint to retrieve a transformed version of an existing PointerPoint object. For intermediate points, you can use the PointerEventArgs member functions GetIntermediatePoints and GetTransformedIntermediatePoints.
  • Direct use of the platform SDK API Windows.UI.Core.CoreDragOperation will not work with WinUI applications.
  • PointerPoint properties RawPosition and ContactRectRaw were removed because they referred to non-predicted values, which were the same as the normal values in the OS. Use Position and ContactRect instead. Pointer prediction is now handled with the Microsoft.UI.Input.PointerPredictor API object.

App Lifecycle

Most of the App Lifecycle features already exist in the UWP platform, and have been brought into the Windows App SDK for use by desktop app types, especially unpackaged Console apps, Win32 apps, Windows Forms apps, and WPF apps. The Windows App SDK implementation of these features cannot be used in UWP apps, since there are equivalent features in the UWP platform itself.

Important

If you're working on a UWP app, then refer to Migrate from UWP to the Windows App SDK.

Non-UWP apps can also be packaged into MSIX packages. While these apps can use some of the Windows App SDK App Lifecycle features, they must use the manifest approach where this is available. For example, they cannot use the Windows App SDK RegisterForXXXActivation APIs and must instead register for rich activation via the manifest.

All the constraints for packaged apps also apply to WinUI apps, which are packaged, and there are additional considerations as described below.

Important considerations:

  • Rich activation: GetActivatedEventArgs

  • Register/Unregister for rich activation

  • Single/Multi-instancing

    • Unpackaged apps: Fully usable.
    • Packaged apps: Fully usable.
    • WinUI apps: If an app wants to detect other instances and redirect an activation, it must do so as early as possible, and before initializing any windows, etc. To enable this, the app must define DISABLE_XAML_GENERATED_MAIN, and write a custom Main (C#) or WinMain (C++) where it can do the detection and redirection.
    • RedirectActivationToAsync is an async call, and you should not wait on an async call if your app is running in an STA. For Windows Forms and C# WinUI apps, you can declare Main to be async, if necessary. For C++ WinUI and C# WPF apps, you cannot declare Main to be async, so instead you need to move the redirect call to another thread to ensure you don't block the STA.
    • For more info, see App instancing with the app lifecycle API.

  • Power/State notifications

Known issue:

  • File Type associations incorrectly encode %1 to be %251 when setting the Verb handler's command line template, which crashes unpackaged Win32 apps. You can manually edit the Registry value to be %1 instead as a partial workaround. If the target file path has a space in it, then it will still fail and there is no workaround for that scenario.
  • These Single/Multi-instancing bugs will be fixed in an upcoming servicing patch:
    • AppInstance redirection doesn't work when compiled for x86
    • Registering a key, unregistering it, and re-registering it causes the app to crash

DWriteCore

DWriteCore is the Windows App SDK implementation of DirectWrite, which is the DirectX API for high-quality text rendering, resolution-independent outline fonts, and full Unicode text and layout support. DWriteCore is a form of DirectWrite that runs on versions of Windows down to Windows 10, version 1809 (10.0; Build 17763), and opens the door for you to use it cross-platform.

Features:

DWriteCore contains all of the features of DirectWrite, with a few exceptions.

Important limitations:

  • DWriteCore does not contain the following DirectWrite features:
    • Per-session fonts
    • End-user defined character (EUDC) fonts
    • Font-streaming APIs
  • Low-level rendering API support is partial.
  • DWriteCore doesn't interoperate with Direct2D, but you can use IDWriteGlyphRunAnalysis and IDWriteBitmapRenderTarget.

For more information, see DWriteCore overview.

MRT Core

MRT Core is a streamlined version of the modern Windows Resource Management System that is distributed as part of the Windows App SDK.

Important limitations:

  • In .NET projects, resource files copy-pasted into the project folder aren't indexed on F5 if the app was already built. As a workaround, rebuild the app. See issue 1503 for more info.

  • In .NET projects, when a resource file is added to the project using the Visual Studio UI, the files may not be indexed by default. See issue 1786 for more info. To work around this issue, please remove the entries below in the CSPROJ file:

    <ItemGroup>
    <Content Remove="<image file name>" />
</ItemGroup>
<ItemGroup>
    <PRIResource Remove="<resw file name>" />
</ItemGroup>

  • For unpackaged C++ WinUI apps, the resource URI is not built correctly. To work around this issue, add the following in the vcxproj:

    <!-- Add the following after <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> -->

<PropertyGroup>
    <AppxPriInitialPath></AppxPriInitialPath>   
</PropertyGroup>

For more information, see Manage resources with MRT Core.

Deployment

New Features and updates:

Important limitations:

  • The .NET wrapper for the bootstrapper API is only intended for use by unpackaged .NET applications to simplify access to the Windows App SDK.
  • Only MSIX packaged apps that are full trust or have the packageManagement restricted capability have the permission to use the deployment API to install the main and singleton package dependencies. Support for partial-trust packaged apps will be coming in later releases.
  • When F5 testing an x86 app which uses the DeploymentManager.Initialize method on an x64 system, ensure that the x64 framework is first installed by running the WindowsAppRuntimeInstall.exe. Otherwise, you will encounter a NOT_FOUND error due to Visual Studio not deploying the x64 framework, which normally occurs through Store deployment or sideloading.

Other limitations and known issues

  • No support for Any CPU build configuration: 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.

  • Upgrading from .NET 5 to .NET 6: When upgrading in the Visual Studio UI, you might run into build errors. As a workaround, manually update your project file's TargetFrameworkPackage to the below:

      <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>

  • C# Single-project MSIX app doesn't compile if C++ UWP Tools aren't installed. If you have a C# Single-project MSIX project, then you'll need to install the C++ (v14x) Universal Windows Platform Tools optional component.

  • Subsequent language VSIX fails to install into Visual Studio 2019 when multiple versions of Visual Studio 2019 are installed. If you have multiple versions of Visual Studio 2019 installed (e.g. Release and Preview) and then install the Windows App SDK VSIX for both C++ and C#, the second installation will fail. To resolve, uninstall the Single-project MSIX Packaging Tools for Visual Studio 2019 after the first language VSIX. View this feedback for additional information about this issue.

  • An alternative to DispatcherQueue.TryEnqueue (for resuming execution on the dispatcher queue thread) is to use the resume_foreground helper function in the Windows Implementation Library (WIL):

    1. Add a reference to your project to the Microsoft.Windows.ImplementationLibrary NuGet package.
    2. Add #include <wil/cppwinrt_helpers.h> to your pch.h.
    3. Add #include <winrt/Microsoft.UI.Dispatching.h> to your pch.h.
    4. Now co_await wil::resume_foreground(your_dispatcherqueue);.