Verarbeitung der URI-Aktivierung

Erfahren Sie, wie Sie eine App registrieren, um zum Standardhandler für einen URI-Schemanamen (Uniform Resource Identifier) zu werden. Sowohl Windows-Desktop-Apps als auch UWP-Apps (Universelle Windows-Plattform) können als Standardhandler für einen URI-Schemanamen registriert werden. Wenn der Benutzer Ihre App als Standardhandler für einen URI-Schemanamen auswäht, wird Ihre App jedes Mal aktiviert, wenn dieser URI-Typ gestartet wird.

Es wird empfohlen, dass Sie sich nur für einen URI-Schemanamen registrieren, wenn Sie erwarten, dass alle URI-Starts für diesen URI-Schematyp behandelt werden. Wenn Sie sich für einen URI-Schemanamen registrieren, müssen Sie dem Endbenutzer die Funktionalität bereitstellen, die erwartet wird, wenn Ihre App für dieses URI-Schema aktiviert wird. Beispielsweise sollte eine App, die sich für den URI-Schemanamen "mailto:" registriert, in einer neuen E-Mail-Nachricht öffnen, damit der Benutzer eine neue E-Mail verfassen kann. Weitere Informationen zu URI-Zuordnungen finden Sie unter Dateien, Ordner und Bibliotheken.

Diese Schritte zeigen, wie Sie sich für einen benutzerdefinierten URI-Schemanamen, alsdk://, registrieren und wie Sie Ihre App aktivieren, wenn der Benutzer einen alsdk://-URI startet.

Wichtige APIs

Die folgenden APIs werden in diesem Thema verwendet:

• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated
• AppInstance.GetActivatedEventArgs

Schritt 1: Angeben des Erweiterungspunkts im Paketmanifest

Die App empfängt Aktivierungsereignisse nur für die im Paketmanifest aufgeführten URI-Schemanamen. Hier erfahren Sie, wie Sie angeben, dass Ihre App den alsdk URI-Schemanamen behandelt.

1. Doppelklicken Sie im Projektmappen-Explorerauf "package.appxmanifest", um den Manifest-Designer zu öffnen. Wählen Sie die Registerkarte Deklarationen aus und in der Dropdownliste Verfügbare Deklarationen wählen Sie Protokoll aus und klicken Sie anschließend auf Hinzufügen.

   Hier ist eine kurze Beschreibung der einzelnen Felder, die Sie möglicherweise im Manifest-Designer für das Protokoll ausfüllen können (details hierzu finden Sie unter AppX-Paketmanifest):

2. Geben Sie images\Icon.png als -Logoein.

3. Geben Sie SDK Sample URI Scheme als Anzeigename ein

4. Geben Sie alsdk als Nameein.

5. Drücken Sie STRG+S, um die Änderung in "package.appxmanifest" zu speichern.

   Dadurch wird dem Paketmanifest ein Extension-Element ähnlich diesem hinzugefügt. Die kategorie windows.protocol gibt an, dass die App den alsdk URI-Schemanamen behandelt.

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

Schritt 2: Hinzufügen der richtigen Symbole

Apps, die zum Standard für einen URI-Schemanamen werden, werden an verschiedenen Stellen im gesamten System angezeigt, z. B. in der Systemsteuerung "Standardprogramme". Fügen Sie dazu ein Symbol mit 44 x 44 in Ihr Projekt ein. Passen Sie das Erscheinungsbild des App-Kachellogos an, und verwenden Sie die Hintergrundfarbe Ihrer App, anstatt das Symbol transparent zu gestalten. Lassen Sie das Logo bis zum Rand erweitern, ohne es zu polstern. Testen Sie Ihre Symbole auf weißen Hintergründen. Weitere Informationen zu Symbolen finden Sie unter App-Symbole und Logos.

Schritt 3: Behandeln des aktivierten Ereignisses

In UWP-Apps empfängt der OnActivated Ereignishandler alle Aktivierungsereignisse. Die eigenschaft Kind gibt den Typ des Aktivierungsereignisses an. In diesem Beispiel wird Protokoll Aktivierungsereignisse behandelt.

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

Der folgende Code startet die App programmgesteuert über den URI:

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

Weitere Informationen zum Starten einer App über einen URI finden Sie unter Starten der Standard-App für einen URI-.

Es wird empfohlen, dass Apps für jedes Aktivierungsereignis, das eine neue Seite öffnet, einen neuen XAML-Frame- erstellen. Auf diese Weise enthält der Navigations-Backstack für das neue XAML--Frame- keine vorherigen Inhalte, die die App im aktuellen Fenster haben könnte, wenn dieses angehalten wird. Apps, die ein einzelnes XAML-Frame- für Start- und Dateiverträge verwenden, sollten die Seiten im Frame--Navigationsjournal löschen, bevor sie zu einer neuen Seite navigieren.

Beim Starten über die Protokollaktivierung sollten Apps die Benutzeroberfläche einbeziehen, die es dem Benutzer ermöglicht, zur oberen Seite der App zurückzukehren.

Bemerkungen

Jede App oder Website kann Ihren URI-Schemanamen verwenden, einschließlich böswilliger. Daher können alle Daten, die Sie im URI erhalten, von einer nicht vertrauenswürdigen Quelle stammen. Es wird empfohlen, niemals eine dauerhafte Aktion basierend auf den Parametern auszuführen, die Sie im URI erhalten. Beispielsweise können URI-Parameter verwendet werden, um die App auf der Kontoseite eines Benutzers zu starten, es wird jedoch empfohlen, sie nie zum direkten Ändern des Benutzerkontos zu verwenden.

Es wird empfohlen, dass Apps für jedes Aktivierungsereignis, das ein neues URI-Ziel öffnet, ein neues XAML-Frame- erstellen. Auf diese Weise enthält der Navigations-Backstack für das neue XAML--Frame- keine früheren Inhalte, die die App bei Unterbrechung im aktuellen Fenster haben könnte.

Wenn Sie entscheiden, dass Ihre Apps ein einzelnes XAML-Frame- für Start- und Protokollverträge verwenden sollen, löschen Sie die Seiten im Frame Navigationsjournal, bevor Sie zu einer neuen Seite navigieren. Wenn eine App über den Protokollvertrag gestartet wird, sollten Sie eine Benutzeroberfläche in Ihre Apps integrieren, die es dem Benutzer ermöglicht, zum Anfang der App zurückzukehren.

Verwandte Inhalte

• Association-UWP-Startbeispiel
• Standardprogramme
• Behandeln der Dateiaktivierung