Implementar el inicio de URI para App Actions en Windows

En este artículo se describen los pasos para crear acciones de aplicación y se describen los componentes de una aplicación de proveedor de acciones de aplicación. Las acciones de aplicación son unidades de comportamiento individuales que una aplicación de Windows puede implementar y registrar para que se pueda acceder a ellas desde otras aplicaciones y experiencias, integrando sin problemas en los flujos de trabajo de usuario. Para obtener más información sobre las acciones de aplicación en Windows, consulte Acciones de aplicación en Información general de Windows.

Las aplicaciones del proveedor de acciones se pueden implementar para usar la activación COM o la activación de inicio de URI. Las acciones de inicio de URI no admiten algunas características de acción avanzadas, como mostrar la interfaz de usuario en contexto o resultados de texto de streaming, pero la implementación es muy sencilla y puede ser la mejor opción para las acciones que solo constan de una sola solicitud y respuesta.

Las aplicaciones de proveedor que usan la activación COM implementan la interfaz IActionProvider para controlar la invocación de acciones. Este método habilita características avanzadas de acción, como la compatibilidad con texto de streaming, pero requiere más código que usar la extensión VSIX de Acciones de aplicaciones de Windows. Para obtener información sobre el uso de la activación COM en un proveedor de aplicaciones, consulte Introducción a acciones de aplicación en 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

Creación de un proyecto de aplicación de Windows en Visual Studio

La característica Acciones de aplicación es compatible con varios lenguajes y marcos de aplicaciones, pero las aplicaciones deben tener la identidad del paquete para poder registrarse en el sistema. En este tutorial se implementará un proveedor de acciones de aplicación de Windows en una aplicación de escritorio de C# WinUI 3 empaquetada.

1. En Visual Studio, cree un nuevo proyecto.

2. En el cuadro de diálogo Crear un nuevo proyecto , establezca el filtro de lenguaje en "C#" y el filtro de plataforma en "WinUI", seleccione la plantilla de proyecto "Aplicación vacía de WinUI (empaquetada)".

3. Asigne al nuevo proyecto el nombre "ExampleAppActionProvider".

4. Cuando se cargue el proyecto, en el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto y seleccione Propiedades. En la página General, desplácese hacia abajo hasta Sistema Operativo de destino y seleccione "Windows". En Versión del sistema operativo de destino y Versión del sistema operativo compatible, seleccione la versión 10.0.26100.0 o posterior.

5. Para actualizar el proyecto para admitir las API del proveedor de acciones, en el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto y seleccione Editar archivo de proyecto. Dentro de PropertyGroup, agregue el siguiente elemento WindowsSdkPackageVersion .

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Adición de una referencia al paquete nuget Microsoft.AI.Actions

El paquete nuget Microsoft.AI.Actions permite inicializar el entorno de ejecución de acciones de la aplicación, que proporciona API para crear los objetos de entidad que se pasan como entradas y salidas desde acciones de la aplicación.

1. En el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto y seleccione Administrar paquetes NuGet...
2. Asegúrese de que está en la pestaña Examinar y busque Microsoft.AI.Actions.
3. Seleccione Microsoft.AI.Actions y haga clic en Instalar.

Adición de un archivo JSON de definición de acción

Las aplicaciones del proveedor de acciones deben proporcionar un archivo de definición de acción que defina las acciones que implementa la aplicación. Este archivo proporciona información como el identificador único y la descripción de cada acción, así como los nombres y tipos de entradas y salidas que admite cada acción. Para obtener más información sobre el formato de archivo JSON de acción de la aplicación, consulte Esquema JSON de definición de acción para proveedores de acciones de aplicación de Windows.

En este ejemplo se definirá una acción denominada SendMessage, que toma una sola entidad Text como entrada y devuelve una única TextEntity como salida. Además de definir acciones, el archivo JSON también especifica si la aplicación del proveedor de acciones debe iniciarse mediante la activación COM o mediante el inicio del URI. En este ejemplo se usará la activación de URI. El esquema urilaunchaction-protocol de URI se registrará en un paso posterior de este tutorial.

1. En el Explorador de soluciones, haga clic con el botón derecho en la Assets carpeta y seleccione Agregar nuevo> elemento....
2. En el cuadro de diálogo Agregar nuevo elemento , seleccione Archivo de texto. Asigne al nuevo archivo el nombre "registration.json" y haga clic en Aceptar.
3. En el Explorador de soluciones, haga clic con el botón derecho en el archivo registration.json y seleccione Propiedades. En el panel Propiedades , establezca Acción de compilación en "Contenido" y establezca Copiar en directorio de salida en "Copiar si es más reciente".
4. Agregue la siguiente definición de acción JSON al archivo 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}"
        }
      }
    }
  ]
}

