Obsługa aktywacji identyfikatora URI

Dowiedz się, jak zarejestrować aplikację, aby stać się domyślną aplikacją obsługującą dla nazwy schematu Uniform Resource Identifier (URI). Aplikacje WinUI mogą być domyślnym programem obsługi schematu URI. Jeśli użytkownik wybierze aplikację jako domyślną procedurę obsługi dla nazwy schematu identyfikatora URI, aplikacja zostanie aktywowana za każdym razem, gdy ten typ identyfikatora URI zostanie uruchomiony.

Notatka

Model aplikacji ma znaczenie. Ta strona obejmuje rejestrację protokołu za pośrednictwem manifestu pakietu dla spakowanych aplikacji (WinUI 3, WPF/Win32 spakowane w MSIX). Jeśli aplikacja jest unpackaged (zwykła aplikacja WPF lub Win32), zarejestruj protokół przy użyciu ActivationRegistrationManager i obsłuż aktywację przy użyciu AppInstance.GetCurrent().GetActivatedEventArgs(). Aby zapoznać się z kompletnym przewodnikiem WPF (w tym przekierowaniem pojedynczego wystąpienia), zobacz Aktywowanie protokołu URIhandle w aplikacji WPF.

Zalecamy rejestrowanie nazwy schematu identyfikatora URI tylko wtedy, gdy oczekujesz obsługi wszystkich uruchomień identyfikatorów URI dla tego typu schematu. Jeśli zdecydujesz się zarejestrować nazwę schematu identyfikatora URI, musisz podać użytkownikowi końcowemu funkcję oczekiwaną po aktywowaniu aplikacji dla tego schematu identyfikatora URI. Na przykład aplikacja, która rejestruje się dla schematu identyfikatora URI mailto:, powinna otworzyć nową wiadomość e-mail, aby użytkownik mógł ją napisać. Aby uzyskać więcej informacji na temat skojarzeń identyfikatorów URI, zobacz Pliki, foldery i biblioteki.

W tych krokach pokazano, jak zarejestrować niestandardową nazwę schematu URI alsdk://i jak aktywować aplikację, gdy użytkownik uruchomi URI alsdk://.

Ważne interfejsy API

W tym temacie są używane następujące interfejsy API:

Notatka

W systemie Windows niektóre identyfikatory URI i rozszerzenia plików są zarezerwowane do użytku przez wbudowane aplikacje i system operacyjny. Próby zarejestrowania aplikacji przy użyciu zastrzeżonego identyfikatora URI lub rozszerzenia pliku zostaną zignorowane. Zobacz zarezerwowane nazwy schematów URI i typy plików, aby uzyskać alfabetyczną listę schematów URI, których nie można zarejestrować w aplikacjach, ponieważ są zastrzeżone lub zabronione.

Krok 1. Określanie punktu rozszerzenia w manifeście pakietu

Aplikacja odbiera zdarzenia aktywacji tylko dla nazw schematów identyfikatorów URI wymienionych w manifeście pakietu. Poniżej przedstawiono sposób wskazywania, że aplikacja obsługuje nazwę schematu identyfikatora URI alsdk.

  1. W eksploratorze rozwiązań kliknij dwukrotnie plik package.appxmanifest, aby otworzyć projektanta manifestu. Wybierz kartę Deklaracje, a następnie z listy rozwijanej Dostępne deklaracje wybierz pozycję Protokół, a potem kliknij przycisk Dodaj.

    Poniżej znajduje się krótki opis każdego pola, które można wypełnić w projektancie manifestu dla Protokołu (zobacz Manifest pakietu AppX, aby uzyskać szczegóły):

