Implementowanie uruchamiania identyfikatora URI dla akcji aplikacji w systemie Windows

W tym artykule opisano kroki tworzenia akcji aplikacji i opisano składniki aplikacji dostawcy akcji 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.

Aplikacje dostawcy akcji można zaimplementować w celu korzystania z aktywacji modelu COM lub aktywacji uruchamiania identyfikatora URI. Akcje uruchamiania identyfikatora URI nie obsługują niektórych zaawansowanych funkcji akcji, takich jak wyświetlanie interfejsu użytkownika w kontekście lub wyniki przesyłania strumieniowego tekstu, ale implementacja jest bardzo prosta i może być najlepszym wyborem dla akcji, które składają się tylko z jednego żądania i odpowiedzi.

Aplikacje dostawcy korzystające z aktywacji MODELU COM implementują interfejs IActionProvider do obsługi wywołania akcji. Ta metoda umożliwia korzystanie z zaawansowanych funkcji akcji, takich jak obsługa tekstu przesyłanego strumieniowo, ale wymaga więcej kodu niż używanie rozszerzenia VSIX akcji aplikacji systemu Windows. Aby uzyskać informacje na temat korzystania z aktywacji modelu COM u dostawcy aplikacji, zobacz Wprowadzenie do akcji aplikacji w systemie 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

Tworzenie nowego projektu aplikacji systemu Windows w programie Visual Studio

Funkcja Akcje aplikacji jest obsługiwana w wielu strukturach aplikacji i językach, 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#.

1. W programie Visual Studio utwórz nowy projekt.

2. 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 WinUI (spakowana)".

3. Nadaj nowej nazwie nowy projekt "ExampleAppActionProvider".

4. Po załadowaniu projektu w Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nazwę projektu i wybierz polecenie Właściwości. Na stronie Ogólne przewiń w dół do pozycji Docelowy system operacyjny i wybierz pozycję "Windows". W obszarze Docelowa wersja systemu operacyjnego i obsługiwana wersja systemu operacyjnego wybierz wersję 10.0.26100.0 lub nowszą.

5. 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. Wewnątrz właściwościGroup dodaj następujący element WindowsSdkPackageVersion .

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Dodawanie odwołania do pakietu NuGet Microsoft.AI.Actions

Pakiet NuGet Microsoft.AI.Actions umożliwia zainicjowanie środowiska uruchomieniowego akcji aplikacji, które udostępnia interfejsy API do tworzenia obiektów jednostki przekazywanych jako dane wejściowe i wyjściowe z akcji aplikacji.

1. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nazwę projektu i wybierz polecenie Zarządzaj pakietami NuGet...
2. Upewnij się, że jesteś na karcie Przeglądaj i wyszukaj ciąg Microsoft.AI.Actions.
3. Wybierz pozycję Microsoft.AI.Actions i kliknij przycisk Zainstaluj.

Dodawanie pliku JSON definicji akcji

Aplikacje dostawcy akcji muszą podać plik definicji akcji definiujący akcje implementujące aplikację. Ten plik zawiera informacje, takie jak unikatowy identyfikator i opis każdej akcji, a także nazwy i typy danych wejściowych i wyjściowych obsługiwane przez każdą akcję. 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 identyfikatora URI. Schemat urilaunchaction-protocol identyfikatora URI zostanie zarejestrowany w późniejszym kroku w tym przewodniku.

1. W Eksploratorze rozwiązań kliknij prawym przyciskiem Assets myszy folder i wybierz polecenie Dodaj nowy> element....
2. W oknie dialogowym Dodawanie nowego elementu wybierz pozycję Plik tekstowy. Nazwij nowy plik "registration.json", a następnie kliknij przycisk OK.
3. 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".
4. Dodaj następującą definicję akcji JSON do pliku registration.json.

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

Aktualizowanie pliku manifestu pakietu aplikacji

Plik Package.appmanifest zawiera szczegóły pakietu MSIX dla aplikacji. Aby być zarejestrowany przez system jako dostawca akcji aplikacji systemu Windows, aplikacja musi zawierać element uap3:Extensionz 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, zobacz App Actions on Windows package manifest XML format (Format XML manifestu pakietu systemu Windows).

