Preview channel release notes for the Windows App SDK 1.0

  • Article

Important

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

The preview channel includes releases of the Windows App SDK with preview channel features in late stages of development. Preview releases do not include experimental features and APIs but may still be subject to breaking changes before the next stable release.

Important links:

Latest preview channel release:

Latest stable channel release:

Version 1.0 Preview 3 (1.0.0-preview3)

Preview 3 is the latest release of the preview channel for version 1.0 of the Windows App SDK. Preview 3 supports all preview channel features.

Download 1.0 Preview 3 Visual Studio extensions (VSIX)

Note

If you have Windows App SDK Visual Studio extensions (VSIX) already installed, then uninstall them before installing a new version. For directions, see Manage extensions for Visual Studio.

From the table below you can download the Visual Studio extensions (VSIX) for the 1.0 Preview 3 release. For all versions, see Latest Windows App SDK downloads. If you haven't done so already, start by configuring your development environment, using the steps in Install tools for the Windows App SDK.

The extensions below are tailored for your programming language and version of Visual Studio.

1.0 Preview 3 downloads Description
C# Visual Studio 2019 extension Build C# apps with the Windows App SDK Visual Studio 2019 extension.
C++ Visual Studio 2019 extension Build C++ apps with the Windows App SDK Visual Studio 2019 extension.
C# Visual Studio 2022 extension Build C# apps with the Windows App SDK Visual Studio 2022 extension.
C++ Visual Studio 2022 extension Build C++ apps with the Windows App SDK Visual Studio 2022 extension.
The .exe installer, and MSIX packages Deploy the Windows App SDK with your app using the .exe installer, and MSIX packages.

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

WinUI 3 (1.0.0-preview3)

We now support deploying WinUI 3 apps without MSIX packaging. See Create your first WinUI 3 (Windows App SDK) project to configure your WinUI 3 application to support unpackaged deployment.

Important limitations:

  • Unpackaged WinUI 3 applications are supported only on Windows versions 1909 and later.
  • Unpackaged WinUI 3 applications are supported on x86 and x64; arm64 support will be added in the next stable release.
  • Single-project MSIX Packaging Tools for Visual Studio 2019 or Visual Studio 2022 is required for unpackaged apps.
  • In an unpackaged app, you might receive a prompt to install .NET 3.5; if you do, then you can ignore it.
  • Some APIs are not currently supported in unpackaged apps. We're aiming to fix this in the next stable release. A few examples:
  • ListView, CalendarView, and GridView controls are using the incorrect styles, and we're aiming to fix this in the next stable release.

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

Other limitations and known issues:

  • Unpackaged apps are not supported on Windows 10 version 1809. We're aiming to fix this in the next release in the stable channel.

  • 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.

  • This release introduces the Blank App, Packaged (WinUI 3 in Desktop) project templates for C# and C++. These templates enable you to build your app into an MSIX package without the use of a separate packaging project (see Package your app using single-project MSIX). These templates have some known issues in this release:

    • Missing Publish menu item until you restart Visual Studio. When creating a new app 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.

    • Error when adding C++ static/dynamic library project references to C++ apps using Single-project MSIX Packaging. Visual Studio displays an error that the project can't be added as a reference because the project types are not compatible.

    • Error when referencing a custom user control in a class library project. The application will crash with the error that the system can't find the path specified.

    • C# or C++ template for Visual Studio 2019. When you try to build the project, you'll encounter the error "The project doesn't know how to run the profile project name". To resolve this issue, install the Single-project MSIX Packaging Tools extension.

    • C# template for Visual Studio 2019 and Visual Studio 2022. In Visual Studio when you Start Debugging or Start Without Debugging, if your app doesn't deploy and run (and there's no feedback from Visual Studio), then click on the project node in Solution Explorer to select it, and try again.

    • C# template for Visual Studio 2019 and Visual Studio 2022. You will encounter the following error when you try to run or debug your project on your development computer: "The project needs to be deployed before we can debug. Please enable Deploy in the Configuration Manager." To resolve this issue, enable deployment for your project in Configuration Manager. For detailed instructions, see the Create your first WinUI 3 (Windows App SDK) project.

    • C++ template for Visual Studio 2022 version 17.0 releases up to Preview 4. You will encounter the following error the first time you try to run your project: "There were deployment errors". To resolve this issue, run or deploy your project a second time. This issue will be fixed in Visual Studio 2022 version 17.0 Preview 7.

  • 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.

  • C# projects using 1.0 Preview 3 must use the following .NET SDK: .NET 6 SDK or later (see Download .NET and .NET 5 will reach End of Support on May 10, 2022).

  • 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);.

