Receber dados

Este artigo explica como receber conteúdo em seu aplicativo UWP (Plataforma Universal do Windows) compartilhado de outro aplicativo usando o contrato de compartilhamento. Esse contrato de compartilhamento permite que seu aplicativo seja apresentado como uma opção quando o usuário invoca o Share.

Declarar seu aplicativo como um destino de compartilhamento

O sistema exibe uma lista de possíveis aplicativos de destino quando um usuário invoca o Share. Para aparecer na lista, seu aplicativo precisa declarar que dá suporte ao contrato de compartilhamento. Isso permite que o sistema saiba que seu aplicativo está disponível para receber conteúdo.

1. Abra o arquivo de manifesto. Ele deve ser chamado de algo como package.appxmanifest.
2. Abra a guia Declarações.
3. Escolha Destino de Compartilhamento na lista de Declarações Disponíveis, e então selecione Adicionar.

Escolher tipos e formatos de arquivo

Em seguida, decida quais tipos de arquivo e formatos de dados você dá suporte. As APIs de compartilhamento dão suporte a vários formatos padrão, como Texto, HTML e Bitmap. Você também pode especificar tipos de arquivo personalizados e formatos de dados. Se você fizer isso, lembre-se de que os aplicativos de origem precisam saber quais são esses tipos e formatos; caso contrário, esses aplicativos não podem usar os formatos para compartilhar dados.

Registre-se apenas para os formatos que seu aplicativo pode manipular. Somente os aplicativos de destino que dão suporte aos dados que estão sendo compartilhados aparecem quando o usuário invoca o Share.

Para definir tipos de arquivo:

1. Abra o arquivo de manifesto. Ele deve ser chamado de algo como package.appxmanifest.
2. Na seção Tipos de Arquivo com Suporte da página Declarações, selecione Adicionar Novo.
3. Digite a extensão de nome de arquivo que você deseja dar suporte, por exemplo, ".docx". Você precisa incluir o período. Se você quiser dar suporte a todos os tipos de arquivo, marque a caixa de seleção SupportsAnyFileType .

Para definir formatos de dados:

1. Abra o arquivo de manifesto.
2. Abra a seção Formatos de Dados da página Declarações e, em seguida, selecione Adicionar Nova.
3. Digite o nome do formato de dados compatível, por exemplo, "Texto".

Gerenciar a ativação de compartilhamento

Quando um usuário seleciona seu aplicativo (geralmente selecionando-o em uma lista de aplicativos de destino disponíveis na interface de compartilhamento), um evento OnShareTargetActivated é gerado. Seu aplicativo precisa lidar com esse evento para processar os dados que o usuário deseja compartilhar.

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
    // Code to handle activation goes here. 
} 

Os dados que o usuário deseja compartilhar estão contidos em um objeto ShareOperation. Você pode usar esse objeto para verificar o formato dos dados que ele contém.

ShareOperation shareOperation = args.ShareOperation;
if (shareOperation.Data.Contains(StandardDataFormats.Text))
{
    string text = await shareOperation.Data.GetTextAsync();

    // To output the text from this example, you need a TextBlock control
    // with a name of "sharedContent".
    sharedContent.Text = "Text: " + text;
} 

Status do compartilhamento de relatórios

Em alguns casos, pode levar tempo para que seu aplicativo processe os dados que ele deseja compartilhar. Exemplos incluem usuários compartilhando coleções de arquivos ou imagens. Esses itens são maiores do que uma cadeia de caracteres de texto simples, portanto, demoram mais para serem processados.

shareOperation.ReportStarted(); 

Depois de chamar o ReportStarted, não espere mais nenhuma interação do usuário com seu aplicativo. Como resultado, você não deve chamá-lo a menos que seu aplicativo esteja em um ponto em que ele possa ser ignorado pelo usuário.

