Implementieren des URI-Starts für 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).

Aktionsanbieter-Apps können implementiert werden, um die COM-Aktivierung oder die URI-Startaktivierung zu verwenden. URI-Startaktionen unterstützen keine erweiterten Aktionsfeatures, z. B. das Anzeigen der Benutzeroberfläche im Kontext oder beim Streamen von Textergebnissen, aber die Implementierung ist sehr einfach und kann die beste Wahl für Aktionen sein, die nur aus einer einzigen Anforderung und Antwort bestehen.

Anbieter-Apps, die die COM-Aktivierung verwenden, implementieren die IActionProvider-Schnittstelle zum Behandeln von Aktionsaufrufen. Diese Methode ermöglicht erweiterte Aktionsfeatures wie die Unterstützung für Streamingtext, erfordert jedoch mehr Code als die Verwendung der VSIX-Erweiterung für Windows-App-Aktionen. Informationen zur Verwendung der COM-Aktivierung in einem App-Anbieter finden Sie unter "Erste Schritte mit App-Aktionen unter Windows".

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

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

Erstellen eines neuen Windows-App-Projekts in Visual Studio

Das Feature "App-Aktionen" wird für mehrere App-Frameworks und -Sprachen unterstützt, aber Apps müssen paketidentitäten haben, 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 "WinUI Blank App (Paket)" 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 "Eigenschaften" aus. Scrollen Sie auf der Seite "Allgemein " nach unten zum 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. Um das Projekt zur Unterstützung der Aktionsanbieter-APIs zu aktualisieren, 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"

Mit dem Nuget-Paket "Microsoft.AI.Actions" können Sie die Laufzeit der App-Aktionen initialisieren, die APIs zum Erstellen der Entitätsobjekte bereitstellt, die als Eingaben und Ausgaben von App-Aktionen übergeben werden.

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 JSON-Datei mit Aktionsdefinition

Aktionsanbieter-Apps müssen eine Aktionsdefinitionsdatei bereitstellen, die die von der App implementierten Aktionen definiert. Diese Datei enthält Informationen wie den eindeutigen Bezeichner und die Beschreibung für jede Aktion sowie die Namen und Typen von Eingaben und Ausgaben, die jede Aktion unterstützt. Weitere Informationen zum JSON-Dateiformat der App-Aktion finden Sie unter JSON-Schema der Aktionsdefinition für Windows-App-Aktionsanbieter.

In diesem Beispiel wird eine Aktion namens "SendMessage" definiert, die eine einzelne Textentität als Eingabe akzeptiert und eine einzelne TextEntity als Ausgabe zurückgibt. Zusätzlich zum Definieren von Aktionen gibt die JSON-Datei auch an, ob die Aktionsanbieter-App mithilfe der COM-Aktivierung oder über den URI-Start gestartet werden soll. In diesem Beispiel wird die URI-Aktivierung verwendet. Das URI-Schema urilaunchaction-protocol wird in einem späteren Schritt in dieser exemplarischen Vorgehensweise registriert.

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Assets Ordner, und wählen Sie "Neues Element hinzufügen>" aus.
2. Wählen Sie im Dialogfeld " Neues Element hinzufügen " die Option "Textdatei" aus. Nennen Sie die neue Datei "registration.json", und klicken Sie auf "OK".
3. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die registration.json Datei, und wählen Sie "Eigenschaften" aus. Legen Sie im Eigenschaftenbereich die Buildaktion auf "Inhalt" fest, und legen Sie "In Ausgabeverzeichnis kopieren, wenn neuer" fest.
4. Fügen Sie der registration.json-Datei die folgende JSON-Aktionsdefinition hinzu.

{
  "version": 3,
  "actions": [
    {
      "id": "ExampleActionProvider.SendMessage",
      "description": "Send a message (URI Launch)",
      "icon": "ms-resource://Files/Assets/LockScreenLogo.png",
      "usesGenerativeAI": false,
      "allowedAppInvokers": ["*"],
      "inputs": [
        {
          "name": "message",
          "kind": "Text"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "message"
          ],
          "description": "Send message '${message.Text}'"
        }
      ],
      "outputs": [
        {
          "name": "response",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "Uri",
        "uri": "urilaunchaction-protocol://",
        "inputData": {
          "message": "${message.Text}"
        }
      }
    }
  ]
}

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. Weitere Informationen zum Manifestformat des App-Paketmanifests des Aktionsanbieters finden Sie unter App-Aktionen im XML-Format des Windows-Paketmanifests.

Damit ein App-Aktionsanbieter über den URI gestartet werden kann, muss er ein Protokoll beim System registrieren. Diese Registrierung erfolgt durch Bereitstellen des com2:Extension-Elements im App-Paketmanifest. Das Name-Attribut des Protocol-Elementsmuss mit dem in der JSON-Datei der Aktionsdefinition angegebenen Wert übereinstimmen, der für dieses Beispiel angegeben isturilaunchaction-protocol. Weitere Informationen zur URI-Startaktivierung finden Sie unter Starten einer App für Ergebnisse.

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 den folgenden Namespace hinzu.

xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"

3. Fügen Sie das folgende Extensions-Element innerhalb des Application-Elements und nach dem VisualElements-Element hinzu.

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="urilaunchaction-protocol" ReturnResults="always">
      <!-- app-defined protocol name -->
      <uap:DisplayName>URI Launch Action Scheme</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  <uap3:Extension Category="windows.appExtension">
    <uap3:AppExtension Name="com.microsoft.windows.ai.actions" DisplayName="URILaunchAction" Id="UriLaunchActionId" PublicFolder="Assets">
      <uap3:Properties>
        <Registration xmlns="">registration.json</Registration>
      </uap3:Properties>
    </uap3:AppExtension>
  </uap3:Extension>
</Extensions>

Behandeln der App-Aktivierung

Wenn der App-Aktionsanbieter über das registrierte URI-Schema gestartet wird, können die Eingaben für die Aktion über das AppActivationArguments-Objekt aufgerufen werden, das durch Aufrufen der AppInstance.GetActivatedEventArgs abgerufen wird. Um sicherzustellen, dass die Aktivierung aus dem registrierten Protokoll stammt, müssen Sie zuerst überprüfen, ob der Wert der Kind-Eigenschaft"ExtendedActivationKind.ProtocolForResults" lautet. Wenn ja, können Sie das Argumentobjekt in ein ProtocolForResultsActivatedEventArgs-Objekt umwandeln.

Auf die Eingaben für die Aktion wird über die Data-Eigenschaft der Ereignisargumente zugegriffen. Dabei handelt es sich um ein ValueSet , das Schlüssel-Wert-Paare für jede Eingabeentität enthält. In diesem Beispiel wird die message Eingabeentität wie in der datei registration.json definiert. Der Wert dieser Eingabe ist eine Textzeichenfolge.

Um Ergebnisse für die Aktion zurückzugeben, muss der App-Aktionsanbieter mindestens eine Ausgabeentitäten instanziieren. In diesem Beispiel wird eine einzelne TextActionEntity zurückgegeben, die die Antwort auf die Eingabemeldung enthält.

Rufen Sie zum Instanziieren einer neuen Ausgabeentität eine Instanz der ActionEntityFactory-Klasse aus der EntityFactory-Eigenschaft des ActionRuntime-Objekts ab. Das Factoryobjekt stellt Methoden zum Instanziieren aller verschiedenen Arten von Aktionsentitäten bereit. Nach dem Erstellen der Textentität, die unsere Antwortnachricht enthält, erstellen wir einen Eintrag in einem neuen ValueSet , wobei der Schlüssel der ausgabename ist, der in der datei registrationl.json, "response" angegeben ist und der Wert die ID der TextActionEntity ist. Beachten Sie, dass beim Erstellen der Entität durch Aufrufen von CreateTextEntity die Entität bei der Aktionslaufzeit registriert wird. Aus diesem Grund fügen Sie die ID der Entität als Wert im ValueSet hinzu. Consumer Ihrer Aktion rufen das Entitätsobjekt mithilfe dieser ID aus der Aktionslaufzeit ab.

Der letzte Schritt bei der Behandlung der URI-Aktivierung besteht darin, eine neue ProtocolForResultsOperation zu erstellen und die ReportCompleted-Methode aufzurufen und das ValueSet zu übergeben, das den Ausgabeentitätsverweis enthält.

Ersetzen Sie in App.xaml.cs die Standardimplementierung von "OnLaunched" durch den folgenden Code.

  ProtocolForResultsOperation? _operation;
  protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
  {
      var eventargs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();

      if ((eventargs != null) && (eventargs.Kind == ExtendedActivationKind.ProtocolForResults))
      {
          ProtocolForResultsActivatedEventArgs? protocolForResultsArgs = eventargs.Data as ProtocolForResultsActivatedEventArgs;
      
          if (protocolForResultsArgs.CallerPackageFamilyName.EndsWith("_cw5n1h2txyewy"))
          {
              using (ActionRuntime runtime = ActionRuntimeFactory.CreateActionRuntime())
              {
                  if (protocolForResultsArgs != null)
                  {
                      ValueSet inputData = protocolForResultsArgs.Data;
                      var message = inputData["message"];
      
                      Windows.AI.Actions.ActionEntityFactory source = runtime.EntityFactory;
                      Windows.AI.Actions.ActionEntity textEntity = source.CreateTextEntity("Message response.");
      
                      ValueSet result = new ValueSet();
                      result["response"] = textEntity.Id;
      
                      _operation = protocolForResultsArgs.ProtocolForResultsOperation;
                      _operation.ReportCompleted(result);
                  }
              }
          }
      }

      _window = new MainWindow();
      _window.Activate();
  }

Testen der Windows-App-Aktion

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

Zusätzliche App-Aktionen für Windows-Features

Die folgenden Artikel enthalten Informationen zu zusätzlichen Features von App-Aktionen unter Windows.

• Umschalten der Verfügbarkeit einer App-Aktion für Windows

Verwandte Inhalte