Rozpocznij korzystanie z funkcji App Actions w systemie Windows

W niniejszym artykule opisano kroki tworzenia akcji aplikacji oraz składniki aplikacji, która udostępnia akcje aplikacji. Akcje aplikacji to poszczególne jednostki zachowania, które aplikacja systemu Windows może implementować i rejestrować, aby można było uzyskiwać do nich dostęp z innych aplikacji i środowisk, bezproblemowo integrując się z przepływami pracy użytkownika. Aby uzyskać więcej informacji na temat akcji aplikacji w systemie Windows, zobacz Akcje aplikacji w systemie Windows — omówienie

Interfejs IActionProvider jest podstawowym interfejsem używanym przez dostawców akcji aplikacji do komunikowania się z platformą akcji systemu Windows. Firma Microsoft udostępnia jednak pakiet NuGet Microsoft.AI.Actions , który automatycznie generuje implementację IActionProvider na podstawie atrybutów platformy .NET w kodzie, umożliwiając tworzenie silnie typiowanych klas reprezentujących akcje. Jest to zalecany sposób implementowania aplikacji dostawcy akcji aplikacji i jest techniką opisaną w tym artykule. W przypadku niektórych scenariuszy brzegowych deweloperzy mogą chcieć bezpośrednio zaimplementować IActionProvider . Aby uzyskać więcej informacji, zobacz Ręczne implementowanie IActionProvider.

Możesz również zaimplementować dostawcę akcji aplikacji przy użyciu aktywacji uruchamiania identyfikatora URI, a nie aktywacji MODELU COM, chociaż niektóre bardziej zaawansowane scenariusze, takie jak przesyłanie strumieniowe odpowiedzi tekstowe z akcji, nie są obsługiwane. Aby uzyskać więcej informacji, zobacz Implement URI launch for App Actions on Windows (Implementowanie uruchamiania identyfikatora URI dla akcji aplikacji w systemie Windows).

winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cs.winget

Tworzenie nowego projektu aplikacji systemu Windows w programie Visual Studio

Funkcja Akcje aplikacji w systemie Windows jest obsługiwana w przypadku wielu struktur aplikacji, ale aplikacje muszą mieć tożsamość pakietu, aby móc zarejestrować się w systemie. Ten przewodnik spowoduje zaimplementowanie dostawcy akcji aplikacji systemu Windows w spakowanej aplikacji klasycznej WinUI 3 języka C#.

1. W programie Visual Studio utwórz nowy projekt.

2. W oknie dialogowym Tworzenie nowego projektu ustaw filtr języka na "C#" i filtr platformy na "WinUI", a następnie wybierz szablon projektu "Pusta aplikacja, spakowana (WinUI 3 w programie Desktop)."

3. Nadaj nowej nazwie nowy projekt "ExampleAppActionProvider".

4. Po załadowaniu projektu w Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nazwę projektu i wybierz pozycję właściwości . Na stronie Ogólne przewiń w dół do Target OS i wybierz pozycję "Windows". W obszarze Docelowa wersja systemu operacyjnego i obsługiwana wersja systemu operacyjnego wybierz wersję 10.0.26100.0 lub nowszą.

5. Aby zaktualizować projekt do obsługi interfejsów API dostawcy akcji, w Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nazwę projektu i wybierz polecenie Edytuj plik projektu. W środku PropertyGroup, dodaj następujący element WindowsSdkPackageVersion.

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Dodawanie odwołania do pakietu NuGet Microsoft.AI.Actions

W przykładzie w tym artykule użyto funkcji generowania kodu pakietu NuGet Microsoft.AI.Actions.

1. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nazwę projektu i wybierz polecenie Zarządzaj pakietami NuGet...
2. Upewnij się, że jesteś na karcie Przeglądaj i wyszukaj ciąg Microsoft.AI.Actions.
3. Wybierz pozycję Microsoft.AI.Actions i kliknij przycisk Zainstaluj.

Dodawanie klasy ActionProvider do obsługi operacji akcji

