在 Windows 上實作應用程式動作的 URI 啟動

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

動作提供程式可以使用 COM 啟動或 URI 啟用來實作。 URI 啟動動作不支援某些進階動作功能，例如在內容中顯示 UI 或串流文字結果，但實作非常簡單，對於僅包含單一要求和回應的動作來說，可能是最佳選擇。

使用 COM 啟用的提供者應用程式會實作 IActionProvider 介面來處理動作叫用。此方法會啟用進階動作功能，例如支援串流文字，但需要比使用 Windows 應用程式動作 VSIX 延伸模組更多的程式碼。如需在應用程式提供者中使用 COM 啟用的相關資訊，請參閱開始使用 Windows 上的應用程式動作。

自動相依性安裝（建議）
手動相依性安裝

在終端機中執行下列其中一個命令（無論您是 C# 還是 C++ 開發人員）。這會執行一個 WinGet 配置檔案，其將執行下列工作（已安裝的相依性將會略過）：
- 啟用開發人員模式。
- 安裝 Visual Studio Community Edition
- 包括 Windows 應用程式開發工作負載和 C++ 或 .NET/C# 工作負載
- 包含 MSIX 封裝工具

對於 C# 開發人員：

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

對於 C++ 開發人員：

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

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

多種應用程式架構和語言支援應用程式動作功能，但應用程式必須具有套件身分識別，才能向系統註冊。本逐步解說將在封裝的 C# WinUI 3 桌面應用程式中實作 Windows 應用程式動作提供者。

在 Visual Studio 中，建立新的專案。
在 [ 建立新專案 ] 對話方塊中，將語言篩選設定為「C#」，並將平臺篩選設定為「WinUI」，然後選取 [WinUI 空白應用程式（已封裝）] 專案範本。
將新專案命名為「ExampleAppActionProvider」。
載入專案時，在 [方案總管] 中，以滑鼠右鍵按一下專案名稱，然後選取 [屬性]。 在「 一般」 頁面上，向下捲動至 「目標作業系統」 ，然後選取「Windows」。針對 [目標作業系統版本] 和 [支援的作業系統版本]，選取 10.0.26100.0 版或更新版本。
若要更新專案以支援動作提供者 API，請在 [方案總管 ] 中以滑鼠右鍵按一下專案名稱，然後選取 [編輯專案檔案]。在 PropertyGroup 內，新增下列 WindowsSdkPackageVersion 元素。
```
<WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
```

新增 Microsoft.AI.Actions NuGet 套件的引用

Microsoft.AI.Actions nuget 套件可讓您初始化應用程式動作執行階段，其提供 API 來建立實體物件，這些物件會傳遞為應用程式動作的輸入和輸出。

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

新增動作定義 JSON 檔案

動作提供者應用程式必須提供動作定義檔案，以定義應用程式實作的動作。此檔案提供每個動作的唯一識別碼和說明，以及每個動作支援的輸入和輸出的名稱和類型等資訊。如需應用程式動作 JSON 檔案格式的詳細資訊，請參閱 Windows 應用程式動作提供者的動作定義 JSON 結構描述。

此範例將定義一個名為 SendMessage 的動作，該動作會採用單一 Text 實體作為輸入，並傳回單一 TextEntity 作為輸出。除了定義動作之外，JSON 檔案也會指定動作提供者應用程式是否應該使用 COM 啟用或透過 URI 啟動來啟動。此範例將使用 URI 啟動。 URI 方案 urilaunchaction-protocol 將會在本逐步解說的稍後步驟中註冊。

在 [方案總管] 中，以滑鼠右鍵按一下資料夾 Assets ，然後選取 [新增>專案...]。
在「新增項目」對話方塊中，選取「文字檔」。 將新檔案命名為「registration.json」，然後按一下「確定」。
在 [方案總管] 中，以滑鼠右鍵按一下 registration.json 檔案，然後選取 [屬性]。在 [屬性] 窗格中，將 [建置動作 ] 設定為 [內容]，並將 [複製到輸出目錄] 設定為 [如果較新，則複製]。
將下列 JSON 動作定義新增至 registration.json 檔案。

{
  "version": 3,
  "actions": [
    {
      "id": "ExampleActionProvider.SendMessage",
      "description": "Send a message (URI Launch)",
      "icon": "ms-resource://Files/Assets/LockScreenLogo.png",
      "usesGenerativeAI": false,
      "allowedAppInvokers": ["*"],
      "inputs": [
        {
          "name": "message",
          "kind": "Text"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "message"
          ],
          "description": "Send message '${message.Text}'"
        }
      ],
      "outputs": [
        {
          "name": "response",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "Uri",
        "uri": "urilaunchaction-protocol://",
        "inputData": {
          "message": "${message.Text}"
        }
      }
    }
  ]
}

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

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

