Receba conteúdo na sua aplicação - integre o Windows Share

A Folha de Partilha do Windows permite-lhe receber conteúdo (partilhado de outras aplicações) através da sua aplicação. Este guia explica como registar a sua aplicação como Share Target e gerir conteúdos partilhados entre aplicações empacotadas (MSIX), Progressive Aplicações Web (PWAs) e aplicações Win32 não empacotadas.

Neste artigo

Antes de declarares capacidades

A maioria dos erros de integração do destino de partilha resulta de declarar mais do que a sua aplicação consegue realmente processar. Se a sua aplicação declarar <uap:SupportsAnyFileType />, aparecerá na Folha de Partilha para todos os tipos de ficheiros, incluindo ficheiros que não consegue processar (por exemplo, um editor de fotos que aparece quando um utilizador partilha uma folha de cálculo).

Declare sempre apenas os tipos de ficheiros e formatos de dados específicos que a sua aplicação consegue gerir. Por exemplo:

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

Reserve <uap:SupportsAnyFileType /> apenas para ferramentas de utilização geral para mover ficheiros (armazenamento na cloud, aplicações de transferência de ficheiros). Consulte a referência DataFormat & FileType para declarações por categoria de aplicação.

Implementar Share Target para aplicações empacotadas (UWP e desktop empacotado)

Esta secção aplica-se a aplicações UWP e aplicações de ambiente de trabalho empacotadas (WinUI 3, WPF, WinForms). Ambos são enviados como pacotes MSIX com identidade de pacote, por isso declaram o Share Target da mesma forma e diferem apenas na forma como lidam com a ativação (mostrado no passo 2).

1. Declarar no manifesto

Edita package.appxmanifest para o registares como destino de partilha. Declare apenas os tipos de ficheiros e formatos de dados que a sua aplicação gere:

<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. Gerir a ativação da Partilha

Quando a sua aplicação for ativada como destino de partilha, processe o evento 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
}

Para aplicações de ambiente de trabalho empacotadas (WinUI 3, WPF, WinForms) criadas com o SDK de Aplicações Windows, não há OnShareTargetActivated nenhuma sobreposição. Em vez disso, inspecione a ativação no método Main e verifique a existência de 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. Escolher que formatos de dados declarar

Use esta referência para decidir o que declarar:

Para mais detalhes, consulte DataFormat & FileType reference.

Implementar destino de partilha para aplicações Web progressivas (PWAs)

As PWAs no Windows registam-se como destino de partilha através do manifesto da aplicação Web. Adicionar uma share_target entrada:

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

Na sua /share rota, trate a solicitação 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('/');
});

Declara apenas os tipos de ficheiros que a tua PWA consegue gerir. Por exemplo, não declare * como tipo de aceitação a menos que a sua aplicação realmente trate de todos os ficheiros.

Receber partilhas numa aplicação Win32 sem pacote

Para se registar como Share Target, a sua aplicação precisa de identidade de pacote. Se a sua aplicação Win32 não for empacotada, conceda-lhe identidade de pacote de duas formas:

• Reembalar com MSIX (preferido): use o modelo Windows Application Packaging Project no Visual Studio para uma instalação limpa e de confiança. Veja Configurar a sua aplicação de ambiente de trabalho para a embalagem MSIX.
• Pacote com localização externa (pacote esparso): adicione um pacote MSIX vazio que contenha identidade, o registo do share target e os ativos visuais, enquanto o seu instalador atual continua a gerir os binários da aplicação. Usa isto apenas quando tiveres um instalador que não consegues transferir para o MSIX.

O resto desta secção explica a abordagem de localização externa.

1. Crie o manifesto do pacote

Crie um AppxManifest.xml que defina <uap10:AllowExternalContent>, declare identidade e capacidades, e registre o destino de partilha. Mantenha Publisher, PackageName e ApplicationId sincronizados com o seu .exe.manifest e certificado de assinatura.

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

Adicione um manifesto de aplicação (YourApp.exe.manifest) que ligue o executável à identidade do pacote:

<?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. Criar e assinar o pacote

Use MakeAppx.exe com o /nv switch para construir um pacote que contenha apenas o manifesto, depois assine com um certificado de confiança usando 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>

Instale o certificado de assinatura num local de confiança na máquina.

3. Registe o pacote na primeira execução

Na primeira execução, regista o pacote de localização externa para que a aplicação reinicie com a identidade. Forneça caminhos absolutos para o local externo e para o .msix assinado.

[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. Ativação de partilhas de controlo

Depois de a aplicação reiniciar com a identidade, trate ExtendedActivationKind.ShareTarget conforme mostrado em Lidar com a ativação da partilha.

Para exemplos completos, veja a amostra PhotoStoreDemo (empacotada com localização externa) e a amostra do WinUI Share Target.

Para partilha no ambiente de trabalho do lado da fonte, use IDataTransferManagerInterop conforme descrito em Partilhar conteúdo da sua aplicação.

Melhores práticas

Use esta lista de verificação ao construir fluxos de receção.

Reporte o progresso do recebimento (opcional, mas recomendado)

Para conteúdos de grande dimensão ou processamento mais demorado, comunique o estado a partir do destino de partilha:

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

Use ReportCompleted(QuickLink) quando quiser devolver um QuickLink para futuras partilhas.

Troubleshooting

A minha aplicação não aparece na Folha de Partilha:

• Verifica se as declarações do teu manifesto correspondem ao conteúdo partilhado (verifica os tipos de ficheiros e formatos de dados).
• Para aplicações embaladas, certifique-se de que está a executar a aplicação com identidade de pacote.
• Verifique a referência DataFormat & FileType para a categoria da sua aplicação.

A minha aplicação é apresentada para conteúdo que não consegue processar:

• Reduza as suas listas de SupportedFileTypes e DataFormat apenas às que suporta.

A folha de partilha é fechada com um erro:

• Certifica-te de que ligas ReportStarted() antes de qualquer trabalho assíncrono e ReportCompleted() quando terminares.
• Trata das exceções e chama ReportError() com uma mensagem descritiva.

Não estou a receber o ficheiro que espero:

• Verifique se o formato do ficheiro corresponde a um declarado FileType ou DataFormat.
• Adiciona lógica de validação no teu handler de ativação para inspecionar o que está realmente a chegar.

Conteúdo relacionado

• Partilhe conteúdo da sua aplicação
• Referência de DataFormat & FileType
• Pessoas no Windows (API de Pessoas entre dispositivos)
• Referência do esquema ShareTarget
• Web Share API (W3C)