W poniższej sekcji pokazano, jak zaimplementować niestandardową klasę dostawcy akcji, która używa atrybutów platformy .NET z przestrzeni nazw Microsoft.AI.Actions.Annotations w celu zidentyfikowania składników akcji. Pakiet NuGet Microsoft.AI.Actions używa tych atrybutów do automatycznego generowania podstawowej implementacji interfejsu IActionProvider . Dzięki temu można tworzyć silnie typizowane klasy dla akcji bez konieczności bezpośredniej interakcji z interfejsami API dostawcy akcji niskiego poziomu.

1. W programie Visual Studio kliknij prawym przyciskiem myszy projekt ExampleAppActionProvider w eksploratorze rozwiązań i wybierz pozycję Dodaj>Klasa.
2. W oknie dialogowym Dodawanie klasy nadaj klasie nazwę "MyActionProvider" i kliknij przycisk Dodaj.
3. Zastąp zawartość MyActionProvider.cs pliku następującym kodem.

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

Funkcje generowania kodu pakietu NuGet Microsoft.AI.Actions używają atrybutów platformy .NET w kodzie w celu określenia szczegółów akcji, które udostępnia aplikacja. W tym przykładzie są używane następujące atrybuty:

Większość obsługiwanych atrybutów mapuje się bezpośrednio na pola w pliku JSON definicji akcji używanym przez system do odnajdywania akcji. W rzeczywistości, jak pokazano w dalszej części tego artykułu, funkcja generowania kodu Microsoft.AI.Actions używa tych atrybutów do automatycznego generowania pliku JSON definicji akcji w czasie kompilacji. Podczas aktualizowania klasy dostawcy akcji, dodawania lub modyfikowania tych atrybutów pakiet Nuget ponownie wygeneruje plik definicji akcji w celu odzwierciedlenia zmian. Aby uzyskać więcej informacji na temat pliku JSON definicji akcji, zobacz Schemat JSON definicji akcji dla akcji aplikacji w systemie Windows.

Aby uzyskać listę obsługiwanych atrybutów, zobacz plik readme pakietu Nuget Microsoft.AI.Actions .

Aktualizowanie pliku manifestu pakietu aplikacji

Plik Package.appmanifest zawiera szczegóły pakietu MSIX dla aplikacji. Aby być zarejestrowanym przez system jako dostawca działań w aplikacjach dla Windowsa, aplikacja musi zawierać element uap3:Extension z kategorią ustawioną na "windows.appExtension". Ten element służy do określania lokalizacji pliku JSON akcji aplikacji, który definiuje akcje aplikacji. Należy również określić com.microsoft.windows.ai.actions jako nazwę elementu uap3:AppExtension . Aby uzyskać więcej informacji na temat formatu manifestu pakietu aplikacji dostawcy akcji systemu Windows, zobacz Format XML manifestu dostawcy akcji aplikacji systemu Windows.

W przykładzie w tym przewodniku użyto aktywacji COM do uruchomienia dostawcy działań aplikacji. Aby włączyć aktywację modelu COM, użyj elementu com2:Extension w manifeście pakietu aplikacji. Wartość invocation.clsid określona w pliku JSON definicji akcji musi być zgodna z identyfikatorem klasy określonym w elemenie com:Class w manifeście pakietu aplikacji.

1. Kliknij prawym przyciskiem myszy plik Package.appxmanifest i wybierz polecenie Wyświetl kod
2. Dodaj następujące przestrzenie nazw do elementu Package w katalogu głównym pliku.

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. Dodaj następujący element Extensions wewnątrz elementu Application i po elemecie 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>

Zaimplementuj niestandardową metodę Main

W domyślnym szablonie projektu punkt wejścia metody Main jest generowany automatycznie przez kompilator. W tym przykładzie zostanie wyłączone automatyczne generowanie pliku Main , aby podczas uruchamiania można było uruchomić niezbędny kod aktywacji.

1. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy ikonę projektu i wybierz polecenie Edytuj plik projektu.
2. W elemecie PropertyGroup dodaj następujący element podrzędny, aby wyłączyć automatycznie wygenerowaną funkcję główną.

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

Następnie w Eksploratorze rozwiązań kliknij prawym przyciskiem myszy ikonę projektu i wybierz polecenie Dodaj nowy> element. Wybierz pozycję Plik kodu. Zmień nazwę pliku na "Program.cs", a następnie kliknij przycisk Dodaj.

W pliku Program.cs dodamy wiersz kodu, który spowoduje, że pakiet nuget akcji automatycznie wygeneruje aktywację serwera COM, która umożliwia systemowi wywołanie dostawcy akcji.

ComServerRegisterActions.RegisterActions();

Pozostała część kodu w metodzie Main w tym przykładzie to tylko standardowy kod umożliwiający uruchomienie aplikacji WinUI. Zastąp zawartość Program.cs następującym kodem.

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

Dodawanie właściwości konfiguracji Microsoft.AI.Actions do pliku projektu

Funkcja generowania kodu pakietu NuGet Microsoft.AI.Actions używa wartości właściwości zdefiniowanych w pliku projektu w celu skonfigurowania jego zachowania w czasie kompilacji. Dodaj następujące właściwości wewnątrz pierwszego elementu PropertyGroup w pliku csproj.

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

W poniższej tabeli opisano te właściwości.

Wprowadzanie aktualizacji na podstawie wygenerowanego pliku registration.json

Po utworzeniu projektu możesz wyświetlić wygenerowany registration.json plik w folderze Assets w Eksploratorze rozwiązań.

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

Aktualizowanie identyfikatora CLSID w pliku manifestu pakietu aplikacji

Podczas pierwszej kompilacji aplikacji dostawcy akcji zostanie wyświetlone ostrzeżenie: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Jest to spowodowane tym, że automatycznie wygenerowany registration.json plik deklaruje clsid serwera COM dla akcji z unikatowym identyfikatorem GUID. Po utworzeniu registration.json projektu otwórz plik i zwróć uwagę, że plik deklaruje, że akcja używa aktywacji MODELU COM i określa wartość clsid . Zastąp wartość atrybutu Id w elemencie com:Class w pliku manifestu pakietu aplikacji, aby użyć wygenerowanego identyfikatora GUID.

Jeśli na przykład wartość clsid w wygenerowany registration.json plik to 11112222-bbbb-3333-cccc-4444dddd5555, zaktualizowany element com:Class będzie wyglądać następująco:

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

Dozwolone wywołania aplikacji

Nowe pole, które zostało dodane do schematu JSON definicji akcji, jest dozwoloneAppInvokers , które określa listę identyfikatorów modelu użytkownika aplikacji (AppUserModelIDs), które mogą odnaleźć akcję za pomocą wywołania metody GetActionsForInputs lub GetAllActions. Obsługiwane są symbole wieloznaczne. Wartość "*" będzie zgodna ze wszystkimi identyfikatorami AppUserModelID. Jest to zalecane w przypadku większości akcji, chyba że istnieje określona przyczyna ograniczenia elementów wywołujących, które mogą wywołać akcję. Jeśli aplikacja allowedAppInvokers zostanie pominięta lub jest pustą listą, żadne aplikacje nie będą mogły odnaleźć akcji. Aby uzyskać więcej informacji na temat identyfikatorów AppUserModelID, zobacz Identyfikatory modelu użytkownika aplikacji.

Poniższy przykład przedstawia zalecaną praktykę ustawiania dozwolonej aplikacjiAppInvokers w celu umożliwienia wszystkim aplikacjom odnajdywania skojarzonej akcji.

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

Testowanie akcji aplikacji systemu Windows

Aplikacja App Actions Testing Playground umożliwia zweryfikowanie rejestracji i funkcjonalności aplikacji dostawcy akcji aplikacji systemu Windows. Aby uzyskać więcej informacji na temat korzystania z tego narzędzia, zobacz Testowanie akcji aplikacji — plac zabaw.