Aan de slag met app-acties in Windows

In dit artikel worden de stappen beschreven voor het maken van app-acties en worden de onderdelen van een app-actieprovider-app beschreven. App-acties zijn afzonderlijke gedragseenheden die een Windows-app kan implementeren en registreren, zodat ze kunnen worden geopend vanuit andere apps en ervaringen, naadloos kunnen worden geïntegreerd in gebruikerswerkstromen. Zie App-acties in Windows-overzicht voor meer informatie over app-acties in Windows.

De IActionProvider-interface is de primaire interface die app-actieproviders gebruiken om te communiceren met het Windows Actions Framework. Microsoft biedt echter het NuGet-pakket Microsoft.AI.Actions waarmee automatisch de IActionProvider-implementatie wordt gegenereerd op basis van .NET-kenmerken in uw code, zodat u sterk getypte klassen kunt maken om uw acties weer te geven. Dit is de aanbevolen manier om een app-actieprovider-app te implementeren en is de techniek die in dit artikel wordt beschreven. Voor sommige edge-casescenario's willen ontwikkelaars mogelijk IActionProvider rechtstreeks implementeren. Zie IActionProvider handmatig implementeren voor meer informatie.

U kunt ook een app-actieprovider implementeren met URI-activering in plaats van COM-activering, hoewel sommige geavanceerdere scenario's, zoals gestreamde tekstreacties van een actie, niet worden ondersteund. Zie URI-start voor App Actions op Windows implementeren voor meer informatie.

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

Een nieuw Windows-app-project maken in Visual Studio

De functie App-acties in Windows wordt ondersteund voor meerdere app-frameworks, maar apps moeten een pakketidentiteit hebben om zich bij het systeem te kunnen registreren. In deze walkthrough wordt een Windows-app Action provider geïmplementeerd in een verpakte C# WinUI 3-bureaublad-app.

1. Maak in Visual Studio een nieuw project.

2. Stel in het dialoogvenster Een nieuw project maken het taalfilter in op 'C#' en het platformfilter op WinUI en selecteer vervolgens de projectsjabloon 'Lege app, verpakt (WinUI 3 in desktop)'.

3. Geef het nieuwe project de naam ExampleAppActionProvider.

4. Wanneer het project wordt geladen, klikt u in Solution Explorer met de rechtermuisknop op de projectnaam en selecteert u Eigenschappen. Op de pagina Algemeen, schuif omlaag naar Doelbesturingssysteem en selecteer "Windows". Selecteer voor doelbesturingssystemen en ondersteund besturingssysteemversie versie 10.0.26100.0 of hoger.

5. Als u uw project wilt bijwerken ter ondersteuning van de Action Provider-API's, klikt u in Solution Explorer met de rechtermuisknop op de projectnaam en selecteert u Projectbestand bewerken. Voeg in PropertyGroup het volgende Element WindowsSdkPackageVersion toe.

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Voeg een verwijzing toe naar het Microsoft.AI.Actions NuGet-pakket

In dit artikel maakt het voorbeeld gebruik van de codegeneratiefuncties van het Microsoft.AI.Actions NuGet-pakket.

1. Klik in Solution Explorer met de rechtermuisknop op de projectnaam en selecteer NuGet-pakketten beheren...
2. Zorg ervoor dat u zich op het tabblad Bladeren bevindt en zoek naar Microsoft.AI.Actions.
3. Selecteer Microsoft.AI.Actions en klik op Installeren.

Een ActionProvider-klasse toevoegen om actiebewerkingen af te handelen

In de volgende sectie ziet u hoe u een aangepaste actieproviderklasse implementeert die gebruikmaakt van .NET-kenmerken van de naamruimte Microsoft.AI.Actions.Annotations om de onderdelen van een actie te identificeren. Het Microsoft.AI.Actions NuGet-pakket maakt gebruik van deze kenmerken om automatisch een onderliggende implementatie van de IActionProvider-interface te genereren. Hierdoor kunt u sterk getypte klassen maken voor acties zonder dat u rechtstreeks hoeft te communiceren met de API's van de actieprovider op laag niveau.

1. Klik in Visual Studio met de rechtermuisknop op het ExampleAppActionProvider-project in de Solution Explorer en selecteer Toevoegen->Klasse.
2. Geef in het dialoogvenster Klasse toevoegen de klasse 'MyActionProvider' een naam en klik op Toevoegen.
3. Vervang de inhoud van MyActionProvider.cs door de volgende 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 Task<string> ProcessMessageAsync(string contact, string? message)
        {
            if (message != null)
            {
                return Task.FromResult($"Processed {contact}, {message}");
            }
            else
            {
                return Task.FromResult($"Processed {contact}");
            }
        }
    }
}

De functies voor het genereren van code van het Microsoft.AI.Actions NuGet-pakket gebruiken .NET-attributes in uw code om de details te bepalen van de acties die uw app biedt. In dit voorbeeld worden de volgende kenmerken gebruikt:

De meeste ondersteunde kenmerken worden rechtstreeks toegewezen aan velden in het JSON-bestand met de actiedefinitie dat door het systeem wordt gebruikt om acties te detecteren. Zoals verderop in dit artikel wordt weergegeven, gebruikt de codegeneratiefunctie Microsoft.AI.Actions deze kenmerken om automatisch het JSON-bestand met de actiedefinitie te genereren tijdens de build. Wanneer u de klasse van de actieprovider bijwerkt door deze kenmerken toe te voegen of te wijzigen, genereert het NuGet-pakket het actiedefinitiebestand opnieuw om uw wijzigingen weer te geven. Zie het JSON-schema voor actiedefinities voor App Actions in Windows voor meer informatie over het JSON-bestand voor de actiedefinitie.

