Muokkaa

Jaa

Latest experimental channel release notes for the Windows App SDK

  • Artikkeli

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 includes releases of the Windows App SDK with experimental channel features 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 are subject to extensive revisions and breaking changes. Experimental features and APIs may be removed from subsequent releases at any time.

Important links:

Experimental channel release note archive:

Version 1.6 Experimental (1.6.0-experimental1)

This is the latest release of the experimental channel.

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

Required C# project changes for 1.6-experimental1

In 1.6-experimental1, Windows App SDK managed apps require Microsoft.Windows.SDK.NET.Ref *.*.*.35-preview (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.35-preview</WindowsSdkPackageVersion>
   <PropertyGroup>
   ...

In addition, Windows App SDK managed apps using C#/WinRT should update to Microsoft.Windows.CsWinRT 2.1.0-prerelease.240602.1 (or later).

Native AOT support

The .NET PublishAot project property is now supported for native Ahead-Of-Time compilation. For details, 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, 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.0-prerelease.240602.1 (or later) to enable the source generator from that package.

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 Condition="'$(ExcludeRestorePackageImports)'=='true'">true</PublishAot>

In addition, we recommend conditionally enabling PublishAot when publishing release configurations, either in publish profiles or the project:

<PublishAot Condition="'$(Configuration)'=='Release'">true</PublishAot>

Resolving AOT Issues

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.

Partial Classes

C#/WinRT also includes PublishAot support in version 2.1.0-prerelease.240602.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.

Reflection-Free Techniques

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.

Rooting Types

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.

Improved TabView tab tear-out

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.

Known issue: In this release, pointer input behavior for CanTearOutTabs is incorrect on monitors with scale factor different than 100%. This will be fixed in the next 1.6 release.

New TitleBar control

A new TitleBar control makes it easy to create a great, customizable titlebar for your app with the following features:

  • Configurable Icon, Title, and Subtitle properties
  • An integrated back button
  • The ability to add a custom control like a search box
  • Automatic hiding and showing of elements based on window width
  • Affordances for showing active or deactive window state
  • Support for default titlebar features including draggable regions in empty areas, theme responsiveness, default caption (min/max/close) buttons, and built-in accessibility support

The TitleBar control is designed to support various combinations of titlebars, making it flexible to create the experience you want without having to write a lot of custom code. We took feedback from the community toolkit titlebar prototype and look forward to additional feedback!

Known issue: In this release, the TitleBar only shows the Icon and Title due to an issue where some elements don't show up on load. To work around this, use the following code to load the other elements (Subtitle, Header, Content, and Footer):

public MainWindow()
  {
      this.InitializeComponent();
      this.ExtendsContentIntoTitleBar = true;
      this.SetTitleBar(MyTitleBar);

      MyTitleBar.Loaded += MyTitleBar_Loaded;
  }

  private void MyTitleBar_Loaded(object sender, RoutedEventArgs e)
  {
      // Parts get delay loaded. If you have the parts, make them visible.
      VisualStateManager.GoToState(MyTitleBar, "SubtitleTextVisible", false);
      VisualStateManager.GoToState(MyTitleBar, "HeaderVisible", false);
      VisualStateManager.GoToState(MyTitleBar, "ContentVisible", false);
      VisualStateManager.GoToState(MyTitleBar, "FooterVisible", false);

      // Run layout so we re-calculate the drag regions.
      MyTitleBar.InvalidateMeasure();
  }

This issue will be fixed in the next 1.6 release.

Other notable changes

  • Unsealed ItemsWrapGrid. This should be a backward-compatible change.
  • PipsPager supports a new mode where it can wrap between the first and list 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.

New APIs for 1.6-experimental1

1.6-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.UI.Xaml.Controls

    PipsPager
        WrapMode
        WrapModeProperty

    PipsPagerWrapMode
        None
        Wrap

Additional 1.6-experimental1 APIs

This release includes the following new and modified experimental APIs:

Microsoft.UI.Content

    ChildContentLink
    ContentExternalOutputLink
        IsAboveContent

    ContentIsland
        Children
        Create
        FindAllForCompositor
        GetByVisual
        Offset
        RotationAngleInDegrees

    ContentSite
        Offset
        RotationAngleInDegrees

    ContentSiteView
        Offset
        RotationAngleInDegrees

    IContentLink
    IContentSiteBridge2
    ReadOnlyDesktopSiteBridge

Microsoft.UI.Input

    EnteredMoveSizeEventArgs
    EnteringMoveSizeEventArgs
    ExitedMoveSizeEventArgs
    InputNonClientPointerSource
        EnteredMoveSize
        EnteringMoveSize
        ExitedMoveSize
        WindowRectChanged
        WindowRectChanging

    MoveSizeOperation
    WindowRectChangedEventArgs
    WindowRectChangingEventArgs

Microsoft.UI.Windowing

    AppWindow
        DefaultTitleBarShouldMatchAppModeTheme

Microsoft.UI.Xaml

    XamlRoot
        CoordinateConverter
        TryGetContentIsland

Microsoft.UI.Xaml.Controls

    ScrollingViewChangingEventArgs
    ScrollView
        ViewChanging

    StackLayout
        IsVirtualizationEnabled
        IsVirtualizationEnabledProperty

    TabView
        CanTearOutTabs
        CanTearOutTabsProperty
        ExternalTornOutTabsDropped
        ExternalTornOutTabsDropping
        TabTearOutRequested
        TabTearOutWindowRequested

    TabViewExternalTornOutTabsDroppedEventArgs
    TabViewExternalTornOutTabsDroppingEventArgs
    TabViewTabTearOutRequestedEventArgs
    TabViewTabTearOutWindowRequestedEventArgs
    TitleBar
    TitleBarAutomationPeer
    TitleBarTemplateSettings

Microsoft.UI.Xaml.Controls.Primitives

    ScrollPresenter
        ViewChanging

Other known issues

  • Non-XAML applications that use Microsoft.UI.Content.ContentIslands and do not handle the ContentIsland.AutomationProviderRequested event (or return nullptr as the automation provider) will crash if any accessibility or UI automation tool is enabled such as Voice Access, Narrator, Accessibility Insights, Inspect.exe, etc.

Bug fixes

This release includes the following bug fixes:

  • Fixed an issue where clicking in an empty area of a ScrollViewer would always move focus to the first focusable control in the ScrollViewer 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 setting the NavigationViewItem.IsSelected property to true prevents its children from showing when expanded. For more info, see GitHub issue #7930.
  • Fixed an issue where MediaPlayerElement would not properly display captions with None or DropShadow 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 can hit a trying to find a type or property. For more info, see GitHub issue #8810.
  • Fixed an issue where initial keyboard focus is 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 is shown. For more info, see GitHub issue #8896.
  • Fixed an issue where some controls did not correctly template bind Foreground and Background properties. For more info, see GitHub issue #7070, #9020, #9029, #9083 and #9102.
  • Fixed an issue where ThemeResources used in VisualStateManager 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 can 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 does not work properly. For more info, see GitHub issue #9486.
  • Fixed an issue where MapControl.MapElementClick event doesn't properly fire. For more info, see GitHub issue #9487.
  • Fixed an issue where x:Bind doesn't check for null before using a weak reference, which can result in a crash. For more info, see GitHub issue #9551.
  • Fixed an issue where changing the TeachingTip.Target property doesn'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 a ScrollView can cause blank render frames. For more info, see GitHub issue #9643.
  • Fixed an issue where SceneVisual wasn't working.