在 Windows 上開始使用 App Actions

本文說明建立應用程式動作的步驟，並說明應用程式動作提供者應用程式的元件。 應用程式動作是 Windows 應用程式可以實作並註冊的個別行為單位，以便從其他應用程式和體驗存取它們，並順暢地整合到使用者工作流程中。 如需 Windows 上應用程式動作的詳細資訊，請參閱 Windows 上的應用程式動作概觀

IActionProvider 介面是應用程式動作提供者用來與 Windows 動作架構通訊的主要介面。 不過，Microsoft 提供 Microsoft.AI.Actions NuGet 套件 ，它會根據程式碼中的 .NET 屬性自動產生 IActionProvider 實作，讓您建立強型別類別來代表您的動作。 這是實作應用程式動作提供者應用程式的建議方式，也是本文所述的技術。 針對某些邊緣案例，開發人員可能會想要直接實作 IActionProvider 。 如需詳細資訊，請參閱 手動實作 IActionProvider。

您也可以使用 URI 啟動啟用，而不是 COM 啟用來實作應用程式動作提供者，不過不支援一些更進階的案例，例如從動作串流文字回應。 如需詳細資訊，請參閱 在 Windows 上實作應用程式動作的 URI 啟動。

winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cs.winget

在 Visual Studio 中建立新的 Windows 應用程式專案

多個應用程式架構支援 Windows 上的應用程式動作功能，但應用程式必須具有套件身分識別，才能向系統註冊。 本教學將在已封裝的 C# WinUI 3 桌面應用程式中實作 Windows 應用程式動作提供者。

1. 在 Visual Studio 中，建立新的專案。

2. 在 [ 建立新專案 ] 對話框中，將語言篩選條件設定為 “C#”，並將平臺篩選設定為 “WinUI”，然後選取 [空白應用程式，封裝]（Desktop 中的 WinUI 3）專案範本。

3. 將新專案命名為 「ExampleAppActionProvider」。

4. 當專案載入時，在 [方案總管] 右鍵點擊專案名稱，並選擇 [屬性]。 在 [ 一般] 頁面上，向下捲動至 [目標作系統 ]，然後選取 [Windows]。 針對 目標 OS 版本 和 支援的 OS 版本，選取版本 10.0.26100.0 或更高版本。

5. 若要更新專案以支援動作提供者 API，請在 [方案 總管] 中以滑鼠右鍵按兩下項目名稱，然後選取 [編輯項目檔]。 在 PropertyGroup 內，新增下列 WindowsSdkPackageVersion 元素。

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

新增 Microsoft.AI.Actions Nuget 套件的參考

本文中的範例會使用 Microsoft.AI.Actions Nuget 套件的程式碼產生功能。

1. 在 [方案總管] 中，以滑鼠右鍵按一下專案名稱，然後選取 [管理 NuGet 套件...]
2. 確保您位於 [ 瀏覽] 索引標籤上，並搜尋 Microsoft.AI.Actions。
3. 選取 [Microsoft.AI.Actions]，然後按一下 [安裝]。

新增 ActionProvider 類別來處理動作作業

下一節說明如何實作自訂動作提供者類別，以使用 Microsoft.AI.Actions.Annotations 命名空間中的 .NET 屬性來識別動作的元件。 Microsoft.AI.Actions NuGet 套件會使用這些屬性來自動產生 IActionProvider 介面的基礎實作。 這可讓您為動作建立強型別類別，而不需要直接與低階動作提供者 API 互動。

1. 在 Visual Studio 的 [方案總管] 中，以滑鼠右鍵按一下 ExampleAppActionProvider 專案，然後選取 。
2. 在 [新增類別] 對話方塊中，將類別命名為 「MyActionProvider」，然後按一下 [新增]。
3. 將 的內容 MyActionProvider.cs 替換為以下程式碼。

using Microsoft.AI.Actions.Annotations;
using System.Threading.Tasks;
using Windows.AI.Actions;

namespace ExampleAppActionProvider
{
    [ActionProvider]
    public sealed class MyActionsProvider
    {
        [WindowsAction(
            Description = "Send a message to a contact",
            Icon = "ms-resource://Files/Assets/StoreLogo.png",
            FeedbackHandler = nameof(SendMessageFeedback),
            UsesGenerativeAI = false
        )]
        [WindowsActionInputCombination(
            Inputs = ["Contact"],
            Description = "Send message to '${Contact.Text}'"
        )]
        [WindowsActionInputCombination(
            Inputs = ["Contact", "Message"],
            Description = "Send '${Message.Text}' to '${Contact.Text}'"
        )]

