Behandeln der URI-Aktivierung
Wichtige APIs
- Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
- Windows.UI.Xaml.Application.OnActivated
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.
Diese Schritte zeigen, wie Sie sich für einen benutzerdefinierten URI-Schemanamen registrieren alsdk://
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, 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. Hier erfahren Sie, wie Sie angeben, dass Ihre App den alsdk
URI-Schemanamen verarbeitet.
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 die folgenden 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. Hinweis Windows berücksichtigt bei der Bestimmung der endgültigen Fenstergröße der Ziel-App mehrere verschiedene Faktoren, z. B. die Einstellung der Quell-App, die Anzahl der Apps auf dem Bildschirm, die Bildschirmausrichtung usw. 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 Mobilen Gerätefamilie nicht unterstützt. |
Geben Sie
images\Icon.png
als Logo ein.Geben Sie
SDK Sample URI Scheme
als Anzeigenamen ein.Geben Sie
alsdk
als Name ein.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
alsdk
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 Standard für einen URI-Schemanamen werden, werden ihre Symbole an verschiedenen Stellen im gesamten System angezeigt, z. B. in der Systemsteuerung Standardprogramme. Fügen Sie zu diesem Zweck ein 44x44-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 Starten über den Protokollvertrag sicher, dass die Schaltfläche Zurück den Benutzer zurück zum Bildschirm führt, der die App gestartet hat, und nicht zum vorherigen Inhalt der App.
Der folgende Code startet die App programmgesteuert über ihren 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 Navigationsrückstapel für den neuen XAML-Frame keine vorherigen Inhalte, die die App möglicherweise im aktuellen Fenster enthält, wenn sie 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 Starten über den Protokollvertrag sicher, dass die Schaltfläche Zurück den Benutzer zurück zum Bildschirm führt, der die App gestartet hat, 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 Navigationsrückstapel für den neuen XAML-Frame keine vorherigen Inhalte, die die App möglicherweise im aktuellen Fenster enthält, wenn sie 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.