Hantera URI-aktivering

Artikel
02/22/2025

Lär dig hur du registrerar en app för att bli standardhanterare för ett URI-schemanamn (Uniform Resource Identifier). Både Windows-skrivbordsappar och UWP-appar (Universal Windows Platform) kan registreras som standardhanterare för ett URI-schemanamn. Om användaren väljer din app som standardhanterare för ett URI-schemanamn aktiveras appen varje gång den typen av URI startas.

Vi rekommenderar att du bara registrerar dig för ett URI-schemanamn om du förväntar dig att hantera alla URI-lanseringar för den typen av URI-schema. Om du väljer att registrera dig för ett URI-schemanamn måste du ge slutanvändaren de funktioner som förväntas när din app aktiveras för det URI-schemat. Till exempel bör en app som registrerar sig för mailto: URI-schemanamnet öppnas för ett nytt e-postmeddelande så att användaren kan skriva ett nytt e-postmeddelande. Mer information om URI-associationer finns i Filer, mappar och bibliotek.

De här stegen visar hur du registrerar dig för ett anpassat URI-schemanamn, alsdk://och hur du aktiverar appen när användaren startar en alsdk:// URI.

Viktiga API:er

Följande API:er används i det här avsnittet:

Obs

I Windows är vissa URI:er och filnamnstillägg reserverade för användning av inbyggda appar och operativsystemet. Försök att registrera din app med en reserverad URI eller filnamnstillägg ignoreras. Se Reserverade URI-schemanamn och filtyper för en alfabetisk lista över URI-scheman som du inte kan registrera för dina appar eftersom de antingen är reserverade eller förbjudna.

Steg 1: Ange tilläggspunkten i paketmanifestet

Appen tar endast emot aktiveringshändelser för de URI-schemanamn som anges i paketmanifestet. Så här anger du att din app hanterar alsdk URI-schemanamn.

I Solution Explorerdubbelklickar du på package.appxmanifest för att öppna manifestdesignern. Välj fliken Deklarationer och i listrutan Tillgängliga Deklarationer väljer du Protokoll och klickar sedan på Lägg till.

Här är en kort beskrivning av vart och ett av de fält som du kan fylla i manifestdesignern för protokollet (se AppX-paketmanifestet för mer information):

Fält	Beskrivning
logo	Ange den logotyp som används för att identifiera URI-schemanamnet i Ange standardprogram på Kontrollpanelen. Om ingen logotyp har angetts används den lilla logotypen för appen.
visningsnamn	Ange visningsnamnet för att identifiera URI-schemanamnet i Ange standardprogram på Kontrollpanelen.
Namn	Välj ett namn för Uri-schemat.
	Obs! Namnet måste skrivas med små bokstäver.
	Reserverade och förbjudna filtyper Se reserverade URI-schemanamn och filtyper för en alfabetisk lista över URI-scheman som du inte kan registrera för dina Windows-appar eftersom de antingen är reserverade eller förbjudna.
körbar	Anger den körbara standardstarten för protokollet. Om det inte anges används appens körbara fil. Om det anges måste strängen vara mellan 1 och 256 tecken lång, måste sluta med ".exe", och får inte innehålla följande tecken: >, <, :, ", \|, ?eller . Om det anges används även Startpunkt. Om Startpunkt* inte har angetts används startpunkten som definierats för appen.
Startpunkt	Anger den uppgift som hanterar protokolltillägget. Detta är normalt det fullständigt namnområdeskvalificerade namnet på en Windows Runtime-typ. Om det inte anges används startpunkten för appen.
Startsida	Webbsidan som hanterar utökningspunkten.
resursgrupp	En tagg som du kan använda för att gruppera tilläggsaktiveringar för resurshantering.
Desired View (endast Windows)	Ange fältet Önskad vy för att ange hur mycket utrymme appens fönster behöver när den startas för URI-schemanamnet. Möjliga värden för Desired View är Standard, AnvändMindre, AnvändHalva, AnvändMereller AnvändMinimalt. Obs! Windows tar hänsyn till flera olika faktorer vid fastställandet av målappens slutliga fönsterstorlek, till exempel källappens inställning, antalet appar på skärmen, skärmorienteringen och så vidare. Att ange Önskad vy garanterar inte ett specifikt fönsterbeteende för målappen. Den mobila enhetsfamiljen: Den önskade vyn stöds inte på den mobila enhetsfamiljen.

