Freigeben über

Behandeln der URI-Aktivierung

  • Artikel

Wichtige APIs

Erfahren Sie, wie Sie eine App registrieren, damit sie der Standardhandler eines Uniform Resource Identifier (URI)-Schemanamens wird. Sowohl Windows-Desktop-Apps als auch Universelle Windows-Plattform(UWP)-Apps 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 Richtlinien und Prüfliste für Dateitypen und URIs.

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.

Hinweis

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

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-Explorer auf "package.appxmanifest", um den Manifest-Designer zu öffnen. Wählen Sie die Registerkarte "Deklarationen " und dann in der Dropdownliste "Verfügbare Deklarationen " die Option "Protokoll " aus, und klicken Sie dann auf "Hinzufügen".

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

Feld Beschreibung
Logo Geben Sie das Logo an, das zum Identifizieren des URI-Schemanamens in den Systemsteuerung "Standardprogramme festlegen" verwendet wird. Wenn kein Logo angegeben ist, wird das kleine Logo für die App verwendet.
Anzeigename Geben Sie den Anzeigenamen an, um den URI-Schemanamen in den Systemsteuerung festzulegen.
Name Wählen Sie einen Namen für das URI-Schema aus.
Beachten Sie, dass der Name in allen Kleinbuchstaben enthalten sein muss.
Reservierte und unzulässige Dateitypen finden Sie unter Reservierte URI-Schemanamen und Dateitypen für eine alphabetische Liste von URI-Schemas, die Sie nicht für Ihre UWP-Apps registrieren können, da sie entweder reserviert oder verboten sind.
Ausführbare Datei Gibt die ausführbare Standardstartdatei für das Protokoll an. Wenn nicht angegeben, 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 diese Zeichen nicht enthalten: >, , : <, ", ", |, ?, oder *. Wenn angegeben, wird auch der Einstiegspunkt verwendet. Wenn der Einstiegspunkt nicht angegeben ist, wird der für die App definierte Einstiegspunkt verwendet.
Eingangsstelle Gibt die Aufgabe an, die die Protokollerweiterung behandelt. Dies ist normalerweise der vollständig namespacequalifizierte Name eines Windows-Runtime Typs. Wenn nicht angegeben, wird der Einstiegspunkt für die App verwendet.
Startseite Die Webseite, die den Erweiterungspunkt behandelt.
Ressourcengruppe Ein Tag, mit dem Sie Erweiterungsaktivierungen für Ressourcenverwaltungszwecke gruppieren können.
Gewünschte Ansicht (nur Windows) Geben Sie das Feld "Gewünschte Ansicht" an, um den Speicherplatz anzugeben, den das Fenster der App benötigt, wenn es für den URI-Schemanamen gestartet wird. Die möglichen Werte für "Gewünschte Ansicht " sind "Default", "UseLess", "UseHalf", "UseMore" oder "UseMinimum".
Beachten Sie, dass Windows beim Bestimmen der endgültigen Fenstergröße der Ziel-App mehrere unterschiedliche Faktoren berücksichtigt, z. B. die Einstellung der Quell-App, die Anzahl der Apps auf dem Bildschirm, die Bildschirmausrichtung usw. Das Festlegen der gewünschten Ansicht garantiert kein bestimmtes Fensterverhalten für die Ziel-App.
Mobilgerätefamilie: Die gewünschte Ansicht wird auf der Mobilgerätefamilie nicht unterstützt.

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

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

  3. Geben Sie alsdk als Namen ein.

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

    Dadurch wird dem Paketmanifest ein Erweiterungselement wie dieses 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 auf den Rand erweitern, ohne ihn zu auffüllen. 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

Der OnActivated-Ereignishandler empfängt alle Aktivierungsereignisse. Die Kind-Eigenschaft gibt den Typ des Aktivierungsereignisses an. Dieses Beispiel ist für die Behandlung von Protokollaktivierungsereignissen eingerichtet.

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 Starten über den Protokollvertrag sicher, dass die Schaltfläche "Zurück" den Benutzer zurück zum Bildschirm führt, auf dem die App gestartet wurde, und nicht auf den 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.

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 Navigationsbackstack für den neuen XAML-Frame beim Anhalten keinen vorherigen Inhalt, den die App möglicherweise im aktuellen Fenster hat. Apps, die einen einzelnen 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.

Hinweise

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.

Hinweis

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

Hinweis

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

Es wird empfohlen, dass Apps für jedes Aktivierungsereignis, das ein neues URI-Ziel öffnet, einen neuen XAML-Frame erstellen. Auf diese Weise enthält der Navigationsbackstack für den neuen XAML-Frame beim Anhalten keinen vorherigen Inhalt, den die App möglicherweise im aktuellen Fenster hat.

Wenn Sie entscheiden, dass Ihre Apps einen einzelnen 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 Sie über den Protokollvertrag gestartet werden, sollten Sie die Benutzeroberfläche in Ihre Apps einbeziehen, mit denen der Benutzer zum Anfang der App zurückkehren kann.

Vollständige Beispiel-App

Konzepte

Aufgaben

Richtlinien

Verweis