Uygulamanızda içerik alın - Windows Paylaşımı'nı entegre edin

Windows Paylaşım Sayfası, uygulamanız aracılığıyla içerik (diğer uygulamalardan paylaşılan) almanıza olanak tanır. Bu kılavuzda, uygulamanızı Paylaşım Hedefi olarak kaydetme ve paketlenmiş uygulamalar (MSIX), Aşamalı Web Apps (PWA) ve paketlenmemiş Win32 uygulamaları arasında paylaşılan içeriği işleme açıklanmaktadır.

Bölüm	Ne bulacaksınız?
Özellikleri bildirmeden önce	Yalnızca uygulamanızın işlediği dosya türlerini ve biçimlerini bildirme
Paketlenmiş uygulamalar (UWP ve paketlenmiş masaüstü) için Paylaşım hedefini uygulayın	UWP ve paketlenmiş masaüstü uygulamaları için manifest beyanı ve etkinleştirme işlemleri
PWA'lar için Paylaşım Hedefi Uygulama	share_target manifest ve POST işleme
Paketlenmemiş bir Win32 uygulamasında paylaşım alma	Paket kimliği verme ve Paylaşım Hedefi olarak kaydetme
En iyi uygulamalar	Güvenilir alma akışları için öneriler
Rapor alma ilerlemesi	Büyük veya uzun süren paylaşımlar için durum bildirimi
Troubleshooting	Yaygın Paylaşım Hedefi sorunları için düzeltmeler

Özellikleri bildirmeden önce

Paylaşım hedefi tümleştirme hatalarının çoğu , uygulamanızın işleyebileceğinden daha fazlasını bildirmekten kaynaklanabilir. Uygulamanız <uap:SupportsAnyFileType /> beyan ediyorsa, işleyemediği dosyalar da dahil olmak üzere her dosya türü için Paylaşım menüsünde görünür (örneğin, kullanıcı bir elektronik tablo paylaştığında bir fotoğraf düzenleyicisinin görünmesi).

Her zaman yalnızca uygulamanızın işleyebileceği belirli dosya türlerini ve veri biçimlerini bildirin. Örneğin:

<!-- ✓ Correct: declare only what you support -->
<uap:SupportedFileTypes>
  <uap:FileType>.jpg</uap:FileType>
  <uap:FileType>.png</uap:FileType>
</uap:SupportedFileTypes>

<!-- ✗ Incorrect: declares everything -->
<!-- <uap:SupportsAnyFileType /> -->

<uap:SupportsAnyFileType /> öğesini yalnızca genel amaçlı dosya taşıma uygulamaları (bulut depolama, dosya aktarım uygulamaları) için ayırın. Uygulama kategorisine göre beyanlar için DataFormat & FileType referansına bakın.

Paketlenmiş uygulamalar (UWP ve paketlenmiş masaüstü) için Paylaşım Hedefi'ni uygulayın

Bu bölüm UWP uygulamaları ve paketlenmiş masaüstü uygulamaları (WinUI 3, WPF, WinForms) için geçerlidir. Her ikisi de paket kimliğine sahip MSIX paketleri olarak gönderilir, bu nedenle Paylaşım Hedefi'ni aynı şekilde bildirir ve yalnızca etkinleştirmeyi işleme biçiminde farklılık gösterir (2. adımda gösterilmiştir).

1. Manifestte bildirin

package.appxmanifest öğenizi, Paylaşım Hedefi olarak kaydolacak şekilde düzenleyin. Yalnızca uygulamanızın işlediği dosya türlerini ve veri biçimlerini bildirin:

<Extensions>
  <uap:Extension Category="windows.shareTarget">
    <uap:ShareTarget>
      <uap:SupportedFileTypes>
        <uap:FileType>.jpg</uap:FileType>
        <uap:FileType>.jpeg</uap:FileType>
        <uap:FileType>.png</uap:FileType>
        <uap:FileType>.gif</uap:FileType>
        <uap:FileType>.bmp</uap:FileType>
      </uap:SupportedFileTypes>
      <uap:DataFormat>Bitmap</uap:DataFormat>
    </uap:ShareTarget>
  </uap:Extension>
</Extensions>

2. Paylaşım etkinleştirmesini işleme

Uygulamanız bir Paylaşım Hedefi olarak etkinleştirildiğinde, OnShareTargetActivated olayını işleyin:

Note

