Prise en main des actions d’application sur Windows

Cet article décrit les étapes de création d’actions d’application et décrit les composants d’une application fournisseur d’actions d’application. Les actions d’application sont des unités de comportement individuelles qu’une application Windows peut implémenter et inscrire afin qu’elle puisse être accessible à partir d’autres applications et expériences, en intégrant en toute transparence les flux de travail utilisateur. Pour plus d’informations sur les actions d’application sur Windows, consultez Vue d’ensemble des actions d’application sur Windows

L’interface IActionProvider est l’interface principale que les fournisseurs d’actions d’application utilisent pour communiquer avec l’infrastructure d’actions Windows. Toutefois, Microsoft fournit le package NuGet Microsoft.AI.Actions qui génère automatiquement l’implémentation IActionProvider basée sur des attributs .NET dans votre code, ce qui vous permet de créer des classes fortement typées pour représenter vos actions. Il s’agit de la méthode recommandée d’implémentation d’une application fournisseur d’actions d’application et est la technique décrite dans cet article. Pour certains scénarios de périphérie, les développeurs peuvent souhaiter implémenter IActionProvider directement. Pour plus d’informations, consultez Implémenter manuellement IActionProvider.

Vous pouvez également implémenter un fournisseur d’actions d’application à l’aide de l’activation de lancement d’URI plutôt que d’activation COM, bien que certains scénarios plus avancés, tels que la diffusion en continu de réponses de texte à partir d’une action, ne soient pas pris en charge. Pour plus d’informations, consultez Implémenter le lancement de l’URI pour les actions d’application sur Windows.

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

Créer un projet d’application Windows dans Visual Studio

La fonctionnalité Actions d’application sur Windows est prise en charge pour plusieurs frameworks d’application, mais les applications doivent avoir une identité de package pour pouvoir s’inscrire auprès du système. Cette procédure pas à pas implémente un fournisseur d’actions d’application Windows dans une application de bureau C# WinUI 3 empaquetée.

1. Dans Visual Studio, créez un projet.

2. Dans la boîte de dialogue Créer un projet , définissez le filtre de langue sur « C# » et le filtre de plateforme sur « WinUI », puis sélectionnez le modèle de projet « Application vide, Empaquetée (WinUI 3 dans Desktop) ».

3. Nommez le nouveau projet « ExampleAppActionProvider ».

4. Lorsque le projet se charge, dans l’Explorateur de solutions , cliquez avec le bouton droit sur le nom du projet et sélectionnez Propriétés. Dans la page Général , faites défiler jusqu’au système d’exploitation cible , puis sélectionnez « Windows ». Pour la version du système d’exploitation cible et la version prise en charge du système d’exploitation, sélectionnez la version 10.0.0.26100.0 ou ultérieure.

5. Pour mettre à jour votre projet pour prendre en charge les API du fournisseur d’actions, dans l’Explorateur de solutions , cliquez avec le bouton droit sur le nom du projet et sélectionnez Modifier le fichier projet. À l’intérieur de PropertyGroup, ajoutez l’élément WindowsSdkPackageVersion suivant.

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Ajouter une référence au package Nuget Microsoft.AI.Actions

L’exemple de cet article utilise les fonctionnalités de génération de code du package Nuget Microsoft.AI.Actions.

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nom du projet, puis sélectionnez Gérer les packages NuGet...
2. Vérifiez que vous êtes sous l’onglet Parcourir et recherchez Microsoft.AI.Actions.
3. Sélectionnez Microsoft.AI.Actions, puis cliquez sur Installer.

Ajouter une classe ActionProvider pour gérer les opérations d’action

La section suivante montre comment implémenter une classe de fournisseur d’actions personnalisée qui utilise des attributs .NET à partir de l’espace de noms Microsoft.AI.Actions.Annotations pour identifier les composants d’une action. Le package NuGet Microsoft.AI.Actions utilise ces attributs pour générer automatiquement une implémentation sous-jacente de l’interface IActionProvider . Cela vous permet de créer des classes fortement typées pour les actions sans avoir à interagir directement avec les API du fournisseur d’actions de bas niveau.

1. Dans Visual Studio, cliquez avec le bouton droit sur le projet dans ExampleAppActionProvider de solutions, puis sélectionnez Add-Class>.
2. Dans la boîte de dialogue Ajouter une classe , nommez la classe « MyActionProvider », puis cliquez sur Ajouter.
3. Remplacez le contenu du MyActionProvider.cs code suivant.

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}");
            }
        }
    }
}

Les fonctionnalités de génération de code du package Nuget Microsoft.AI.Actions utilisent des attributs .NET dans votre code pour déterminer les détails des actions fournies par votre application. Cet exemple utilise les attributs suivants :

La plupart des attributs pris en charge correspondent directement aux champs du fichier JSON de définition d’action que le système utilise pour découvrir des actions. En fait, comme indiqué plus loin dans cet article, la fonctionnalité de génération de code Microsoft.AI.Actions utilise ces attributs pour générer automatiquement le fichier JSON de définition d’action au moment de la génération. Lorsque vous mettez à jour votre classe de fournisseur d’actions, en ajoutant ou en modifiant ces attributs, le package Nuget régénère le fichier de définition d’action pour refléter vos modifications. Pour plus d’informations sur le fichier JSON de définition d’action, consultez le schéma JSON de définition d’action pour Les actions d’application sur Windows.

