Windows でのアプリ アクションを開始する

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

IActionProvider インターフェイスは、アプリ アクション プロバイダーが Windows アクション フレームワークとの通信に使用する主要なインターフェイスです。 ただし、Microsoft では、コード内の .NET 属性に基づいて IActionProvider 実装を自動的に生成する Microsoft.AI.Actions NuGet パッケージを提供しています。これにより、アクションを表す厳密に型指定されたクラスを作成できます。 これは、アプリ アクション プロバイダー アプリを実装するための推奨される方法であり、この記事で説明する手法です。 一部のエッジ ケース シナリオでは、開発者は IActionProvider を直接実装する必要があります。 詳細については、「 IActionProvider を手動で実装する」を参照してください。

また、COM のアクティブ化ではなく URI 起動のアクティブ化を使用してアプリ アクション プロバイダーを実装することもできますが、アクションからのテキスト応答のストリーミングなど、より高度なシナリオはサポートされていません。 詳細については、「 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 上のアプリ アクション機能は複数のアプリ フレームワークでサポートされていますが、システムに登録するにはアプリにパッケージ ID が必要です。 このチュートリアルでは、パッケージ化された C# WinUI 3 デスクトップ アプリに Windows アプリ アクション プロバイダーを実装します。

1. Visual Studio で、新しいプロジェクトを作成します。

2. [ 新しいプロジェクトの作成 ] ダイアログで、言語フィルターを "C#" に設定し、プラットフォーム フィルターを "WinUI" に設定し、"空のアプリ、パッケージ (デスクトップの WinUI 3)" プロジェクト テンプレートを選択します。

3. 新しいプロジェクトに "ExampleAppActionProvider" という名前を付けます。

4. プロジェクトが読み込まれたら、 ソリューション エクスプローラー でプロジェクト名を右クリックし、[ プロパティ] を選択します。 [全般] ページで、下にスクロールして [ターゲット OS し、[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 で、ソリューション エクスプローラー で プロジェクトを右クリックし、[クラスを追加] を選択します。
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 パッケージの readme ファイルを参照してください。

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

Package.appmanifest ファイルは、アプリの MSIX パッケージの詳細を提供します。 システムが Windows アプリ アクション プロバイダーとして登録するには、アプリに、カテゴリが "windows.appExtension" に設定された uap3:Extension 要素を含める必要があります。 この要素は、アプリのアクションを定義する App Action JSON ファイルの場所を指定するために使用されます。 uap3:AppExtension 要素の名前としてcom.microsoft.windows.ai.actionsも指定する必要があります。 アクション プロバイダー アプリ パッケージ マニフェスト形式の詳細については、「 Windows アプリ アクション プロバイダー パッケージ マニフェスト XML 形式」を参照してください。

このチュートリアルの例では、COM のアクティブ化を使用してアプリ アクション プロバイダーを起動します。 COM のアクティブ化を有効にするには、アプリ パッケージ マニフェストで com2:Extension 要素を使用します。 アクション定義 JSON ファイルで指定された invocation.clsid 値は、アプリ パッケージ マニフェストの com:Class 要素で指定されたクラス ID と一致する必要があります。

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>

次に、 ソリューション エクスプローラーでプロジェクト アイコンを右クリックし、[ Add->New Item] を選択します。 [コード ファイル] を選択します。 ファイル名を "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 ファイルをソリューション エクスプローラーの Assets フォルダーに表示できます。

{
  "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 ファイルが、アクションの COM サーバーの clsid を一意の GUID で宣言するためです。 プロジェクトをビルドした後、 registration.json ファイルを開き、アクションが COM アクティブ化を使用することを宣言し、 clsid 値を指定します。 生成された GUID を 使用するには、アプリ パッケージ マニフェスト ファイルの com:Class 要素の Id 属性の値を置き換えます。

たとえば、生成されたregistration.json ファイルの clsid 値が11112222-bbbb-3333-cccc-4444dddd5555場合、更新された com:Class 要素は次のようになります。

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

許可されているアプリ呼び出し子

アクション定義 JSON スキーマに追加された新しいフィールドは allowedAppInvokers であり、 GetActionsForInputs または GetAllActions の呼び出しを通じてアクションを検出できるアプリケーション ユーザー モデル ID (AppUserModelIDs) の一覧を指定します。 ワイルドカードがサポートされています。 "*" はすべての AppUserModelID と一致します。 これは、アクションを呼び出すことができる呼び出し元を制限する特定の理由がない限り、ほとんどのアクションに推奨されます。 allowedAppInvokers が省略されているか、空のリストである場合、アプリはアクションを検出できません。 AppUserModelID の詳細については、「 アプリケーション ユーザー モデル ID」を参照してください。

次の例は、すべてのアプリが関連するアクションを検出できるように 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 アプリ アクションをテストする

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