Implementar a inicialização do 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 do provedor de Ação de Aplicativo. As ações de 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 aplicativo no Windows, consulte Ações de Aplicativo na Visão Geral do 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 dão suporte a alguns recursos de ação avançados, como exibir a interface do usuário em resultados de texto de contexto ou streaming, 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 lidar com a invocação de ação. Esse método permite 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 de 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 de Aplicativo tem suporte para várias estruturas de aplicativos e idiomas, mas os aplicativos devem ter a identidade do pacote para poderem se registrar no sistema. Este passo a passo implementará um provedor de Ação de Aplicativo do 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é o sistema operacional de destino e selecione "Windows". Para a versão do sistema operacional de destino e a versão do sistema operacional com suporte, selecione a versão 10.0.26100.0 ou superior.

5. Para atualizar o projeto para dar suporte às APIs do Provedor de Ações, no Gerenciador de Soluções , clique com o botão direito do mouse no nome do projeto e selecione Editar Arquivo de Projeto. Dentro do 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 runtime de 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. Verifique se você está na guia Procurar e pesquise por 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 para cada ação, bem como os nomes e tipos de entradas e saídas que cada ação dá suporte. Para obter mais informações sobre o formato de arquivo JSON da Ação de Aplicativo, consulte o 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 Entidade de Texto 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 por meio da inicialização do 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 a Ação de Build como "Conteúdo" e defina Copiar para Diretório de Saída como "Copiar se for mais recente".
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 do 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 da Ação de 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 de Aplicativo no formato XML do manifesto do pacote do Windows.

Para que um provedor de ações de aplicativo seja iniciado por meio do URI, ele deve registrar um protocolo no 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 do 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 depois do 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 da ação podem ser acessadas por meio do objeto AppActivationArguments obtido chamando o AppInstance.GetActivatedEventArgs. Para garantir que a ativação foi do protocolo registrado, primeiro verifique se o valor da propriedade Kind é ExtendedActivationKind.ProtocolForResults. Nesse caso, você pode converter o objeto arguments em um objeto ProtocolForResultsActivatedEventArgs .

As entradas da ação são acessadas por meio da propriedade Data dos args de evento, 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 os resultados da ação, o provedor de ação do aplicativo deve instanciar uma ou mais entidades de saída. Este exemplo retorna uma única TextActionEntity que contém a resposta à mensagem de entrada.

Para criar uma instância de uma nova entidade de saída, obtenha uma instância da classe ActionEntityFactory da propriedade EntityFactory do objeto ActionRuntime . O objeto de fábrica 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 em que a chave é o nome de saída especificado no arquivo de registrationl.json, "resposta", e o valor é a ID da TextActionEntity. Observe que quando você cria a entidade chamando CreateTextEntity, a entidade é registrada com o runtime de ação. É por isso que você adiciona a ID da entidade como o valor no ValueSet. Os consumidores de sua ação recuperarão o objeto de entidade do runtime de 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.

Em 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

O aplicativo Playground de Teste de Ações de Aplicativo permite validar o registro e a funcionalidade do seu aplicativo do provedor de Ação de Aplicativo do Windows. Para obter mais informações sobre como usar essa ferramenta, consulte o aplicativo Playground de Teste de Ações de Aplicativo.

Ações adicionais de aplicativo em recursos do Windows

Os artigos a seguir fornecem informações sobre recursos adicionais das Ações de Aplicativo no Windows.

• Alternar a disponibilidade de uma ação de aplicativo para Windows

Conteúdo relacionado