Erste Schritte mit App-Aktionen unter Windows

In diesem Artikel werden die Schritte zum Erstellen von App-Aktionen beschrieben und die Komponenten einer App-Aktion-Anbieter-App beschrieben. App-Aktionen sind einzelne Verhaltenseinheiten, die eine Windows-App implementieren und registrieren kann, sodass sie von anderen Apps und Erfahrungen aus aufgerufen werden können, nahtlos in Benutzerworkflows integriert werden können. Weitere Informationen zu App-Aktionen unter Windows finden Sie unter App-Aktionen unter Windows – Übersicht

Die IActionProvider-Schnittstelle ist die primäre Schnittstelle, die App-Aktionsanbieter für die Kommunikation mit dem Windows-Aktionsframework verwenden. Microsoft stellt jedoch das Microsoft.AI.Actions NuGet-Paket bereit, das die IActionProvider-Implementierung basierend auf .NET-Attributen in Ihrem Code automatisch generiert, sodass Sie stark typierte Klassen erstellen können, um Ihre Aktionen darzustellen. Dies ist die empfohlene Methode zum Implementieren einer App-App für Aktionsanbieter und ist die in diesem Artikel beschriebene Technik. Für einige Edgefallszenarien möchten Entwickler möglicherweise IActionProvider direkt implementieren. Weitere Informationen finden Sie unter Manuelles Implementieren von IActionProvider.

Sie können einen App-Aktionsanbieter auch mithilfe der URI-Startaktivierung anstelle der COM-Aktivierung implementieren, obwohl einige komplexere Szenarien, z. B. Streamingtextantworten aus einer Aktion, nicht unterstützt werden. Weitere Informationen finden Sie unter Implementieren des URI-Starts für App-Aktionen unter Windows.

Automatische Abhängigkeitsinstallation (empfohlen)

