使用 Windows App SDK 的预览和实验通道创建一个 WinUI 3 应用

Windows App SDK 包括 WinUI 3 项目模板，你可以利用这些模板，使用完全基于 WinUI 的用户界面创建桌面应用。 使用这些项目模板创建应用时，应用程序的整个用户界面都是使用 WinUI 3 提供的窗口、控件和其他 UI 类型实现的。 有关项目模板的完整列表，请参阅 Visual Studio 中的 WinUI 3 模板。

使用 Windows App SDK 稳定版：要使用 Windows App SDK 的稳定版本生成 WinUI 3 应用，请参阅创建你的第一个 WinUI 3 项目。

先决条件

要使用本文所述的 WinUI 3 项目模板，请配置开发计算机，并安装适用于 Visual Studio 的 Windows App SDK 扩展。 有关详细信息，请参阅安装 Windows App SDK 的预览和试验通道工具.

注意

特定基础 WinRT 类型包括 CoreWindow、ApplicationView、CoreApplicationViewCoreDispatcher而其依赖项在桌面应用中不可用。 这些类型专为 UWP 应用中的 UI 方案设计，由于线程模型和其他平台差异，它们在桌面应用中不能正常运行。 有关详细信息，包括建议的替代 API，请参阅桌面应用中不支持的 Windows 运行时 API。

打包的 WinUI 3 桌面应用的说明

要创建使用 MSIX 打包的 WinUI 3 应用程序，请根据项目语言和已安装的 Windows App SDK 版本，从以下说明集中选择一个。

具有 1.0 预览版 3 的 C#

要使用 Windows App SDK 1.0 预览版 3，通过 C# 创建 WinUI 3 桌面应用，请执行以下操作：

1. 在 Visual Studio 中，选择“文件”->“新建”->“项目”。

2. 在“项目”下拉筛选器中，分别选择“C#”、“Windows”和“WinUI”。

3. 选择以下项目类型之一，然后单击“下一步”。

   • 打包的空白应用（桌面版 WinUI 3）：使用基于 WinUI 的用户界面创建桌面 C# .NET 应用。 生成的项目会配置有将应用生成为 MSIX 程序包所需的程序包清单和其他支持，而无需使用单独的打包项目。 有关此项目类型的详细信息，请参阅使用单项目 MSIX 将应用打包。

     注意

     如果安装了带有 Visual Studio 2019 的 Windows App SDK 1.0 预览版 2，则此项目模板有一个导致生成错误的已知问题。 要解决此问题，请在安装 Windows App SDK 1.0 预览版 2 后，安装适用于 Visual Studio 2019 VSIX 的单项目 MSIX 打包工具扩展。

   • 使用 WAP 打包的空白应用（桌面版 WinUI 3）：使用基于 WinUI 的用户界面创建桌面 C# .NET 应用。 生成的解决方案包括一个单独的 Windows 应用程序打包项目，该项目经配置后可将应用生成为 MSIX 程序包。

   

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

5. 在下面的对话框中，将“目标版本”设置为 Windows 10 版本 2004（内部版本 19041），并将“最低版本”设置为 Windows 10 版本 1809（内部版本 17763），然后单击“确定”。

   

6. 此时，Visual Studio 生成一个或更多项目：

   • 项目名称(桌面) ：此项目包含应用的代码。 App.xaml 文件和 App.xaml.cs 和代码隐藏文件定义了一个 Application 类，它表示你的应用实例 。 MainWindow.xaml 文件和 MainWindow.xaml.cs 代码隐藏文件定义了一个 MainWindow 类，它表示你的应用显示的主窗口 。 这些类派生自 WinUI 提供的 Microsoft.UI.Xaml 命名空间中的类型。

     如果使用了“打包的空白应用（桌面版 WinUI 3）”项目模板，则此项目还包括用于将应用生成为 MSIX 程序包的程序包清单。

     

   • 项目名称（程序包）：仅当使用“使用 WAP 打包的空白应用（桌面版 WinUI 3）”项目模板时，才生成此项目。 此项目是一个 Windows 应用程序打包项目，已配置该项目以将应用生成为 MSIX 程序包。 此项目包含应用的程序包清单，默认情况下它是你的解决方案的启动项目。

     