Aby dostawca akcji aplikacji został uruchomiony za pośrednictwem identyfikatora URI, musi zarejestrować protokół w systemie. Ta rejestracja jest wprowadzana przez podanie elementu com2:Extension w manifeście pakietu aplikacji. Atrybut Name elementu Protocol musi być zgodny z wartością invocation.uri określoną w pliku JSON definicji akcji, który dla tego przykładu to urilaunchaction-protocol. Aby uzyskać więcej informacji na temat aktywacji uruchamiania identyfikatora URI, zobacz Uruchamianie aplikacji w celu uzyskania wyników.

1. Kliknij prawym przyciskiem myszy plik Package.appxmanifest i wybierz polecenie Wyświetl kod
2. Dodaj następującą przestrzeń nazw do elementu Package w katalogu głównym pliku.

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

3. Dodaj następujący element Extensions wewnątrz elementu Application i po elemecie VisualElements .

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

Obsługa aktywacji aplikacji

Po uruchomieniu dostawcy akcji aplikacji ze schematu zarejestrowanego identyfikatora URI można uzyskać dostęp do danych wejściowych akcji za pośrednictwem obiektu AppActivationArguments uzyskanego przez wywołanie klasy AppInstance.GetActivatedEventArgs. Aby upewnić się, że aktywacja pochodzi z zarejestrowanego protokołu, należy najpierw sprawdzić, czy wartość właściwości Kind to ExtendedActivationKind.ProtocolForResults. Jeśli tak, można rzutować obiekt argumentów na obiekt ProtocolForResultsActivatedEventArgs .

Dane wejściowe akcji są dostępne za pośrednictwem właściwości Data zdarzeń args, która jest wartością ValueSet zawierającą pary klucz/wartość dla każdej jednostki wejściowej. Ten przykład pobiera jednostkę wejściową message zgodnie z definicją w pliku registration.json. Wartość tych danych wejściowych jest ciągiem tekstowym.

Aby zwrócić wyniki akcji, dostawca akcji aplikacji musi utworzyć wystąpienie co najmniej jednej jednostki wyjściowej. Ten przykład zwraca pojedynczy element TextActionEntity zawierający odpowiedź na komunikat wejściowy.

Aby utworzyć wystąpienie nowej jednostki wyjściowej, pobierz wystąpienie klasy ActionEntityFactory z właściwości EntityFactory obiektu ActionRuntime . Obiekt fabryki udostępnia metody tworzenia wystąpień wszystkich różnych typów jednostek akcji. Po utworzeniu jednostki tekstowej zawierającej komunikat odpowiedzi tworzymy wpis w nowym zestawie wartości , gdzie klucz jest nazwą wyjściową określoną w pliku registrationl.json, "odpowiedź", a wartość jest identyfikatoremtextActionEntity. Należy pamiętać, że podczas tworzenia jednostki przez wywołanie metody CreateTextEntity jednostka jest zarejestrowana w środowisku uruchomieniowym akcji. Dlatego należy dodać identyfikator jednostki jako wartość w elemencji ValueSet. Użytkownicy akcji pobierzą obiekt jednostki ze środowiska uruchomieniowego akcji przy użyciu tego identyfikatora.

Ostatnim krokiem obsługi aktywacji identyfikatora URI jest utworzenie nowego elementu ProtocolForResultsOperation i wywołanie metody ReportCompleted , przekazując element ValueSet zawierający odwołanie do jednostki wyjściowej.

W App.xaml.cs zastąp domyślną implementację metody OnLaunched następującym kodem.

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

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 App Actions Testing Playground app (Testowanie akcji aplikacji — plac zabaw).

Dodatkowe akcje aplikacji w funkcjach systemu Windows

Poniższe artykuły zawierają informacje o dodatkowych funkcjach akcji aplikacji w systemie Windows.

• Przełącz dostępność akcji aplikacji dla systemu Windows

Treści powiązane