Introdução às Ações de Aplicativo no Windows

Este artigo descreve as etapas para criar ações de aplicativos e descreve os componentes de um aplicativo fornecedor de ações 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 Visão geral das Ações de Aplicativo no Windows

A interface IActionProvider é a interface principal que os provedores de ação de aplicativo usam para se comunicar com a estrutura de ações do Windows. No entanto, a Microsoft fornece o Pacote NuGet Microsoft.AI.Actions que gera automaticamente a implementação IActionProvider com base em atributos .NET em seu código, permitindo que você faça classes fortemente tipadas para representar suas ações. Essa é a maneira recomendada de implementar um aplicativo de provedor de ações de aplicativo e é a técnica descrita neste artigo. Para alguns cenários de borda, os desenvolvedores podem querer implementar o IActionProvider diretamente. Para obter mais informações, consulte Implementar manualmente o IActionProvider.

Você também pode implementar um provedor de ação de aplicativo usando a ativação de inicialização de URI em vez de ativação com, embora alguns cenários mais avançados, como respostas de texto de streaming de uma ação, não tenham suporte. Para obter mais informações, consulte Implementar a inicialização do URI para 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

Criar um novo projeto de aplicativo do Windows no Visual Studio

O recurso Ações de Aplicativo no Windows tem suporte para várias estruturas de aplicativo, mas os aplicativos devem ter a identidade do pacote para poderem se registrar no sistema. Este tutorial implementará um provedor de ações para aplicativos do Windows em um aplicativo de desktop empacotado com C# e WinUI 3.

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 selecione o modelo de projeto "Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho)".

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é 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 seu 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 exemplo neste artigo usa os recursos de geração de código do pacote Nuget Microsoft.AI.Actions.

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 uma classe ActionProvider para lidar com operações de ação

A seção a seguir mostra como implementar uma classe de provedor de ações personalizada que usa atributos .NET do namespace Microsoft.AI.Actions.Annotations para identificar os componentes de uma ação. O pacote NuGet Microsoft.AI.Actions usa esses atributos para gerar automaticamente uma implementação subjacente da interface IActionProvider . Isso permite que você crie classes fortemente tipados para ações sem precisar interagir diretamente com as APIs do provedor de ações de baixo nível.

1. No Visual Studio, clique com o botão direito do mouse no projeto ExampleAppActionProvider no Gerenciador de Soluções e selecione Adicionar –> Classe.
2. Na caixa de diálogo Adicionar classe , nomeie a classe "MyActionProvider" e clique em Adicionar.
3. Substitua o conteúdo do MyActionProvider.cs código a seguir.

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

Os recursos de geração de código do pacote Nuget Microsoft.AI.Actions usam atributos .NET em seu código para determinar os detalhes das ações que seu aplicativo fornece. Este exemplo usa os seguintes atributos:

A maioria dos atributos com suporte é mapeada diretamente para campos no arquivo JSON de definição de ação que o sistema usa para descobrir ações. Na verdade, como será mostrado posteriormente neste artigo, o recurso de geração de código Microsoft.AI.Actions usa esses atributos para gerar automaticamente o arquivo JSON de definição de ação no momento do build. À medida que você atualiza sua classe de provedor de ações, adicionando ou modificando esses atributos, o pacote Nuget regenerará o arquivo de definição de ação para refletir suas alterações. Para obter mais informações sobre o arquivo JSON de definição de ação, consulte o esquema JSON de definição de ação para Ações de Aplicativo no Windows.

Para obter uma lista dos atributos com suporte, consulte o arquivo readme do pacote Nuget Microsoft.AI.Actions .

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. Você também deve especificar com.microsoft.windows.ai.actions como o Nome do elemento uap3:AppExtension . Para obter mais informações sobre o formato de manifesto do pacote do aplicativo do Provedor de Ações, consulte o formato XML do manifesto do pacote do Provedor de Ação de Aplicativo do Windows.