Actualización del archivo de manifiesto del paquete de aplicación

El archivo Package.appmanifest proporciona los detalles del paquete MSIX para una aplicación. Para que el sistema lo registre como proveedor de acciones de la aplicación de Windows, la aplicación debe incluir un elemento uap3:Extension con la categoría establecida en "windows.appExtension". Este elemento se usa para especificar la ubicación del archivo JSON de acción de la aplicación que define las acciones de la aplicación. Para obtener más información sobre el formato de manifiesto del paquete de aplicaciones del proveedor de acciones, consulta el formato XML del manifiesto del paquete de Windows para acciones de aplicaciones.

Para que un proveedor de acciones de la aplicación pueda iniciarse mediante un URI, debe registrar un protocolo con el sistema. Este registro se realiza proporcionando el elemento com2:Extension en el manifiesto del paquete de la aplicación. El atributo Name del elemento Protocol debe coincidir con el valor invocation.uri especificado en el archivo JSON de definición de acción, que para este ejemplo es urilaunchaction-protocol. Para obtener más información sobre la activación de inicio de URI, consulte Iniciar una aplicación para obtener resultados.

1. Haga clic con el botón derecho en el archivo Package.appxmanifest y seleccione Ver código.
2. Agregue el siguiente espacio de nombres al elemento Package en la raíz del archivo.

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

3. Agregue el siguiente elemento Extensions dentro del elemento Application y después del elemento 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>

Controlar la activación de la aplicación

Cuando el proveedor de acciones de la aplicación se inicia desde su esquema de URI registrado, se puede acceder a las entradas de la acción a través del objeto AppActivationArguments que se obtiene llamando a AppInstance.GetActivatedEventArgs. Para asegurarse de que la activación procede del protocolo registrado, primero debe comprobar para asegurarse de que el valor de la propiedad Kind es ExtendedActivationKind.ProtocolForResults. Si es así, puede convertir el objeto arguments en un objeto ProtocolForResultsActivatedEventArgs.

Se obtiene acceso a las entradas de la acción a través de la propiedad Data de los argumentos del evento, que es un ValueSet que contiene pares clave/valor para cada entidad de entrada. En este ejemplo se obtiene la message entidad de entrada tal como se define en el archivo registration.json. El valor de esta entrada es una cadena de texto.

Para obtener los resultados de la acción, el proveedor de acciones de aplicación debe instanciar una o varias entidades de salida. En este ejemplo se devuelve un valor TextActionEntity único que contiene la respuesta al mensaje de entrada.

Para crear una instancia de una nueva entidad de salida, obtenga una instancia de la clase ActionEntityFactory de la propiedad EntityFactory del objeto ActionRuntime . El objeto factory proporciona métodos para crear instancias de todos los distintos tipos de entidades de acción. Después de crear la entidad de texto que contiene el mensaje de respuesta, realizamos una entrada en un nuevo ValueSet donde la clave es el nombre de salida especificado en el archivo de registrationl.json, "response" y el valor es el id . de TextActionEntity. Tenga en cuenta que, al crear la entidad mediante una llamada a CreateTextEntity, la entidad se registra con el entorno de ejecución de la acción. Este es el motivo por el que se agrega el identificador de la entidad como valor en valueSet. Los consumidores de la acción recuperarán el objeto de la entidad del entorno de ejecución de la acción mediante este identificador.

El último paso para controlar la activación de URI es crear un nuevo ProtocolForResultsOperation y llamar al método ReportCompleted , pasando el ValueSet que contiene la referencia de entidad de salida.

En App.xaml.cs, reemplace la implementación predeterminada de OnLaunched por el código siguiente.

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

Prueba la acción de tu aplicación de Windows

La aplicación App Actions Testing Playground te permite validar el registro y la funcionalidad de la aplicación del proveedor de acciones de aplicaciones de Windows. Para obtener más información sobre el uso de esta herramienta, consulta App Actions Testing Playground app.

Acciones de aplicación adicionales en las características de Windows

En los artículos siguientes se proporciona información sobre las características adicionales de Acciones de aplicación en Windows.

• Alternar la disponibilidad de una acción de aplicación para Windows

Contenido relacionado