URI-activering afhandelen

Meer informatie over het registreren van een app om de standaardhandler voor een URI-schemanaam (Uniform Resource Identifier) te worden. WinUI-apps kunnen zich registreren als een standaardhandler voor een URI-schemanaam. Als de gebruiker uw app kiest als de standaardhandler voor een URI-schemanaam, wordt uw app telkens geactiveerd wanneer dat type URI wordt gestart.

Notitie

App-model is belangrijk. Deze pagina bevat protocolregistratie via het package manifest voor verpakte apps (WinUI 3, MSIX-pakket WPF/Win32). Als uw app unpackaged is (een gewone WPF of Win32-app), registreert u uw protocol met ActivationRegistrationManager en verwerkt u de activering met AppInstance.GetCurrent().GetActivatedEventArgs(). Zie Handle URI-protocolactivering in een WPF-app voor een volledige WPF-rondleiding (inclusief omleiding van een enkele instantie).

U wordt aangeraden u alleen te registreren voor een URI-schemanaam als u verwacht dat alle URI-lanceringen voor dat type URI-schema worden verwerkt. Als u ervoor kiest om u te registreren voor een URI-schemanaam, moet u de eindgebruiker voorzien van de functionaliteit die wordt verwacht wanneer uw app wordt geactiveerd voor dat URI-schema. Een app die zich registreert voor de naam van het e-mailto: URI-schema, moet bijvoorbeeld worden geopend voor een nieuw e-mailbericht, zodat de gebruiker een nieuw e-mailbericht kan opstellen. Zie Bestanden, mappen en bibliothekenvoor meer informatie over URI-koppelingen.

Deze stappen laten zien hoe u zich registreert voor een aangepaste URI-schemanaam, alsdk://en hoe u uw app activeert wanneer de gebruiker een alsdk:// URI start.

Belangrijke API's

De volgende API's worden in dit onderwerp gebruikt:

Notitie

In Windows zijn bepaalde URI's en bestandsextensies gereserveerd voor gebruik door ingebouwde apps en het besturingssysteem. Pogingen om uw app te registreren met een gereserveerde URI of bestandsextensie, worden genegeerd. Zie gereserveerde URI-schemanamen en bestandstypen voor een alfabetische lijst met URI-schema's die u niet kunt registreren voor uw apps omdat deze zijn gereserveerd of verboden.

Stap 1: Geef het extensiepunt op in het pakketmanifest

De app ontvangt alleen activeringsevenementen voor de URI-schemanamen die worden vermeld in het pakketmanifest. U geeft als volgt aan dat uw app de naam van het alsdk URI-schema verwerkt.

  1. Dubbelklik in de Solution Explorerop package.appxmanifest om de manifestontwerper te openen. Selecteer het tabblad Declaraties en selecteer in de vervolgkeuzelijst Beschikbare declaratiesProtocol en klik vervolgens op Toevoegen.

    Hier volgt een korte beschrijving van elk van de velden die u kunt invullen in de manifestontwerper voor het protocol (zie AppX-pakketmanifest voor meer informatie):

Veld Beschrijving
logo Geef het logo op dat wordt gebruikt om de naam van het URI-schema te identificeren in de Standaardprogramma's instellen op het Configuratiescherm. Als er geen logo is opgegeven, wordt het kleine logo voor de app gebruikt.
weergavenaam Geef de weergavenaam op om de naam van het URI-schema te identificeren in de Standaardprogramma's instellen op het Configuratiescherm.
naam Kies een naam voor het URI-schema.
Opmerking De naam moet in alle kleine letters staan.
gereserveerde en verboden bestandstypen Zie namen en bestandstypen van gereserveerde URI-schema's voor een alfabetische lijst met URI-schema's die u niet kunt registreren voor uw Windows-apps omdat deze zijn gereserveerd of verboden.
Uitvoerbaar Geeft het standaard uitvoerbare bestand voor het protocol op. Als dit niet is opgegeven, wordt het uitvoerbare bestand van de app gebruikt. Indien opgegeven, moet de tekenreeks tussen 1 en 256 tekens lang zijn, eindigen op ".exe", en mag deze tekens niet bevatten: >, <, :, ", |, ?, of *. Indien opgegeven, wordt ook het ingangspunt gebruikt. Als het ingangspunt niet is opgegeven, wordt het toegangspunt gebruikt dat voor de app is gedefinieerd.
toegangspunt Specificeert de taak die de protocolextensie afhandelt. Dit is normaal gesproken de volledig met namespace gekwalificeerde naam van een Windows Runtime type. Als dit niet is opgegeven, wordt het toegangspunt voor de app gebruikt.
startpagina De webpagina die het uitbreidbaarheidspunt verwerkt.
Resourcegroep Een tag die u kunt gebruiken om activeringen van extensies te groeperen voor resourcebeheerdoeleinden.
gewenste weergave (alleen Windows) Geef het veld gewenste weergave op om aan te geven hoeveel ruimte het venster van de app nodig heeft wanneer het wordt gestart voor de naam van het URI-schema. De mogelijke waarden voor gewenste weergave zijn Standaard, UseLess, UseHalf, UseMoreof UseMinimum.
Opmerking Windows houdt rekening met meerdere verschillende factoren bij het bepalen van de uiteindelijke venstergrootte van de doel-app, bijvoorbeeld de voorkeur van de bron-app, het aantal apps op het scherm, de schermstand enzovoort. Het instellen van gewenste weergave garandeert geen specifiek venstergedrag voor de doel-app.
Familie van mobiele apparaten: Gewenste weergave wordt niet ondersteund in de familie van mobiele apparaten.

  1. Voer images\Icon.png in als het logo.

  2. Voer SDK Sample URI Scheme in als weergavenaam

  3. Voer alsdk in als de naam.

  4. Druk op Ctrl+S om de wijziging op te slaan in package.appxmanifest.

    Hiermee wordt een -extensie element zoals dit aan het pakketmanifest toegevoegd. De categorie windows.protocol geeft aan dat de app de naam van het alsdk URI-schema verwerkt.

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

