URI etkinleştirmeyi işleme

Tekdüzen Kaynak Tanımlayıcısı (URI) düzeni adının varsayılan işleyicisi olmak üzere bir uygulamayı kaydetmeyi öğrenin. WinUI uygulamaları, URI düzeni adı için varsayılan işleyici olmak üzere kaydolabilir. Kullanıcı bir URI düzeni adı için varsayılan işleyici olarak uygulamanızı seçerse, bu tür URI her başlatıldığında uygulamanız etkinleştirilir.

Not

Uygulama modeli önemlidir. Bu sayfa, paketlenmiş uygulamalar için package bildirimi aracılığıyla protokol kaydını kapsar (WinUI 3, MSIX paketlenmiş WPF/Win32). Uygulamanız unpackaged (düz bir WPF veya Win32 uygulaması) ise, ActivationRegistrationManager kullanarak protokolünüzü kaydedin ve etkinleştirmeyi AppInstance.GetCurrent().GetActivatedEventArgs() ile işleyebilir. Tam bir WPF kılavuzu (tek örnekli yeniden yönlendirme dahil) için bkz. WPF uygulamasında Handle URI protokolü etkinleştirme.

Yalnızca bu tür URI düzeni için tüm URI başlatmalarını işlemeyi bekliyorsanız bir URI düzeni adına kaydolmanızı öneririz. Bir URI düzeni adına kaydolmayı seçerseniz, uygulamanız bu URI düzeni için etkinleştirildiğinde beklenen işlevselliği son kullanıcıya sağlamanız gerekir. Örneğin, mailto: URI düzeni adına kaydolan bir uygulama, kullanıcının yeni bir e-posta oluşturabilmesi için yeni bir e-posta iletisine açılmalıdır. URI ilişkilendirmeleri hakkında daha fazla bilgi için bkz. Dosyalar, klasörler ve kitaplıklar.

Bu adımlar, alsdk://özel bir URI düzeni adının nasıl kaydedileceğini ve kullanıcı bir alsdk:// URI'si başlattığında uygulamanızın nasıl etkinleştirileceğini gösterir.

Önemli API'ler

Bu konuda aşağıdaki API'ler kullanılır:

Not

Windows'ta, bazı URI'ler ve dosya uzantıları yerleşik uygulamalar ve işletim sistemi tarafından kullanılmak üzere ayrılmıştır. Uygulamanızı ayrılmış bir URI'ye veya dosya uzantısına kaydetme girişimleri yoksayılır. Ayrılmış veya yasak URI düzenlerinin ve dosya türlerinin alfabetik bir listesi için'e bakın. Bu düzenleri uygulamalarınıza kaydedemezsiniz.

1. Adım: Paket bildiriminde uzantı noktasını belirtin

Uygulama yalnızca paket bildiriminde listelenen URI düzeni adları için etkinleştirme olaylarını alır. Uygulamanızın alsdk URI düzeni adını işlediğini şu şekilde belirtirsiniz.

  1. Çözüm Gezginipackage.appxmanifest dosyasına çift tıklayarak bildirim tasarımcısını açın. Bildirimler sekmesini seçin ve Kullanılabilir Bildirimler açılır listesinden Protokolü seçin ve ardından Ekle'yi tıklayın.

    Protokol bildirim tasarımcısında doldurabileceğiniz alanların her birinin kısa bir açıklaması aşağıdadır (ayrıntılar için bkz. AppX Paket Bildirimi):

