Recevoir du contenu dans votre application - intégrer Windows Share

La feuille de partage Windows vous permet de recevoir du contenu (partagé à partir d’autres applications) via votre application. Ce guide explique comment inscrire votre application en tant que cible de partage et gérer du contenu partagé entre des applications empaquetées (MSIX), des applications progressives Web Apps (PWA) et des applications Win32 non empaquetées.

Dans cet article

Avant de déclarer des fonctionnalités

La plupart des bogues d’intégration de la cible de partage sont dus à la déclaration d’un plus grand nombre d’éléments que votre application ne peut réellement en gérer. Si votre application déclare <uap:SupportsAnyFileType />, elle apparaît dans la feuille de partage pour chaque type de fichier, y compris les fichiers qu’elle ne peut pas traiter (par exemple, un éditeur de photos apparaissant lorsqu’un utilisateur partage une feuille de calcul).

Déclarez toujours uniquement les types de fichiers et les formats de données spécifiques que votre application peut gérer. Par exemple:

<!-- ✓ 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 /> -->

Réservez <uap:SupportsAnyFileType /> uniquement aux applications de déplacement de fichiers d’usage général (stockage dans le cloud, applications de transfert de fichiers). Consultez la référence DataFormat &FileType pour les déclarations par catégorie d’application.

Implémenter la cible de partage pour les applications empaquetées (applications UWP et applications de bureau empaquetées)

Cette section s’applique aux applications UWP et aux applications de bureau empaquetées (WinUI 3, WPF, WinForms). Les deux sont fournis en tant que packages MSIX avec l’identité de package, de sorte qu’ils déclarent la cible de partage de la même façon et diffèrent uniquement dans la façon dont ils gèrent l’activation (illustré à l’étape 2).

1. Déclarer dans le manifeste

Modifiez votre package.appxmanifest pour vous enregistrer comme cible de partage. Déclarez uniquement les types de fichiers et les formats de données gérés par votre application :

<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. Gérer l’activation de partage

Lorsque votre application est activée en tant que cible de partage, gérez l’événement OnShareTargetActivated :

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
}

Pour les applications de bureau empaquetées (WinUI 3, WPF, WinForms) créées avec le SDK d'application Windows, il n’existe pas de substitution OnShareTargetActivated. À la place, vérifiez l’activation dans votre méthode Main et recherchez ExtendedActivationKind.ShareTarget :

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. Choisir les formats de données à déclarer

Utilisez cette référence pour décider de ce qu’il faut déclarer :

Pour plus d’informations, consultez la référence DataFormat &FileType.

Implémenter la fonctionnalité Share Target pour les applications web progressives (PWA)

Les PWA sur Windows s’inscrivent en tant que cible de partage via le manifeste d’application web. Ajoutez une share_target entrée :

{
  "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/*"]
        }
      ]
    }
  }
}

Dans votre /share itinéraire, gérez la requête POST :

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('/');
});

Déclarez uniquement les types de fichiers que votre PWA peut gérer. Par exemple, ne déclarez * pas comme type d’acceptation, sauf si votre application gère réellement tous les fichiers.

Recevoir des partages dans une application Win32 non empaquetée

Pour vous inscrire en tant que cible de partage, votre application a besoin d’une identité de package. Si votre application Win32 n’est pas empaquetée, accordez-la à l’identité de package de l’une des deux manières suivantes :

• Repackage avec MSIX (préféré) : utilisez le modèle Windows Application Packaging Project dans Visual Studio pour une installation propre et approuvée. Consultez Configurer votre application de bureau pour l’empaquetage MSIX.
• Package avec emplacement externe (package sparse) : ajoutez un package MSIX vide qui porte l’identité, l’enregistrement en tant que cible de partage et les éléments visuels, tandis que votre programme d’installation existant continue de gérer les binaires de l’application. Utilisez cette option uniquement lorsque vous disposez d’un programme d’installation que vous ne pouvez pas déplacer vers MSIX.

Le reste de cette section présente l’approche basée sur les emplacements externes.

1. Rédiger le manifeste du package

Créez un AppxManifest.xml qui définit <uap10:AllowExternalContent>, déclare l’identité et les capacités, et enregistre la cible de partage. Maintenez Publisher, PackageName et ApplicationId synchronisés avec votre .exe.manifest et certificat de signature.

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

Ajoutez un manifeste d’application (YourApp.exe.manifest) qui lie l’exécutable à l’identité du package :

<?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. Créer et signer le package

Utilisez MakeAppx.exe avec le commutateur /nv pour créer un package qui contient uniquement le manifeste, puis signez-le avec un certificat de confiance à l’aide de SignTool.exe :

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>

Installez le certificat de signature à un emplacement approuvé sur l’ordinateur.

3. Inscrire le package lors de la première exécution

Lors de la première exécution, enregistrez le package external-location afin que l’application redémarre avec son identité. Fournissez des chemins absolus vers l’emplacement externe et le signe .msix.

[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. Gérer l’activation de partage

Une fois l’application redémarrée avec l’identité, gérez ExtendedActivationKind.ShareTarget comme indiqué dans Gérer l’activation du partage.

Pour obtenir des exemples complets, consultez l’exemple PhotoStoreDemo (empaqueté avec emplacement externe) et l’exemple Cible de partage WinUI.

Pour le partage de bureau côté source, utilisez IDataTransferManagerInterop ce qui est décrit dans Partager du contenu à partir de votre application.

Bonnes pratiques

Utilisez cette liste de contrôle lors de la génération de flux de réception.

Progression de la réception du rapport (facultatif mais recommandé)

Pour les charges utiles importantes ou en cas de traitement prolongé, signalez l’état depuis la cible de partage :

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}");
  }
}

Utilisez ReportCompleted(QuickLink) lorsque vous souhaitez renvoyer un QuickLink pour de futurs partages.

Résolution des problèmes

Mon application n’apparaît pas dans la feuille De partage :

• Vérifiez que vos déclarations de manifeste correspondent au contenu partagé (vérifiez les types de fichiers et les formats de données).
• Pour les applications empaquetées, vérifiez que vous exécutez l’application avec l’identité de package.
• Vérifiez la référence DataFormat &FileType pour votre catégorie d’application.

Mon application s’affiche pour le contenu qu’elle ne peut pas gérer :

• Réduisez vos listes SupportedFileTypes et DataFormat aux seuls éléments que vous prenez en charge.

La feuille de partage se ferme avec une erreur :

• Veillez à appeler ReportStarted() avant tout travail asynchrone et ReportCompleted() lorsque vous avez terminé.
• Gérez les exceptions et les appels ReportError() avec un message descriptif.

Je ne reçois pas le fichier que je m’attends :

• Vérifiez que le format de fichier correspond à un fichier déclaré FileType ou DataFormat.
• Ajoutez une logique de validation dans votre gestionnaire d’activation pour inspecter ce qui arrive réellement.

Contenu connexe

• Partager du contenu à partir de votre application
• Référence de DataFormat & FileType
• Personnes dans Windows (API Personnes inter-appareils)
• Informations de référence sur le schéma ShareTarget
• API Web Share (W3C)