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 App Actions no Windows, consulte Descrição geral de App Actions 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 no seu código, permitindo-lhe criar classes fortemente tipadas para representar as suas ações. Esta é a forma recomendada de implementar uma aplicação fornecedora de ações da aplicação 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.

Pode também implementar um fornecedor de ações de aplicações utilizando a ativação de início por URI em vez da ativação COM, embora alguns cenários mais avançados, como a transmissão em fluxo de respostas de texto a partir 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 utiliza as funcionalidades de geração de código do pacote NuGet Microsoft.AI.Actions.

1. No Explorador de Soluções, clique com o botão direito no nome do projeto e selecione Gerir Pacotes NuGet...
2. Certifique-se de que está no separador Pesquisar 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 utiliza estes atributos para gerar automaticamente uma implementação subjacente da interface IActionProvider. Isso permite criar classes fortemente tipadas para ações sem ter de interagir diretamente com as APIs do fornecedor 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 de MyActionProvider.cs pelo 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 Task<string> ProcessMessageAsync(string contact, string? message)
        {
            if (message != null)
            {
                return Task.FromResult($"Processed {contact}, {message}");
            }
            else
            {
                return Task.FromResult($"Processed {contact}");
            }
        }
    }
}

As funcionalidades de geração de código do pacote NuGet Microsoft.AI.Actions utilizam atributos .NET no seu código para determinar os detalhes das ações que a sua aplicação 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 atualiza a sua classe de provedor de ações, adicionando ou modificando estes atributos, o pacote NuGet irá regenerar o ficheiro de definição de ação para refletir as 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 uma lista dos atributos suportados, consulte o ficheiro 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 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 no ficheiro Package.appxmanifest e selecione View Code.
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 Explorador de Soluções, clique com o botão direito no ícone do projeto e selecione Adicionar->Novo Item. Selecione Ficheiro 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

A funcionalidade de geração de código do pacote NuGet Microsoft.AI.Actions utiliza valores de propriedade definidos no ficheiro do projeto para configurar o seu comportamento em tempo de compilação. Adicione as seguintes propriedades dentro do primeiro elemento PropertyGroup no seu ficheiro .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 compilar o seu projeto, pode ver o ficheiro gerado registration.json na pasta Assets no Explorador 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 a sua aplicação de fornecedor de ações, 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 o seu projeto, abra o ficheiro registration.json e observe que o ficheiro 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" />

Aplicações autorizadas a invocar

O campo allowedAppInvokers no esquema JSON de definição de ação especifica uma lista de IDs de Modelo de Utilizador de Aplicação (AppUserModelIDs) que podem descobrir a ação através 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.