Introdução às Ações de Aplicações 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 Aplicativo no Windows, consulte Visão geral de 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 provedor de ação de aplicativo e é a técnica descrita neste artigo. Para alguns cenários de casos de borda, os desenvolvedores podem querer implementar IActionProvider diretamente. Para obter mais informações, consulte Implementar manualmente IActionProvider.

Você também pode implementar um provedor de ação de aplicativo usando a ativação de inicialização de URI em vez da ativação COM, embora alguns cenários mais avançados, como streaming de respostas de texto de uma ação, não sejam suportados. Para obter mais informações, consulte Implementar inicialização de 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 é suportado para várias estruturas de aplicativos, mas os aplicativos devem ter identidade de pacote para poder se registrar no sistema. Este tutorial implementará um fornecedor de Ação de Aplicação Windows num aplicativo de desktop C# WinUI 3 em pacote.

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, 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é SO de destino 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 seu 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 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. Certifique-se de que está no separador Procurar e procure Microsoft.AI.Actions.
3. Selecione Microsoft.AI.Actions e clique em Instalar.

Adicionar uma classe ActionProvider para manipular operações de ação

A seção a seguir mostra como implementar uma classe de provedor de ação 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 tipadas para ações sem ter que 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 pelo código a MyActionProvider.cs 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 suportados são mapeados 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 mais adiante 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 da compilação. À 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 Esquema JSON de definição de ação para ações de aplicativo no Windows.

Para obter uma lista dos atributos suportados, consulte o arquivo readme para o 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 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. Você também deve especificar com.microsoft.windows.ai.actions como o Name para o elemento uap3:AppExtension . Para mais informações sobre o formato do manifesto do pacote do aplicativo do provedor de ações, consulte Formato XML do manifesto do pacote do aplicativo do provedor de ações do Windows.

O exemplo neste passo a passo usa a ativação COM para iniciar o provedor de ações 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 ao ID de classe especificado 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 após o 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 Main é gerado automaticamente pelo compilador. Este exemplo desativará 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 desativar 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 ficheiro para "Program.cs" e clique em Adicionar.

No arquivo Program.cs, adicionaremos uma linha de código que fará com que o pacote de ações nuget 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 o conteúdo 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 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 em tempo de compilação. Adicione as seguintes propriedades 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 você criar seu aplicativo provedor de ação, 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 criar 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 terá a seguinte aparência:

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

Invocadores de aplicativos 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. Caracteres universais são suportados. "*" 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 Application User Model IDs.

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

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