        public async Task<SendMessageResult> SendMessage(
            [Entity(Name = "Contact")] string contact,
            [Entity(Name = "Message")] string? message,
            InvocationContext context)
        {
            // Your action logic here
            string result = await ProcessMessageAsync(contact, message);

            return new SendMessageResult
            {
                Text = context.EntityFactory.CreateTextEntity(result)
            };
        }
        
        public Task SendMessageFeedback(ActionFeedback feedback, InvocationContext context)
        {
            // Handle user feedback for the action
            return Task.CompletedTask;
        }

        public record SendMessageResult
        {
            public required TextActionEntity Text { get; init; }
        }

        public async Task<string> ProcessMessageAsync(string contact, string? message)
        {
            if (message != null)
            {
                return await Task.Run(() => $"Processed {contact}, {message}");
            }
            else
            {
                return await Task.Run(() => $"Processed {contact}");
            }
        }
    }
}

Microsoft.AI.Actions Nuget 套件的程式碼產生功能會使用程式碼中的 .NET 屬性來判斷應用程式所提供動作的詳細數據。 此範例使用下列屬性：

大多數支援的屬性會直接對應至系統用來探索動作的動作定義 JSON 檔案中的欄位。 事實上，如本文稍後所示，Microsoft.AI.Actions 程式碼產生功能會使用這些屬性，在建置時自動產生動作定義 JSON 檔案。 當您更新動作提供者類別、新增或修改這些屬性時，Nuget 套件會重新產生動作定義檔，以反映您的變更。 如需動作定義 JSON 檔案的詳細資訊，請參閱 Windows 上應用程式動作的動作定義 JSON 結構描述。

如需支援屬性的清單，請參閱 Microsoft.AI.Actions Nuget 套件的自述檔案。

更新應用程式套件指令清單檔案

Package.appmanifest 檔案會提供應用程式 MSIX 套件的詳細數據。 若要由系統註冊為 Windows App Action 提供者，應用程式必須包含 uap3：Extension 元素， 且 Category 設定為 “windows.appExtension”。 此元素可用來指定定義應用程式動作的 App Action JSON 檔案位置。 您也必須指定com.microsoft.windows.ai.actions為 uap3：AppExtension 元素的 名稱。 如需動作提供者應用程式套件指令清單格式的詳細資訊，請參閱 Windows 應用程式動作提供者套件指令清單 XML 格式。

本逐步解說中的範例會透過 COM 的啟動來啟動應用程式動作提供者。 若要開啟 COM 啟用，請使用應用程式套件指令清單中的 com2:Extension 元素。 動作定義 JSON 檔案中指定的 invocation.clsid 值必須符合應用程式套件指令清單中 com：Class 元素中指定的類別標識碼。

1. 以滑鼠右鍵按兩下 Package.appxmanifest 檔案，然後選取 [檢視程式代碼]
2. 將下列命名空間新增至檔案根目錄的 Package 元素。

xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
xmlns:com2="http://schemas.microsoft.com/appx/manifest/com/windows10/2"
xmlns:com3="http://schemas.microsoft.com/appx/manifest/com/windows10/3"

3. 在 Application 元素和 VisualElements 元素後面新增下列 Extensions 元素。

<Extensions>
  <com2:Extension Category="windows.comServer">
    <com2:ComServer>
        <com3:ExeServer Executable="ExampleAppActionProvider.exe" DisplayName="ExampleAppActionProvider">
            <com:Class Id="00001111-aaaa-2222-bbbb-3333cccc4444" DisplayName="ExampleAppActionProvider" />
        </com3:ExeServer>
      </com2:ComServer>
    </com2:Extension>
    <uap3:Extension Category="windows.appExtension">
        <uap3:AppExtension Name="com.microsoft.windows.ai.actions" DisplayName="Example App Action Provider" Id="appactionprovider" PublicFolder="Assets">
        <uap3:Properties>
            <Registration>registration.json</Registration>
        </uap3:Properties>
    </uap3:AppExtension>
</uap3:Extension>
</Extensions>

實作自定義 Main 主程序函式

在預設項目範本中，編譯程式會自動產生 Main 方法進入點。 此範例會停用 Main 的自動產生，以便在啟動時執行必要的啟用程式代碼。

1. 在 [方案總管] 中，以滑鼠右鍵按兩下項目圖示，然後選取 [編輯項目檔]。
2. 在 PropertyGroup 元素中，新增下列子專案以停用自動產生的 main 函式。

<DefineConstants>$(DefineConstants);DISABLE_XAML_GENERATED_MAIN</DefineConstants>

接下來，在 [方案總管] 中，以滑鼠右鍵按一下專案圖示，然後選取 [新增>專案]。 選取 [程式碼檔案]。 將檔名變更為 「Program.cs」，然後按兩下 [ 新增]。

在 Program.cs 檔案中，我們將新增一行程式碼，讓動作 nuget 套件自動產生 COM 伺服器啟用，以允許系統叫用動作提供者。