Important issue impacting 1.0 Preview 1 and Preview 2

Version 1.0 Preview 1 and Preview 2 of the Windows App SDK includes a mechanism to clean up any environment variable changes made by a packaged app when that app is uninstalled. This feature is in an experimental state, and the first release includes a known bug that can corrupt the system PATH environment variable.

Preview 1 and Preview 2 corrupts any PATH environment variable that contains the expansion character %. This happens whenever any packaged app is uninstalled, regardless of whether that app uses the Windows App SDK.

Also see PATH environment variable corruption issue.

Details

The system PATH entry is stored in the Path value in the following key in the Windows Registry:

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

If you launch the Registry Editor (regedit.exe), then you can copy and paste the path above into the breadcrumb bar (immediately below the menu bar), and press Enter to locate the key.

The Path value of that key should be of type REG_EXPAND_SZ, but the bug changes it to REG_SZ. And that makes the system PATH environment variable unusable if it contains the variable expansion character %.

Affected releases

Mitigation

To get your machine back into a good state, take the following steps:

  1. Check whether the PATH in the Registry is corrupt and, if so, reset it by running the script below.

    You can accomplish step 1 with the following Windows PowerShell script (PowerShell Core won't work). Run it elevated.

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# If the PATH in the Registry has been set to REG_SZ, then delete
# it, and recreate it as REG_EXPAND_SZ.

$EnvPath = 'Registry::HKLM\System\CurrentControlSet\Control\Session Manager\Environment'
$Environment=Get-Item $EnvPath
$PathKind = $Environment.GetValueKind('Path')

if ($PathKind -ne 'ExpandString') {
  $Path = $Environment.GetValue('Path')
  Remove-ItemProperty $EnvPath -Name Path
  New-ItemProperty $EnvPath -Name Path -PropertyType ExpandString -Value $Path
}

  2. Uninstall all apps that use the Windows App SDK 1.0 Preview1 or Preview2 (see the script below).

  3. Uninstall the Windows App SDK 1.0 Preview1/Preview2 packages, including the package that contains the bug (see the script below).

    You can accomplish steps 2 and 3 with the following Windows PowerShell script (PowerShell Core won't work). Run it elevated.

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# Remove the Windows App SDK 1.0 Preview1/2, and all apps that use it.

$winappsdk = "Microsoft.WindowsAppRuntime.1.0-preview*"
Get-AppxPackage | Where-Object { $_.Dependencies -like $winappsdk } | Remove-AppxPackage
Get-AppxPackage $winappsdk | Remove-AppxPackage

Fix in Windows App SDK 1.0 Preview 3

The feature causing the PATH environment variable to be corrupted will be removed in the upcoming Windows App SDK 1.0 Preview 3 release. It might be reintroduced at a later date, when all bugs have been fixed and thoroughly tested.

We recommend using version 1.0 Preview 3.

Version 1.0 Preview 2 (1.0.0-preview2)

Important

Version 1.0 Preview 1 and Preview 2 contain a critical bug. If you've already installed one of these previews, see how to resolve the issue. We recommend using version 1.0 Preview 3 instead.

This is the latest release of the preview channel for version 1.0. It supports all preview channel features.

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

WinUI 3 (1.0.0-preview2)

New updates:

  • Controls have been updated to reflect the latest Windows styles from WinUI 2.6.
  • Single-project MSIX is supported.
  • WinUI 3 package can now target build 17763 and later. See issue #921 for more info.
  • In-app toolbar is supported. However, the in-app toolbar and existing Hot Reload/Live Visual Tree support require the upcoming Visual Studio 17.0 Preview 5 release, available later in October.

Bug fixed: WebView2Runtime text is now localized.

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

Windowing (1.0.0-preview2)

This release introduces updates to the AppWindow class. There are no major new features added in this release, but there are changes to method names, properties, and some return values have been removed. See the documentation and samples for detailed updates. If you worked with AppWindow in the 1.0 Experimental or 1.0 Preview 1 releases, expect some changes to your code.

New updates:

  • The AppWindowConfiguration class has been removed. The properties of this class is now available on the AppWindow itself, or on the Presenter classes.
  • Most bool return values for the WinRT API methods in this space has been removed and are now void since these methods would always succeed.
  • The C# ImportDll calls are no longer needed for GetWindowIdFromWindow and GetWindowFromWindowId. Use the .NET wrapper methods available in the Microsoft.UI.Win32Interop class instead.

Important limitations:

  • 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.
  • Window title bar customization works only on Windows 11. Use the IsCustomizationSupported method to check for title bar customization feature support. We intend to bring this functionality down-level.

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

Input (1.0.0-preview2)

New updates:

  • Improved support for precision touchpad input.

Important limitations:

  • All PointerPoint static factory functions have been removed: GetCurrentPoint, GetCurrentPointTransformed, GetIntermediatePoints, and GetIntermediatePointsTransformed.
  • The Windows App SDK does not 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. See the documentation for additional details.

MRT Core (1.0.0-preview2)

New updates:

  • App developers can now opt out an image file or a RESW file from being indexed in the PRI file in .NET projects. See issue 980 for more info.

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, existing resource files added from an external folder aren't indexed without manual setting of the Build Action. To work around this issue, set the Build Action in Visual Studio: Content for image files and PRIResource for RESW files. See issue 1504 for more info.

Deployment for unpackaged apps

New features:

  • Windows App SDK 1.0 Preview 2 introduces a .NET wrapper for the bootstrapper API (see Use the Windows App SDK runtime for apps packaged with external location or unpackaged). The bootstrapper API is a set of native C/C++ functions that unpackaged apps must use to dynamically take a dependency on the Windows App SDK framework package at run time. The .NET wrapper provides an easier way to call the bootstrapper API from .NET apps, including Windows Forms and WPF apps. The .NET wrapper for the bootstrapper API is available in the Microsoft.WindowsAppRuntime.Bootstrap.Net.dll assembly, which is local to your app project. For more info about the .NET wrapper, see .NET wrapper library.
  • Packaged apps can now use the deployment API to get the main and singleton MSIX packages installed on the machine. The main and singleton packages are part of the framework package that is installed with the app, but due to a limitation with the Windows application model, packaged apps will need to take this additional step in order to get those packages installed. For more info about how the deployment API works, see Windows App SDK deployment guide for framework-dependent packaged apps.

Important limitations:

  • The .NET wrapper for the bootstrapper API only 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.

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.

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 3 apps that 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 3 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 3 apps, you can declare Main to be async, if necessary. For C++ WinUI 3 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.

Other limitations and known issues:

  • Version 1.0 Preview 1 and Preview 2 contain a critical bug. If you've already installed one of these previews, see how to resolve the issue. We recommend using version 1.0 Preview 3 instead.

  • This release introduces the Blank App, Packaged (WinUI 3 in Desktop) templates for C# and C++ projects. These templates enable you to build your app into an MSIX package without the use of a separate packaging project. These templates have some known issues in this release:

    • C# template for Visual Studio 2019. You will encounter the error when you try to build the project: "The project doesn't know how to run the profile project name". To resolve this issue, install the Single-project MSIX Packaging Tools extension.

    • C# template for Visual Studio 2019 and Visual Studio 2022. You will encounter the following error when you try to run or debug your project on your development computer: "The project needs to be deployed before we can debug. Please enable Deploy in the Configuration Manager." To resolve this issue, enable deployment for your project in Configuration Manager. For detailed instructions, see the Create your first WinUI 3 (Windows App SDK) project.

    • C++ template for Visual Studio 2019 and Visual Studio 2022. In this release, these projects are restricted to calling the subset of Win32 APIs that can be called by UWP apps. The Blank App, Packaged with WAP (WinUI 3 in Desktop) template is not affected by this issue.

    • C++ template for Visual Studio 2022 version 17.0 releases up to Preview 4. You will encounter the following error the first time you try to run your project: "There were deployment errors". To resolve this issue, run or deploy your project a second time. This issue will be fixed in Visual Studio 2022 version 17.0 Preview 5.

  • Push notifications API (Microsoft.Windows.PushNotifications namespace) incorrectly included in the 1.0 Preview 2 release. This is still an experimental feature, and to you use it you must install the 1.0 Experimental release instead. This feature will be removed from the upcoming 1.0 release.

  • App lifecycle API (Microsoft.Windows.AppLifecycle namespace) incorrectly includes the Experimental attribute in the 1.0 Preview 2 release. The Experimental attribute will be removed from this API in the next release.

  • 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.

  • C# projects using 1.0 Preview 2 must use the following .NET SDK: .NET 6 SDK or later (see Download .NET and .NET 5 will reach End of Support on May 10, 2022).

  • 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);.

Version 1.0 Preview 1 (1.0.0-preview1)

Important

Version 1.0 Preview 1 and Preview 2 contain a critical bug. If you've already installed one of these previews, see how to resolve the issue. We recommend using version 1.0 Preview 3 instead.

This is the first release of the preview channel for version 1.0. It supports all preview channel features.

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

WinUI 3 (1.0.0-preview1)

This release of WinUI 3 is focused on building towards 1.0 with bug fixes.

  • New features: No new features in Preview 1.
  • Fixed issues: For the full list of issues addressed in this release, see our GitHub repo.

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

Windowing (1.0.0-preview1)

This release brings the Windowing API we introduced in Experimental 1 to a Preview state. There are no major new features areas in this release as it is focused on bugfixes, stability, and adjustments to the API signature. The noteworthy changes and additions are called out below.

New features:

  • DisplayAreaWatcher has been added to the Windowing APIs. This allows a developer to observe changes in the display topology and enumerate DisplayAreas currently defined in the system.
  • AppWindow now supports setting the window icon via the SetIcon method, and AppWindowTitleBar now supports selecting whether to show/hide the window icon along with the system menu via the IconShowOptions property.

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.
  • Window title bar customization works only on Windows 11. Use the IsCustomizationSupported method to check for title bar customization feature support. We intend to bring this functionality down-level.

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

Input (1.0.0-preview1)

This release brings some new features to the Input API. The noteworthy changes and additions are called out below.

New features and updates:

  • PointerPredictor gives input latency sensitive applications such inking applications the ability to predict input point locations up to 15ms in the future to achieve better latency and smooth animation.
  • PenDeviceInterop enables you to acquire a reference to the Windows.Devices.Input.PenDevice by using the FromPointerPoint method.
  • InputCursor provides an explicit distinction between preset system cursor types and custom cursor types by removing the "Custom" type present in CoreCursor, and splitting the CoreCursor object into separate objects.
  • Updates to InputCursor APIs.
  • GestureRecognizer moved out of experimental to Microsoft.UI.Input.
  • PointerPoint moved out of experimental to Microsoft.UI.Input.
  • Mouse, touch, and pen input fully supported for WinUI 3 drag and drop.

Important limitations:

  • This release of Input APIs has known issues with Windows version 1809.
  • MRT Core is not yet supported by any subtype of InputCursor.
  • Direct use of the platform SDK API Windows.UI.Core.CoreDragOperation will not work with WinUI 3 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.

MRT Core (1.0.0-preview1)

Starting in version 1.0 Preview 1, MRT Core APIs have moved from the Microsoft.ApplicationModel.Resources namespace to the Microsoft.Windows.ApplicationModel.Resources namespace.

Other limitations and known issues:

  • Version 1.0 Preview 1 and Preview 2 contain a critical bug. If you've already installed one of these previews, see how to resolve the issue. We recommend using version 1.0 Preview 3 instead.

  • Projects created by using the C++ Blank App, Packaged with WAP (WinUI 3 in Desktop) project template encounter the following build error by default: fatal error C1083: Cannot open include file: 'winrt/microsoft.ui.dispatching.co_await.h': No such file or directory. To resolve this issue, remove the following line of code from the pch.h file. This issue will be fixed in the next release.

    #include <winrt/microsoft.ui.dispatching.co_await.h>

  • 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);.

  • 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# projects using 1.0 Preview 1 must use the following .NET SDK: .NET 6 SDK or later (see Download .NET and .NET 5 will reach End of Support on May 10, 2022).

  • Unpackaged apps not supported on Windows 10 version 1809: This should be resolved in the next release.