Behandeln der URI-Aktivierung

  • Artikel
  • 6 Minuten Lesedauer

Wichtige APIs

Erfahren Sie, wie Sie eine App registrieren, damit sie der Standardhandler eines Uniform Resource Identifier (URI)-Schemanamens wird. Windows-Desktop-Apps und UWP (Universelle Windows-Plattform)-Apps können als Standarddateihandler für URI-Schemanamen registriert werden. Wenn Ihre App vom Benutzer als Standardhandler für einen URI-Schemanamen ausgewählt wird, wird sie immer dann aktiviert, wenn dieser URI-Typ gestartet wird.

Wir empfehlen, die Registrierung für einen URI-Schemanamen nur durchzuführen, wenn davon auszugehen ist, dass Sie alle entsprechenden Vorgänge für diesen URI-Schematyp behandeln werden. Wenn Sie sich entscheiden, die Registrierung für einen bestimmten URI-Schemanamen durchzuführen, müssen Sie die entsprechenden Funktionen bereitstellen, die vom Benutzer bei der Aktivierung für dieses URI-Schemas erwartet werden. Beispielsweise sollte eine App, die für den URI-Schemanamen "mailto:" registriert wird, eine neue E-Mail-Nachricht öffnen, damit Benutzer eine neue E-Mail erstellen können. Weitere Informationen zu URI-Zuordnungen finden Sie unter Richtlinien und Prüflisten für Dateitypen und URIs.

In diesen Schritten wird gezeigt, wie Sie sich für einen benutzerdefinierten URI-Schemanamen () registrieren und Ihre App aktivieren, alsdk://wenn der Benutzer einen alsdk:// URI startet.

Hinweis

In UWP-Apps sind bestimmte URIs und Dateierweiterungen für die Verwendung durch integrierte Apps und das Betriebssystem reserviert. Versuche, die App mit einem reservierten URI oder einer reservierten Dateierweiterung zu registrieren, werden ignoriert. Eine alphabetische Liste der URI-Schemas, die Sie nicht für Ihre UWP-Apps registrieren können, da diese entweder reserviert oder verboten sind, finden Sie unter Reservierte URI-Schemanamen und Dateitypen.

Schritt 1: Angeben des Erweiterungspunkts im Paketmanifest

Die App empfängt nur für die im Paketmanifest angegebenen URI-Schemanamen Aktivierungsereignisse. So geben Sie an, dass Ihre App den Namen des URI-Schemas alsdk behandelt.

  1. Doppelklicken Sie im Projektmappen-Explorer auf „package.appxmanifest“, um den Manifest-Designer zu öffnen. Wählen Sie die Registerkarte Deklarationen und in der Dropdownliste Verfügbare Deklarationen die Option Protokoll aus, und klicken Sie dann auf Hinzufügen.

    Es folgt eine kurze Beschreibung der einzelnen Felder, die Sie im Manifest-Designer für das Protokoll ausfüllen können (Einzelheiten finden Sie unter AppX Package Manifest):

Feld BESCHREIBUNG
Logo Geben Sie das Logo zur Identifikation des URI-Schemanamens in der Systemsteuerung unter Standardprogramme festlegen an. Wenn kein Logo angegeben wird, wird das kleine Logo für die App verwendet.
Anzeigename Geben Sie den Anzeigenamen zur Identifikation des URI-Schemanamens in der Systemsteuerung unter Standardprogramme festlegen an.
Name Wählen Sie einen Namen für das URI-Schema aus.
Hinweis Der Name muss in Kleinbuchstaben enthalten sein.
Reservierte und verbotene Dateitypen Eine alphabetische Liste der URI-Schemas, die Sie nicht für Ihre UWP-Apps registrieren können, da diese entweder reserviert oder verboten sind, finden Sie unter Reservierte URI-Schemanamen und Dateitypen.
Ausführbare Datei Gibt die standardmäßige ausführbare Datei für den Start des Protokolls an. Wenn keine Datei angegeben wird, wird die ausführbare Datei der App verwendet. Wenn angegeben, muss die Zeichenfolge zwischen 1 und 256 Zeichen lang sein, muss mit ".exe" enden und darf folgende Zeichen nicht enthalten: >, <, :, ", |, ?, oder *. Bei Angabe einer Datei wird auch der Einstiegspunkt verwendet. Wenn der Einstiegspunkt nicht angegeben wird, wird der für die App definierte Einstiegspunkt verwendet.
Einstiegspunkt Gibt die Aufgabe an, die die Protokollerweiterung behandelt. Dies ist normalerweise der vollständig qualifizierte Namespacename eines Windows-Runtime-Typs. Wenn keine Angabe erfolgt, wird der Einstiegspunkt für die App verwendet.
Startseite Die Webseite, die den Erweiterungspunkt behandelt.
Ressourcengruppe Eine Markierung, die Sie zum Gruppieren von Erweiterungsaktivierungen zu Zwecken der Ressourcenverwaltung verwenden können.
Gewünschte Ansicht (nur Windows) Verwenden Sie das Feld Gewünschte Ansicht, um anzugeben, wie viel Platz für das Fenster der App benötigt wird, wenn sie für den URI-Schemanamen gestartet wird. Die möglichen Werte für Gewünschte Ansicht sind Default, UseLess, UseHalf, UseMore oder UseMinimum.
Beachten Windows, dass bei der Bestimmung der endgültigen Fenstergröße der Ziel-App mehrere verschiedene Faktoren berücksichtigt werden, z. B. die Einstellung der Quell-App, die Anzahl der Apps auf dem Bildschirm, die Bildschirmausrichtung und so weiter. Das Festlegen von Gewünschte Ansicht ist keine Garantie, dass das Fenster für die Ziel-App auch wirklich so angezeigt wird.
Familie mobiler Geräte: Die gewünschte Ansicht wird in der Familie der mobilen Geräte nicht unterstützt.

  1. Geben Sie images\Icon.png als images\Icon.png ein.

  2. Geben Sie SDK Sample URI Scheme als SDK Sample URI Scheme ein.

  3. Geben Sie alsdk als alsdk.

  4. Drücken Sie STRG+S, um die an „package.appxmanifest“ vorgenommenen Änderungen zu speichern.

    Dadurch wird dem Paketmanifest ein Extension-Element wie das unten dargestellte hinzugefügt. Die windows.protocol-Kategorie gibt an, dass die App den 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 geeigneten Symbole