7. 在“配置管理器”中为项目启用部署。 如果不按照以下步骤启用部署，则在开发计算机上尝试运行或调试项目时，会遇到以下错误：“需要先部署项目，然后才能进行调试。 请在配置服务器启用部署”。

   1. 选择“生成”->“配置管理器”。

   2. 在“配置管理器”中，对配置和平台的每个组合单击“部署”复选框（例如“调试”和“x86”、“调试”和“arm64”、“发布”和“x64”等）。

      注意

      请务必使用顶部的“活动解决方案配置”和“活动解决方案平台”下拉菜单，而不是与“部署”复选框位于相同行中的“配置”和“平台”下拉菜单。

      

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

   

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

将 WinUI 桌面应用本地化

要在 WinUI 桌面应用中支持多种语言，并确保将打包的项目适当本地化，请将适当的资源添加到项目中（参阅应用资源和资源管理系统），并在项目的 package.appxmanifest 文件中声明每种受支持的语言。 生成项目时，指定的语言将添加到生成的应用清单 (AppxManifest.xml) 中，并将使用相应的资源。

1. 在文本编辑器中打开 .wapproj 的 package.appxmanifest，找到以下部分：

   <Resources>
       <Resource Language="x-generate"/>
   </Resources>
   

2. 对于你支持的每种语言，请将 <Resource Language="x-generate"> 替换为 <Resource /> 元素。 例如，以下标记指定“en-US”和“es-ES”本地化资源可用：

   <Resources>
       <Resource Language="en-US"/>
       <Resource Language="es-ES"/>
   </Resources>
   

具有早期版本的 C#

要使用 Windows App SDK 1.0 实验版或早期版本，通过 C# 和 .NET 创建 WinUI 3 桌面应用，请执行以下操作：

1. 在 Visual Studio 中，选择“文件”->“新建”->“项目”。

2. 在“项目”下拉筛选器中，分别选择“C#”、“Windows”和“WinUI”。

3. 选择“打包的空白应用(桌面版 WinUI 3)”，然后单击“下一步”。 输入项目名称，根据需要选择任何其他选项，然后单击“创建”。

4. 在下面的对话框中，将“目标版本”设置为 Windows 10 版本 2004（内部版本 19041），并将“最低版本”设置为 Windows 10 版本 1809（内部版本 17763），然后单击“确定”。

   

5. 此时，Visual Studio 生成两个项目：

   • 项目名称(桌面) ：此项目包含应用的代码。 App.xaml 文件和 App.xaml.cs 和代码隐藏文件定义了一个 Application 类，它表示你的应用实例 。 MainWindow.xaml 文件和 MainWindow.xaml.cs 代码隐藏文件定义了一个 MainWindow 类，它表示你的应用显示的主窗口 。 这些类派生自 WinUI 提供的 Microsoft.UI.Xaml 命名空间中的类型。

     

   • 项目名称(程序包) ：这是一个 Windows 应用程序打包项目，已配置该项目以将应用生成到 MSIX 包中。 此项目包含应用的程序包清单，默认情况下它是你的解决方案的启动项目。

     

     注意

     或者，可以为 Visual Studio 安装单项目 MSIX 打包工具扩展，并将打包项目设置合并到应用程序项目中。 此扩展使你可以开发和生成打包应用，而无需单独的打包项目。 有关详细信息，请参阅使用单项目 MSIX 将应用打包。

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

   

7. 生成并运行解决方案，确认应用运行时不会出错。

将 WinUI 桌面 C# 应用本地化

要在 WinUI 桌面应用中支持多种语言，并确保将打包的项目适当本地化，请将适当的资源添加到项目中（参阅应用资源和资源管理系统），并在项目的 package.appxmanifest 文件中声明每种受支持的语言。 生成项目时，指定的语言将添加到生成的应用清单 (AppxManifest.xml) 中，并将使用相应的资源。

1. 在文本编辑器中打开 .wapproj 的 package.appxmanifest，找到以下部分：

   <Resources>
       <Resource Language="x-generate"/>
   </Resources>
   

2. 对于你支持的每种语言，请将 <Resource Language="x-generate"> 替换为 <Resource /> 元素。 例如，以下标记指定“en-US”和“es-ES”本地化资源可用：

   <Resources>
       <Resource Language="en-US"/>
       <Resource Language="es-ES"/>
   </Resources>
   

具有 1.0 预览版 3 的 C++

要使用 Windows App SDK 1.0 预览版 2，通过 C++ 创建 WinUI 3 桌面应用，请执行以下操作：