Zie het readme-bestand voor het Microsoft.AI.Actions NuGet-pakket voor een lijst met ondersteunde kenmerken.

Het manifestbestand van het app-pakket bijwerken

Het bestand Package.appmanifest bevat de details van het MSIX-pakket voor een app. Als u door het systeem wilt worden geregistreerd als een Windows-app Action-provider, moet de app een uap3:Extension-element bevatten met de categorie ingesteld op 'windows.appExtension'. Dit element wordt gebruikt om de locatie op te geven van het JSON-bestand van de app-actie waarmee de acties van de app worden gedefinieerd. U moet ook opgeven com.microsoft.windows.ai.actions als de naam voor het element uap3:AppExtension . Zie voor meer informatie over de manifestindeling van het app-pakket van de actieprovider, de XML-indeling van het pakketmanifest voor Windows-app Action-provider.

In het voorbeeld in deze handleiding wordt COM-activering gebruikt om de actieprovider van de app te starten. Als u COM-activering wilt inschakelen, gebruikt u het element com2:Extension in het manifest van het app-pakket. De waarde invocation.clsid die is opgegeven in het JSON-bestand voor de actiedefinitie moet overeenkomen met de klasse-id die is opgegeven in het com:Class-element in het manifest van het app-pakket.

1. Klik met de rechtermuisknop op het bestand Package.appxmanifest en selecteer Code weergeven.
2. Voeg de volgende naamruimten toe aan het pakketelement in de hoofdmap van het bestand.

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. Voeg het volgende uitbreidingselement toe in het toepassingselement en na het element 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>

Een aangepaste Main-methode implementeren

In de standaardprojectsjabloon wordt het ingangspunt voor de main-methode automatisch gegenereerd door de compiler. In dit voorbeeld wordt de automatische generatie van Main uitgeschakeld, zodat de benodigde activeringscode kan worden uitgevoerd bij het opstarten.

1. Klik in Solution Explorer met de rechtermuisknop op het projectpictogram en selecteer Projectbestand bewerken.
2. Voeg in het element PropertyGroup het volgende onderliggende element toe om de automatisch gegenereerde hoofdfunctie uit te schakelen.

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

Klik vervolgens in Solution Explorer met de rechtermuisknop op het projectpictogram en selecteer Add->New Item. Selecteer codebestand. Wijzig de bestandsnaam in 'Program.cs' en klik op Toevoegen.

In het bestand Program.cs voegen we een coderegel toe die ervoor zorgt dat het NuGet-pakket actions automatisch de COM-serveractivering genereert waarmee het systeem de actieprovider kan aanroepen.

ComServerRegisterActions.RegisterActions();

De rest van de code in de Main-methode in dit voorbeeld is alleen de standaardcode om een WinUI-app te starten. Vervang de inhoud van Program.cs door de volgende 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();
        });
    }
}

Configuratie-eigenschappen van Microsoft.AI.Actions toevoegen aan het projectbestand

De functie voor het genereren van code van het Microsoft.AI.Actions NuGet-pakket maakt gebruik van eigenschapswaarden die zijn gedefinieerd in het projectbestand om het gedrag ervan tijdens de build te configureren. Voeg de volgende eigenschappen toe in het eerste PropertyGroup-element in uw .csproj-bestand.

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

In de volgende tabel worden deze eigenschappen beschreven.

Updates uitvoeren op basis van het gegenereerde registration.json-bestand

Nadat u het project hebt gebouwd, kunt u het gegenereerde registration.json bestand weergeven in de map Assets in Solution Explorer.

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

De CLSID bijwerken in het manifestbestand van het app-pakket

De eerste keer dat u uw actieprovider-app bouwt, krijgt u de waarschuwing: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Dit komt doordat het automatisch gegenereerde registration.json bestand de clsid van de COM-server declareert voor de actie met een unieke GUID. Nadat u het project hebt gebouwd, opent u het registration.json bestand en ziet u dat het bestand declareert dat de actie COM-activering gebruikt en een clsid-waarde opgeeft. Vervang de waarde van het kenmerk Id in het com:Class-element in het manifestbestand van het app-pakket om de gegenereerde GUID te gebruiken.

Als de clsid-waarde in het gegenereerde registration.json bestand bijvoorbeeld is 11112222-bbbb-3333-cccc-4444dddd5555, ziet het bijgewerkte com:Class-element er als volgt uit:

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

Toegestane app-oproepers

Het veld allowedAppInvokers in het JSON-schema van de actiedefinitie geeft een lijst met Application User Model ID's (AppUserModelIDs) op waarmee de actie kan worden gevonden via een aanroep naar GetActionsForInputs of GetAllActions. Wildcards worden ondersteund. *komt overeen met alle AppUserModelIDs. Dit wordt aanbevolen voor de meeste acties, tenzij er een specifieke reden is om de aanroepers te beperken die een actie kunnen aanroepen. Als allowedAppInvokers wordt weggelaten of een lege lijst is, kunnen er geen apps de actie ontdekken. Zie Application User Model IDs voor meer informatie over AppUserModelIDs.

In het volgende voorbeeld ziet u de aanbevolen procedure voor het instellen van allowedAppInvokers, zodat alle apps de bijbehorende actie kunnen ontdekken.

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

De windows-app-actie testen

Met de App Actions Testing Playground-app kunt u de registratie en functionaliteit van uw App Action-app valideren. Zie App Actions Testing Playground voor meer informatie over het gebruik van dit hulpprogramma.