Delen via

URI-activering afhandelen

  • Artikel

Meer informatie over het registreren van een app om de standaardhandler voor een URI-schemanaam (Uniform Resource Identifier) te worden. Zowel Windows-bureaublad-apps als UWP-apps (Universal Windows Platform) kunnen worden geregistreerd als 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.

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 kunt u in App.OnLaunched (of in feite op elk gewenst moment) aanroepen (AppInstance.GetActivatedEventArgs) om de geactiveerde gebeurtenisargumenten op te halen en deze te controleren 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.

Opmerkingen

Elke app of website kan de naam van uw URI-schema gebruiken, inclusief schadelijke apps. Alle gegevens die u in de URI krijgt, kunnen dus afkomstig zijn van een niet-vertrouwde bron. U wordt aangeraden nooit een permanente actie uit te voeren op basis van de parameters die u in de URI ontvangt. URI-parameters kunnen bijvoorbeeld worden gebruikt om de app te starten op de accountpagina van een gebruiker, maar we raden u aan deze nooit rechtstreeks te gebruiken om het account van de gebruiker rechtstreeks te wijzigen.

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 navigatiestack voor de nieuwe XAML Frame geen eerdere inhoud die de app mogelijk in het huidige venster heeft wanneer de app wordt 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