Kom igång med App Actions i Windows

Den här artikeln beskriver stegen för att skapa appåtgärder och beskriver komponenterna i en appåtgärdsproviderapp. Appåtgärder är enskilda beteendeenheter som en Windows-app kan implementera och registrera så att de kan nås från andra appar och upplevelser och smidigt integreras i användararbetsflöden. Mer information om appåtgärder i Windows finns i Appåtgärder i Översikt över Windows.

Gränssnittet IActionProvider är det primära gränssnittet som providers för appåtgärder använder för att kommunicera med Windows-åtgärdsramverket. Microsoft tillhandahåller dock NuGet-paketet Microsoft.AI.Actions som automatiskt genererar IActionProvider-implementeringen baserat på .NET-attribut i koden, så att du kan göra starkt skrivna klasser för att representera dina åtgärder. Det här är det rekommenderade sättet att implementera en app för leverantör av appåtgärder och är den teknik som beskrivs i den här artikeln. För vissa scenarier med kantfall kanske utvecklare vill implementera IActionProvider direkt. Mer information finns i Implementera IActionProvider manuellt.

Du kan också implementera en app action provider med URI-startaktivering i stället för COM-aktivering, även om vissa mer avancerade scenarier, till exempel strömmande textsvar från en åtgärd, inte stöds. Mer information finns i Implementera URI-start för appåtgärder i Windows.

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

Skapa ett nytt Windows-appprojekt i Visual Studio

Funktionen Appåtgärder i Windows stöds för flera appramverk, men appar måste ha paketidentitet för att kunna registrera sig i systemet. Den här genomgången implementerar en Windows App Action-provider i en paketerad C# WinUI 3-skrivbordsapp.

1. Skapa ett nytt projekt i Visual Studio.

2. I dialogrutan Skapa ett nytt projekt anger du språkfiltret till "C#" och plattformsfiltret till "WinUI" och väljer sedan projektmallen "Tom app, paketerad (WinUI 3 i desktop)".

3. Ge det nya projektet namnet "ExampleAppActionProvider".

4. När projektet läses in, i Prieskumník riešení högerklicka på projektnamnet och välj Egenskaper. På sidan Allmänt rullar du ned till Måloperativsystem och väljer "Windows". Välj version 10.0.26100.0 eller senare för Måloperativsystemversion och Operativsystemversion som stöds.

5. Om du vill uppdatera projektet för att stödja API:erna för åtgärdsprovidern högerklickar du på projektnamnet i Prieskumník riešení och väljer Redigera projektfil. I PropertyGroup lägger du till följande WindowsSdkPackageVersion-element .

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Lägg till en referens till NuGet-paketet Microsoft.AI.Actions

I exemplet i den här artikeln används kodgenereringsfunktionerna i Microsoft.AI.Actions NuGet-paket.

1. Högerklicka på projektnamnet i Prieskumník riešení och välj Hantera NuGet-paket...
2. Kontrollera att du är på fliken Bläddra och sök efter Microsoft.AI.Actions.
3. Välj Microsoft.AI.Actions och klicka på Installera.

Lägg till en ActionProvider-klass för att hantera åtgärder

Följande avsnitt visar hur du implementerar en anpassad åtgärdsproviderklass som använder .NET-attribut från namnområdet Microsoft.AI.Actions.Annotations för att identifiera komponenterna i en åtgärd. Microsoft. AI. Actions NuGet-paketet använder dessa attribut för att automatiskt generera en underliggande implementering av gränssnittet IActionProvider. På så sätt kan du skapa starkt typade klasser för åtgärder utan att behöva interagera direkt med lågnivåleverantörens åtgärds-API:er.

1. I Visual Studio högerklickar du på projektet ExampleAppActionProvider i Prieskumník riešení och väljer Lägg till>klass.
2. I dialogrutan Lägg till klass ger du klassen namnet "MyActionProvider" och klickar på Lägg till.
3. Ersätt innehållet i MyActionProvider.cs med följande kod.

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

Kodgenereringsfunktionerna i NuGet-paketet Microsoft.AI.Actions använder .NET-attribut i koden för att fastställa information om de åtgärder som appen tillhandahåller. I det här exemplet används följande attribut:

De flesta attribut som stöds mappar direkt till fält i JSON-filen för åtgärdsdefinitionen som systemet använder för att identifiera åtgärder. Som visas senare i den här artikeln använder kodgenereringsfunktionen Microsoft.AI.Actions dessa attribut för att automatiskt generera åtgärdsdefinitionens JSON-fil vid byggtiden. När du uppdaterar klassen för åtgärdsprovidern och lägger till eller ändrar dessa attribut återskapar NuGet-paketet åtgärdsdefinitionsfilen så att den återspeglar dina ändringar. Mer information om JSON-filen för åtgärdsdefinition finns i JSON-schema för åtgärdsdefinition för appåtgärder i Windows.