O exemplo neste passo a passo usa a ativação COM para iniciar o provedor de ação do aplicativo. Para habilitar a ativação com, use o elemento com2:Extension no manifesto do pacote do aplicativo. O valor invocation.clsid especificado no arquivo JSON de definição de ação deve corresponder à ID de classe especificada no elemento com:Class no manifesto do pacote do aplicativo.

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

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. Adicione o seguinte elemento Extensions dentro do elemento Application e depois do elemento 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>

Implementar um método Main personalizado

No modelo de projeto padrão, o ponto de entrada do método Principal é gerado automaticamente pelo compilador. Este exemplo desabilitará a geração automática de Main para que o código de ativação necessário possa ser executado na inicialização.

1. No Gerenciador de Soluções, clique com o botão direito do mouse no ícone do projeto e selecione Editar Arquivo de Projeto.
2. No elemento PropertyGroup , adicione o seguinte elemento filho para desabilitar a função principal gerada automaticamente.

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

Em seguida, no Gerenciador de Soluções, clique com o botão direito do mouse no ícone do projeto e selecione Adicionar> Novo Item. Selecione Arquivo de Código. Altere o nome do arquivo para "Program.cs" e clique em Adicionar.

No arquivo Program.cs, adicionaremos uma linha de código que fará com que o pacote nuget de ações gere automaticamente a ativação do servidor COM que permite que o sistema invoque o provedor de ações.

ComServerRegisterActions.RegisterActions();

O restante do código no método Main neste exemplo é apenas o código clichê para iniciar um aplicativo WinUI. Substitua os conteúdos do Program.cs pelo código a seguir.

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

Adicionar propriedades de configuração do Microsoft.AI.Actions ao arquivo de projeto

O recurso de geração de código do pacote Nuget Microsoft.AI.Actions usa valores de propriedade definidos no arquivo de projeto para configurar seu comportamento no momento do build. Adicione as propriedades a seguir dentro do primeiro elemento PropertyGroup em seu arquivo .csproj.

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

A tabela a seguir descreve essas propriedades.

Fazer atualizações com base no arquivo de registration.json gerado

Depois de criar seu projeto, você pode exibir o arquivo gerado registration.json na pasta Ativos no Gerenciador de Soluções.

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

Atualizar o CLSID no arquivo de manifesto do pacote do aplicativo

Na primeira vez que criar seu aplicativo de provedor de ações, você receberá o aviso: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Isso ocorre porque o arquivo gerado registration.json automaticamente declara o clsid do servidor COM para a ação com um GUID exclusivo. Depois de compilar seu projeto, abra o registration.json arquivo e observe que o arquivo declara que a ação usa a ativação COM e especifica um valor clsid . Substitua o valor do atributo Id no elemento com:Class no arquivo de manifesto do pacote do aplicativo para usar o GUID gerado.

Por exemplo, se o valor clsid no arquivo gerado registration.json for 11112222-bbbb-3333-cccc-4444dddd5555, o elemento com:Class atualizado será semelhante ao seguinte:

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

Invocadores de aplicativo permitidos

Um novo campo que foi adicionado ao esquema JSON de definição de ação é allowedAppInvokers que especifica uma lista de IDs de modelo de usuário de aplicativo (AppUserModelIDs) que podem descobrir a ação por meio de uma chamada para GetActionsForInputs ou GetAllActions. Os caracteres curinga têm suporte. "*" corresponderá a todos os AppUserModelIDs. Isso é recomendado para a maioria das ações, a menos que haja um motivo específico para limitar os chamadores que podem invocar uma ação. Se allowedAppInvokers for omitido ou for uma lista vazia, nenhum aplicativo poderá descobrir a ação. Para obter mais informações sobre AppUserModelIDs, consulte IDs do modelo de usuário do aplicativo.

O exemplo a seguir mostra a prática recomendada de definir allowedAppInvokers para permitir que todos os aplicativos descubram a ação associada.

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

Testar a ação do aplicativo 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 App Actions Testing Playground.