Implémenter le lancement d’URI pour les 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.

Les applications de fournisseur d’actions peuvent être implémentées pour utiliser l’activation COM ou l’activation de lancement d’URI. Les actions de lancement d’URI ne prennent pas en charge certaines fonctionnalités d’action avancées telles que l’affichage de l’interface utilisateur dans le contexte ou le streaming de résultats de texte, mais l’implémentation est très simple et peut être le meilleur choix pour les actions qui se composent uniquement d’une seule requête et réponse.

Les applications fournisseurs qui utilisent l’activation COM implémentent l’interface IActionProvider pour gérer l’appel d’action. Cette méthode active des fonctionnalités d’action avancées telles que la prise en charge du texte de diffusion en continu, mais nécessite plus de code que l’utilisation de l’extension VSIX Windows App Actions. Pour plus d’informations sur l’utilisation de l’activation COM dans un fournisseur d’applications, consultez Prise en main des 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

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

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

La fonctionnalité Actions d’application est prise en charge pour plusieurs frameworks et langues 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 WinUI (empaquetée) ».

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

Le package nuget Microsoft.AI.Actions vous permet d’initialiser le runtime d’actions d’application, qui fournit des API pour créer les objets d’entité passés en tant qu’entrées et sorties à partir d’actions d’application.

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 un fichier JSON de définition d’action

Les applications du fournisseur d’actions doivent fournir un fichier de définition d’action qui définit les actions que l’application implémente. Ce fichier fournit des informations telles que l’identificateur unique et la description de chaque action, ainsi que les noms et les types d’entrées et de sorties pris en charge par chaque action. Pour plus d’informations sur le format de fichier JSON De l’action d’application, consultez schéma JSON de définition d’action pour les fournisseurs d’actions d’application Windows.

Cet exemple définit une action appelée SendMessage, qui prend une seule entité Text en tant qu’entrée et retourne une seule TextEntity en tant que sortie. En plus de définir des actions, le fichier JSON spécifie également si l’application du fournisseur d’actions doit être lancée à l’aide de l’activation COM ou via le lancement de l’URI. Cet exemple utilise l’activation de l’URI. Le schéma urilaunchaction-protocol d’URI sera inscrit dans une étape ultérieure de cette procédure pas à pas.

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le Assets dossier, puis sélectionnez Add-New> Item....
2. Dans la boîte de dialogue Ajouter un nouvel élément , sélectionnez Fichier texte. Nommez le nouveau fichier «registration.json», puis cliquez sur OK.
3. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le fichier registration.json, puis sélectionnez Propriétés. Dans le volet Propriétés , définissez l’action de génération sur « Contenu » et définissez Copier dans le répertoire de sortie sur « Copier si plus récent ».
4. Ajoutez la définition d’action JSON suivante au fichier 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}"
        }
      }
    }
  ]
}

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. Pour plus d’informations sur le format du manifeste du package d’application du fournisseur d’actions, consultez Actions d’application sur le format XML du manifeste de package Windows.

Pour qu’un fournisseur d’actions d’application soit lancé via l’URI, il doit inscrire un protocole auprès du système. Cette inscription est effectuée en fournissant l’élément com2 :Extension dans le manifeste du package d’application. L’attribut Name de l’élément Protocol doit correspondre à la valeur invocation.uri spécifiée dans le fichier JSON de définition d’action, qui, pour cet exemple, est urilaunchaction-protocol. Pour plus d’informations sur l’activation du lancement d’URI, consultez Lancer une application pour obtenir des résultats.

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

xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/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>
  <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>

Gérer l’activation de l’application

Lorsque le fournisseur d’actions d’application est lancé à partir de son schéma d’URI inscrit, les entrées de l’action sont accessibles via l’objet AppActivationArguments obtenu en appelant AppInstance.GetActivatedEventArgs. Pour vous assurer que l’activation provient du protocole inscrit, vous devez d’abord vérifier que la valeur de la propriété Kind est ExtendedActivationKind.ProtocolForResults. Dans ce cas, vous pouvez convertir l’objet arguments en objet ProtocolForResultsActivatedEventArgs .

Les entrées de l’action sont accessibles via la propriété Données des arguments d’événement, qui est un ValueSet qui contient des paires clé/valeur pour chaque entité d’entrée. Cet exemple obtient l’entité message d’entrée telle que définie dans le fichier registration.json. La valeur de cette entrée est une chaîne de texte.

Pour retourner les résultats de l’action, le fournisseur d’actions d’application doit instancier une ou plusieurs entités de sortie. Cet exemple retourne une valeur TextActionEntity unique contenant la réponse au message d’entrée.

Pour instancier une nouvelle entité de sortie, obtenez une instance de la classe ActionEntityFactory à partir de la propriété EntityFactory de l’objet ActionRuntime . L’objet factory fournit des méthodes pour instancier tous les différents types d’entités d’action. Après avoir créé l’entité texte contenant notre message de réponse, nous créons une entrée dans un nouvel ensemble de valeurs où la clé est le nom de sortie spécifié dans le fichier registrationl.json, « response » et la valeur correspond à l’ID de TextActionEntity. Notez que lorsque vous créez l’entité en appelant CreateTextEntity, l’entité est inscrite auprès du runtime d’action. C’est pourquoi vous ajoutez l’ID de l’entité comme valeur dans ValueSet. Les consommateurs de votre action récupèrent l’objet d’entité à partir du runtime d’action à l’aide de cet ID.

La dernière étape de gestion de l’activation de l’URI consiste à créer un protocole ProtocolForResultsOperation et à appeler la méthode ReportCompleted , en passant la valeur ValueSet qui contient la référence d’entité de sortie.

Dans App.xaml.cs, remplacez l’implémentation par défaut d’OnLaunched par le code suivant.

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

Tester votre action d’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 l’application App Actions Testing Playground.

Actions d’application supplémentaires sur les fonctionnalités Windows

Les articles suivants fournissent des informations sur les fonctionnalités supplémentaires d’Actions d’application sur Windows.

• Désactiver la disponibilité d’une action d’application pour Windows

Contenu connexe