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
Anmerkung
In Windows 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 nicht für Ihre Apps 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.
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):
Feld | Beschreibung |
---|---|
Logo | Geben Sie das Logo an, das zur Identifizierung des URI-Schemanamens im Festlegen von Standardprogrammen in der Systemsteuerungverwendet 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 im Bereich Standardprogramme festlegen der Systemsteuerungzu erkennen. |
Name | Wählen Sie einen Namen für das URI-Schema aus. |
Hinweis Der Name muss in Kleinbuchstaben geschrieben sein. | |
Reservierte und unzulässige Dateitypen Siehe Reservierte URI-Schemanamen und Dateitypen für eine alphabetische Liste von URI-Schemas, die Sie nicht für Ihre Windows-Apps registrieren können, da sie entweder reserviert oder verboten sind. | |
Ausführbare | 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. |
Einstiegspunkt | 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 Aktivierungen von Erweiterungen zu Verwaltungszwecken 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 Desired View sind Default, UseLess, UseHalf, UseMoreoder UseMinimum. Hinweis Windows berücksichtigt beim Bestimmen der endgültigen Fenstergröße der Ziel-App mehrere unterschiedliche Faktoren, z. B. die Einstellung der Quell-App, die Anzahl der Apps auf dem Bildschirm, die Bildschirmausrichtung usw. Das Festlegen Gewünschte Ansicht garantiert kein bestimmtes Fensterverhalten für die Ziel-App. Mobilgerätefamilie: Die gewünschte Ansicht wird für die Mobilgerätefamilie nicht unterstützt. |
Geben Sie
images\Icon.png
als -Logoein.Geben Sie
SDK Sample URI Scheme
als Anzeigename einGeben Sie
alsdk
als Nameein.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
Anmerkung
In einer WinUI-App können Sie in App.OnLaunched (oder tatsächlich jederzeit) die Methode (AppInstance.GetActivatedEventArgs) aufrufen, um die aktivierten Ereignisargumente abzurufen und sie zu überprüfen, um zu bestimmen, wie die App aktiviert wurde. Weitere Informationen zu Lebenszyklusunterschieden zwischen UWP- und WinUI-Apps finden Sie unter Migration der Anwendungslebenszyklus-Funktionalität.
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
}
}
Anmerkung
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 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.
Anmerkung
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.
Anmerkung
Wenn eine UWP-App über den Protokollvertrag gestartet wird, stellen Sie 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, 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
Windows developer