En lista över attribut som stöds finns i readme-filen för Microsoft.AI.Actions NuGet-paket.

Uppdatera apppaketets manifestfil

Filen Package.appmanifest innehåller information om MSIX-paketet för en app. För att kunna registreras av systemet som en Windows App Action-provider måste appen innehålla ett uap3:Extension-element med kategorin inställd på "windows.appExtension". Det här elementet används för att ange platsen för JSON-filen appåtgärd som definierar appens åtgärder. Du måste också ange com.microsoft.windows.ai.actions som Namn för elementet uap3:AppExtension . Mer information om manifestformatet för åtgärdsproviderns apppaket finns i XML-format för Paketmanifest för Windows App Action Provider.

I exemplet i den här genomgången används COM-aktivering för att starta appåtgärdsprovidern. Om du vill aktivera COM-aktivering använder du com2:Extension-elementet i apppaketmanifestet. Värdet invocation.clsid som anges i JSON-filen för åtgärdsdefinition måste matcha klass-ID:t som anges i com:Class-elementet i apppaketmanifestet.

1. Högerklicka på filen Package.appxmanifest och välj Visa kod.
2. Lägg till följande namnområden i paketelementet i filens rot.

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. Lägg till följande tilläggselement i programelementet och efter elementet 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>

Implementera en anpassad Main-metod

I standardprojektmallen genereras startpunkten för Main-metoden automatiskt av kompilatorn. Det här exemplet inaktiverar autogenereringen av Main så att den nödvändiga aktiveringskoden kan köras vid start.

1. Högerklicka på projektikonen i Prieskumník riešení och välj Redigera projektfil.
2. I elementet PropertyGroup lägger du till följande underordnade element för att inaktivera den automatiskt genererade huvudfunktionen.

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

Högerklicka sedan på projektikonen i Prieskumník riešení och välj Lägg till->Nytt objekt. Välj Kodfil. Ändra filnamnet till "Program.cs" och klicka på Lägg till.

I filen Program.cs lägger vi till en kodrad som gör att nuget-paketet för åtgärder automatiskt genererar COM-serveraktiveringen som gör att systemet kan anropa åtgärdsprovidern.

ComServerRegisterActions.RegisterActions();

Resten av koden i Main-metoden i det här exemplet är bara standardkoden för att starta en WinUI-app. Ersätt innehållet i Program.cs med följande kod.

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

Lägg till konfigurationsegenskaper för Microsoft.AI.Actions i projektfilen

Funktionen för kodgenerering i Microsoft.AI.Actions NuGet-paketet använder egenskapsvärden som definierats i projektfilen för att konfigurera dess beteende vid bygget. Lägg till följande egenskaper i det första PropertyGroup-elementet i .csproj-filen.

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

I följande tabell beskrivs dessa egenskaper.

Gör uppdateringar baserat på den genererade registration.json-filen

När du har skapat projektet kan du visa den genererade registration.json filen i mappen Assets i Prieskumník riešení.

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

Uppdatera CLSID i apppaketets manifestfil

Första gången du skapar din åtgärdsproviderapp får du varningen: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Det beror på att den automatiskt genererade registration.json filen deklarerar clsid för COM-servern för åtgärden med ett unikt GUID. När du har byggt projektet öppnar du registration.json filen och noterar att filen deklarerar att åtgärden använder COM-aktivering och anger ett clsid-värde. Ersätt värdet för ID-attributet i com:Class-elementet i din apppaketmanifestfil för att använda det genererade GUID:t.

Om clsid-värdet i den genererade registration.json filen till exempel är 11112222-bbbb-3333-cccc-4444dddd5555, ser det uppdaterade com:Class-elementet ut så här:

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

Appar som får anropa

Fältet allowedAppInvokers i JSON-schemat för åtgärdsdefinitionen anger en lista över programanvändarmodell-ID:n (AppUserModelIDs) som kan identifiera åtgärden via ett anrop till GetActionsForInputs eller GetAllActions. Jokertecken stöds. "*" kommer att matcha alla AppUserModelIDs. Detta rekommenderas för de flesta åtgärder, såvida det inte finns en specifik anledning att begränsa de anropare som kan anropa en åtgärd. Om allowedAppInvokers utelämnas eller är en tom lista kan inga appar upptäcka åtgärden. Mer information om AppUserModelIDs finns i Application User Model IDs.

I följande exempel visas den rekommenderade metoden att ange allowedAppInvokers så att alla appar kan upptäcka den associerade åtgärden.

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

Testa Windows-appåtgärden

Med appen App Actions Testing Playground kan du verifiera registreringen och funktionerna i din Windows App Action-providerapp. Mer information om hur du använder det här verktyget finns i Testlekplats för appåtgärder.