在 Windows Forms (WinForms) 應用程式中使用 Windows 應用程式 SDK

發行項
08/22/2024

Windows 應用程式 SDK 是 Windows 應用程式開發平台的新一代演進。但本主題要說明的是如何在 Windows Forms (WinForms) 應用程式中使用 Windows 應用程式 SDK API (和 Windows 執行階段 API)！

許多情況下，您需要以 WinUI 3 應用程式的形式重新建立 WinForms 應用程式。移至 WinUI 3 的優點之一就是能夠存取 Fluent 設計系統 (另請參閱設計與編碼 Windows 應用程式)。且 WinUI 3 是 Windows 應用程式 SDK 的一部分，因此，WinUI 3 應用程式自然也可以使用其他 Windows 應用程式 SDK 功能和 API。本主題並未收錄將 WinForms 應用程式移轉至 WinUI 3 的程序。
但是，如果您發現您使用的 WinForms 的功能尚未在 WinUI 3 提供，您仍然可以在 WinForms 應用程式中使用 Windows 應用程式 SDK 功能 (例如應用程式生命週期、MRT Core、DWriteCore 等)。本主題會說明作法。

如果您目前沒有 WinForms 專案，或您想要練習此程序，本主題收錄了建立 WinForms 專案的步驟，以便您可按照步驟來設定專案，藉此呼叫 Windows 應用程式 SDK API。

必要條件

安裝 Windows 應用程式 SDK 的工具。
本主題的範圍涵蓋未封裝和已封裝的 WinForms 應用程式。如果您的 WinForms 應用程式為未封裝 (WinForms 應用程式預設即是未封裝)，請確認未封裝應用程式的所有相依性皆已安裝 (請參閱架構相依的含外部位置封裝應用程式或未封裝應用程式的 Windows 應用程式 SDK 部署指南)。若要快速執行此動作，請前往 Windows 應用程式 SDK 的最新下載項目，然後下載、解壓縮並執行其中一個穩定的版本的執行階段下載項目。

重要

您安裝的執行階段版本必須與您在稍後的步驟中安裝的 Microsoft.WindowsAppSDK NuGet 套件版本相符。

如需詳細了解未封裝和封裝等詞彙，請參閱封裝應用程式的優點和缺點。

如果您還沒有 WinForms 專案，請先建立專案

如果您已經有 WinForms 專案，請繼續下一節。

在 Visual Studio 中，建立新的 C# Windows Forms 應用程式 專案 (也就是 .NET 專案)。請小心選擇，專案範本的確切名稱須為 Windows Forms App，不是 Windows Forms App (.NET Framework)。
為專案命名，並接受任何預設選項。

至此您已有一個專案組建了未封裝 WinForms 應用程式。

設定 WinForms 專案來支援 Windows 應用程式 SDK

首先編輯專案檔。

在「方案總管」中，以滑鼠右鍵按一下專案，然後選擇 [編輯專案檔]。
此步驟可讓您呼叫 Windows 執行階段 (WinRT) API (包括 Windows 應用程式 SDK API)。 PropertyGroup 元素當中是 TargetFramework 元素，它已設為 net6.0 之類的值。在該目標架構值附加 Moniker (具體來說是 Target Framework Moniker)。舉例來說，如果您的應用程式以 Windows 10 版本 2004 為目標，請使用下列項目：
```
<TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
```
此外，在 PropertyGroup 元素內，新增 RuntimeIdentifiers 元素，如下所示：
```
<RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
```
根據預設，WinForms 應用程式為未封裝 (亦即不是使用 MSIX 安裝)。未封裝的應用程式必須先初始化 Windows 應用程式 SDK 執行階段，才能使用 Windows 應用程式 SDK 的任何其他功能。如果您的應用程式透過自動初始化開始建立，您就可以自動執行此動作。您只需要正確地設定 WindowsPackageType 專案屬性 (也是在 PropertyGroup 元素中)，如下所示：
```
<WindowsPackageType>None</WindowsPackageType>
```
如果您有進階需求 (例如自訂錯誤處理，或載入特定版本的 Windows 應用程式 SDK)，則您可以明確呼叫啟動程序載入程式 API，而不是自動初始化，如需詳細資訊，請參閱將 Windows 應用程式 SDK 執行階段使用於含有外部位置的封裝應用程式或未封裝應用程式。
儲存並關閉專案檔。

接下來，我們要在專案中安裝 Windows 應用程式 SDK NuGet 套件。

