Implementar a inicialização de URI para Ações de Aplicativo no Windows

Este artigo descreve as etapas para criar ações de aplicativo e descreve os componentes de um aplicativo provedor de Ação de Aplicativo. As ações do aplicativo são unidades individuais de comportamento que um aplicativo do Windows pode implementar e registrar para que possam ser acessadas de outros aplicativos e experiências, integrando-se perfeitamente aos fluxos de trabalho do usuário. Para obter mais informações sobre Ações de aplicativos no Windows, consulte Visão geral de ações de aplicativos no Windows.

Os aplicativos do provedor de ações podem ser implementados para usar a ativação COM ou a ativação de inicialização de URI. As ações de inicialização de URI não suportam alguns recursos de ação avançados, como exibir a interface do usuário no contexto ou transmitir resultados de texto, mas a implementação é muito simples e pode ser a melhor opção para ações que consistem apenas em uma única solicitação e resposta.

Os aplicativos de provedor que usam a ativação COM implementam a interface IActionProvider para manipular a chamada de ação. Esse método habilita recursos de ação avançados, como suporte para streaming de texto, mas requer mais código do que usar a extensão VSIX do Windows App Actions. Para obter informações sobre como usar a ativação COM em um provedor de aplicativos, consulte Introdução às ações do aplicativo no 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

Criar um novo projeto de aplicativo do Windows no Visual Studio

O recurso Ações do aplicativo é compatível com várias estruturas e idiomas do aplicativo, mas os aplicativos devem ter identidade do pacote para poder se registrar no sistema. Este passo a passo implementará um provedor de Ação de Aplicativo Windows em um aplicativo de área de trabalho C# WinUI 3 empacotado.

1. No Visual Studio, crie um novo projeto.

2. Na caixa de diálogo Criar um novo projeto , defina o filtro de idioma como "C#" e o filtro de plataforma como "WinUI" e, em seguida, selecione o modelo de projeto "Aplicativo em Branco WinUI (Empacotado)".

3. Nomeie o novo projeto como "ExampleAppActionProvider".

4. Quando o projeto for carregado, no Gerenciador de Soluções , clique com o botão direito do mouse no nome do projeto e selecione Propriedades. Na página Geral , role para baixo até Target OS e selecione "Windows". Para Versão do SO de destino e Versão do SO suportada, selecione a versão 10.0.26100.0 ou superior.

5. Para atualizar o projeto para dar suporte às APIs do Provedor de Ação, no Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Editar Arquivo de Projeto. Dentro de PropertyGroup, adicione o seguinte elemento WindowsSdkPackageVersion .

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Adicionar uma referência ao pacote nuget Microsoft.AI.Actions

O pacote nuget Microsoft.AI.Actions permite inicializar o tempo de execução das ações do aplicativo, que fornece APIs para criar os objetos de entidade que são passados como entradas e saídas de ações do aplicativo.

1. No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Gerenciar Pacotes NuGet...
2. Certifique-se de que está no separador Procurar e procure Microsoft.AI.Actions.
3. Selecione Microsoft.AI.Actions e clique em Instalar.

Adicionar um arquivo JSON de definição de ação

Os aplicativos do provedor de ações devem fornecer um arquivo de definição de ação que defina as ações que o aplicativo implementa. Esse arquivo fornece informações como o identificador exclusivo e a descrição de cada ação, bem como os nomes e tipos de entradas e saídas suportadas por cada ação. Para obter mais informações sobre o formato de arquivo JSON da Ação do Aplicativo, consulte Esquema JSON de definição de ação para provedores de Ação de Aplicativo do Windows.

Este exemplo definirá uma ação chamada SendMessage, que usa uma única entidade Text como entrada e retorna uma única TextEntity como saída. Além de definir ações, o arquivo JSON também especifica se o aplicativo do provedor de ações deve ser iniciado usando a ativação COM ou via inicialização de URI. Este exemplo usará a ativação de URI. O esquema urilaunchaction-protocol de URI será registrado em uma etapa posterior neste passo a passo.

1. No Gerenciador de Soluções, clique com o botão direito do mouse na Assets pasta e selecione Adicionar> Novo Item....
2. Na caixa de diálogo Adicionar Novo Item , selecione Arquivo de Texto. Nomeie o novo arquivo como "registration.json" e clique em OK.
3. No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo registration.json e selecione Propriedades. No painel Propriedades , defina Build Action como "Content" e Copy to Output Directory como "Copy if Newer".
4. Adicione a seguinte definição de ação JSON ao arquivo 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}"
        }
      }
    }
  ]
}

