创建第一个 WinUI 3(Windows 应用 SDK)项目

在本主题中,我们将了解如何使用 Visual Studio 为 C# .NET 或 C++ 应用创建一个具有 Windows UI 库 (WinUI) 3 用户界面 (UI) 的新 Windows 应用 SDK 项目。 我们还将了解生成的项目中的一些代码、它们执行的操作以及其工作原理。

下面的步骤有完整安装详细信息的链接。 建议安装并面向 Windows 应用 SDK 的最新稳定版本(请参阅稳定渠道发行说明)。

提示

无论选择安装和面向哪个版本的 Windows 应用 SDK(或使用的是哪个版本的 Visual Studio),请务必检查该版本的发行说明中的​​任何限制和已知问题(请参阅 Windows 应用 SDK 发行渠道)。 通过了解你的 Windows 应用 SDK 版本的任何限制和已知问题,你将能够解决按照本主题中的步骤操作时遇到的任何问题。

如果遇到任何其他问题,你都可以在 GitHub 问题或 WindowsAppSDK GitHub 存储库的“讨论”标签中找到有关它们的信息;或通过在线搜索找到。

重要

如果使用的是 UWP 应用,请参阅从 UWP 迁移到 Windows 应用 SDK

关键概念

对于任何 Windows 应用 SDK 项目,都应着重考虑打包。 如果需要,可以跳过此部分,并创建一个未打包的项目。 但请稍后回来阅读有关它的更多信息。

  • MSIX 打包。 这是使用 MSIX 技术打包应用的过程(请参阅什么是 MSIX?)。 MSIX 是一种包格式,为用户提供了一种使用新式 UI 安装、卸载和更新应用的便捷方式。 MSIX 打包还为应用提供了一个程序包标识,这是某些 Windows 功能(例如,自定义上下文菜单扩展)所必需的。
  • 稀疏打包。 这是一种选择退出 MSIX 打包的方式,以便应用在应用类型、可以调用的 API 以及对注册表和文件系统的访问方面不受限制。 使用稀疏打包,你的应用仍具有程序包标识符,因此你可以使用上面提到的 Windows 功能。 稀疏打包的应用通常使用 .exe.msi 文件进行安装和更新,并使用自定义安装程序、ClickOnce 或 xcopy 部署。
  • 不打包。 出于上述原因而选择退出 MSIX 打包的另一种方式。 但未打包的应用没有程序包标识符。 未打包的应用通常使用 .exe.msi 文件进行安装和更新,并使用自定义安装程序、ClickOnce 或 xcopy 部署。

MSIX 打包:为 MSIX 打包的 C# 或 C++ WinUI 3 桌面应用创建一个新项目

  1. 若要设置开发计算机,请参阅安装适用于 Windows App SDK 的工具

  2. 在 Visual Studio 中,选择“文件”>“新建”>“项目”。

  3. 在“新建项目”对话框的下拉筛选器中,分别选择“C#”/“C++”、“Windows”和“WinUI”。

  4. 选择“打包的空白应用(桌面版 WinUI 3)”项目模板,然后单击“下一步”。 该模板创建一个具有基于 WinUI 3 的用户界面的桌面应用。 生成的项目配置有将应用生成到 MSIX 包所需的包清单和其他支持(请参阅什么是 MSIX?)。 有关此项目模板的详细信息,请参阅使用单项目 MSIX 将应用打包

    Screenshot of Create a new project wizard with the Blank App Packaged (Win UI in Desktop) option highlighted.

  5. 输入项目名称,根据需要选择任何其他选项,然后单击“创建”。

  6. Visual Studio 生成的项目包含应用的代码。 App.xaml 文件和代码隐藏文件定义了一个 Application 派生类,它表示正在运行的应用。 MainWindow.xaml 文件和代码隐藏文件定义了一个 MainWindow 类,它表示应用显示的主窗口。 这些类派生自 WinUI 3 提供的 Microsoft.UI.Xaml 命名空间中的类型。

    该项目还包括用于将应用生成到 MSIX 包的包清单。

    Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Main Windows X A M L dot C S file for single project M S I X.

  7. 若要向应用添加新项,请在解决方案资源管理器中右键单击项目节点,然后选择“添加”>“新项”。 在“添加新项”对话框中,选择“WinUI”选项卡,选择要添加的项,然后单击“添加”。 有关可用项的更多详细信息,请参阅 Visual Studio 中的 WinUI 3 模板

    Screenshot of the Add New Item dialog box with the Installed > Visual C sharp Items > Win U I selected and the Blank Page option highlighted.

  8. 在开发计算机上生成并运行解决方案,确认应用运行时不会出错。

