Windows でアプリアクションの URI 起動を実装する

この記事では、アプリアクションを作成する手順と、アプリアクションプロバイダーアプリのコンポーネントについて説明します。アプリアクションは、Windows アプリが実装して登録できる個々の動作の単位であり、他のアプリやエクスペリエンスからアクセスしてユーザーワークフローにシームレスに統合できるようにします。 Windows でのアプリアクションの詳細については、「Windows でのアプリアクションの概要」を参照してください。

アクションプロバイダーアプリは、COM のアクティブ化または URI 起動のアクティブ化を使用するように実装できます。 URI 起動アクションでは、コンテキストでの UI の表示やテキストの結果のストリーミングなど、いくつかの高度なアクション機能はサポートされていませんが、実装は非常に単純であり、1 つの要求と応答のみで構成されるアクションに最適な選択肢になる場合があります。

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 アプリプロジェクトを作成する

アプリアクション機能は、複数のアプリフレームワークと言語でサポートされていますが、アプリをシステムに登録するにはパッケージ ID が必要です。このチュートリアルでは、パッケージ化された C# WinUI 3 デスクトップアプリに Windows アプリアクションプロバイダーを実装します。

Visual Studio で、新しいプロジェクトを作成します。
[ 新しいプロジェクトの作成 ] ダイアログで、言語フィルターを "C#" に設定し、プラットフォームフィルターを "WinUI" に設定し、"WinUI Blank App (Packaged)" プロジェクトテンプレートを選択します。
新しいプロジェクトに "ExampleAppActionProvider" という名前を付けます。
プロジェクトが読み込まれたら、 ソリューションエクスプローラー でプロジェクト名を右クリックし、[ プロパティ] を選択します。 [ 全般 ] ページで、[ ターゲット OS ] まで下にスクロールし、[Windows] を選択します。 ターゲット OS のバージョンとサポートされている OS バージョンの場合は、バージョン 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 という 1 つのアクションを定義します。このアクションは、単一 の Text エンティティを入力として受け取り、 単一の TextEntity を 出力として返します。アクションの定義に加えて、JSON ファイルでは、アクションプロバイダーアプリを COM アクティブ化を使用して起動するか、URI 起動を使用して起動するかを指定します。この例では、URI のアクティブ化を使用します。 URI スキームは、このチュートリアルの後の手順で登録します。

ソリューションエクスプローラーで、Assets フォルダーを右クリックし、[Add->New Item...] を選択します。
[ 新しい項目の追加 ] ダイアログで、[ テキストファイル] を選択します。新しいファイルに "registration.json" という名前を付け、[OK] をクリックします。
ソリューションエクスプローラーで、registration.json ファイルを右クリックし、[プロパティ] を選択します。 [プロパティ] ウィンドウで、[ビルドアクション] を [コンテンツ] に設定し、[出力ディレクトリにコピー] を [新しい場合はコピー] に設定します。
registration.json ファイルに次の 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 アプリアクションプロバイダーとして登録するには、アプリに、カテゴリが "windows.appExtension" に設定された uap3:Extension 要素を含める必要があります。この要素は、アプリのアクションを定義する App Action JSON ファイルの場所を指定するために使用されます。アクションプロバイダーのアプリパッケージマニフェスト形式の詳細については、「 Windows パッケージマニフェスト XML 形式でのアプリアクション」を参照してください。

アプリアクションプロバイダーを URI 経由で起動するには、プロトコルをシステムに登録する必要があります。この登録は、アプリパッケージマニフェストで com2:Extension 要素を指定することによって行われます。 Protocol 要素の 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 です。この例では、registration.json ファイルで定義されている message 入力エンティティを取得します。この入力の値はテキスト文字列です。

アクションの結果を返すには、アプリアクションプロバイダーが 1 つ以上の出力エンティティをインスタンス化する必要があります。次の使用例は、入力メッセージへの応答を含む単一の TextActionEntity を返します。

新しい出力エンティティをインスタンス化するには、ActionRuntime オブジェクトの EntityFactory プロパティから ActionEntityFactory クラスのインスタンスを取得します。ファクトリオブジェクトには、さまざまな種類のアクションエンティティをすべてインスタンス化するためのメソッドが用意されています。応答メッセージを含むテキストエンティティを作成した後、新しい ValueSet にエントリを作成します。ここで、キーは registrationl.json ファイルで指定された出力名 "response"、値は TextActionEntity の ID です。 CreateTextEntity を呼び出してエンティティを作成すると、エンティティはアクションランタイムに登録されることに注意してください。これが、エンティティの ID をValueSet の値として追加する理由です。アクションのコンシューマーは、この ID を使用してアクションランタイムからエンティティオブジェクトを取得します。

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 アプリアクションをテストする

App Actions Testing Playground アプリを使用すると、Windows アプリアクションプロバイダーアプリの登録と機能を検証できます。このツールの使用方法の詳細については、「アプリアクションテストプレイグラウンドアプリ」を参照してください。

Windows の機能に対するその他のアプリアクション

次の記事では、Windows 上のアプリアクションの追加機能について説明します。

Windows 用アプリアクションの可用性を切り替える

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-08-20

次の方法で共有

Windows でアプリ アクションの URI 起動を実装する

Visual Studio で新しい Windows アプリ プロジェクトを作成する

Microsoft.AI.Actions nuget パッケージへの参照を追加する

アクション定義 JSON ファイルを追加する

アプリ パッケージ マニフェスト ファイルを更新する

アプリのアクティブ化を処理する

Windows アプリ アクションをテストする

Windows の機能に対するその他のアプリ アクション

関連コンテンツ