OnShareTargetActivated , UWP uygulamalarıWindows.UI.Xaml.Application () için etkinleştirme geçersiz kılma işlemidir. Paketlenmiş masaüstü uygulamaları (WinUI 3, WPF, WinForms), AppInstance.GetActivatedEventArgs aracılığıyla paylaşım etkinleştirmesi alır ve ExtendedActivationKind.ShareTarget öğesini denetler. Bkz. Paketlenmiş uygulamalar için etkinleştirme bilgilerini alma.

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
    ShareOperation shareOperation = args.ShareOperation;
    shareOperation.ReportStarted();

    try
    {
        if (shareOperation.Data.Contains(StandardDataFormats.StorageItems))
        {
            IReadOnlyList<IStorageItem> items = await shareOperation.Data.GetStorageItemsAsync();
            
            // Validate: check count, types, and sizes
            if (items.Count == 0)
            {
                shareOperation.ReportError("No items received.");
                return;
            }

            var file = (IStorageFile)items[0];
            
            // Process the file
            await ProcessImageAsync(file);
        }
        
        shareOperation.ReportCompleted();
    }
    catch (Exception ex)
    {
        shareOperation.ReportError($"Error: {ex.Message}");
    }
}

private async Task ProcessImageAsync(IStorageFile file)
{
    // Your processing logic here
}

Windows Uygulama SDK'sı ile oluşturulan paketlenmiş masaüstü uygulamaları (WinUI 3, WPF, WinForms) için geçersiz kılma yokturOnShareTargetActivated. Bunun yerine, Main yönteminizde etkinleştirmeyi inceleyin ve ExtendedActivationKind.ShareTarget öğesini kontrol edin:

using Microsoft.Windows.AppLifecycle;
using Windows.ApplicationModel.Activation;
using Windows.ApplicationModel.DataTransfer;

[STAThread]
static void Main(string[] args)
{
    AppActivationArguments activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();
    if (activatedArgs.Kind == ExtendedActivationKind.ShareTarget)
    {
        HandleShareAsync(activatedArgs.Data as ShareTargetActivatedEventArgs);
    }
    else
    {
        // Normal launch path
    }
}

static async void HandleShareAsync(ShareTargetActivatedEventArgs args)
{
    ShareOperation shareOperation = args.ShareOperation;
    shareOperation.ReportStarted();

    if (shareOperation.Data.Contains(StandardDataFormats.StorageItems))
    {
        IReadOnlyList<IStorageItem> items = await shareOperation.Data.GetStorageItemsAsync();
        // Process the shared items.
    }

    shareOperation.ReportCompleted();
}

3. Hangi veri biçimlerinin bildirileceğini seçin

Neyi beyan edeceğinize karar vermek için bu referansı kullanın:

Format	Ne zaman kullanılır?	Örnek uygulamalar
StorageItems	Uygulamanız dosyaları alır	Fotoğraf düzenleyicileri, belge okuyucuları
Bitmap	Uygulamanız görüntü alıyor	Görüntü görüntüleyiciler, tasarım uygulamaları
Text	Uygulamanız düz metin alıyor	Not uygulamaları, metin düzenleyicileri
Html	Uygulamanız zengin metin içeriği alır	E-posta istemcileri, zengin düzenleyiciler
Uri / WebLink	Uygulamanız bağlantıları işler	Tarayıcılar, bağlantı yöneticileri
Rtf	Uygulamanız biçimlendirilmiş metin alıyor	Word işlemciler

Daha fazla ayrıntı için bkz. DataFormat & FileType referansı.

Aşamalı Web Uygulamaları (PWA) için Paylaşım Hedefi'ni Uygulayın

Windows üzerindeki PWA’lar, Web Uygulaması Manifesti aracılığıyla paylaşım hedefi olarak kaydedilir. share_target girişi ekleyin:

{
  "name": "My PWA",
  "short_name": "MyPWA",
  "share_target": {
    "action": "/share",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "title",
      "text": "text",
      "url": "url",
      "files": [
        {
          "name": "media",
          "accept": ["image/*", "video/*"]
        }
      ]
    }
  }
}

/share rotanızda POST isteğini işleyin:

app.post('/share', async (req, res) => {
  const { title, text, url, files } = req.body;

  // Validate and process
  if (files && files.length > 0) {
    const file = files[0];
    // Process the file
    console.log('Received file:', file.originalname);
  }

  if (text) {
    console.log('Received text:', text);
  }

  res.redirect('/');
});

Yalnızca PWA'nızın işleyebileceği dosya türlerini bildirin. Örneğin, uygulamanız gerçekten tüm dosyaları işlemiyorsa * ögesini accept türü olarak bildirmeyin.