1. 在 Visual Studio 中，选择“文件”->“新建”->“项目”。

2. 在“项目”下拉筛选器中，选择“C++”、“Windows”和“WinUI”。

3. 选择以下项目类型之一，然后单击“下一步”。

   • 打包的空白应用（桌面版 WinUI 3）：使用基于 WinUI 的用户界面创建桌面 C++ 应用。 生成的项目会配置有将应用生成为 MSIX 程序包所需的程序包清单和其他支持，而无需使用单独的打包项目。 有关此项目类型的详细信息，请参阅使用单项目 MSIX 将应用打包。

     注意

     此项目类型在生成的 MSIX 程序包中仅支持单个可执行文件。 如果需要将多个可执行文件合并到单个 MSIX 程序包中，则必须使用“使用 WAP 打包的空白应用（桌面版 WinUI 3）”项目模板或向解决方案添加 Windows 应用程序打包 项目。

   • 使用 WAP 打包的空白应用（桌面版 WinUI 3）：使用基于 WinUI 的用户界面创建桌面 C++ 应用。 生成的解决方案包括一个单独的 Windows 应用程序打包项目，该项目经配置后可将应用生成为 MSIX 程序包。

   

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

5. 在下面的对话框中，将“目标版本”设置为 Windows 10 版本 2004（内部版本 19041），并将“最低版本”设置为 Windows 10 版本 1809（内部版本 17763），然后单击“确定”。

   

6. 此时，Visual Studio 生成一个或更多项目：

   • 项目名称(桌面) ：此项目包含应用的代码。 App.xaml 和各种应用代码文件定义一个表示应用实例的 Application 类，MainWindow.xaml 和各种 MainWindow 代码文件定义一个表示应用显示的主窗口的 MainWindow 类。 这些类派生自 WinUI 提供的 Microsoft.UI.Xaml 命名空间中的类型。

     如果使用了“打包的空白应用（桌面版 WinUI 3）”项目模板，则此项目还包括用于将应用生成为 MSIX 程序包的程序包清单。

     

   • 项目名称（程序包）：仅当使用“使用 WAP 打包的空白应用（桌面版 WinUI 3）”项目模板时，才生成此项目。 此项目是一个 Windows 应用程序打包项目，已配置该项目以将应用生成为 MSIX 程序包。 此项目包含应用的程序包清单，默认情况下它是你的解决方案的启动项目。

     

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

   

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

   注意

   在 Visual Studio 2022 版本 17.0 到预览版 4 中，首次尝试运行解决方案时遇到错误“出现部署错误”。 要解决此问题，请再次运行或部署解决方案。 此问题将在 Visual Studio 2022 版本 17.0 预览版 5 中得到修复。

将 WinUI 桌面 C++ 应用本地化

要在 WinUI 桌面应用中支持多种语言，并确保将打包的项目适当本地化，请将适当的资源添加到项目中（参阅应用资源和资源管理系统），并在项目的 package.appxmanifest 文件中声明每种受支持的语言。 生成项目时，指定的语言将添加到生成的应用清单 (AppxManifest.xml) 中，并将使用相应的资源。

1. 在文本编辑器中打开 .wapproj 的 package.appxmanifest，找到以下部分：

   <Resources>
       <Resource Language="x-generate"/>
   </Resources>
   

2. 对于你支持的每种语言，请将 <Resource Language="x-generate"> 替换为 <Resource /> 元素。 例如，以下标记指定“en-US”和“es-ES”本地化资源可用：

   <Resources>
       <Resource Language="en-US"/>
       <Resource Language="es-ES"/>
   </Resources>
   

具有早期版本的 C++

要使用 Windows App SDK 1.0 实验版和早期版本，通过 C++ 创建 WinUI 3 桌面应用，请执行以下操作：

1. 在 Visual Studio 中，选择“文件”->“新建”->“项目”。

2. 在“项目”下拉筛选器中，选择“C++”、“Windows”和“WinUI”。

3. 选择“打包的空白应用(桌面版 WinUI 3)”，然后单击“下一步”。 输入项目名称，根据需要选择任何其他选项，然后单击“创建”。

4. 在下面的对话框中，将“目标版本”设置为 Windows 10 版本 2004（内部版本 19041），并将“最低版本”设置为 Windows 10 版本 1809（内部版本 17763），然后单击“确定”。

   