Com um compartilhamento estendido, é possível que o usuário ignore o aplicativo de origem antes que seu aplicativo tenha todos os dados do objeto DataPackage. Como resultado, recomendamos que você informe ao sistema quando seu aplicativo adquiriu os dados necessários. Dessa forma, o sistema pode suspender ou encerrar o aplicativo de origem conforme necessário.

shareOperation.ReportSubmittedBackgroundTask(); 

Se algo der errado, chame ReportError para enviar uma mensagem de erro ao sistema. O usuário verá a mensagem quando verificar o status do compartilhamento. Nesse ponto, seu aplicativo é desligado e o compartilhamento é encerrado. O usuário precisará começar novamente para compartilhar o conteúdo em seu aplicativo. Dependendo do seu cenário, você pode decidir que um erro específico não é grave o suficiente para encerrar a operação de compartilhamento. Nesse caso, você pode optar por não chamar ReportError e continuar a compartilhar.

shareOperation.ReportError("Could not reach the server! Try again later."); 

Por fim, quando seu aplicativo tiver processado com êxito o conteúdo compartilhado, você deverá chamar ReportCompleted para informar o sistema.

shareOperation.ReportCompleted();

Ao usar esses métodos, você geralmente os chama na ordem descrita e não os chama mais de uma vez. No entanto, há momentos em que um aplicativo de destino pode chamar ReportDataRetrieved antes de ReportStarted . Por exemplo, o aplicativo pode recuperar os dados como parte de uma tarefa no manipulador de ativação, mas não chamar ReportStarted até que o usuário selecione um botão Compartilhar.

Devolver um QuickLink se o compartilhamento tiver sido bem-sucedido

Quando um usuário seleciona seu aplicativo para receber conteúdo, recomendamos que você crie um QuickLink. Um QuickLink é como um atalho que facilita aos usuários o compartilhamento de informações com seu aplicativo. Por exemplo, você pode criar um QuickLink que abre uma nova mensagem de email pré-configurada com o endereço de email de um amigo.

Um QuickLink deve ter um título, um ícone e uma Id. O título (como "Email Mom") e o ícone aparecem quando o usuário toca no ícone de compartilhamento. A ID é o que seu aplicativo usa para acessar qualquer informação personalizada, como um endereço de email ou credenciais de logon. Quando seu aplicativo cria um QuickLink, o aplicativo retorna o QuickLink para o sistema chamando ReportCompleted.

Um QuickLink realmente não armazena dados. Em vez disso, ele contém um identificador que, quando selecionado, é enviado para seu aplicativo. Seu aplicativo é responsável por armazenar a ID do QuickLink e os dados de usuário correspondentes. Quando o usuário toca no QuickLink, você pode obter seu identificador por meio da propriedade QuickLinkId .

async void ReportCompleted(ShareOperation shareOperation, string quickLinkId, string quickLinkTitle)
{
    QuickLink quickLinkInfo = new QuickLink
    {
        Id = quickLinkId,
        Title = quickLinkTitle,

        // For quicklinks, the supported FileTypes and DataFormats are set 
        // independently from the manifest
        SupportedFileTypes = { "*" },
        SupportedDataFormats = { StandardDataFormats.Text, StandardDataFormats.Uri, 
                StandardDataFormats.Bitmap, StandardDataFormats.StorageItems }
    };

    StorageFile iconFile = await Windows.ApplicationModel.Package.Current.InstalledLocation.CreateFileAsync(
            "assets\\user.png", CreationCollisionOption.OpenIfExists);
    quickLinkInfo.Thumbnail = RandomAccessStreamReference.CreateFromFile(iconFile);
    shareOperation.ReportCompleted(quickLinkInfo);
}

Consulte também

• Comunicação entre aplicativos
• Compartilhar dados
• QuandoAlvoCompartilhadoAtivado
• ReportStarted
• RelatarErro
• RelatórioConcluído
• DadosDoRelatórioRecuperados
• ReportStarted
• Link Rápido
• QuickLInkId