Apps, die zum Standardnamen für einen URI-Schemanamen werden, werden an verschiedenen Stellen im System angezeigt, z. B. in der Systemsteuerung Standardprogramme. Fügen Sie zu diesem Zweck ein 44 x 44-Symbol in Ihr Projekt ein. Stimmen Sie das Erscheinungsbild des Logos der App-Kachel ab, und verwenden Sie die Hintergrundfarbe der App, anstatt das Symbol transparent darzustellen. Erweitern Sie das Logo bis zum Rand, ohne eine Auffüllung vorzunehmen. Testen Sie Ihre Symbole auf weißem Hintergrund. Weitere Informationen zu Symbolen finden Sie unter App-Symbole und -Logos.

Schritt 3: Behandeln des activated-Ereignisses

Der OnActivated-Ereignishandler empfängt alle Aktivierungsereignisse. Die Kind-Eigenschaft gibt den Typ des Aktivierungsereignisses an. In diesem Beispiel werden Protocol-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
      }
   }
}

Protected Overrides Sub OnActivated(ByVal args As Windows.ApplicationModel.Activation.IActivatedEventArgs)
   If args.Kind = ActivationKind.Protocol Then
      ProtocolActivatedEventArgs eventArgs = args As ProtocolActivatedEventArgs
      
      ' TODO: Handle URI activation
      ' The received URI is eventArgs.Uri.AbsoluteUri
 End If
End Sub

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

Hinweis

Stellen Sie beim Start über den Protokollvertrag sicher, dass Schaltfläche "Zurück" benutzer zurück zum Bildschirm führt, auf dem die App gestartet wurde, und nicht zum vorherigen Inhalt der App.

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.

Apps sollten für jedes Aktivierungsereignis, durch das eine neue Seite geöffnet wird, einen neuen XAML-Frame erstellen. Auf diese Weise enthält der Navigations-Backstack für den neuen XAML-Frame keinen vorherigen Inhalt, den die App möglicherweise im aktuellen Fenster hat, wenn er angehalten wird. Apps, für die ein einziger XAML-Frame für Start- und Dateiverträge verwendet wird, sollten vor dem Navigieren zu einer neuen Seite die Seiten im Frame-Navigationsjournal löschen.

Per Protokollaktivierung gestartete Apps sollten ggf. eine Benutzeroberfläche enthalten, über die der Benutzer zur ersten Seite der App zurückkehren kann.

Hinweise

Ihr URI-Schemaname kann von jeder App oder Website verwendet werden, auch von schädlichen. Alle im URI empfangenen Daten könnten daher von einer nicht vertrauenswürdigen Quelle stammen. Wir empfehlen, niemals eine endgültige Aktion auf Grundlage der Parameter auszuführen, die Sie im URI erhalten. URI-Parameter können z. B. zum Starten der App mit der Kontoseite eines Benutzers, aber nicht zum direkten Ändern des Kontos des Benutzers verwendet werden.

Hinweis

Wenn Sie einen neuen URI-Schemanamen für Ihre App erstellen, befolgen Sie unbedingt die Anleitung in RFC 4395. Damit wird sichergestellt, dass der Name die Standards für URI-Schemas erfüllt.

Hinweis

Stellen Sie beim Start über den Protokollvertrag sicher, dass Schaltfläche "Zurück" benutzer zurück zum Bildschirm führt, auf dem die App gestartet wurde, und nicht zum vorherigen Inhalt der App.

Apps sollten für jedes Aktivierungsereignis, durch das ein neues URI-Ziel geöffnet wird, einen neuen XAML-Frame erstellen. Auf diese Weise enthält der Navigations-Backstack für den neuen XAML-Frame keinen vorherigen Inhalt, den die App möglicherweise im aktuellen Fenster hat, wenn er angehalten wird.

Falls Ihre Apps für Start- und Protokollverträge einen einzelnen XAML-Frame verwenden sollen, müssen vor dem Navigieren zu einer neuen Seite die Seiten im Frame-Navigationsjournal gelöscht werden. Über den Protokollvertrag gestartete Apps sollten ggf. eine Benutzeroberfläche enthalten, über die der Benutzer zum Anfang der App zurückkehren kann.

Vollständige Beispiel-App

Konzepte

Aufgaben

Richtlinien

Verweis