Paketlenmemiş bir Win32 uygulamasında paylaşım alma

Paylaşım Hedefi olarak kaydolmak için uygulamanızın paket kimliğine ihtiyacı vardır. Win32 uygulamanız paketten çıkarılmışsa, iki yoldan biriyle paket kimliği verin:

• MSIX ile yeniden paketleme (tercih edilen): temiz ve güvenilir bir yükleme için Visual Studio'de Windows Uygulama Paketleme Project şablonunu kullanın. Bkz. MSIX paketlemesi için masaüstü uygulamanızı ayarlama.
• Harici konuma sahip paket (seyrek paket): Kimliği, paylaşım hedefi kaydını ve görsel varlıkları içeren boş bir MSIX paketi ekleyin; mevcut yükleyiciniz ise uygulama ikili dosyalarını yönetmeye devam etsin. Bunu yalnızca MSIX'e taşıyamadığınız bir yükleyiciniz varsa kullanın.

Bu bölümün geri kalanında harici konum yaklaşımı adım adım açıklanmaktadır.

1. Paket bildirimini yazma

AppxManifest.xml öğesini ayarlayan, kimliği ve yetenekleri bildiren ve paylaşım hedefini kaydeden bir <uap10:AllowExternalContent> oluşturun. Publisher, PackageName ve ApplicationId öğelerini .exe.manifest ve imzalama sertifikanızla senkronize tutun.

<Identity Name="PhotoStoreDemo" ProcessorArchitecture="neutral" Publisher="CN=YourPubNameHere" Version="1.0.0.0" />
<Properties>
  <uap10:AllowExternalContent>true</uap10:AllowExternalContent>
</Properties>
<Dependencies>
  <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.19041.0" MaxVersionTested="10.0.19041.0" />
</Dependencies>
<Capabilities>
  <rescap:Capability Name="runFullTrust" />
  <rescap:Capability Name="unvirtualizedResources" />
</Capabilities>
<Applications>
  <Application Id="PhotoStoreDemo" Executable="PhotoStoreDemo.exe" uap10:TrustLevel="mediumIL" uap10:RuntimeBehavior="win32App">
    <Extensions>
      <uap:Extension Category="windows.shareTarget">
        <uap:ShareTarget Description="Send to PhotoStoreDemo">
          <uap:SupportedFileTypes>
            <uap:FileType>.jpg</uap:FileType>
            <uap:FileType>.png</uap:FileType>
          </uap:SupportedFileTypes>
          <uap:DataFormat>StorageItems</uap:DataFormat>
          <uap:DataFormat>Bitmap</uap:DataFormat>
        </uap:ShareTarget>
      </uap:Extension>
    </Extensions>
  </Application>
</Applications>

Yürütülebilir dosyayı paket kimliğine bağlayan bir uygulama bildirimi (YourApp.exe.manifest) ekleyin:

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <assemblyIdentity version="1.0.0.0" name="PhotoStoreDemo.app" />
  <msix xmlns="urn:schemas-microsoft-com:msix.v1"
        publisher="CN=YourPubNameHere"
        packageName="PhotoStoreDemo"
        applicationId="PhotoStoreDemo" />
</assembly>

2. Paketi oluşturma ve imzalama

Yalnızca bildirim dosyasını içeren bir paket oluşturmak için MakeAppx.exe öğesini /nv anahtarıyla kullanın, ardından bunu SignTool.exe kullanarak güvenilir bir sertifikayla imzalayın:

MakeAppx.exe pack /d <folder with AppxManifest.xml> /p <output>\mypackage.msix /nv
SignTool.exe sign /fd SHA256 /a /f <path to cert> /p <cert key> <path to package>

İmzalama sertifikasını makinede güvenilir bir konuma yükleyin.

3. Paketi ilk çalıştırmada kaydetme

İlk çalıştırmada, uygulamanın kimlikle yeniden başlatılması için dış konum paketini kaydedin. Harici konumun ve imzalı .msix öğesinin tam yollarını belirtin.

[STAThread]
public static void Main(string[] cmdArgs)
{
    if (!ExecutionMode.IsRunningWithIdentity())
    {
        string externalLocation = Environment.CurrentDirectory;
        string externalPkgPath = externalLocation + @"\PhotoStoreDemo.package.msix";

        if (registerPackageWithExternalLocation(externalLocation, externalPkgPath))
        {
            // Registration succeeded - restart so the app runs with identity.
            // Join the arguments into a single string; cmdArgs.ToString() would
            // return the array type name ("System.String[]"), not the arguments.
            string forwardedArgs = cmdArgs is null ? string.Empty : string.Join(" ", cmdArgs);
            Process.Start(Application.ResourceAssembly.Location, arguments: forwardedArgs);
        }
        else
        {
            // Registration failed - run without identity.
            new SingleInstanceManager().Run(cmdArgs);
        }
    }
}

