Rozpocznij korzystanie z funkcji App Actions w systemie Windows

2025-05-20

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

Akcje obsługują dwa różne modele aktywacji dla dostawców akcji aplikacji: aktywację COM i uruchamianie przy użyciu identyfikatora URI. W tym artykule opisano kroki tworzenia dostawcy akcji aplikacji korzystającego z aktywacji modelu COM.

Automatyczna instalacja zależności (zalecane)
Ręczna instalacja zależności

Uruchom jedno z poniższych poleceń w terminalu (niezależnie od tego, czy jesteś deweloperem języka C#, czy C++). Spowoduje to uruchomienie pliku konfiguracji WinGet , który wykonuje następujące zadania (zainstalowane już zależności zostaną pominięte):
- Włącza tryb dewelopera.
- Instaluje program Visual Studio Community Edition
- Uwzględnij obciążenie programistyczne aplikacji systemu Windows i obciążenia C++ lub .NET/C#
- Dołączanie narzędzi do tworzenia pakietów MSIX

Dla deweloperów języka C#:

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

Dla deweloperów języka C++:

winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cpp.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#.

W programie Visual Studio utwórz nowy projekt.
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)."
Nadaj nowej nazwie nowy projekt "ExampleAppActionProvider".
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ą.
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.59-preview</WindowsSdkPackageVersion>
```

Dodawanie pliku JSON definicji akcji

Aplikacje dostarczające akcje muszą dostarczyć plik definicji akcji, który określa działania implementowane przez aplikację. Ten plik zawiera informacje o danych wejściowych i wyjściowych akcji oraz metadanych, takich jak unikatowy identyfikator i opis akcji. Aby uzyskać więcej informacji na temat formatu pliku JSON akcji aplikacji, zobacz Schemat JSON definicji akcji dla dostawców akcji aplikacji systemu Windows.

W tym przykładzie zdefiniujemy jedną akcję o nazwie SendMessage, która przyjmuje pojedynczą jednostkę Text jako dane wejściowe i zwraca pojedynczą wartość TextEntity jako dane wyjściowe. Oprócz definiowania akcji plik JSON określa również, czy aplikacja dostawcy akcji powinna być uruchamiana przy użyciu aktywacji COM, czy za pośrednictwem uruchamiania identyfikatora URI. W tym przykładzie zostanie użyta aktywacja COM.

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy plik projektu ExampleAppActionProvider i wybierz polecenie Dodaj nowy> element....
W oknie dialogowym Dodawanie nowego elementu wybierz pozycję Plik tekstowy. Nazwij nowy plik "registration.json", a następnie kliknij przycisk OK.
Dodaj następującą definicję akcji JSON do pliku registration.json.
W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy plik registration.json i wybierz polecenie Właściwości. W okienku Właściwości ustaw opcję Akcja kompilacji na wartość "Zawartość" i ustaw wartość Kopiuj na Katalog wyjściowy na wartość "Kopiuj, jeśli nowsza".
Zastąp wartość invocation.clsid nowym identyfikatorem GUID, który zidentyfikuje dostawcę. Nowy identyfikator GUID można wygenerować w programie Visual Studio, przechodząc do pozycji Narzędzia Tworzenie> identyfikatora GUID. Ten identyfikator GUID będzie ponownie używany w kilku różnych miejscach w tym przewodniku.

{
  "version": 2,
  "actions": [
    {
      "id": "ExampleAppActionProvider.SendMessage",
      "description": "Send a message",
      "icon": "ms-resource://Files/Assets/StoreLogo.png",
      "usesGenerativeAI": false,
      "inputs": [
        {
          "name": "message",
          "kind": "Text"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "message"
          ],
          "description": "Send message '${message.Text}'"
        }
      ],
      "outputs": [
        {
          "name": "response",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "COM",
        "clsid": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  ]
}

Dodawanie klasy ActionProvider do obsługi operacji akcji

Dostawcy akcji muszą zaimplementować interfejs IActionProvider . Ten interfejs wymaga implementacji pojedynczej metody InvokeAsync, której system używa do wywoływania akcji.

W programie Visual Studio kliknij prawym przyciskiem myszy projekt AppActionProvider w eksploratorze rozwiązań i wybierz pozycję Dodaj>Klasa.
W oknie dialogowym Dodawanie klasy nadaj klasie nazwę "ActionProvider" i kliknij przycisk Dodaj.
W wygenerowany plik ActionProvider.cs zaktualizuj definicję klasy, aby wskazać, że implementuje interfejs IActionProvider .
Oznacz klasę etykietą System.Runtime.InteropServices.GuidAttribute. Jest to używane przez kod aktywacji COM pokazany w dalszej części tego przewodnika. Pamiętaj, aby zaktualizować wartość do wartości określonej w polu invocation.clsid w pliku registration.json.

// AppActionProvider.cs
[System.Runtime.InteropServices.GuidAttribute("00001111-aaaa-2222-bbbb-3333cccc4444")] 
public partial class AppActionProvider : IActionProvider

Implementowanie IActionProvider.InvokeAsync

Metoda InvokeAsync ma zwracany typ IAsyncAction. W tym przykładzie użyto klasy pomocniczej zwracającej zadanie, która jest następnie konwertowana na metodę IAsyncAction z wywołaniem metody rozszerzenia AsAsyncAction . Dodaj następującą definicję metody do klasy AppActionProvider .

// AppActionProvider.cs
public IAsyncAction InvokeAsync(ActionInvocationContext context)
{
    return InvokeAsyncHelper(context).AsAsyncAction();
}

W metodzie pomocnika InvokeAsyncHelper są wykonywane następujące akcje:

ActionInvocationContext.GetInputEntities jest używany do pozyskiwania zestawu jednostek, które są przekazywane jako dane wejściowe na potrzeby akcji.
Dostawca akcji może obsługiwać wiele akcji, więc przed przetworzeniem wartości wejściowych właściwość ActionInvocationContext.ActionId jest oceniana w celu określenia, która akcja jest wywoływana. Identyfikator będzie wartością zadeklarowaną dla akcji w polu id w pliku reisgration.json.
W tym przykładzie istnieje jedna jednostka wejściowa typu TextActionEntity o nazwie "message". Metoda pomocnicza przetwarza dane wejściowe i sprawdza oczekiwaną nazwę.
Po znalezieniu oczekiwanej nazwy jednostki wejściowej jest rzutowana na typ TextEntity , a tekst wiadomości jest pobierany przy użyciu właściwości Text . W tym momencie rzeczywista implementacja działania przyjęłaby ten komunikat wejściowy, przetworzyła go i wygenerowała odpowiedź.
W tym przykładzie zostanie utworzona odpowiedź TextEntity, jak określono w polu outputs w pliku registration.json. Jednostka jest tworzona na podstawie zakodowanego ciągu, a następnie dodawana jako dane wyjściowe przez wywołanie metody SetOutputEntity, przekazując nazwę jednostki wyjściowej i obiekt TextEntity .

Dodaj następującą definicję metody do klasy AppActionProvider .

// AppActionProvider.cs
async Task InvokeAsyncHelper(ActionInvocationContext context)
{
    NamedActionEntity[] inputs = context.GetInputEntities();

    var actionId = context.ActionId;
    switch (actionId)
    {
      case "ExampleActionProvider.SendMessage":
          foreach (NamedActionEntity inputEntity in inputs)
          {
              if (inputEntity.Name.Equals("message", StringComparison.Ordinal))
              {
                
                TextActionEntity entity = (TextActionEntity)(inputEntity.Entity);
                string message = entity.Text;
                
                // TODO: Process the message and generate a response

                string response = "This is the message response"; 
                TextActionEntity result = context.EntityFactory.CreateTextEntity(response);
                context.SetOutputEntity("response", result);

              }

          }

          break;

      default:

          break;

  }

}

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

Kliknij prawym przyciskiem myszy plik Package.appxmanifest i wybierz polecenie Wyświetl kod
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"

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 xmlns="">registration.json</Registration>
        </uap3:Properties>
    </uap3:AppExtension>
</uap3:Extension>
</Extensions>

Zaimplementuj fabrykę klas, która utworzy wystąpienie IActionProvidera na żądanie

Po uruchomieniu aplikacji dostawcy akcji przez system, aplikacja musi wywołać CoRegisterClassObject, aby system mógł utworzyć wystąpienie serwera COM dla implementacji IActionProvider. Ta funkcja wymaga implementacji klasy IClassFactory. W tym przykładzie zaimplementowana jest fabryka klas w samodzielnej klasie pomocniczej.

W programie Visual Studio kliknij prawym przyciskiem myszy projekt ExampleAppActionProvider w eksploratorze rozwiązań i wybierz pozycję Dodaj>Klasa. W oknie dialogowym Dodaj klasę nadaj klasie nazwę "FactoryHelper" i kliknij pozycję Dodaj.

Zastąp zawartość pliku FactoryHelper.cs następującym kodem. Ten kod definiuje interfejs IClassFactory i implementuje dwie metody : CreateInstance i LockServer. Ten kod jest standardowy do implementacji fabryki klas i nie jest specyficzny dla funkcjonalności dostawcy akcji aplikacji, z tym wyjątkiem, że wskazuje, iż tworzony obiekt klasy implementuje interfejs IActionProvider.

// FactoryHelper.cs

using Microsoft.Windows.Widgets.Providers;
using System.Runtime.InteropServices;
using WinRT;

namespace COM
{
    static class Guids
    {
        public const string IClassFactory = "00000001-0000-0000-C000-000000000046";
        public const string IUnknown = "00000000-0000-0000-C000-000000000046";
    }

    /// 
    /// IClassFactory declaration
    /// 
    [ComImport, ComVisible(false), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid(COM.Guids.IClassFactory)]
    internal interface IClassFactory
    {
        [PreserveSig]
        int CreateInstance(IntPtr pUnkOuter, ref Guid riid, out IntPtr ppvObject);
        [PreserveSig]
        int LockServer(bool fLock);
    }

    [ComVisible(true)]
    class WidgetProviderFactory<T> : IClassFactory
    where T : IActionProvider, new()
    {
        public int CreateInstance(IntPtr pUnkOuter, ref Guid riid, out IntPtr ppvObject)
        {
            ppvObject = IntPtr.Zero;

            if (pUnkOuter != IntPtr.Zero)
            {
                Marshal.ThrowExceptionForHR(CLASS_E_NOAGGREGATION);
            }

            if (riid == typeof(T).GUID || riid == Guid.Parse(COM.Guids.IUnknown))
            {
                // Create the instance of the .NET object
                ppvObject = MarshalInspectable<IActionProvider>.FromManaged(new T());
            }
            else
            {
                // The object that ppvObject points to does not support the
                // interface identified by riid.
                Marshal.ThrowExceptionForHR(E_NOINTERFACE);
            }

            return 0;
        }

        int IClassFactory.LockServer(bool fLock)
        {
            return 0;
        }

        private const int CLASS_E_NOAGGREGATION = -2147221232;
        private const int E_NOINTERFACE = -2147467262;

    }
}

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.

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy ikonę projektu i wybierz polecenie Edytuj plik projektu.
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 pozycję Dodaj klasę>. Zmień nazwę pliku na "Program.cs", a następnie kliknij przycisk Dodaj.

W pliku Program.cs pliku wykonywalnego funkcja CoRegisterClassObject jest wywoływana w celu zarejestrowania serwera COM dostawcy działań. Zastąp zawartość Program.cs następującym kodem. Ten kod importuje funkcję CoRegisterClassObject i wywołuje ją, przekazując klasę ActionProviderFactory zdefiniowaną w poprzednim kroku. Pamiętaj, aby zaktualizować deklarację zmiennej CLSID_Factory , aby użyć identyfikatora GUID określonego w pliku registration.json.

// Program.cs

using System.Runtime.InteropServices;
using ComTypes = System.Runtime.InteropServices.ComTypes;
using Microsoft.Windows.Widgets;
using ExampleWidgetProvider;
using COM;
using System;


[DllImport("ole32.dll")]

static extern int CoRegisterClassObject(
            [MarshalAs(UnmanagedType.LPStruct)] Guid rclsid,
            [MarshalAs(UnmanagedType.IUnknown)] object pUnk,
            uint dwClsContext,
            uint flags,
            out uint lpdwRegister);

[DllImport("ole32.dll")] static extern int CoRevokeClassObject(uint dwRegister);

uint cookie;

Guid CLSID_Factory = Guid.Parse("00001111-aaaa-2222-bbbb-3333cccc4444");
CoRegisterClassObject(CLSID_Factory, new ActionProviderFactory<AppActionProvider>(), 0x4, 0x1, out cookie);

Application.Start((p) =>
{
    var context = new DispatcherQueueSynchronizationContext(
        DispatcherQueue.GetForCurrentThread());
    SynchronizationContext.SetSynchronizationContext(context);
    _ = new App();
});

PInvoke.CoRevokeClassObject(cookie);

return 0;

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.