在 Windows Forms (WinForms) 应用中使用 Windows App SDK

Windows App SDK 是 Windows 应用开发平台的下一个演变。 但本主题演示如何在 Windows Forms (WinForms) 应用中使用 Windows App SDK API（和 Windows Runtime API）！

• 在许多情况下，需要以 WinUI 3 应用的形式重新创建 WinForms 应用。 迁移到 WinUI 3 的优势之一是有权访问 Fluent Design System（另请参阅设计 Windows 应用并编写代码）。 WinUI 3 是 Windows App SDK 的一部分，因此，WinUI 3 应用也可以使用其他Windows App SDK 功能和 API。 本主题不介绍将 WinForms 应用迁移到 WinUI 3 的过程。
• 但是，如果发现使用的是 WinUI 3 中尚不可用的 WinForms 功能，则仍然可以在 WinForms 应用中使用 Windows App SDK 功能（如 App Lifecycle、MRT Core、DWriteCore 等）。 本主题演示如何执行该操作。

如果目前还没有 WinForms 项目（或者想要练习该过程），本主题包含创建 WinForms 项目的步骤，以便按照步骤操作并进行配置以调用 Windows App SDK API。

先决条件

1. 安装适用于 Windows App SDK 的工具。
2. 本主题介绍未打包和打包的 WinForms 应用。 如果 WinForms 应用已解压缩（默认使用哪个 WinForms 应用），请确保已安装未打包应用的所有依赖项（请参阅 Windows App SDK 部署指南，了解使用外部位置打包或未打包的依赖框架的应用）。 执行此操作的快速方法是访问Windows App SDK 的最新下载，然后下载并解压缩，然后运行其中一个稳定版本 Runtime 下载。

重要

安装的 Runtime 版本需要与将在后续步骤中安装的 Microsoft.WindowsAppSDK NuGet 包的版本相匹配。

有关未打包和打包术语的详细信息，请参阅打包应用的优点和缺点。

如果你没有源，请创建一个 WinForms 项目。

如果已有 WinForms 项目，则可以转到下一部分。

1. 在 Visual Studio 中，创建一个新的 C# Windows Forms 应用项目（即 .NET 项目）。 请谨慎选择项目模板，确切名称为 Windows Forms 应用，而不是 Windows Forms 应用 (.NET Framework)。
2. 为项目指定一个名称，并接受任何默认选项。

现在你有一个项目，用于生成未打包的 WinForms 应用。

配置 WinForms 项目以提供 Windows App SDK 支持

首先，我们将编辑项目文件。

1. 在“解决方案资源管理器”中，右击项目，然后选择“编辑项目文件”。

2. 此步骤可调用 Windows Runtime (WinRT) API（包括 Windows App SDK API）。 PropertyGroup 元素中的 TargetFramework 元素设置为 net6.0 等值。 向目标框架值追加名字对象（具体指目标框架名字对象）。 例如，如果应用目标是 Windows 10 版本 2004，请使用以下项：

   <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
   

3. 此外，在 PropertyGroup 元素中添加 RuntimeIdentifiers 元素，比如：

   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   

4. 默认情况下，WinForms 应用已解压缩（这意味着未使用 MSIX 进行安装）。 未打包的应用在使用 Windows App SDK 的任何其他功能之前，必须先初始化 Windows App SDK 运行时功能。 当应用通过自动初始化启动时，可以自动执行此操作。 只需适当地设置 PropertyGroup 元素中的 WindowsPackageType 项目属性，如下所示：

   <WindowsPackageType>None</WindowsPackageType>
   

   如果有高级需求（例如自定义错误处理或加载特定版本的 Windows App SDK），则无需自动初始化即可显式调用引导程序 API。有关详细信息，请参阅为使用外部位置打包或未打包的应用使用 Windows App SDK 运行时功能。

5. 保存并关闭项目文件。

接下来，我们将在项目中安装 Windows App SDK NuGet 包。

6. 在“解决方案资源管理器”中，右键单击项目的“依赖项”节点，然后选择“管理 Nuget 包...”。
7. 在 NuGet 程序包管理器 窗口中，选择“浏览”选项卡，并安装最新的稳定Microsoft.WindowsAppSDK 包。

在 WinForms 应用中使用一些 Windows App SDK 功能