Pole Opis
Logo Określ logo używane do identyfikowania nazwy schematu identyfikatora URI w Ustaw programy domyślne na panelu sterowania . Jeśli nie określono logo, zostanie użyte małe logo aplikacji.
nazwa wyświetlana Określ nazwę wyświetlaną, aby zidentyfikować nazwę schematu identyfikatora URI w Ustaw programy domyślne na panelu sterowania .
nazwa Wybierz nazwę schematu identyfikatora URI.
Uwaga Nazwa musi zawierać wszystkie małe litery.
zastrzeżone i zabronione typy plików Zobacz nazwy schematów identyfikatorów URI zarezerwowanych i typy plików dla alfabetycznej listy schematów identyfikatorów URI, których nie można zarejestrować w aplikacjach systemu Windows, ponieważ są one zastrzeżone lub zabronione.
Program wykonywalny Określa domyślny plik wykonywalny do uruchamiania dla protokołu. Jeśli nie zostanie określony, zostanie użyty plik wykonywalny aplikacji. Jeśli zostanie określony, ciąg musi mieć długość od 1 do 256 znaków, musi kończyć się znakiem ".exe" i nie może zawierać następujących znaków: >, <, :, ", |, ?, lub *. Jeśli zostanie określony, używany jest również punktu wejścia. Jeśli nie określono punktu wejścia, używany jest punkt wejścia zdefiniowany dla aplikacji.
punkt wejścia Określa zadanie obsługujące rozszerzenie protokołu. Jest to zwykle w pełni kwalifikowana nazwa przestrzeni nazw typu środowiska uruchomieniowego systemu Windows. Jeśli nie zostanie określony, zostanie użyty punkt wejścia dla aplikacji.
strona startowa Strona internetowa, która obsługuje punkt rozszerzalności.
grupa zasobów Tag, którego można użyć do grupowania aktywacji rozszerzeń razem na potrzeby zarządzania zasobami.
Pożądany Widok (tylko system Windows) Określ pole Desired View, aby wskazać ilość miejsca, którego potrzebuje okno aplikacji podczas uruchamiania dla nazwy schematu identyfikatora URI. Możliwe wartości dla żądanego widoku to domyślne, bezużyteczne, półużyteczne, bardziej użytecznelub minimalnie użyteczne.
Uwaga Windows uwzględnia wiele różnych czynników podczas określania końcowego rozmiaru okna aplikacji docelowej, na przykład preferencji aplikacji źródłowej, liczby aplikacji na ekranie, orientacji ekranu itd. Ustawienie żądanego widoku nie gwarantuje określonego sposobu działania okna dla aplikacji docelowej.
Rodzina urządzeń przenośnych: żądany widok nie jest obsługiwany na tej rodzinie urządzeń.

  1. Wprowadź images\Icon.png jako logo .

  2. Wprowadź SDK Sample URI Scheme jako nazwę wyświetlaną

  3. Wprowadź alsdk jako nazwę .

  4. Naciśnij Ctrl+S, aby zapisać zmianę w pliku package.appxmanifest.

    Spowoduje to dodanie do manifestu pakietu elementu rozszerzenia , takiego jak ten. Kategoria windows.protocol wskazuje, że aplikacja obsługuje nazwę schematu identyfikatora URI alsdk.

    <Applications>
        <Application Id= ... >
            <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="alsdk">
                    <uap:Logo>images\icon.png</uap:Logo>
                    <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
          </Extensions>
          ...
        </Application>
   </Applications>

Krok 2. Dodawanie odpowiednich ikon

Aplikacje, które stają się domyślnymi dla nazwy schematu identyfikatora URI, mają swoje ikony wyświetlane w różnych miejscach systemu, na przykład w panelu sterowania Programy domyślne. Dołącz do projektu ikonę 44x44 w tym celu. Dopasuj wygląd logo kafelka aplikacji i użyj koloru tła swojej aplikacji zamiast sprawiać, by ikona była przezroczysta. Logo ma rozciągać się na krawędź bez marginesów. Przetestuj ikony na białych tłach. Zobacz Ikony aplikacji i loga, aby uzyskać więcej informacji o ikonach.

Krok 3. Obsługa aktywowanego zdarzenia

Notatka

W aplikacji WinUI, w App.OnLaunched (lub rzeczywiście w dowolnym momencie), możesz wywołać metodę AppInstance.GetCurrent().GetActivatedEventArgs, aby pobrać argumenty zdarzenia aktywacji i przeanalizować je, aby określić, w jaki sposób aplikacja została aktywowana. Zobacz informacje o migracji funkcji cyklu życia aplikacji, aby uzyskać więcej informacji na temat różnic cyklu życia między aplikacjami UWP i WinUI.

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
  {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;
         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args)
{
    if (args.Kind() == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
    {
        auto protocolActivatedEventArgs{ args.as<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs>() };
        // TODO: Handle URI activation  
        auto receivedURI{ protocolActivatedEventArgs.Uri().RawUri() };
    }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs =
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   }
}

Notatka