5. 此时，Visual Studio 生成两个项目：

   • 项目名称(桌面) ：此项目包含应用的代码。 App.xaml 和各种应用代码文件定义一个表示应用实例的 Application 类，MainWindow.xaml 和各种 MainWindow 代码文件定义一个表示应用显示的主窗口的 MainWindow 类。 这些类派生自 WinUI 提供的 Microsoft.UI.Xaml 命名空间中的类型。

     

   • 项目名称(程序包) ：这是一个 Windows 应用程序打包项目，已配置该项目以将应用生成到 MSIX 包中。 这提供了一种新式部署体验、通过包扩展与 Windows 10 及更高版本功能集成的功能以及更多其他功能。 此项目包含应用的程序包清单，默认情况下它是你的解决方案的启动项目。

     

     注意

     或者，可以为 Visual Studio 安装单项目 MSIX 打包工具扩展，并将打包项目设置合并到应用程序项目中。 此扩展使你可以开发和生成打包应用，而无需单独的打包项目。 有关详细信息，请参阅使用单项目 MSIX 将应用打包。

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

   

7. 生成并运行解决方案，确认应用运行时不会出错。

   注意

   将仅启动打包的项目，因此请确保将其设置为启动项目。

将 WinUI 桌面 C++ 应用本地化

要在 WinUI 桌面应用中支持多种语言，并确保将打包的项目适当本地化，请将适当的资源添加到项目中（参阅应用资源和资源管理系统），并在项目的 package.appxmanifest 文件中声明每种受支持的语言。 生成项目时，指定的语言将添加到生成的应用清单 (AppxManifest.xml) 中，并将使用相应的资源。

1. 在文本编辑器中打开 .wapproj 的 package.appxmanifest，找到以下部分：

   <Resources>
       <Resource Language="x-generate"/>
   </Resources>
   

2. 对于你支持的每种语言，请将 <Resource Language="x-generate"> 替换为 <Resource /> 元素。 例如，以下标记指定“en-US”和“es-ES”本地化资源可用：

   <Resources>
       <Resource Language="en-US"/>
       <Resource Language="es-ES"/>
   </Resources>
   

未打包的 WinUI 3 桌面应用的说明

注意

WinUI 3 对未打包的应用的支持目前为预览版，尚未做好生产准备。 必须下载适用于 Visual Studio 的 Windows App SDK 预览版扩展，才能获取项目模板，并通过 WinUI 3 生成未打包的桌面应用。 有关已知问题列表，请参阅 Windows App SDK 1.0 预览版 3 发行说明。

要创建 WinUI 3 应用程序而不使用 MSIX 打包，请根据项目语言和已安装的 Windows App SDK 版本，从以下说明集中选择一个。

具有 1.0 预览版 3 的 C#

要使用 Windows App SDK 1.0 预览版 3，通过 C# 创建 WinUI 3 桌面应用，请执行以下操作：

1. 安装单项目 MSIX 打包工具。

2. 安装 Visual Studio 2019 C# 扩展或 Visual Studio 2022 C# 扩展，具体取决于你的 Visual Studio 版本。

3. 安装 Windows App SDK 运行时和 MSIX 包。 这些是运行和部署应用所必需的。

4. 使用“打包的空白应用(桌面版 WinUI 3)”项目模板创建新应用。 必须从打包的应用开始，才能使用 XAML 诊断。

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

   <Project ...>
     ...
     <PropertyGroup>
       ...
       <WindowsPackageType>None</WindowsPackageType>
     </PropertyGroup> 
     ...
   </Project>
   

6. 从项目中删除 package.appxmanifest。

   否则，你将看到此错误：“项目配置不正确：WindowsPackageType 设置为 None，但指定了 AppxManifest”。

   注意

   你可能需要关闭 Visual Studio 解决方案才能从文件系统中手动删除此文件。

7. 要在 Visual Studio 中进行调试，请将调试属性从“MsixPackage”更改为“Project”。 否则，你将看到错误：“项目不知道如何运行该配置文件...”

   注意

   如果从命令行或 Windows 文件资源管理器执行应用程序 (.exe)，则无需执行此操作。

   • 在 Visual Studio 2022 中：打开 launchSettings.json 并将配置文件从“MsixPackage”更改为“Project”。

     {
         "profiles": {
             "Preview3": {
                 "commandName": "Project"
             }
         }
     }
     

   • 在 Visual Studio 2019 和 Visual Studio 2022 中：可使用 Visual Studio UI 更改启动设置：

     打开“调试”属性，将启动配置文件更改为“Project”

     

     