4. Paylaşım etkinleştirmeyi işleme

Uygulama kimlikle yeniden başlatıldıktan sonra, ExtendedActivationKind.ShareTargetPaylaşım etkinleştirmesini işleme bölümünde gösterildiği gibi işleyebilirsiniz.

Tam örnekler için bkz. PhotoStoreDemo örneği (dış konumla paketlenmiş) ve WinUI Paylaşım Hedefi örneği.

Kaynak tarafı masaüstü paylaşımı içinIDataTransferManagerInterop bölümünde açıklandığı gibi kullanın.

En iyi yöntemler

Alma akışları oluştururken bu kontrol listesini kullanın.

Recommended	Kaçın	Neden önemlidir?
Yalnızca belirli dosya uzantılarını ve veri biçimlerini bildirme	<uap:SupportsAnyFileType /> Dosya taşımacı olmayan uygulamalar için bildirim	Share Sheet'te ilgisiz hedeflerin görünmesini engeller
İşlemeden önce biçimi, sayımı, dosya türünü ve dosya boyutunu doğrulama	Gelen verilerin her zaman beklentilerle eşleşir olduğunu varsayarsak	Çalışma zamanı hatalarını ve bozuk paylaşım deneyimlerini önler
Uri Bağlantı işleyicileri ve Bitmap + StorageItems görüntü işleyicileri için bildirme	Ortak paylaşım yükleri için kısmi bildirimler	Uygulamanızın gerçekten desteklediği içerik için görünmesini sağlar
ReportStarted, ReportDataRetrieved ve ReportCompleted öğelerini uzun süre çalışan alma akışlarında kullanın	İlerleme raporlaması olmadan uzun süren alma işlemi gerçekleştirme	Paylaşım işlemini güvenilir tutar ve sisteme doğru durumu verir

Rapor alma ilerleme durumu (isteğe bağlı ancak önerilir)

Büyük yükler veya daha uzun işleme için paylaşım hedefinden durumu bildirin:

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
  ShareOperation shareOperation = args.ShareOperation;
  shareOperation.ReportStarted();

  try
  {
    // Acquire the data your app needs.
    var items = await shareOperation.Data.GetStorageItemsAsync();
    shareOperation.ReportDataRetrieved();

    // Process data.
    await ProcessAsync(items);

    shareOperation.ReportCompleted();
  }
  catch (Exception ex)
  {
    shareOperation.ReportError($"Share failed: {ex.Message}");
  }
}

Gelecekteki paylaşımlar için bir QuickLink döndürmek istediğinizde kullanın ReportCompleted(QuickLink) .

Troubleshooting

Uygulamam Paylaşım Sayfası'nda görünmüyor:

• Bildirim bildirimlerinizin paylaşılmakta olan içerikle eşleşip eşleşmedığını doğrulayın (dosya türlerini ve veri biçimlerini denetleyin).
• Paketlenmiş uygulamalar için uygulamayı paket kimliğiyle çalıştırdığınızdan emin olun.
• Uygulama kategoriniz için DataFormat & FileType başvurusunu denetleyin.

Uygulamam işleyemediği içerikler için görüntüleniyor:

• SupportedFileTypes ve DataFormat listelerinizi yalnızca desteklediklerinizle daraltın.

Paylaşım sayfası bir hatayla kapanıyor:

• Herhangi bir eşzamansız işleme başlamadan önce ReportStarted() ve işiniz bittiğinde ReportCompleted() çağırdığınızdan emin olun.
• Özel durumları işleyin ve açıklayıcı bir mesajla ReportError() öğesini çağırın.

Beklediğim dosyayı almıyorum:

• Dosya biçiminin bildirilen FileType veya DataFormatile eşleşir olup olmadığını denetleyin.
• Gerçekten gelenleri incelemek için etkinleştirme işleyicinize doğrulama mantığı ekleyin.

İlgili içerik

• Uygulamanızdan içerik paylaşma
• DataFormat & FileType başvuru kaynağı
• Windows'ta Kişiler (Cihazlar arası Kişiler API'si)
• ShareTarget şema referansı
• Web Paylaşımı API'si (W3C)