Atualizar o arquivo de manifesto do pacote do aplicativo

O arquivo Package.appmanifest fornece os detalhes do pacote MSIX para um aplicativo. Para ser registrado pelo sistema como um provedor de Ação de Aplicativo Windows, o aplicativo deve incluir um elemento uap3:Extension com a Categoria definida como "windows.appExtension". Esse elemento é usado para especificar o local do arquivo JSON de Ação do Aplicativo que define as ações do aplicativo. Para obter mais informações sobre o formato de manifesto do pacote do aplicativo do provedor de ações, consulte Ações do aplicativo no formato XML do manifesto do pacote do Windows.

Para que um provedor de ação de aplicativo seja iniciado via URI, ele deve registrar um protocolo com o sistema. Esse registro é feito fornecendo o elemento com2:Extension no manifesto do pacote do aplicativo. O atributo Name do elemento Protocol deve corresponder ao valor invocation.uri especificado no arquivo JSON de definição de ação, que para este exemplo é urilaunchaction-protocol. Para obter mais informações sobre a ativação de inicialização de URI, consulte Iniciar um aplicativo para obter resultados.

1. Clique com o botão direito do mouse no arquivo Package.appxmanifest e selecione Exibir código
2. Adicione o namespace a seguir ao elemento Package na raiz do arquivo.

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

3. Adicione o seguinte elemento Extensions dentro do elemento Application e após o 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>

Manipular a ativação do aplicativo

Quando o provedor de ação do aplicativo é iniciado a partir de seu esquema de URI registrado, as entradas para a ação podem ser acessadas por meio do objeto AppActivationArguments que é obtido chamando AppInstance.GetActivatedEventArgs. Para certificar-se de que a ativação foi do protocolo registrado, você deve primeiro verificar se o valor da propriedade Kind é ExtendedActivationKind.ProtocolForResults. Em caso afirmativo, você pode converter o objeto arguments em um objeto ProtocolForResultsActivatedEventArgs .

As entradas para a ação são acessadas por meio da propriedade Data do evento args, que é um ValueSet que contém pares chave/valor para cada entidade de entrada. Este exemplo obtém a message entidade de entrada conforme definido no arquivo registration.json. O valor dessa entrada é uma cadeia de caracteres de texto.

Para retornar resultados para a ação, o provedor de ação do aplicativo deve instanciar uma ou mais entidades de saída. Este exemplo retorna um único TextActionEntity contendo a resposta à mensagem de entrada.

Para instanciar uma nova entidade de saída, obtenha uma instância da classe ActionEntityFactory da propriedade EntityFactory do objeto ActionRuntime . O objeto factory fornece métodos para instanciar todos os diferentes tipos de entidades de ação. Depois de criar a entidade de texto que contém nossa mensagem de resposta, fazemos uma entrada em um novo ValueSet onde a chave é o nome de saída especificado no arquivo registrationl.json, "response", e o valor é o Id do TextActionEntity. Observe que quando você cria a entidade chamando CreateTextEntity, a entidade é registrada com o tempo de execução da ação. É por isso que você adiciona o Id da entidade como o valor no ValueSet. Os consumidores de sua ação recuperarão o objeto de entidade do tempo de execução da ação usando essa ID.

A etapa final no tratamento da ativação de URI é criar um novo ProtocolForResultsOperation e chamar o método ReportCompleted , passando o ValueSet que contém a referência da entidade de saída.

No App.xaml.cs, substitua a implementação padrão de OnLaunched pelo código a seguir.

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

Testar sua ação de aplicativo do Windows

A aplicação App Actions Testing Playground permite-lhe validar o registo e a funcionalidade da sua aplicação do fornecedor de Ação de Aplicações Windows. Para obter mais informações sobre como usar essa ferramenta, consulte App Actions Testing Playground app.

Ações adicionais do aplicativo em recursos do Windows

Os artigos a seguir fornecem informações sobre recursos adicionais do App Actions no Windows.

• Alternar a disponibilidade de uma Ação de Aplicativo para Windows

Conteúdo relacionado