Pour obtenir la liste des attributs pris en charge, consultez le fichier lisez-moi du package Nuget Microsoft.AI.Actions .

Mettre à jour le fichier manifeste du package d’application

Le fichier Package.appmanifest fournit les détails du package MSIX pour une application. Pour être inscrite par le système en tant que fournisseur d’actions d’application Windows, l’application doit inclure un élément uap3 :Extension avec la catégorie définie sur « windows.appExtension ». Cet élément est utilisé pour spécifier l’emplacement du fichier JSON d’action d’application qui définit les actions de l’application. Vous devez également spécifier com.microsoft.windows.ai.actions le nom de l’élément uap3 :AppExtension . Pour plus d’informations sur le format du manifeste du package d’application du fournisseur d’actions, consultez le format XML du manifeste de package du fournisseur d’applications Windows.

L’exemple de ce guide pas à pas utilise l’activation COM pour lancer le fournisseur d’actions de l’application. Pour activer l’activation COM, utilisez l’élément com2 :Extension dans le manifeste du package d’application. La valeur invocation.clsid spécifiée dans le fichier JSON de définition d’action doit correspondre à l’ID de classe spécifié dans l’élément com :Class dans le manifeste du package d’application.

1. Cliquez avec le bouton droit sur le fichier Package.appxmanifest et sélectionnez Afficher le code
2. Ajoutez les espaces de noms suivants à l’élément Package à la racine du fichier.

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. Ajoutez l’élément Extensions suivant à l’intérieur de l’élément Application et après l’élément VisualElements .

<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>

Implémenter une méthode Main personnalisée

Dans le modèle de projet par défaut, le point d’entrée de la méthode Main est généré automatiquement par le compilateur. Cet exemple désactive la génération automatique de Main afin que le code d’activation nécessaire puisse être exécuté au démarrage.

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur l’icône du projet, puis sélectionnez Modifier le fichier projet.
2. Dans l’élément PropertyGroup , ajoutez l’élément enfant suivant pour désactiver la fonction principale générée automatiquement.

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

Ensuite, dans l’Explorateur de solutions, cliquez avec le bouton droit sur l’icône du projet, puis sélectionnez Ajouter un> nouvel élément. Sélectionnez Fichier de code. Remplacez le nom du fichier par « Program.cs », puis cliquez sur Ajouter.

Dans le fichier Program.cs, nous allons ajouter une ligne de code qui entraîne la génération automatique du package nuget actions qui permet au système d’appeler le fournisseur d’actions.

ComServerRegisterActions.RegisterActions();

Le reste du code de la méthode Main dans cet exemple est simplement le code réutilisable pour lancer une application WinUI. Remplacez le contenu de Program.cs par le code suivant.

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();
        });
    }
}

Ajouter des propriétés de configuration Microsoft.AI.Actions au fichier projet

La fonctionnalité de génération de code du package Nuget Microsoft.AI.Actions utilise des valeurs de propriété définies dans le fichier projet pour configurer son comportement au moment de la génération. Ajoutez les propriétés suivantes à l’intérieur du premier élément PropertyGroup dans votre fichier .csproj.

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

Le tableau suivant décrit ces propriétés.

Mettre à jour en fonction du fichier de registration.json généré

Après avoir généré votre projet, vous pouvez afficher le fichier généré registration.json dans le dossier Assets dans l’Explorateur de solutions.

{
  "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"
      }
    }
  ]
}

Mettre à jour le CLSID dans le fichier manifeste du package d’application

La première fois que vous générez votre application de fournisseur d’actions, vous recevez l’avertissement : warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Cela est dû au fait que le fichier généré automatiquement registration.json déclare le clsid du serveur COM pour l’action avec un GUID unique. Après avoir généré votre projet, ouvrez le registration.json fichier et notez que le fichier déclare que l’action utilise l’activation COM et spécifie une valeur clsid . Remplacez la valeur de l’attribut ID dans l’élément com :Class dans le fichier manifeste du package d’application pour utiliser le GUID généré.

Par exemple, si la valeur clsid dans le fichier généré registration.json est 11112222-bbbb-3333-cccc-4444dddd5555, l’élément com :Class mis à jour se présente comme suit :

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

Appelants d’application autorisés

Un nouveau champ qui a été ajouté au schéma JSON de définition d’action est allowedAppInvokers qui spécifie une liste d’ID de modèle utilisateur d’application (AppUserModelIDs) qui peuvent découvrir l’action via un appel à GetActionsForInputs ou GetAllActions. Les caractères génériques sont pris en charge. « * » correspond à tous les IdiD AppUserModel. Ceci est recommandé pour la plupart des actions, sauf s’il existe une raison spécifique de limiter les appelants qui peuvent appeler une action. Si allowedAppInvokers est omis ou est une liste vide, aucune application ne pourra découvrir l’action. Pour plus d’informations sur appUserModelIDs, consultez ID de modèle utilisateur d’application.

L’exemple suivant montre la pratique recommandée de définir allowedAppInvokers pour permettre à toutes les applications de découvrir l’action associée.

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

Tester l'action de l'application Windows

L’application App Actions Testing Playground vous permet de valider l’inscription et les fonctionnalités de votre application du fournisseur d’actions d’application Windows. Pour plus d’informations sur l’utilisation de cet outil, consultez App Actions Testing Playground.