非 MSIX 打包:为非 MSIX 打包的 C# 或 C++ WinUI 3 桌面应用创建一个新项目

  1. 若要设置开发计算机,请参阅安装适用于 Windows App SDK 的工具

  2. 下载 Windows App SDK 下载 Windows App SDK 的最新安装程序。 这将安装在目标设备上运行和部署非 MSIX 打包应用所需的运行时包依赖项(请参阅针对未打包的应用的 Windows App SDK 部署指南)。

  3. C++。 安装适用于目标设备体系结构的 Microsoft Visual C++ 可再发行程序包 (VCRedist)

    • VCRedist 的最新版本与 Visual Studio 的最新正式发布版 (GA) (也就是说不是预览版)兼容,并与可用于生成 Windows App SDK 二进制文件的所有 Visual Studio 版本。
    • Visual Studio 的预览体验版本可能安装了更高版本的 VCRedist。在运行公共版本时,预览体验版本将会失败并出现以下错误(可忽略此错误):“错误 0x80070666: 已安装更高版本时,无法安装产品。”

    备注

    如果未在目标设备上安装 VCRedist,则到 c:\windows\system32\vcruntime140.dll 的动态链接会失败。 这种失败可通过各种方式显示给最终用户。

  4. 在 Visual Studio 中,选择“文件”>“新建”>“项目”。

  5. 在“新建项目”对话框的下拉筛选器中,分别选择“C#”/“C++”、“Windows”和“WinUI”。

  6. 需要首先使用 MSIX 打包的项目,才能使用 XAML 诊断。 因此,选择“打包的空白应用(桌面版 WinUI 3)”项目模板,然后单击“下一步”。 .

  7. 将以下属性添加到项目文件中 - .csproj (C#) 或 .vcxproj (C++) 文件中:

    <Project ...>
      ...
      <PropertyGroup>
        ...
        <WindowsPackageType>None</WindowsPackageType>
      </PropertyGroup> 
      ...
    </Project>
    
  8. C++。 在 C++ 项目 (.vcxproj) 文件中,将 AppxPackage 属性设置为 false:

    <Project ...>
      ...
      <PropertyGroup>
        ...
        <AppxPackage>false</AppxPackage>
        ...
      </PropertyGroup> 
      ...
    </Project>
    
  9. C# 中的检测示例。 若要从 Visual Studio 启动 C# 应用(“调试”或“不调试”),请从“启动”下拉菜单中选择“未打包”启动配置文件。 如果选择了包配置文件,Visual Studio 中会出现部署错误。 如果从命令行或 Windows 文件资源管理器启动应用程序 (.exe),则无需执行此操作。

    Visual Studio - Start drop-down with C# application unpackaged launch profile highlighted

  10. 生成并运行。

引导程序 API

设置 <WindowsPackageType>None</WindowsPackageType> 项目属性会使自动初始化程序找到并加载最适合应用的 Windows 应用 SDK 版本。

如果有高级需求(例如自定义错误处理或加载特定版本的 Windows 应用 SDK),则可以改为显式调用引导程序 API。 有关详细信息,请参阅将 Windows 应用 SDK 运行时用于非 MSIX 打包应用教程 - 在使用 Windows 应用 SDK 的非 MSIX 打包应用中使用引导程序 API

有关引导程序的详细信息,请参阅依赖于框架的应用的部署体系结构和概述

查看项目模板中的代码

在本演练中,我们使用了“打包的空白应用(桌面版 WinUI 3)”项目模板,该模板创建了一个具有基于 WinUI 3 用户界面的桌面应用。 让我们看看该模板附带的一些代码及其执行的操作。 若要详细了解可用的 WinUI 3 项目和项模板,请参阅 Visual Studio 中的 WinUI 3 模板

应用的入口点

当 Windows 操作系统 (OS) 运行应用时,OS 在应用的入口点中开始执行。 该入口点采用 Main(或者对于 C++/WinRT 采用 wWinMain)函数的形式。 通常,新项目会将该函数配置为由 Visual Studio 生成进程自动生成。 它默认处于隐藏状态,因此你无需关注它。 但如果你想要了解详细信息,请参阅 Main 或 wWinMain 中的单实例

App 类

整个应用由一个类表示,该类通常简称为 App。 该类在 App.xaml 中定义,位于其代码隐藏文件中(App.xaml.csApp.xaml.h.cpp)。 App 派生自 WinUI 3 Microsoft.UI.Xaml.Application 类。

入口点中生成的代码会创建一个 App 的实例,并将其设置为运行。

在 App 的构造函数中,你将看到正在调用 InitializeComponent 方法。 该方法本质上分析 App.xaml 的内容,即 XAML 标记。 这一点很重要,因为 App.xaml 包含合并资源,需要将这些资源解析并加载到字典中以供正在运行的应用使用。

App 的另一个有趣的方法是 OnLaunched。 使用此方法可创建和激活 MainWindow 类(我们接下来会进行介绍)的新实例。

MainWindow 类

应用所显示的主窗口当然由 MainWindow 类表示。 该类在 MainWindow.xaml 中定义,位于其代码隐藏文件中(MainWindow.xaml.csMainWindow.xaml.h.cpp)。 MainWindow 派生自 WinUI 3 Microsoft.UI.Xaml.Window 类。

MainWindow 的构造函数调用其自己的 InitializeComponent 方法。 同样,它的工作是将 MainWindow.xaml 中的 XAML 标记转换为用户界面 (UI) 对象图形。

在 MainWindow.xaml 中,你将看到 MainWindow 的基本布局。 在此布局中,根目录是一个名为 Microsoft.UI.Xaml.Controls.StackPanel 的动态面板。 有关布局面板的详细信息,请参阅布局面板

该 StackPanel 内是一个 Microsoft.UI.Xaml.Controls.Button。 该 Button 使用标记 Click="myButton_Click" 以声明方式连接 Click 事件的事件处理程序方法。

该方法名为 myButton_Click,你可以在 MainWindow.xaml.csMainWindow.xaml.cpp 中找到该方法的实现。 其中,按钮的内容从默认的“单击我”更改为“已单击”。

C++。 如果创建了 C++ 项目,则还会看到一个 MainWindow.idl 文件。 有关详细信息,请参阅 C++/WinRT 文档。 XAML 控件;绑定到 C++/WinRT 属性是开始了解 .idl 文件的用途和用法的不错位置。

后续步骤

若要继续使用 Windows App SDK 进行开发,请参阅开发 Windows 桌面应用