在「方案總管」中以滑鼠右鍵按一下專案的 [相依性] 節點，然後選擇 [管理 NuGet 套件...]。
在 [NuGet 封裝管理員] 視窗中，選取 [流覽] 索引標籤，然後安裝最新的穩定Microsoft.WindowsAppSDK 套件。

在 WinForms 應用程式中使用部分 Windows 應用程式 SDK 功能

本節提供非常簡單的範例，說明從 WinForms 應用程式呼叫 Windows 應用程式 SDK API 的方法。它會使用 MRT Core 功能 (請參閱使用 MRT Core 管理資源)。如果此範例適用於您的 WinForms 專案 (且如果您在此逐步解說中建立了新的專案，則必然適用)，則您可以遵循下列步驟。

開啟 Form1.cs (使用 View Designer 命令)，然後將 「按鈕」和「標籤」從「工具箱」拖曳到設計工具。
按一下 button1，以產生事件處理常式。
現在，我們將新增一些程序代碼，以使用 Windows 應用程式 SDK 中的 ResourceManager 類別來載入字串資源。
1. 將新的資源檔案 (.resw) 項目新增到您的專案 (保留預設名稱 Resource.resw)。
2. 在編輯器已開啟資源檔案的情況下，使用下列屬性建立新的字串資源。
  - 名稱：Message
  - 值：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;
}
```
組建專案並執行應用程式。按一下按鈕即可看到字串 Hello, resources! 顯示。

提示

如果您在執行階段看到訊息框，指出應用程式需要特定版本的 Windows 應用程式執行階段，並詢問您是否要立即安裝，請按一下 [是]。這會將您帶往 Windows 應用程式 SDK 的最新下載項目。如需詳細資訊，請參閱上節的先決條件。

另請參閱執行階段架構，以深入瞭解應用程式使用 Windows 應用程式 SDK 時所接受的架構套件相依性，以及操作未封裝應用程式所需的額外元件。

使用 MSIX 封裝和部署 WinForms 應用程式

有些 Windows 功能和 API (包括 Windows 應用程式 SDK 通知 API) 需要應用程式在執行階段時具備套件身分識別 (換句話說，您的應用程式須為已封裝)。如需詳細資訊，請參閱需要套件身分識別的功能。

在 Visual Studio 的「方案總管」中，以滑鼠右鍵按一下解決方案，然後選擇 [新增]>[新增專案...]。
在「新增專案」對話方塊中，搜尋「packaging」，選擇 C# 的 [Windows 應用程式封裝專案] 專案範本，然後按 [下一步]。
為專案命名，然後按一下 [確定]。
我們要指定將解決方案中的哪些應用程式包含在封裝中。因此，在封裝專案中 (不是 WinForms 專案)，以滑鼠右鍵按一下 [相依性] 節點，然後選擇 [新增專案參照...]。
在解決方案的專案清單中，選擇 WinForms 專案，然後按一下 [確定]。
展開封裝專案的 [相依性]>[應用程式] 節點，並確認您的 WinForms 專案已參照並標示為粗體。這表示其會作為套件的起點使用。
以滑鼠右鍵按一下封裝專案，然後選擇 [設為啟始專案]。
以滑鼠右鍵按一下 WinForms 專案，然後選擇 [編輯專案檔]。
刪除 <WindowsPackageType>None</WindowsPackageType>，然後儲存並關閉。
在 [解決方案平台] 下拉式清單中，挑選 [x64] (而非 [任何 Cpu])。
確認您可以組建並執行。

既然您已封裝 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);
}

再次組建並執行。按一下按鈕，並確認快顯通知已顯示。如果在執行階段呼叫的程序缺少套件識別，通知 API 會擲回例外狀況。

注意

本節的步驟示範如何建立已封裝的應用程式。替代方法是建立含有外部位置的已封裝應用程式。如需複習上述所有詞彙，請參閱封裝應用程式的優點和缺點。

共用方式為

在 Windows Forms (WinForms) 應用程式中使用 Windows 應用程式 SDK

必要條件

如果您還沒有 WinForms 專案，請先建立專案

設定 WinForms 專案來支援 Windows 應用程式 SDK

在 WinForms 應用程式中使用部分 Windows 應用程式 SDK 功能

使用 MSIX 封裝和部署 WinForms 應用程式

其他資源

共用方式為

在 Windows Forms (WinForms) 應用程式中使用 Windows 應用程式 SDK

必要條件

如果您還沒有 WinForms 專案，請先建立專案

設定 WinForms 專案來支援 Windows 應用程式 SDK

在 WinForms 應用程式中使用部分 Windows 應用程式 SDK 功能

使用 MSIX 封裝和部署 WinForms 應用程式

相關主題

其他資源