ComServerRegisterActions.RegisterActions();

此範例中 Main 方法中的其餘程式碼只是啟動 WinUI 應用程式的樣板程式碼。 將 Program.cs 的內容取代為下列程式碼。

namespace ExampleAppActionProvider;

public static class Program
{

    [global::System.STAThreadAttribute]
    static void Main(string[] args)
    {
        global::WinRT.ComWrappersSupport.InitializeComWrappers();
        ComServerRegisterActions.RegisterActions();
        global::Microsoft.UI.Xaml.Application.Start((p) =>
        {
            var context = new global::Microsoft.UI.Dispatching.DispatcherQueueSynchronizationContext(global::Microsoft.UI.Dispatching.DispatcherQueue.GetForCurrentThread());
            global::System.Threading.SynchronizationContext.SetSynchronizationContext(context);
            new App();
        });
    }
}

將 Microsoft.AI.Actions 組態屬性新增至專案檔

Microsoft.AI.Actions Nuget 套件的程式碼產生功能會使用專案檔中定義的屬性值，在建置階段設定其行為。 在 .csproj 檔案中的第一個 PropertyGroup 元素內新增下列屬性。

<GenerateActionRegistrationManifest>true</GenerateActionRegistrationManifest>
<ActionRegistrationManifest>Assets\registration.json</ActionRegistrationManifest>
<GenerateActionsWinRTComServer>true</GenerateActionsWinRTComServer>
<RootNamespace>ExampleAppActionProvider</RootNamespace>

下表描述這些屬性。

根據產生的 registration.json 檔案進行更新

建置專案之後，您可以在 [方案總管] 的 [資產] 資料夾中檢視產生registration.json的檔案。

{
  "version": 2,
  "actions": [
    {
      "id": "ExampleAppActionProvider.MyActionsProvider.SendMessage",
      "description": "Send a message to a contact",
      "icon": "ms-resource://Files/Assets/StoreLogo.png",
      "usesGenerativeAI": false,
      "hasFeedbackHandler": true,
      "inputs": [
        {
          "name": "Contact",
          "kind": "Text"
        },
        {
          "name": "Message",
          "kind": "Text"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "Contact"
          ],
          "description": "Send message to '${Contact.Text}'"
        },
        {
          "inputs": [
            "Contact",
            "Message"
          ],
          "description": "Send '${Message.Text}' to '${Contact.Text}'"
        }
      ],
      "outputs": [
        {
          "name": "Text",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "COM",
        "clsid": "11112222-bbbb-3333-cccc-4444dddd5555"
      }
    }
  ]
}

更新應用程式套件資訊清單檔案中的 CLSID

第一次建置動作提供者應用程式時，您會收到警告： warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'。 這是因為自動產生 registration.json 的檔案會宣告具有唯一 GUID 之動作的 COM 伺服器 clsid 。 建置專案之後，請開啟檔案 registration.json ，並注意檔案會宣告動作使用 COM 啟用，並指定 clsid 值。 取代應用程式套件資訊清單檔案中 com：Class 元素中的 Id 屬性值，以使用產生的 GUID。

例如，如果產生registration.json檔案中的 clsid 值是 11112222-bbbb-3333-cccc-4444dddd5555，則更新的 com：Class 元素看起來會如下所示：

<com:Class Id="11112222-bbbb-3333-cccc-4444dddd5555" DisplayName="ExampleAppActionProvider" />

允許的應用程式叫用程式

已新增至動作定義 JSON 結構描述的新欄位是 allowedAppInvokers ，它指定應用程式使用者模型識別碼 （AppUserModelID） 清單，可透過呼叫 GetActionsForInputs 或 GetAllActions 來探索動作。 支援萬用字元。 “*” 會符合所有 AppUserModelID。 建議對大部分動作執行此動作，除非有特定原因來限制可以叫用動作的呼叫端。 如果省略 allowedAppInvokers 或是空白清單，則任何應用程式都無法探索動作。 如需 AppUserModelID 的詳細資訊，請參閱 應用程式使用者模型識別碼。

下列範例顯示設定 allowedAppInvokers 的建議做法，以允許所有應用程式探索相關聯的動作。

"actions": [
    {
      "id": "ExampleAppActionProvider.MyActionsProvider.SendMessage",
      "description": "Send a message to a contact",
      "icon": "ms-resource://Files/Assets/StoreLogo.png",
      "usesGenerativeAI": false,
      "hasFeedbackHandler": true,
      "allowedAppInvokers" : ["*"],
    ...

測試 Windows 應用程式動作

應用程式動作測試遊樂場應用程式可讓您驗證 Windows 應用程式動作提供者應用程式的註冊和功能。 如需使用此工具的詳細資訊，請參閱 應用程式動作測試遊樂場。