8. 如果尚未执行此操作，请安装运行和部署应用所需的 Windows App SDK 运行时和 MSIX 包。

   下载最新的安装程序和 MSIX 包

9. 生成并运行。 有关其他部署信息，请参阅 Windows App SDK 教程，了解如何部署使用外部位置打包的应用和未打包的应用（教程：在使用外部位置打包的应用或使用 Windows App SDK 的未打包应用中使用引导程序 API）。 本教程将指导你使用引导程序 API（请参阅将 Windows App SDK 运行时用于使用外部位置打包的应用或未打包的应用）来初始化 Windows App SDK 运行时，以便应用可以使用 Windows App SDK 和 WinUI 3 API。

具有 1.0 预览版 3 的 C++

要使用 Windows App SDK 1.0 预览版 3，通过 C++ 创建 WinUI 3 桌面应用，请执行以下操作：

1. 安装单项目 MSIX 打包工具。

2. 安装 Visual Studio 2019 C++ 扩展或 Visual Studio 2022 C++ 扩展，具体取决于你的 Visual Studio 版本。

3. 安装 Windows App SDK 运行时和 MSIX 包。 这些是运行和部署应用所必需的。

4. 使用“打包的空白应用(桌面版 WinUI 3)”项目模板创建新应用。 必须从打包的应用开始，才能使用 XAML 诊断。

5. 安装适当体系结构的 Microsoft Visual C++ 可再发行程序包

   • 最新版本的可再发行组件与最新的 Visual Studio GA 版本以及用于生成 Windows App SDK 二进制文件的 Visual Studio 所有版本兼容。
   • Visual Studio 的预览体验版本可能安装了更高版本的 VCRedist，在运行公共版本时，将会失败并出现以下错误（此错误可忽略）：“错误 0x80070666：由于已安装更高版本，无法安装产品。”

   注意

   如果未在目标设备上安装 VCRedist，则指向 c:\windows\system32\vcruntime140.dll 的动态链接将失败，这可能会以多种方式显示给最终用户。

6. 使用“打包的空白应用(桌面版 WinUI 3)”项目模板创建新应用。 必须从打包的应用开始，才能使用 XAML 诊断。

7. 将此属性添加到项目文件：

   <WindowsPackageType>None</WindowsPackageType>
   

8. 将以下两个项目属性更改为 false：

    <AppxPackage>false</AppxPackage>
    <AppContainerApplication>false</AppContainerApplication>
   

9. 从项目中删除 package.appxmanifest。

   • 否则，你将看到此错误：“项目配置不正确：WindowsPackageType 设置为 None，但 AppxPackage 设置为 true”。

   注意

   你可能需要关闭 Visual Studio 解决方案才能从文件系统中手动删除此文件。

10. 要在 Visual Studio 中进行调试，请将调试属性从“MsixPackage”更改为“Project”。

    注意

    如果使用可执行文件 (.exe) 打开应用程序，则无需执行此操作。

    • 在 Visual Studio 2019 和 Visual Studio 2022 中：打开“调试”属性，将“要启动的调试器”更改为“本地 Windows 调试器”

      

      

11. 如果尚未执行此操作，请安装运行和部署应用所需的 Windows App SDK 运行时和 MSIX 包。

    下载最新的安装程序和 MSIX 包

12. 8. 生成并运行。 有关其他部署信息，请参阅 Windows App SDK 教程，了解如何部署使用外部位置打包的应用和未打包的应用（教程：在使用外部位置打包的应用或使用 Windows App SDK 的未打包应用中使用引导程序 API）。 本教程将指导你使用引导程序 API（请参阅将 Windows App SDK 运行时用于使用外部位置打包的应用或未打包的应用）来初始化 Windows App SDK 运行时，以便应用可以使用 Windows App SDK 和 WinUI 3 API。

ASTA 到 STA 线程模型

如果要将代码从现有 UWP 应用迁移到使用 Windows App SDK 的新 WinUI 3 项目，请注意，新项目使用单线程单元 (STA) 线程模型，而不是 UWP 应用使用的应用程序 STA (ASTA) 线程模型。 如果代码采用 ASTA 线程模型的非可重入行为，则代码可能不会按预期方式运行。

请参阅

• Windows 应用 SDK
• Windows应用 SDK 示例