本部分提供一个非常简单的示例来介绍如何从 WinForms 应用调用 Windows App SDK API。 它使用 MRT Core 功能（请参阅使用 MRT Core 管理资源）。 如果本示例适用于 WinForms 项目（即为此演练创建了一个新项目），则可以按照以下步骤操作。

1. 打开 Form1.cs（使用 View Designer 命令），然后从从工具箱中拖出一个按钮和一个标签到设计器上。

2. 双击 button1 以生成一个事件处理程序。

3. 现在，我们将添加一些代码来使用 Windows App SDK 中的 ResourceManager 类加载字符串资源。

   1. 将新的资源文件 (.resw) 项添加到项目（保留 Resources.resw 的默认名称）。

   2. 在编辑器中打开资源文件后，使用以下属性创建新的字符串资源。

      • 名称：消息
      • 值：Hello, resources!

   3. 保存并关闭资源文件。

   4. 打开 Form1.cs（使用 View Code 命令）并编辑事件处理程序，如下所示：

   private void button1_Click(object sender, EventArgs e)
   {
       // Construct a resource manager using the resource index generated during build.
       var manager =
           new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
   
       // Look up a string in the resources file using the string's name.
       label1.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
   }
   

4. 生成项目并运行应用。 单击该按钮可查看显示的字符串 Hello, resources!。

提示

如果在运行时看到一个消息框，指示应用程序需要特定版本的 Windows App Runtime 并询问是否要立即安装，则单击“是”。 这将带你进入 Windows App SDK 最新下载。 有关详细信息，请参阅上面的先决条件部分。

另请参阅运行时体系结构，详细了解应用在使用 Windows App SDK 时采用的 Framework 包依赖项，以及需要在未打包的应用中使用的其他组件。

使用 MSIX 打包并部署 WinForms 应用

某些 Windows 功能和 API（包括 Windows App SDK 通知 API）要求应用在运行时具有包标识（换句话说，应用需要打包）。 有关详细信息，请参阅需要包标识的功能。

1. 在 Visual Studio 的“解决方案资源管理器”中，右键单击解决方案，然后选择“添加”>“新项目...”。
2. 在“添加新项目”对话框中，搜索 packaging，选择 C#“Windows 应用程序打包项目”项目模板，然后单击“下一步”。
3. 命名项目，然后单击“创建”。
4. 我们希望指定要将解决方案中的哪些应用程序包含在包中。 因此，在打包项目（不是 WinForms 项目）中，右键单击“依赖项”节点，然后选择“添加项目引用...”。
5. 在解决方案中的项目列表中，选择 WinForms 项目，然后单击“确定”。
6. 展开打包项目的依赖项>应用程序节点，确认已引用 WinForms 项目并用粗体突出显示。 这意味着它将用作包的起点。
7. 右键单击打包项目，然后选择“设为启动项目”。
8. 右键单击 WinForms 项目，然后选择“编辑项目文件”。
9. 删除 <WindowsPackageType>None</WindowsPackageType>、保存并关闭。
10. 在“解决方案平台”下拉列表中，选择 x64（而不是任何 CPU）。
11. 确认可以生成并运行。

打包 WinForms 应用后，可以调用需要包标识的 API。 所以，打开 Form1.cs（使用 View Code 命令）并编辑事件处理程序，如下所示：

private void button1_Click(object sender, EventArgs e)
{
    var notification = new AppNotificationBuilder()
        .AddArgument("action", "viewConversation")
        .AddArgument("conversationId", "9813")
        .AddText("Andrew sent you a picture")
        .AddText("Check this out, The Enchantments in Washington!")
        .BuildNotification();

    AppNotificationManager.Default.Show(notification);
}

生成并重新运行。 单击该按钮，确认显示 Toast 通知。 从运行时缺少包标识的进程调用时，通知 API 将引发异常。

备注

本部分中的步骤演示了如何创建打包的应用。 另一种方法是使用外部位置创建打包的应用。 有关所有这些关键词的提醒，请参阅打包应用的优点和缺点。

相关主题

• Windows 窗体 (WinForms)
• 安装适用于 Windows App SDK 的工具
• 依赖于框架的使用外部位置打包的应用或未打包应用的 Windows App SDK 部署指南
• Windows App SDK 最新下载
• 打包应用的优点和缺点
• 为使用外部位置打包的应用或未打包的应用使用 Windows App SDK 运行时
• 运行时体系结构
• 需要包标识的功能