Windows 应用 SDK 1.6 的实验频道发行说明
重要
不支持在生产环境中使用试验通道,并且无法将使用试验版本的应用发布到 Microsoft Store。
试验通道提供 Windows App SDK 的版本,其中包括开发早期阶段的试验通道功能。 用于试验功能的 API 具有试验特性。 如果在代码中调用试验 API,会收到生成时警告。 试验通道中的所有 API 在将来的版本中可能会有重大更改,但试验 API 特别容易更改。 试验功能可能会从下一版本中删除,也可能永远不会发布。
重要链接:
- 如果要将现有应用从较旧版本的 Windows App SDK 升级到较新版本,请参阅将现有项目更新到 Windows App SDK 的最新版本。
- 有关试验版本的文档,请参阅安装 Windows App SDK 的预览和试验通道工具。
最新试验通道版本:
最新稳定通道版本:
版本 1.6 实验版 (1.6.0-experimental2)
这是试验通道的最新版本。
若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.6.240701003-experimental2
。
注意
此版本不包括 Phi 硅和 OCR API。 这些版本将在未来 1.6 版本中推出。
本机 AOT 支持更新
在 1.6 实验性 1 中,XAML 编译器使用对 AOT/剪裁不安全的代码生成 XamlTypeInfo.g.cs
。 这与 GitHub 问题 #9675 相关,尽管它未完全修复该问题。
更改了 Edge WebView2 SDK 集成
Windows 应用 SDK现在使用 Edge WebView2 SDK 作为 NuGet 引用,而不是嵌入边缘 WebView2 SDK 的硬编码版本。 新模型允许应用选择较新版本的Microsoft.Web.WebView2
包,而不是仅限于生成Windows 应用 SDK的版本。 新模型还允许应用引用也引用 Edge WebView2 SDK 的 NuGet 包。 有关详细信息,请参阅 GitHub 问题 #5689。
新建包部署 API
包管理 API 已收到多项增强功能,包括 Is*ReadyOrNewerAvailable*()、EnsureReadyOptions.RegisterNewerIfAvailable、Is*Provisioned*()、IsPackageRegistrationPending()和多个 bug 修复。 有关更多详细信息,请参阅 PackageManagement.md 和 拉取请求 #4453 。
其他值得注意的更改
- 从 1.6-experimental2 开始,最新的 WinUI 3 源现在将发布到 microsoft-ui-xaml GitHub 存储库中的主分支,这将在该存储库中启用源搜索。
- 我们添加了一个新的
ColorHelper.ToDisplayName()
API,填补了 UWP 的空白。- 已知问题: 某些语言翻译存在字符编码问题。 将在下一个 1.6 版本中修复此问题。
- 添加了一个新
Microsoft.Windows.Globalization.ApplicationLanguages
类,其中特别包括新功能PrimaryLanguageOverride
。 有关详细信息,请参阅 GitHub 问题 #4523。 - 新的扩展使小组件提供程序能够向小组件提供 Web 内容和小组件的公告。
适用于 1.6-experimental2 的新 API
1.6-experimental2 包括以下新 API。 这些 API 不是实验性的,但尚未包含在 WinAppSDK 的稳定版本中。
Microsoft.UI.Xaml.Controls
PipsPager
WrapMode
WrapModeProperty
PipsPagerWrapMode
Microsoft.Windows.Globalization
ApplicationLanguages
Microsoft.Windows.Management.Deployment
EnsureReadyOptions
RegisterNewerIfAvailable
PackageDeploymentFeature
PackageDeploymentManager
IsPackageDeploymentFeatureSupported
IsPackageProvisioned
IsPackageProvisionedByUri
IsPackageReadyOrNewerAvailable
IsPackageReadyOrNewerAvailableByUri
IsPackageSetProvisioned
IsPackageSetReadyOrNewerAvailable
PackageReadyOrNewerAvailableStatus
其他 1.6 实验性 2 API
此版本包括以下新的和经过修改的实验 API:
Microsoft.UI
ColorHelper
ToDisplayName
Microsoft.UI.Composition
CompositionNotificationDeferral
Microsoft.UI.Composition.Experimental
ExpCompositionVisualSurface
ExpExpressionNotificationProperty
IExpCompositionPropertyChanged
IExpCompositionPropertyChangedListener
IExpCompositor
IExpVisual
Microsoft.UI.Content
AutomationOptions
ChildContentLink
ContentAppWindowBridge
ContentDisplayOrientations
ContentExternalBackdropLink
ContentExternalOutputLink
ContentIsland
Children
Compositor
Connected
ConnectionInfo
ConnectRemoteEndpoint
Create
Disconnected
FindAllForCompositor
FragmentRootAutomationProvider
GetByVisual
IsRemoteEndpointConnected
NextSiblingAutomationProvider
Offset
ParentAutomationProvider
PreviousSiblingAutomationProvider
Root
RotationAngleInDegrees
ContentIslandEnvironment
AutomationOption
CurrentOrientation
DisplayScale
NativeOrientation
ThemeChanged
ContentSite
Compositor
Offset
RotationAngleInDegrees
SetContentNodeParent
SetIsInputPassThrough
SiteVisual
TryGetAutomationProvider
ContentSiteAutomationProviderRequestedEventArgs
ContentSiteEnvironment
CurrentOrientation
DisplayScale
NativeOrientation
NotifyThemeChanged
ContentSiteView
Offset
RotationAngleInDegrees
CoreWindowSiteBridge
CoreWindowTopLevelWindowBridge
DesktopChildSiteBridge
AcceptRemoteEndpoint
ConnectionInfo
IsRemoteEndpointConnected
RemoteEndpointConnecting
RemoteEndpointDisconnected
RemoteEndpointRequestedStateChanged
DesktopSiteBridge
TryCreatePopupSiteBridge
EndpointConnectionEventArgs
EndpointRequestedStateChangedEventArgs
IContentIslandEndpointConnectionPrivate
IContentLink
IContentNodeOwner
IContentSiteBridge2
IContentSiteBridgeAutomation
IContentSiteBridgeEndpointConnectionPrivate
PopupWindowSiteBridge
ProcessStarter
ReadOnlyDesktopSiteBridge
SystemVisualSiteBridge
Microsoft.UI.Input
EnteredMoveSizeEventArgs
EnteringMoveSizeEventArgs
ExitedMoveSizeEventArgs
InputKeyboardSource
GetForWindowId
InputLayoutPolicy
InputLightDismissAction
GetForIsland
InputNonClientPointerSource
EnteredMoveSize
EnteringMoveSize
ExitedMoveSize
WindowRectChanged
WindowRectChanging
InputPointerActivationBehavior
InputPointerSource
ActivationBehavior
DirectManipulationHitTest
GetForVisual
GetForWindowId
RemoveForVisual
TouchHitTesting
TrySetDeviceKinds
MoveSizeOperation
ProximityEvaluation
TouchHitTestingEventArgs
WindowRectChangedEventArgs
WindowRectChangingEventArgs
Microsoft.UI.Input.Experimental
ExpInputSite
ExpPointerPoint
Microsoft.UI.Windowing
AppWindow
DefaultTitleBarShouldMatchAppModeTheme
DisplayArea
GetMetricsFromWindowId
Microsoft.UI.Xaml
XamlIsland
XamlRoot
CoordinateConverter
TryGetContentIsland
Microsoft.UI.Xaml.Automation.Peers
PagerControlAutomationPeer
ScrollPresenterAutomationPeer
Microsoft.UI.Xaml.Controls
ContentDialogPlacement
UnconstrainedPopup
ElementFactory
FlowLayout
FlowLayoutAnchorInfo
FlowLayoutLineAlignment
FlowLayoutState
IApplicationViewSpanningRects
IndexPath
ISelfPlayingAnimatedVisual
ItemContainer
CanUserInvoke
CanUserInvokeProperty
CanUserSelect
CanUserSelectProperty
ItemInvoked
MultiSelectMode
MultiSelectModeProperty
ItemContainerInteractionTrigger
ItemContainerInvokedEventArgs
ItemContainerMultiSelectMode
ItemContainerUserInvokeMode
ItemContainerUserSelectMode
LayoutPanel
NumberBox
InputScope
InputScopeProperty
TextAlignment
TextAlignmentProperty
PagerControl
PagerControlButtonVisibility
PagerControlDisplayMode
PagerControlSelectedIndexChangedEventArgs
PagerControlTemplateSettings
ProgressRing
DeterminateSource
DeterminateSourceProperty
IndeterminateSource
IndeterminateSourceProperty
RecyclePool
RecyclingElementFactory
ScrollingViewChangingEventArgs
ScrollView
ViewChanging
SelectionModel
SelectionModelChildrenRequestedEventArgs
SelectionModelSelectionChangedEventArgs
SelectTemplateEventArgs
StackLayout
IsVirtualizationEnabled
IsVirtualizationEnabledProperty
StackLayoutState
TabView
CanTearOutTabs
CanTearOutTabsProperty
ExternalTornOutTabsDropped
ExternalTornOutTabsDropping
TabTearOutRequested
TabTearOutWindowRequested
TabViewExternalTornOutTabsDroppedEventArgs
TabViewExternalTornOutTabsDroppingEventArgs
TabViewTabTearOutRequestedEventArgs
TabViewTabTearOutWindowRequestedEventArgs
TitleBar
TitleBarAutomationPeer
TitleBarTemplateSettings
UniformGridLayoutState
Microsoft.UI.Xaml.Controls.Primitives
ScrollPresenter
ViewChanging
Microsoft.Windows.ApplicationModel.WindowsAppRuntime
DeploymentManager
Repair
DeploymentStatus
PackageRepairFailed
ReleaseInfo
RuntimeInfo
VersionInfoContract
Microsoft.Windows.Widgets.Feeds.Providers
FeedManager
TryRemoveAnnouncementById
IFeedManager3
Microsoft.Windows.Widgets.Notifications
WidgetAnnouncement
WidgetAnnouncementInvokedArgs
Microsoft.Windows.Widgets.Providers
IWidgetAnnouncementInvokedTarget
IWidgetManager2
IWidgetManager3
IWidgetProviderMessage
IWidgetResourceProvider
WidgetManager
SendMessageToContent
TryRemoveAnnouncementById
TryShowAnnouncement
WidgetMessageReceivedArgs
WidgetResourceRequest
WidgetResourceRequestedArgs
WidgetResourceResponse
已知问题
- 对于 TabView 选项卡拆解,CanTearOutTabs 的指针输入行为在缩放系数不同于 100% 的监视器上不正确。 将在下一个 1.6 版本中修复此问题。
Bug 修复
- 修复了 1.6-experimental1 中
NumberBox
未使用正确前景和背景色的问题。 有关详细信息,请参阅 GitHub 问题 #9714。 - 修复了箭头键和选项卡键引发重复
KeyUp
事件的问题。 有关详细信息,请参阅 GitHub 问题 #9399。 - 修复了无法获取
SystemSuspendStatus
事件的问题PowerManager.SystemSuspendStatusChanged
。 有关详细信息,请参阅 GitHub 问题 #2833。 - 修复了以下问题:初始键盘焦点未正确提供给窗口中唯一
WebView2
控件的时间。 - 修复了在
ExtendsContentIntoTitleBar=true
UI 自动化中未正确显示 Min/Max/Close 按钮的问题,这阻止了语音访问显示这些按钮的数字。 - 修复了由于意外重新进入而导致应用在锁定检查中崩溃的问题。
- 修复了 1.6-experimental1 中
TitleBar
仅显示图标和标题的问题,因为某些元素未在加载时显示。 - 修复了切换为高对比度主题时颜色未正确更新的问题
Hyperlink
。 - 修复了以下问题:更改后台窗口中的
ListView
集合可能会错误地将该窗口移动到前台并获取焦点。 - 修复了 1.6 实验性 1
AcrylicBrush.TintLuminosityOpacity
的问题:类库项目中的 .xaml 设置会崩溃并出现类型转换错误。 - 修复了调用
ItemsRepeater.StartBringIntoView
有时可能导致项目消失的问题。 - 修复了触摸和拖动
Button
处于ScrollViewer
按下状态的问题。 - 更新了 IntelliSense,它缺少许多较新的类型和成员的信息。
版本 1.6 实验版 (1.6.0-experimental1)
这是试验通道的最新版本。
若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.6.240531000-experimental1
。
1.6-experimental1 所需的 C# 项目更改
在 1.6-experimental1 中,Windows 应用 SDK托管应用需要Microsoft.Windows.SDK.NET.Ref *.*.*.35-preview
(或更高版本),这可以通过文件中的 csproj
WindowsSdkPackageVersion 指定。 例如:
<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>
...
此外,Windows 应用 SDK使用 C#/WinRT 的托管应用应更新为 Microsoft.Windows.CsWinRT 2.1.0-prerelease.240602.1
(或更高版本)。
本机 AOT 支持
注意
对于 Windows 应用 SDK 1.6.0 稳定版,以下指南已过时。 项目应改为无条件地设置为 PublishAot
true 。
本机预编译现在支持 .NET PublishAot
项目属性。 有关详细信息,请参阅 本机 AOT 部署。 由于 AOT 基于剪裁支持而构建,因此以下大部分与剪裁相关的指南也适用于 AOT。
对于PublishAot
支持,除了上一节中所述的 C# 项目更改之外,还需要对 Microsoft.Windows.CsWinRT 2.1.0-prerelease.240602.1
(或更高版本)的包引用来启用该包中的源生成器。
由于Windows 应用 SDK在 F5 部署时调用发布目标,因此我们建议在 NuGet 还原时启用PublishAot
,方法是将此项添加到csproj
文件:
<PublishAot Condition="'$(ExcludeRestorePackageImports)'=='true'">true</PublishAot>
此外,我们建议在发布发布配置文件或项目中有条件地启用 PublishAot
发布配置:
<PublishAot Condition="'$(Configuration)'=='Release'">true</PublishAot>
解决 AOT 问题
在此版本中,开发人员负责确保所有类型都正确植根以避免剪裁(如基于 {Binding}
反射的目标)。 以后的版本将增强 C#/WinRT 和 XAML 编译器,以便尽可能自动进行根治,提醒开发人员剪裁风险,并提供解决的机制。
分部类
C#/WinRT 还支持 PublishAot
版本 2.1.0-prerelease.240602.1。 若要使用 C#/WinRT 为 AOT 发布启用类,必须先标记 partial
该类。 这样,C#/WinRT AOT 源分析器就可以将类特性化为静态分析。 只有类(包含方法,剪裁的目标)才需要此属性。
无反射技术
若要启用 AOT 兼容性,应将基于反射的技术替换为静态类型化序列化、AppContext.BaseDirectory、typeof()等。有关详细信息,请参阅 剪裁警告简介。
根类型
在完全支持{Binding}
实现之前,可以将类型从剪裁中保留,如下所示:给定项目P
使用具有命名空间N
中类型的T
程序集A
(仅动态引用(因此通常已剪裁),T
可以通过:
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>
有关完整的根描述符 XML 表达式语法,请参阅 根描述符。
注意
尚未采用 AOT 支持的依赖项包可能会显示运行时问题。
改进了 TabView 选项卡拆解
TabView
支持新的 CanTearOutTabs
模式,该模式为拖动选项卡和拖出新窗口提供了增强的体验。 启用此新选项后,选项卡拖动非常类似于 Edge 和 Chrome 中的选项卡拖动体验,在拖动过程中会立即创建一个新窗口,允许用户将其拖动到屏幕边缘,以最大化或将窗口贴靠在一个平滑动作中。 此实现也不使用拖放 API,因此不受这些 API 中的任何限制的影响。 值得注意的是,在以管理员身份提升的进程中,支持选项卡拆解。
已知问题: 在此版本中,对于比例系数不同于 100% 的监视器,指针输入行为 CanTearOutTabs
不正确。 将在下一个 1.6 版本中修复此问题。
新建 TitleBar 控件
使用新的 TitleBar
控件,可以轻松为应用创建一个具有以下功能的出色可自定义标题栏:
- 可配置的图标、标题和副标题属性
- 集成后退按钮
- 添加自定义控件(如搜索框)的功能
- 基于窗口宽度自动隐藏和显示元素
- 显示活动窗口或非活动窗口状态的提供
- 支持默认标题栏功能,包括空区域中的可拖动区域、主题响应能力、默认标题(min/max/close)按钮和内置辅助功能支持
该 TitleBar
控件旨在支持各种标题栏组合,使创建所需的体验变得灵活,而无需编写大量自定义代码。 我们从社区工具包 titlebar 原型获取反馈,并期待其他反馈!
已知问题: 在此版本中,由于某些元素未在加载时出现的问题, TitleBar
唯一显示图标和标题。 若要解决此问题,请使用以下代码加载其他元素(副标题、页眉、内容和页脚):
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();
}
此问题将在下一个 1.6 版本中修复。
其他值得注意的更改
- 未
ItemsWrapGrid
密封。 这应该是向后兼容的更改。 PipsPager
支持可在第一个项和列表项之间换行的新模式。RatingControl
现在,通过将一些硬编码样式属性移动到主题资源,可以更自定义。 这样,应用就可以重写这些值,以便更好地自定义 RatingControl 的外观。
1.6 实验性 1 的新 API
1.6-experimental1 包括以下新 API。 这些 API 不是实验性的,但尚未包含在 WinAppSDK 的稳定版本中。
Microsoft.UI.Xaml.Controls
PipsPager
WrapMode
WrapModeProperty
PipsPagerWrapMode
None
Wrap
其他 1.6 实验性 1 API
此版本包括以下新的和经过修改的实验 API:
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
其他已知问题
- 如果启用了任何辅助功能或 UI 自动化工具(例如语音访问、讲述人、辅助功能见解、Inspect.exe等),则使用
Microsoft.UI.Content.ContentIslands
和不处理 ContentIsland.AutomationProviderRequested 事件(或返回 nullptrr 作为自动化提供程序)的非 XAML 应用程序将崩溃。
Bug 修复
此版本中包含以下 bug 修复:
- 修复了以下问题:在空区域中
ScrollViewer
单击将焦点始终移动到该控件中的第一个可聚焦控件,ScrollViewer
并将该控件滚动到视图中。 有关详细信息,请参阅 GitHub 问题 #597。 - 修复了事件有时多次触发的问题
Window.Activated
。 有关详细信息,请参阅 GitHub 问题 #7343。 - 修复了设置
NavigationViewItem.IsSelected
属性以防止true
其子级在展开时显示的问题。 有关详细信息,请参阅 GitHub 问题 #7930。 - 修复了无法正确显示带有
None
或DropShadow
边缘效果的标题的问题MediaPlayerElement
。 有关详细信息,请参阅 GitHub 问题 #7981。 - 修复了显示浮出控件时未使用该属性的问题
Flyout.ShowMode
。 有关详细信息,请参阅 GitHub 问题 #7987。 - 修复了有时会出现舍入错误的问题
NumberBox
。 有关详细信息,请参阅 GitHub 问题 #8780。 - 修复了使用针对旧版 WinAppSDK 编译的库可能会命中尝试查找类型或属性的问题。 有关详细信息,请参阅 GitHub 问题 #8810。
- 修复了启动窗口时未设置初始键盘焦点的问题。 有关详细信息,请参阅 GitHub 问题 #8816。
- 修复了首次显示后无法正常工作的问题
FlyoutShowMode.TransientWithDismissOnPointerMoveAway
。 有关详细信息,请参阅 GitHub 问题 #8896。 - 修复了某些控件无法正确绑定模板
Foreground
和Background
属性的问题。 有关详细信息,请参阅 GitHub 问题 #7070、 #9020、 #9029、 #9083 和 #9102。 - 修复了在 setter 中使用的
VisualStateManager
主题更改不会更新的问题ThemeResource
。 浮出控件中经常受影响的控件。 有关详细信息,请参阅 GitHub 问题 #9198。 - 修复了失去关键焦点的问题
WebView
,导致额外的模糊/焦点事件和其他问题。 有关详细信息,请参阅 GitHub 问题 #9288。 - 修复了在调试输出中显示绑定错误的问题
NavigationView
。 有关详细信息,请参阅 GitHub 问题 #9384。 - 修复了定义负视图框的 SVG 文件不再呈现的问题。 有关详细信息,请参阅 GitHub 问题 #9415。
- 修复了更改
ItemsView.Layout
方向导致项目被删除的问题。 有关详细信息,请参阅 GitHub 问题 #9422。 - 修复了滚动
ScrollView
生成大量调试输出的问题。 有关详细信息,请参阅 GitHub 问题 #9434。 - 修复了无法
MapContorl.InteractiveControlsVisible
正常工作的问题。 有关详细信息,请参阅 GitHub 问题 #9486。 - 修复了事件
MapControl.MapElementClick
未正确触发的问题。 有关详细信息,请参阅 GitHub 问题 #9487。 - 修复了在使用弱引用之前 x:Bind 不会检查 null 的问题,这可能会导致崩溃。 有关详细信息,请参阅 GitHub 问题 #9551。
- 修复了更改
TeachingTip.Target
属性无法正确更新其位置的问题。 有关详细信息,请参阅 GitHub 问题 #9553。 - 修复了下拉列表未在 WebView2 中响应的问题。 有关详细信息,请参阅 GitHub 问题 #9566。
- 修复了使用
GeometryGroup
时内存泄漏问题。 有关详细信息,请参阅 GitHub 问题 #9578。 - 修复了从中
ItemRepeater
ScrollView
滚动大量项可能会导致空白呈现帧的问题。 有关详细信息,请参阅 GitHub 问题 #9643。 - 修复了无法正常工作的问题
SceneVisual
。