Alan Açıklama
Logo Varsayılan Programları Ayarla içindeki URI düzeni adını tanımlamak için kullanılan logoyu, Denetim Masasıüzerinde belirtin. Logo belirtilmezse, uygulamanın küçük logosu kullanılır.
görünen ad Denetim Masasıiçindeki Varsayılan Programları Ayarla bölümünde URI düzeni adını tanımlayacak görünen adı belirtin.
Adı Uri düzeni için bir ad seçin.
Not Ad küçük harflerle yazılmalıdır.
Ayrılmış ve yasak dosya türleri Ayrılmış veya yasak olduğu için Windows uygulamalarınıza kaydettiremeyeceğiniz alfabetik bir Uri düzeni listesi için Ayrılmış URI düzeni adları ve dosya türlerine bakın.
Yürütülebilir Protokol için varsayılan başlatma yürütülebilir dosyasını belirtir. Belirtilmezse, uygulamanın yürütülebilir dosyası kullanılır. Belirtilirse, dizenin uzunluğu 1 ile 256 karakter arasında olmalıdır, ".exe" ile bitmelidir ve şu karakterleri içeremez: >, <, :, ", |, ?veya *. Belirtilirse, Giriş noktası de kullanılır. Giriş noktası belirtilmezse, uygulama için tanımlanan giriş noktası kullanılır.
Giriş noktası Protokol uzantısını işleyen görevi belirtir. Bu, genellikle bir Windows Çalışma Zamanı türünün tam nitelikli ad alanı adıdır. Belirtilmezse, uygulamanın giriş noktası kullanılır.
Başlangıç sayfası Genişletilebilirlik noktasını işleyen web sayfası.
kaynak grubu Kaynak yönetimi amacıyla uzantı etkinleştirmelerini birlikte gruplandırmak için kullanabileceğiniz bir etiket.
İstenen Görünüm (Yalnızca Windows) Uygulama penceresinin URI düzeni adı için başlatıldığında ihtiyaç duyduğu alan miktarını belirtmek için İstenen Görünüm alanını belirtin. İstenen Görünüm için olası değerler, Varsayılan, Kullanılamaz, Yarım Kullan, Daha Fazla Kullanveya Minimum Kullan.
Not Windows, hedef uygulamanın son pencere boyutunu belirlerken, örneğin kaynak uygulamanın tercihini, ekrandaki uygulama sayısını, ekran yönünü vb. birden çok farklı faktörü dikkate alır. İstenen Görünüm ayarlanması, hedef uygulama için belirli bir pencereleme davranışını garanti etmez.
Mobil cihaz ailesi: İstenen Görünüm mobil cihaz ailesinde desteklenmez.

  1. images\Icon.png'ı Logoolarak girin.

  2. Görünen ad olarak SDK Sample URI Scheme girin

  3. alsdk'ı Adıolarak girin.

  4. Package.appxmanifest dosyasının değişikliğini kaydetmek için Ctrl+S tuşlarına basın.

    Bu, paket bildirimine bunun gibi bir Uzantısı öğesi ekler. windows.protocol kategorisi, uygulamanın alsdk URI düzeni adını işlediğini gösterir.

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

2. Adım: Uygun simgeleri ekleme

URI düzeni adı için varsayılan haline gelen uygulamaların simgeleri, varsayılan programlar denetim masası gibi sistem genelinde çeşitli yerlerde görüntülenir. Bu amaçla projenize 44x44 simgesi ekleyin. Uygulama kutucuğu logosunun görünümünü eşleştirin ve simgeyi saydam hale getirmek yerine uygulamanızın arka plan rengini kullanın. Logonun boşluk bırakmadan kenarlara kadar genişlemesini sağlayın. Simgelerinizi beyaz arka planlarda test edin. Simgeler hakkında daha fazla bilgi için bkz. Uygulama simgeleri ve logoları.

3. Adım: Etkinleştirilmiş olayı işleme

Not

WinUI uygulamasında, App.OnLaunched içinde (veya aslında herhangi bir zamanda) AppInstance.GetCurrent().GetActivatedEventArgs öğesini çağırarak etkinleştirilmiş olay argümanlarını alabilir ve bu argümanları denetleyerek uygulamanın nasıl etkinleştirildiğini belirleyebilirsiniz. Daha fazla bilgi için UWP ve WinUI uygulamaları arasındaki yaşam döngüsü farklılıkları hakkında uygulama yaşam döngüsü işlevselliği geçişi 'e bakın.

UWP uygulamalarında, OnActivated olay işleyicisi tüm etkinleştirme olaylarını alır. Kind özelliği etkinleştirme olayının türünü gösterir. Bu örnek, Protokolü etkinleştirme olaylarını işleyecek şekilde ayarlanmıştır.

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

