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 App Actions w systemie Windows, zobacz App Actions on Windows Overview.

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 Twoim kodzie, co pozwala tworzyć silnie typowane klasy reprezentujące akcje. Jest to zalecany sposób implementowania aplikacji App Action Provider i technika opisana 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 COM, chociaż niektóre bardziej zaawansowane scenariusze, takie jak przesyłanie strumieniowe odpowiedzi tekstowych z akcji, nie są obsługiwane. Aby uzyskać więcej informacji, zobacz Implement URI launch for App Actions on 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>
   

Dodaj odwołanie 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 Browse i wyszukaj ciąg Microsoft.AI.Actions.
3. Wybierz pozycję Microsoft.AI.Actions i kliknij przycisk Zainstaluj.

Dodaj klasę 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 wewnętrznej 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 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 Task<string> ProcessMessageAsync(string contact, string? message)
        {
            if (message != null)
            {
                return Task.FromResult($"Processed {contact}, {message}");
            }
            else
            {
                return Task.FromResult($"Processed {contact}");
            }
        }
    }
}

Funkcje generowania kodu pakietu NuGet Microsoft.AI.Actions używają atrybutów .NET w kodzie, aby określić szczegóły akcji zapewnianych przez aplikację. 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 zostanie pokazane w dalszej części tego artykułu, funkcja generowania kodu Microsoft.AI.Actions używa tych atrybutów do automatycznego generowania pliku definicji akcji w formacie JSON w czasie kompilacji. Podczas aktualizowania klasy dostawcy akcji dodanie lub zmodyfikowanie tych atrybutów spowoduje ponowne wygenerowanie pliku definicji akcji w celu odzwierciedlenia zmian. Aby uzyskać więcej informacji na temat pliku JSON definicji akcji, zobacz Schemat JSON definicji akcji dla App Actions w systemie Windows.

Aby uzyskać listę obsługiwanych atrybutów, zobacz plik readme dla 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 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 actions 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();
        });
    }
}

Dodaj 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 swojego 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.

Wprowadź aktualizacje na podstawie wygenerowanego pliku registration.json

Po skompilowaniu 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 projektu otwórz plik registration.json 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 wygenerowanym pliku registration.json 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" />

Dozwoleni wywołujący aplikację

Pole allowedAppInvokers w schemacie JSON definicji akcji 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ść "*" oznacza dopasowanie do wszystkich identyfikatorów AppUserModelID. Jest to zalecane w przypadku większości akcji, chyba że istnieje określona przyczyna ograniczenia podmiotów wywołujących, które mogą wywołać akcję. Jeśli allowedAppInvokers zostanie pominięte 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 allowedAppInvokers 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.