Stap 2: De juiste pictogrammen toevoegen

Apps die de standaardnaam voor een URI-schema worden, hebben hun pictogrammen op verschillende plaatsen in het systeem weergegeven, zoals in het configuratiescherm standaardprogramma's. Neem hiervoor een 44x44-pictogram op met uw project. Het uiterlijk van het logo van de app-tegel aanpassen en de achtergrondkleur van uw app gebruiken in plaats van het pictogram transparant te maken. Laat het logo doorlopen tot aan de rand zonder opvulling. Test uw pictogrammen op witte achtergronden. Zie App-pictogrammen en -logo's voor meer informatie over pictogrammen.

Stap 3: de geactiveerde gebeurtenis afhandelen

Notitie

In een WinUI-app, in App.OnLaunched (of in feite op elk gewenst moment), kunt u AppInstance.GetCurrent() aanroepen. GetActivatedEventArgs om de geactiveerde gebeurtenisargumenten op te halen en controleer deze om te bepalen hoe de app is geactiveerd. Zie functiemigratie van toepassingslevenscycli voor meer informatie over de verschillen in levenscyclus tussen UWP- en WinUI-apps.

In UWP-apps ontvangt de OnActivated event handler alle activeringsgebeurtenissen. De eigenschap Type geeft het type activeringsevenement aan. Dit voorbeeld is ingesteld voor het afhandelen van Protocol activeringsevenementen.

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

Notitie

Wanneer u via Protocol Contract bent gestart, moet u ervoor zorgen dat de gebruiker teruggaat naar het scherm dat de app heeft gestart en niet naar de vorige inhoud van de app.

Met de volgende code wordt de app programmatisch gestart via de URI:

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

Zie De standaard-app starten voor een URIvoor meer informatie over het starten van een app via een URI.

Het wordt aanbevolen dat apps een nieuwe XAML-Frame- maken voor elke activeringsevenement waarmee een nieuwe pagina wordt geopend. Op deze manier bevat de navigatieachterstack voor de nieuwe XAML Frame geen eerdere inhoud die de app mogelijk in het huidige venster heeft wanneer deze is onderbroken. Apps die besluiten om een enkel XAML-Frame- te gebruiken voor het starten en het bestandscontract, moeten de pagina's in het Frame-navigatielogboek wissen voordat ze naar een nieuwe pagina navigeren.

Wanneer apps worden gestart via Protocolactivering, moet u overwegen de gebruikersinterface op te nemen waarmee de gebruiker terug kan gaan naar de bovenste pagina van de app.

Beveiligingsoverwegingen

Elke app of website kan uw URI-schema aanroepen met willekeurige payloads, inclusief schadelijke payloads. Alle URI-parameters behandelen als niet-vertrouwde invoer. Volg deze procedures:

  • Voer nooit onherstelbare acties uit (bestanden verwijderen, accountgegevens wijzigen, berichten verzenden) alleen op basis van URI-parameters.
  • Alle parameters valideren en opschonen voordat u ze gebruikt. Controleer op onverwachte tekens, padkruisreeksen (../) en waarden die buiten het bereik vallen.
  • Onverwachte schema's of hosts afwijzen. Als uw handler alleen verwacht alsdk://action, controleert u of de host en het pad overeenkomen met een acceptatielijst met bekende patronen voordat u hierop optreedt.
  • Er is geen belleridentiteit beschikbaar. In tegenstelling tot benoemde pijpen of sockets, biedt een URI-activering u geen betrouwbare manier om te controleren welk proces de URI heeft verzonden. Elk proces (inclusief malware) kan uw schema starten.
  • Vermijd het behandelen van URI-parameters als uitvoerbare invoer. Geef geen URI-querywaarden rechtstreeks door aan Process.Start, ShellExecute of SQL-query's zonder beveiliging.

Notitie

Zorg ervoor dat u de richtlijnen in RFC 4395volgt als u een nieuwe URI-schemanaam voor uw app maakt. Dit zorgt ervoor dat uw naam voldoet aan de standaarden voor URI-schema's.

Notitie

Wanneer een UWP-app wordt gestart via ProtocolContract, moet u ervoor zorgen dat de gebruiker teruggaat naar het scherm dat de app heeft gestart en niet naar de vorige inhoud van de app.

Het is raadzaam dat apps een nieuwe XAML-Frame- maken voor elke activeringsevenement waarmee een nieuw URI-doel wordt geopend. Op deze manier bevat de navigatieachterstack voor de nieuwe XAML Frame geen eerdere inhoud die de app mogelijk in het huidige venster heeft wanneer deze is onderbroken.

Als u besluit dat uw apps één XAML-Frame- voor opstarten en protocolcontracten gebruiken, wis dan de pagina's in het navigatiedagboek van het Frame voordat u naar een nieuwe pagina navigeert. Wanneer u via Protocol Contract wordt gestart, kunt u overwegen de gebruikersinterface op te nemen in uw apps waarmee de gebruiker weer naar de bovenkant van de app kan gaan.

Verwante inhoud

  • Last updated on