若要透過 URI 啟動應用程式動作提供者，它必須向系統註冊通訊協定。此註冊是藉由在應用程式套件資訊清單中提供 com2：Extension 元素來進行。通訊協定元素的 Name 屬性必須符合動作定義 JSON 檔中指定的 invocation.uri 值，在此範例中為 urilaunchaction-protocol。如需 URI 啟動啟用的詳細資訊，請參閱啟動應用程式以取得結果。

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

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

在 Application 元素內和 VisualElements 元素之後，新增下列 Extensions 元素。

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="urilaunchaction-protocol" ReturnResults="always">
      <!-- app-defined protocol name -->
      <uap:DisplayName>URI Launch Action Scheme</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  <uap3:Extension Category="windows.appExtension">
    <uap3:AppExtension Name="com.microsoft.windows.ai.actions" DisplayName="URILaunchAction" Id="UriLaunchActionId" PublicFolder="Assets">
      <uap3:Properties>
        <Registration xmlns="">registration.json</Registration>
      </uap3:Properties>
    </uap3:AppExtension>
  </uap3:Extension>
</Extensions>

處理應用程式啟用

從已註冊的 URI 標架啟動應用程式動作提供者時，可以透過呼叫 AppInstance.GetActivatedEventArgs 所取得的 AppActivationArguments 物件來存取動作的輸入。若要確定啟用是來自已註冊的通訊協定，您必須先檢查以確定 Kind 屬性的值是 ExtendedActivationKind.ProtocolForResults。如果是，您可以將引數物件轉換至 ProtocolForResultsActivatedEventArgs 物件。

備註

此範例會使用 ProtocolForResultsActivatedEventArgs 物件來確認 Windows 叫用動作，如果動作是由另一個呼叫端啟動，則結束而不完成。如需詳細資訊，請參閱偵測和篩選 Windows 上應用程式動作的呼叫端。

動作的輸入是透過事件引數的 Data 屬性來存取，這是包含每個輸入實體索引鍵/值組的 ValueSet 。此範例會取得 message registration.json 檔案中定義的輸入實體。此輸入的值是文字字串。

若要傳回動作的結果，應用程式動作提供者必須具現化一或多個輸出實體。此範例會傳回單一 TextActionEntity ，其中包含輸入訊息的回應。

若要具現化新的輸出實體，請從 ActionRuntime 物件的 EntityFactory 屬性取得 ActionEntityFactory 類別的實例。 Factory 物件提供實例化所有不同類型的動作實體的方法。建立包含回應訊息的文字實體之後，我們在新的 ValueSet 中建立項目，其中鍵值是 registration.json 檔案中指定的輸出名稱 “response”，值是 TextActionEntity 的 ID。請注意，當您呼叫 CreateTextEntity 來建立實體時，實體會向動作執行階段註冊。這就是您將實體的 ID 新增為 ValueSet 中的值的原因。取用此動作的使用者將使用識別碼從動作執行階段擷取實體物件。

處理 URI 啟用的最後一個步驟是建立新的 ProtocolForResultsOperation 並呼叫 ReportCompleted 方法，傳入包含輸出實體參考的 ValueSet 。

在 App.xaml.cs 中，將 OnLaunched 的預設實作取代為下列程式碼。

  ProtocolForResultsOperation? _operation;
  protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
  {
      var eventargs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();

      if ((eventargs != null) && (eventargs.Kind == ExtendedActivationKind.ProtocolForResults))
      {
          ProtocolForResultsActivatedEventArgs? protocolForResultsArgs = eventargs.Data as ProtocolForResultsActivatedEventArgs;
      
          if (protocolForResultsArgs.CallerPackageFamilyName.EndsWith("_cw5n1h2txyewy"))
          {
              using (ActionRuntime runtime = ActionRuntimeFactory.CreateActionRuntime())
              {
                  if (protocolForResultsArgs != null)
                  {
                      ValueSet inputData = protocolForResultsArgs.Data;
                      var message = inputData["message"];
      
                      Windows.AI.Actions.ActionEntityFactory source = runtime.EntityFactory;
                      Windows.AI.Actions.ActionEntity textEntity = source.CreateTextEntity("Message response.");
      
                      ValueSet result = new ValueSet();
                      result["response"] = textEntity.Id;
      
                      _operation = protocolForResultsArgs.ProtocolForResultsOperation;
                      _operation.ReportCompleted(result);
                  }
              }
          }
      }

      _window = new MainWindow();
      _window.Activate();
  }

測試您的 Windows 應用程式動作

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

在 Windows 上的附加應用程式操作功能

下列文章提供 Windows 上應用程式動作其他功能的相關資訊。

切換適用於 Windows 的應用程式動作的可用性

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-21