Ange images\Icon.png som -logotypen.
Ange SDK Sample URI Scheme som visningsnamn
Ange alsdk som namn.
Tryck på Ctrl+S för att spara ändringen till package.appxmanifest.

Detta lägger till ett -tilläggselement, ett sådant som detta, i paketmanifestet. Kategorin windows.protocol anger att appen hanterar alsdk URI-schemanamn.

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

Steg 2: Lägg till rätt ikoner

Appar som blir standard för ett URI-schemanamn har sina ikoner som visas på olika platser i systemet, till exempel i kontrollpanelen För standardprogram. Inkludera en 44x44-ikon med ditt projekt för detta ändamål. Matcha utseendet på appens panellogotyp och använd appens bakgrundsfärg i stället för att göra ikonen transparent. Låt logotypen gå ända ut till kanten utan marginal. Testa dina ikoner på vita bakgrunder. Mer information om ikoner finns i appikoner och logotyper.

Steg 3: Hantera den aktiverade händelsen

Anteckning

I en WinUI-app i App.OnLaunched (eller faktiskt när som helst) kan du anropa (AppInstance.GetActivatedEventArgs) för att hämta de aktiverade händelse args och kontrollera dem för att avgöra hur appen aktiverades. Se Migrering av programlivscykelfunktioner för mer information om skillnader i livscykel mellan UWP och WinUI-appar.

I UWP-appar tar händelsehanteraren OnActivated emot alla aktiveringshändelser. Egenskapen Kind anger typen av aktiveringshändelse. Det här exemplet är konfigurerat för att hantera Protocol aktiveringshändelser.

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

Not

När du startar via protokollkontraktet kontrollerar du att bakåtknappen tar användaren tillbaka till skärmen som startade appen och inte till appens tidigare innehåll.

Följande kod startar appen programmatiskt via dess URI:

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

Mer information om hur du startar en app via en URI finns i Starta standardappen för en URI-.

Vi rekommenderar att appar skapar en ny XAML-Frame- för varje aktiveringshändelse som öppnar en ny sida. På så sätt innehåller inte navigeringsryggstacken för den nya XAML-Frame- något tidigare innehåll som appen kan ha i det aktuella fönstret när det pausas. Appar som bestämmer sig för att använda en enda XAML-Frame för Start och Filkontrakt bör rensa sidorna i navigeringsjournalen Frame innan de navigerar till en ny sida.

När de startas via protokollaktivering bör appar överväga att inkludera användargränssnitt som gör att användaren kan gå tillbaka till appens översta sida.

Anmärkningar

Alla appar eller webbplatser kan använda ditt URI-schemanamn, inklusive skadliga. Så alla data som du får i URI:n kan komma från en ej betrodd källa. Vi rekommenderar att du aldrig utför en permanent åtgärd baserat på de parametrar som du får i URI:n. URI-parametrar kan till exempel användas för att starta appen till en användares kontosida, men vi rekommenderar att du aldrig använder dem för att ändra användarens konto direkt.

Obs

Om du skapar ett nytt URI-schemanamn för din app bör du följa anvisningarna i RFC 4395. Detta säkerställer att ditt namn uppfyller standarderna för URI-scheman.

Notera

När en UWP-app startas via Protokollkontrakt kontrollerar du att bakåtknappen tar användaren tillbaka till skärmen som startade appen och inte till appens tidigare innehåll.

Vi rekommenderar att appar skapar en ny XAML-Frame för varje aktiveringshändelse som öppnar ett nytt Uri-mål. På så sätt innehåller inte navigeringsryggstacken för den nya XAML-Frame- något tidigare innehåll som appen kan ha i det aktuella fönstret när det pausas.

Om du vill att dina appar ska använda en enda XAML-Frame för Start- och protokollkontrakt rensar du sidorna i navigeringsjournalen Frame innan du navigerar till en ny sida. När du startar via protokollkontrakt bör du överväga att inkludera användargränssnittet i dina appar som gör att användaren kan gå tillbaka till appens överkant.

Dela via

Hantera URI-aktivering

Viktiga API:er

Steg 1: Ange tilläggspunkten i paketmanifestet

Steg 2: Lägg till rätt ikoner

Steg 3: Hantera den aktiverade händelsen

Anmärkningar

Ytterligare resurser

Dela via

Hantera URI-aktivering

Viktiga API:er

Steg 1: Ange tilläggspunkten i paketmanifestet

Steg 2: Lägg till rätt ikoner

Steg 3: Hantera den aktiverade händelsen

Anmärkningar

Relaterat innehåll

Ytterligare resurser