Po uruchomieniu za pośrednictwem kontraktu protokołu upewnij się, że przycisk Wstecz przenosi użytkownika z powrotem na ekran, który uruchomił aplikację, a nie do poprzedniej zawartości aplikacji.

Poniższy kod programowo uruchamia aplikację za pomocą identyfikatora URI.

   // Launch the URI
   var uri = new Uri("alsdk:");
   var success = await Windows.System.Launcher.LaunchUriAsync(uri);

Aby uzyskać więcej informacji na temat sposobu uruchamiania aplikacji za pośrednictwem identyfikatora URI, zobacz Uruchamianie domyślnej aplikacji dla identyfikatora URI.

Zaleca się, aby aplikacje utworzyły nowy XAML Frame dla każdego zdarzenia aktywacji, które otwiera nową stronę. W ten sposób stos nawigacyjny dla nowego XAML Frame nie będzie zawierał żadnej poprzedniej zawartości, którą aplikacja mogłaby mieć w bieżącym oknie, gdy zostanie zawieszona. Aplikacje, które zdecydują się używać pojedynczego ramki XAML do uruchamiania i kontraktów plików, powinny wyczyścić strony na ramce dziennika nawigacji przed przejściem do nowej strony.

Po uruchomieniu za pośrednictwem aktywacji protokołu aplikacje powinny rozważyć uwzględnienie interfejsu użytkownika, który umożliwia użytkownikowi powrót do górnej strony aplikacji.

Zagadnienia dotyczące zabezpieczeń

Każda aplikacja lub strona internetowa może wywołać Twój schemat URI z dowolnymi, także złośliwymi, ładunkami. Traktuj wszystkie parametry identyfikatora URI jako niezaufane dane wejściowe. Postępuj zgodnie z następującymi rozwiązaniami:

  • Nigdy nie wykonuj nieodwracalnych akcji (usuń pliki, zmodyfikuj dane konta, wysyłaj komunikaty) wyłącznie na podstawie parametrów identyfikatora URI.
  • Przed użyciem zweryfikuj i odczysz wszystkie parametry. Sprawdź nieoczekiwane znaki, sekwencje przechodzenia ścieżki (../) i wartości, które są poza zakresem.
  • Odrzuć nieoczekiwane schematy lub hosty. Jeśli program obsługi oczekuje tylko alsdk://action, sprawdź, czy host i ścieżka są zgodne z listą dozwolonych znanych wzorców, zanim podejmiesz działania.
  • Nie jest dostępna żadna tożsamość wywołująca. W przeciwieństwie do nazwanych potoków lub gniazd aktywacja identyfikatora URI nie zapewnia niezawodnego sposobu weryfikowania, który proces wysłał identyfikator URI. Każdy proces (w tym złośliwe oprogramowanie) może uruchomić schemat.
  • Unikaj traktowania parametrów identyfikatora URI jako danych wejściowych pliku wykonywalnego. Nie przekazuj wartości zapytania identyfikatora URI bezpośrednio do Process.Start, ShellExecute lub zapytań SQL bez filtrowania.

Notatka

Jeśli tworzysz nową nazwę schematu identyfikatora URI dla aplikacji, postępuj zgodnie ze wskazówkami w RFC 4395. Dzięki temu twoja nazwa spełnia standardy schematów identyfikatorów URI.

Notatka

Po uruchomieniu aplikacji platformy UWP za pośrednictwem kontraktu protokołu upewnij się, że przycisk Wstecz przenosi użytkownika z powrotem na ekran, który uruchomił aplikację, a nie do poprzedniej zawartości aplikacji.

Zalecamy, aby aplikacje tworzyły nową ramkę XAML dla każdego zdarzenia aktywacji, które otwiera nowy cel URI. W ten sposób stos nawigacyjny dla nowego XAML Frame nie będzie zawierał żadnej poprzedniej zawartości, którą aplikacja mogłaby mieć w bieżącym oknie, gdy zostanie zawieszona.

Jeśli zdecydujesz, że chcesz, aby Twoje aplikacje używały jednej ramki XAML w przypadku uruchamiania i kontraktów protokołów, wyczyść strony w dzienniku nawigacji ramki zanim przejdziesz do nowej strony. Po uruchomieniu za pośrednictwem kontraktu protokołu rozważ uwzględnienie interfejsu użytkownika w aplikacjach, które umożliwiają użytkownikowi powrót do góry aplikacji.

Powiązana zawartość

  • Last updated on