Protokol Sözleşmesi aracılığıyla başlatıldığında, Geri düğmesinin kullanıcıyı uygulamanın önceki içeriğine değil, uygulamayı başlatan ekrana geri aldığından emin olun.

Aşağıdaki kod, uygulamayı URI'sini kullanarak program aracılığıyla başlatır:

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

Bir uygulamayı URI aracılığıyla başlatma hakkında daha fazla bilgi için bkz. URI için varsayılan uygulamayı başlatma.

Uygulamaların yeni bir sayfa açan her etkinleştirme olayı için yeni bir XAML Çerçeve oluşturması önerilir. Bu şekilde, yeni XAML Frame için gezinti arka yığını, uygulamanın askıya alındığında geçerli pencerede sahip olabileceği önceki içeriği içermez. Başlatma ve Dosya Sözleşmeleri için tek bir XAML Çerçeve kullanmaya karar veren uygulamalar, yeni bir sayfaya geçmeden önce Çerçeve gezinti günlüğündeki sayfaları temizlemelidir.

Protokol etkinleştirme yoluyla başlatıldığında, uygulamalar kullanıcının uygulamanın en üst sayfasına geri dönmesine izin veren kullanıcı arabirimini dahil etmeyi göz önünde bulundurmalıdır.

Güvenlikle ilgili dikkat edilmesi gerekenler

Herhangi bir uygulama veya web sitesi, kötü amaçlı olanlar da dahil olmak üzere rastgele yüklerle URI şemanızı çağırabilir. Tüm URI parametrelerini güvenilmeyen giriş olarak değerlendirin. Şu uygulamaları izleyin:

  • Yalnızca URI parametrelerine dayalı olarak hiçbir zaman geri alınamaz eylemler gerçekleştirmeyin (dosyaları silme, hesap verilerini değiştirme, ileti gönderme).
  • Kullanmadan önce tüm parametreleri doğrulayın ve temizleyin. Beklenmeyen karakterleri, yol geçiş dizilerini (../ ) ve aralık dışında kalan değerleri denetleyin.
  • Beklenmeyen şemaları veya sunucuları reddedin. İşleyiciniz yalnızca alsdk://action öğesini bekliyorsa, host ve yolun, bunlar üzerinde harekete geçmeden önce bilinen desenlerin izinli listesiyle eşleşip eşleşmediğini doğrulayın.
  • Arayan kimliği mevcut değil. Adlandırılmış kanallar veya yuvalardan farklı olarak, bir URI etkinleştirmesi, URI'nin hangi işlem tarafından gönderildiğini doğrulamanın güvenilir bir yolunu size sunmaz. Herhangi bir işlem (kötü amaçlı yazılım dahil) şemanızı başlatabilir.
  • URI parametrelerini yürütülebilir giriş olarak işlemekten kaçının. URI sorgu değerlerini temizlemeden doğrudan Process.Start, ShellExecuteveya SQL sorgularına geçirmeyin.

Not

Uygulamanız için yeni bir URI düzeni adı oluşturuyorsanız rfc 4395 yönergelerini izlediğinizden emin olun. Bu, adınızın URI şemaları için standartları karşılamasını sağlar.

Not

Protokol Sözleşmesi aracılığıyla bir UWP uygulaması başlatıldığında, Geri düğmesinin kullanıcıyı uygulamanın önceki içeriğine değil, uygulamayı başlatan ekrana geri aldığından emin olun.

Uygulamaların yeni bir Uri hedefi açan her etkinleştirme olayı için yeni bir XAML Çerçeve oluşturmasını öneririz. Bu şekilde, yeni XAML Frame için gezinti arka yığını, uygulamanın askıya alındığında geçerli pencerede sahip olabileceği önceki içeriği içermez.

Uygulamalarınızın Başlatma ve Protokol Sözleşmeleri için tek bir XAML Çerçeve kullanmasına karar verirseniz, yeni bir sayfaya geçmeden önce Frame gezinti günlüğündeki sayfaları temizleyin. Protokol Sözleşmesi aracılığıyla başlatıldığında, kullanıcının uygulamanın en üstüne geri dönmesine izin veren kullanıcı arabirimini uygulamalarınıza eklemeyi göz önünde bulundurun.

İlgili içerik

  • Last updated on