1. Führen Sie den folgenden Befehl im Terminal aus (unabhängig davon, ob Sie C#- oder C++-Entwickler sind). Dadurch wird eine WinGet-Konfigurationsdatei ausgeführt, die die folgenden Aufgaben ausführt (abhängigkeiten, die bereits installiert sind, werden übersprungen):

   • Aktiviert den Entwicklermodus.
   • Installiert Visual Studio Community Edition
   • Umfassen Windows-App-Entwicklungs-Arbeitslast und entweder C++- oder .NET/C#-Arbeitslasten
   • Einbeziehen der MSIX Packaging-Tools

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

Manuelle Installation der Abhängigkeit

• Installieren von Visual Studio 2022 (v17.6+)
  • Download 2022 Community
  • Download 2022 Professional
  • Download 2022 Enterprise
• Fügen Sie C++-Workload oder .NET-Workload für die C#-Entwicklung ein.
• Stellen Sie sicher, dass MSIX Packaging Tools unter .NET Desktopentwicklung ausgewählt ist.
• Stellen Sie sicher, dass die Windows-Anwendungsentwicklung ausgewählt ist.
• Stellen Sie sicher, dass die Entwicklung von Windows-UI-Anwendungen ausgewählt ist.

Weitere Informationen zum Verwalten von Workloads in Visual Studio finden Sie unter Ändern von Workloads, Komponenten und Language Packs in Visual Studio.

Erstellen eines neuen Windows-App-Projekts in Visual Studio

Das Feature "App-Aktionen unter Windows" wird für mehrere App-Frameworks unterstützt, apps müssen jedoch über paketidentität verfügen, um sich beim System registrieren zu können. Diese exemplarische Vorgehensweise implementiert einen Windows-App-Aktionsanbieter in einer verpackten C#WinUI 3-Desktop-App.

1. Erstellen Sie in Visual Studio ein neues Projekt.

2. Legen Sie im Dialogfeld " Neues Projekt erstellen " den Sprachfilter auf "C#" und den Plattformfilter auf "WinUI" fest, und wählen Sie dann die Projektvorlage "Leere App, Verpackt (WinUI 3 in Desktop)" aus.

3. Nennen Sie das neue Projekt "ExampleAppActionProvider".

4. Wenn das Projekt geladen wird, klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektnamen, und wählen Sie Eigenschaftenaus. Scrollen Sie auf der Seite Allgemein nach unten zu Zielbetriebssystem und wählen Sie "Windows" aus. Wählen Sie für die Zielbetriebssystemversion und die unterstützte Betriebssystemversion Version 10.0.26100.0 oder höher aus.

5. Wenn Sie Ihr Projekt aktualisieren möchten, um die Aktionsanbieter-APIs zu unterstützen, klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektnamen, und wählen Sie " Projektdatei bearbeiten" aus. Fügen Sie in PropertyGroup das folgende WindowsSdkPackageVersion-Element hinzu.

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Hinzufügen eines Verweises auf das Nuget-Paket "Microsoft.AI.Actions"

Im Beispiel in diesem Artikel werden die Codegenerierungsfeatures des Nuget-Pakets "Microsoft.AI.Actions" verwendet.

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektnamen, und wählen Sie " NuGet-Pakete verwalten" aus...
2. Stellen Sie sicher, dass Sie sich auf der Registerkarte " Durchsuchen " befinden und nach "Microsoft.AI.Actions" suchen.
3. Wählen Sie "Microsoft.AI.Actions" aus, und klicken Sie auf "Installieren".

Hinzufügen einer ActionProvider-Klasse zum Behandeln von Aktionsvorgängen

Im folgenden Abschnitt wird gezeigt, wie Sie eine benutzerdefinierte Aktionsanbieterklasse implementieren, die .NET-Attribute aus dem Namespace "Microsoft.AI.Actions.Annotations " verwendet, um die Komponenten einer Aktion zu identifizieren. Das NuGet-Paket "Microsoft.AI.Actions" verwendet diese Attribute, um automatisch eine zugrunde liegende Implementierung der IActionProvider-Schnittstelle zu generieren. Auf diese Weise können Sie stark typierte Klassen für Aktionen erstellen, ohne direkt mit den ApIs des Aktionsanbieters auf niedriger Ebene interagieren zu müssen.

1. Klicken Sie in Visual Studio mit der rechten Maustaste auf das ExampleAppActionProvider-Projekt im -Projektmappen-Explorer und wählen Sie Hinzufügen ->Klasseaus.
2. Nennen Sie im Dialogfeld " Klasse hinzufügen " die Klasse "MyActionProvider", und klicken Sie auf "Hinzufügen".
3. Ersetzen Sie den Inhalt durch MyActionProvider.cs den folgenden Code.

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

Die Codegenerierungsfeatures des Nuget-Pakets "Microsoft.AI.Actions" verwenden .NET-Attribute in Ihrem Code, um die Details der von Ihrer App bereitgestellten Aktionen zu ermitteln. In diesem Beispiel werden die folgenden Attribute verwendet:

Merkmal	Description
ActionProviderAttribute	Dieses Attribut identifiziert eine Klasse, die eine oder mehrere Aktionen implementiert.
WindowsActionAttribute	Dieses Attribut stellt Metadaten zu einer Aktion bereit, z. B. die lesbare Beschreibung der App und eine Symboldatei, die Verbraucher von Aktionen benutzern anzeigen können.
WindowsActionInputCombinationAttribute	Dieses Attribut deklariert eine Reihe von Eingabeentitäten, die eine Aktion als Eingabe akzeptieren kann. Eine einzelne Aktion kann mehrere Kombinationen von Eingaben unterstützen.
EntityAttribute	Gibt an, dass eine Klasse eine ActionEntity darstellt.

Die meisten unterstützten Attribute werden direkt den Feldern in der JSON-Datei der Aktionsdefinition zugeordnet, die vom System zum Ermitteln von Aktionen verwendet wird. Wie weiter unten in diesem Artikel gezeigt wird, verwendet das Microsoft.AI.Actions-Codegenerierungsfeature diese Attribute, um die JSON-Datei der Aktionsdefinition automatisch zur Erstellungszeit zu generieren. Wenn Sie Ihre Aktionsanbieterklasse aktualisieren, diese Attribute hinzufügen oder ändern, generiert das Nuget-Paket die Aktionsdefinitionsdatei neu, um Ihre Änderungen widerzuspiegeln. Weitere Informationen zur JSON-Datei der Aktionsdefinition finden Sie unter JSON-Schema der Aktionsdefinition für App-Aktionen unter Windows.

Eine Liste der unterstützten Attribute finden Sie in der Infodatei für das Nuget-Paket "Microsoft.AI.Actions ".

Aktualisieren der App-Paketmanifestdatei

Die Datei "Package.appmanifest" enthält die Details des MSIX-Pakets für eine App. Um vom System als Windows App Action-Anbieter registriert zu werden, muss die App ein uap3:Extension-Element enthalten, wobei die Kategorie auf "windows.appExtension" festgelegt ist. Dieses Element wird verwendet, um den Speicherort der JSON-Datei "App-Aktion" anzugeben, die die Aktionen der App definiert. Sie müssen auch als Name für das uap3:AppExtension-Element angebencom.microsoft.windows.ai.actions. Weitere Informationen zum Manifestformat des App-Pakets des Aktionsanbieters finden Sie im XML-Format des Paketmanifests des Windows-App-Aktionsanbieters.

Im Beispiel dieser Anleitung wird die COM-Aktivierung zum Starten des App-Aktionsanbieters verwendet. Verwenden Sie zum Aktivieren der COM-Aktivierung das Com2:Extension-Element im App-Paketmanifest. Der in der JSON-Datei der Aktionsdefinition angegebene Wert " invocation.clsid " muss mit der Klassen-ID übereinstimmen, die im com:Class-Element im App-Paketmanifest angegeben ist.

1. Klicken Sie mit der rechten Maustaste auf die Datei "Package.appxmanifest", und wählen Sie "Code anzeigen" aus.
2. Fügen Sie dem Package-Element im Stammverzeichnis der Datei die folgenden Namespaces hinzu.

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. Fügen Sie das folgende Extensions-Element innerhalb des Application-Elements und nach dem VisualElements-Element hinzu.

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

Implementieren einer benutzerdefinierten Main-Methode

In der Standardprojektvorlage wird der Einstiegspunkt der Main-Methode automatisch vom Compiler generiert. In diesem Beispiel wird die automatische Generierung von Main deaktiviert, sodass der erforderliche Aktivierungscode beim Start ausgeführt werden kann.

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projektsymbol, und wählen Sie "Projektdatei bearbeiten" aus.
2. Fügen Sie im PropertyGroup-Element das folgende untergeordnete Element hinzu, um die automatisch generierte Hauptfunktion zu deaktivieren.

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

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projektsymbol, und wählen Sie "Neues Element hinzufügen>" aus. Wählen Sie "Codedatei" aus. Ändern Sie den Dateinamen in "Program.cs", und klicken Sie auf "Hinzufügen".

In der datei Program.cs fügen wir eine Codezeile hinzu, die dazu führt, dass das Aktions-Nuget-Paket die COM-Serveraktivierung automatisch generiert, mit der das System den Aktionsanbieter aufrufen kann.

ComServerRegisterActions.RegisterActions();

Der rest des Codes in der Main-Methode in diesem Beispiel ist nur der Codebausteine zum Starten einer WinUI-App. Ersetzen Sie den Inhalt von "Program.cs" durch den folgenden Code.

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

Hinzufügen von Konfigurationseigenschaften von Microsoft.AI.Actions zur Projektdatei

Das Codegenerierungsfeature des Nuget-Pakets "Microsoft.AI.Actions" verwendet eigenschaftswerte, die in der Projektdatei definiert sind, um sein Verhalten zur Erstellungszeit zu konfigurieren. Fügen Sie die folgenden Eigenschaften innerhalb des ersten PropertyGroup-Elements in der CSPROJ-Datei hinzu.

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

In der folgenden Tabelle werden diese Eigenschaften beschrieben.

Eigentum	Description
GenerateActionRegistrationManifest	Wenn dieser Wert auf "true " festgelegt ist, generiert das Aktionspaket automatisch eine JSON-Datei mit Aktionsdefinitionen basierend auf den .NET-Attributen in ihrer Klassendefinition des Aktionsanbieters. Beachten Sie, dass manuelle Änderungen, die Sie an der generierten Aktionsdefinitionsdatei vornehmen, immer dann überschrieben werden, wenn Sie das Projekt erstellen. Wenn Sie also manuelle Änderungen beibehalten müssen, die Sie vorgenommen haben, können Sie diesen Wert auf "false" festlegen.
ActionRegistrationManifest	Der paketrelative Pfad zur JSON-Datei der automatisch generierten Aktionsdefinition. Beachten Sie, dass das System in dem ordner sucht, der im PublicFolder-Attribut des uap3:AppExtension-Elements in der App-Paketmanifestdatei angegeben ist. Stellen Sie daher sicher, dass der Pfad für diese Eigenschaft und der öffentliche Ordner, der in der Manifestdatei deklariert ist, übereinstimmen.
GenerateActionsWinRTComServer	Legen Sie diesen Wert auf "true " fest, um die automatische Generierung von COM-Serveraktivierungscode aus dem Aufruf "ComServerRegisterActions.RegisterActions " in diesem Artikel zu Program.cs aktivieren. Wenn dieser Wert auf "false " festgelegt ist, müssen Sie ihre eigene COM-Serveraktivierung implementieren.
RootNamespace	Legt den Stammnamespace des automatisch generierten Codes fest, damit Sie über Ihren eigenen Code darauf zugreifen können.

Aktualisierungen basierend auf der generierten registration.json Datei vornehmen

Nach dem Erstellen des Projekts können Sie die generierte registration.json Datei im Ordner "Assets " im Projektmappen-Explorer anzeigen.

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

Aktualisieren der CLSID in der App-Paketmanifestdatei

Beim ersten Erstellen Der App für Aktionsanbieter erhalten Sie die Warnung: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Dies liegt daran, dass die automatisch generierte registration.json Datei die CLSID des COM-Servers für die Aktion mit einer eindeutigen GUID deklariert. Öffnen Sie nach dem Erstellen des Projekts die registration.json Datei, und beachten Sie, dass die Datei deklariert, dass die Aktion COM-Aktivierung verwendet und einen clsid-Wert angibt. Ersetzen Sie den Wert des Id-Attributs im com:Class-Element in ihrer App-Paketmanifestdatei, um die generierte GUID zu verwenden.

Wenn beispielsweise der Clsid-Wert in der generierten registration.json Datei lautet 11112222-bbbb-3333-cccc-4444dddd5555, würde das aktualisierte com:Class-Element wie folgt aussehen:

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

Zugelassene App-Aufrufer

Ein neues Feld, das dem JSON-Schema der Aktionsdefinition hinzugefügt wurde, ist allowedAppInvokers , das eine Liste der Anwendungsbenutzermodell-IDs (AppUserModelIDs) angibt, die die Aktion über einen Aufruf von GetActionsForInputs oder GetAllActions ermitteln können. Platzhalter werden unterstützt. "*" entspricht allen AppUserModelIDs. Dies wird für die meisten Aktionen empfohlen, es sei denn, es gibt einen bestimmten Grund, die Aufrufer einzuschränken, die eine Aktion aufrufen können. Wenn allowedAppInvokers ausgelassen wird oder eine leere Liste ist, können keine Apps die Aktion ermitteln. Weitere Informationen zu AppUserModelIDs finden Sie unter Anwendungsbenutzermodell-IDs.

Das folgende Beispiel zeigt die empfohlene Vorgehensweise zum Festlegen von allowedAppInvokers , damit alle Apps die zugeordnete Aktion ermitteln können.

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

Von Bedeutung

In der aktuellen Version von Microsoft.AI.Actions wird allowedAppInvokers immer dann überschrieben, wenn die Aktionsdefinitionsdatei neu generiert wird. Nachdem Sie "allowedAppInvokers " zur JSON-Datei der Aktionsdefinition hinzugefügt haben, sollten Sie "GenerateActionRegistrationManifest " auf "false " in Der Projektdatei festlegen. Wenn Sie Ihren Code ändern und die JSON-Dateigenerierung erneut aktivieren müssen, müssen Sie "allowedAppInvokers " wieder zur Datei hinzufügen und die Generierung von JSON-Dateien erneut deaktivieren.

Testen der Aktion in der Windows-App

Mit der App-Aktionen-Test-Playground-App können Sie die Registrierung und Funktionalität Ihrer Windows App Action-Anbieter-App überprüfen. Weitere Informationen zur Verwendung dieses Tools finden Sie unter App Actions Testing Playground.