BackgroundUploader Classe

Definição

Namespace:

Windows.Networking.BackgroundTransfer

Usado para configurar o upload antes da criação real da operação de upload usando CreateUpload. Para obter uma visão geral dos recursos de Transferência em Segundo Plano, confira Como transferir dados em segundo plano. Baixe o exemplo de transferência em segundo plano para um exemplo de código.

Observação

A Transferência em Segundo Plano foi projetada principalmente para operações de transferência de longo prazo para recursos como vídeo, música e imagens grandes. Para operações de curto prazo que envolvem transferências de recursos menores (ou seja, alguns KB), use o namespace Windows.Web.Http .

public ref class BackgroundUploader sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundUploader final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundUploader

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

Herança

Object Platform::Object IInspectable BackgroundUploader

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementações

IBackgroundTransferBase

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)
Funcionalidades do aplicativo	internetClient internetClientServer privateNetworkClientServer

Exemplos

O exemplo a seguir demonstra como configurar e iniciar uma operação de upload básica.

using Windows.Foundation; 
using Windows.Networking.BackgroundTransfer;
using Windows.Storage.Pickers;
using Windows.Storage;

private async void StartUpload_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri uri = new Uri(serverAddressField.Text.Trim());
        FileOpenPicker picker = new FileOpenPicker();
        picker.FileTypeFilter.Add("*");
        StorageFile file = await picker.PickSingleFileAsync();

        BackgroundUploader uploader = new BackgroundUploader();
        uploader.SetRequestHeader("Filename", file.Name);

        UploadOperation upload = uploader.CreateUpload(uri, file);

        // Attach progress and completion handlers.
        HandleUploadAsync(upload, true);
    }
    catch (Exception ex)
    {
        LogException("Upload Error", ex);
    }
}

Comentários

Após o encerramento do aplicativo, um aplicativo deve enumerar todas as instâncias existentes de UploadOperation na próxima inicialização usando GetCurrentUploadsAsync. Quando um aplicativo UWP que usa a Transferência em Segundo Plano é encerrado, os uploads incompletos persistirão em segundo plano. Se o aplicativo for reiniciado após o encerramento e as operações da sessão anterior não forem enumeradas e anexadas novamente à sessão atual, elas permanecerão incompletas e continuarão ocupando recursos. Depois de enumeradas, as operações de carregamento PUT são reiniciadas automaticamente e as operações de upload POST são encerradas.

Observação

Quando um aplicativo é desinstalado, todas as operações atuais ou persistentes de Transferência em Segundo Plano associadas a ele são limpas.

Ao implementar uma biblioteca para operações de Transferência em Segundo Plano e essa mesma biblioteca é usada por outros aplicativos ou componentes, especifique uma cadeia de caracteres de nome degrupo exclusiva (por exemplo, um GUID) ao criar uploads. Um upload com uma cadeia de caracteres de nome de grupo só pode ser enumerado fornecendo a cadeia de caracteres correspondente para GetCurrentDownloadsAsync(String)e não aparecerá em chamadas GetCurrentDownloadsAsync sem. Isso garantirá que outros aplicativos que implementam a mesma biblioteca para uploads não vejam seus uploads

Não há suporte para operações de upload via FTP.

Preocupações de segurança podem existir quando as operações de upload exigem um nome de usuário e uma senha para autenticação. Se o modelo de autenticação a ser usado tiver suporte do WinINet, use as propriedades ServerCredential ou ProxyCredential . Esses valores serão salvos com segurança no WinVault. Para obter informações sobre métodos de autenticação com suporte, consulte Manipulando a autenticação.

Se o modelo de autenticação não tiver suporte do WinINet, use HttpClient para implementar a autenticação personalizada e obter um token seguro específico de upload (cookie). Defina o cabeçalho apropriado para ter o valor do token seguro usado para transferência em segundo plano. O serviço deve limitar a validade do token seguro somente ao arquivo que está sendo carregado.

Observação

O token seguro será armazenado em texto não criptografado dentro da pasta do aplicativo.

Os serviços de upload que exigem que o nome de usuário e a senha sejam definidos em texto não criptografado em um cabeçalho personalizado para cada arquivo de upload não são seguros. A transferência em segundo plano armazenará em cache os cabeçalhos em texto não criptografado durante a operação dentro da pasta do aplicativo.

Notificações do sistema

A classe BackgroundUploader no Windows 8.1 e no Windows Server 2012 R2 dá suporte a opções para o usuário receber notificações do bloco e do sistema quando uma transferência for concluída com êxito ou falhar na conclusão.

Um aplicativo que usa Windows.Networking.BackgroundTransfer para se comunicar por meio de uma notificação do sistema deve declarar que ele é compatível com Toast no arquivo de manifesto do aplicativo. A configuração compatível com o Sistema está localizada na seção Notificações da guia Aplicativo . Defina a opção Do sistema como "Sim" para que o aplicativo possa receber notificações do sistema.

Se a capacidade do Sistema não estiver habilitada no manifesto do aplicativo, as configurações do sistema no namespace Windows.Networking.BackgroundTransfer serão ignoradas silenciosamente e nenhuma notificação do sistema será recebida pelo aplicativo.

Observação

Um usuário pode desabilitar ou habilitar manualmente as notificações do sistema para seu aplicativo a qualquer momento.

Para obter mais informações sobre notificações do sistema, consulte Enviando notificações do sistema e Como aceitar notificações do sistema.

Tratamento de exceções

Vários erros podem fazer com que exceções ocorram durante uma operação de upload. Você deve escrever código para lidar com exceções ao chamar métodos nessa classe. As exceções podem resultar de erros de validação de parâmetro, falhas de resolução de nomes e erros de rede. Exceções de erros de rede (perda de conectividade, falhas de conexão e outros erros HTTP, por exemplo) podem ocorrer a qualquer momento. Esses erros geram exceções. Se não for tratada pelo aplicativo, uma exceção poderá fazer com que todo o aplicativo seja encerrado pelo runtime.

Um aplicativo pode usar o HRESULT da exceção para determinar o erro que causou a exceção. Em seguida, um aplicativo pode decidir como lidar com a exceção com base no código de erro. O método BackgroundTransferError.GetStatus pode converter a maioria dos valores HRESULT retornados para um valor de enumeração WebErrorStatus . A maioria dos valores de enumeração WebErrorStatus corresponde a um erro retornado pela operação nativa de cliente HTTP ou FTP. Um aplicativo pode filtrar por um valor específico de enumeração WebErrorStatus para modificar o comportamento do aplicativo, dependendo da causa da exceção.

Alguns valores HRESULT não podem ser convertidos em um valor de enumeração WebErrorStatus . Quando uma operação POST em segundo plano é cancelada, uma exceção é gerada. A operação não é reiniciada. Para obter mais informações, consulte UploadOperation.StartAsync

Para obter informações sobre exceções de rede, consulte Tratamento de exceções em aplicativos de rede.

Diretrizes de depuração

Parar uma sessão de depuração no Microsoft Visual Studio é comparável a fechar seu aplicativo; uploads PUT são pausados e uploads POST são finalizados. Mesmo durante a depuração, seu aplicativo deve enumerar e então reiniciar ou cancelar quaisquer uploads que persistam. Por exemplo, você pode fazer com que seu aplicativo cancele as operações de upload enumeradas e existentes na inicialização do aplicativo se não houver interesse nas operações anteriores para essa sessão de depuração.

Enquanto numera downloads/uploads na inicialização do aplicativo, durante uma sessão de depuração, seu aplicativo poderá cancelá-los se não houver interesse nas operações anteriores para essa sessão de depuração. Observe que, se houver atualizações de projeto do Microsoft Visual Studio, como alterações no manifesto do aplicativo e o aplicativo estiver desinstalado e implantado novamente, GetCurrentUploadsAsync não poderá enumerar as operações criadas usando a implantação anterior do aplicativo.

Consulte Depurando e testando aplicativos UWP para obter mais informações.

Ao usar a Transferência em segundo plano durante o desenvolvimento, talvez você esteja em uma situação na qual os caches internos das operações de transferência ativas e concluídas podem ficar fora de sincronia. Isso pode resultar na incapacidade de iniciar novas operações de transferência ou de interagir com operações existentes e objetos BackgroundTransferGroup. Em alguns casos, a tentativa de interagir com operações existentes pode gerar uma falha. Isso pode ocorrer se a propriedade TransferBehavior estiver definida para Parallel. Esse problema ocorre somente em determinados cenários, durante o desenvolvimento, e não se aplica a usuários finais de seu aplicativo.

Quatro cenários que usam o Microsoft Visual Studio podem causar esse problema.

• Você pode criar um novo projeto com o mesmo nome de aplicativo de um projeto existente, mas em uma linguagem diferente (de C++ para C#, por exemplo).
• Você pode alterar a arquitetura de destino (de x86 para x64, por exemplo) em um projeto existente.
• Você pode alterar a cultura (de neutra para en-US, por exemplo) em um projeto existente.
• Você pode adicionar ou remover um recurso no manifesto do pacote (adicionando Autenticação Empresarial, por exemplo) em um projeto existente. Aplicativos comuns em serviço, incluindo atualizações de manifesto, que adicionam ou removem recursos, não geram esse problema nas implantações de usuário final para seu aplicativos.

Para contornar esse problema, desinstale completamente todas as versões do aplicativo e reimplante com a nova linguagem, arquitetura, cultura ou recurso. Isso pode ser feito por meio da tela Inicial ou usando o PowerShell e o Remove-AppxPackage cmdlet .

Construtores

BackgroundUploader()	Cria uma instância de um novo objeto BackgroundUploader .
BackgroundUploader(BackgroundTransferCompletionGroup)	Cria uma instância de um novo objeto BackgroundUploader como membro de um grupo de conclusão.

Propriedades

CompletionGroup	Obtém o BackgroundTransferCompletionGroup associado ao BackgroundUploader.
CostPolicy	Obtém ou define a política de custo para a operação de upload em segundo plano.
FailureTileNotification	Obtém e define a TileNotification usada para definir os visuais, a marca de identificação e o tempo de expiração de uma notificação de bloco usada para atualizar o bloco do aplicativo ao indicar falha de um upload para o usuário.
FailureToastNotification	Obtém ou define o ToastNotification que define o conteúdo, os metadados associados e os eventos usados em uma notificação do sistema para indicar a falha de um upload para o usuário.
Group	Observação O grupo pode ser alterado ou indisponível para versões após Windows 8.1. Em vez disso, use TransferGroup. Obtém ou define um valor de cadeia de caracteres (por exemplo, um GUID) que indica o grupo ao qual o upload pertencerá. Uma operação de upload com uma ID de grupo só aparecerá em enumerações de operação usando GetCurrentDownloadsAsync(String) com o valor de cadeia de caracteres de grupo específico.
Method	Obtém ou define o método HTTP usado para o upload. O método padrão usado para operações de upload é POST.
ProxyCredential	Obtém ou define as credenciais de proxy para o upload.
ServerCredential	Obtém ou define as credenciais a serem usadas para autenticar com o servidor de origem.
SuccessTileNotification	Obtém e define a TileNotification usada para definir os visuais, a marca de identificação e o tempo de expiração de uma notificação de bloco usada para atualizar o bloco do aplicativo ao indicar o êxito de um upload para o usuário.
SuccessToastNotification	Obtém ou define o ToastNotification que define o conteúdo, os metadados associados e os eventos usados em uma notificação do sistema para indicar o sucesso de um upload para o usuário.
TransferGroup	Obtém ou define o grupo ao qual uma operação de upload pertencerá.

Métodos

CreateUpload(Uri, IStorageFile)	Inicializa uma UploadOperation que indica o local e o arquivo para upload.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Retorna uma operação assíncrona que, após a conclusão, retorna uma UploadOperation com o URI especificado e um ou mais objetos BackgroundTransferContentPart .
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Retorna uma operação assíncrona que, após a conclusão, retorna uma UploadOperation com o URI especificado, um ou mais objetos BackgroundTransferContentPart e o subtipo de várias partes.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Retorna uma operação assíncrona que, após a conclusão, retorna uma UploadOperation com o URI, o subtipo de várias partes especificados, um ou mais objetos BackgroundTransferContentPart e o valor de limite do delimitador usado para separar cada parte.
CreateUploadFromStreamAsync(Uri, IInputStream)	Retorna uma operação assíncrona que, após a conclusão, retorna uma UploadOperation com o URI especificado e o fluxo de origem.
GetCurrentUploadsAsync()	Retorna uma coleção de uploads pendentes que não estão associados a um grupo.
GetCurrentUploadsAsync(String)	Observação GetCurrentUploadsAsync(group) pode ser alterado ou indisponível para versões após Windows 8.1. Em vez disso, use GetCurrentUploadsForTransferGroupAsync. Retorna uma coleção de uploads pendentes para um Grupo específico.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Obtém todos os uploads associados ao BackgroundTransferGroup fornecido.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Observação RequestUnconstrainedUploadsAsync pode ser alterado ou indisponível para versões após o Windows 10, versão 1607. Em vez disso, use CreateUploadAsync. Usado para solicitar uma operação de carregamento irrestrita. Quando esse método é chamado, o usuário recebe um prompt de interface do usuário que ele pode usar para indicar seu consentimento para uma operação irrestrita. Uma operação de transferência irrestrita será executada sem as restrições de recursos normalmente associadas às operações de rede em segundo plano enquanto um dispositivo estiver em execução na bateria.
SetRequestHeader(String, String)	Usado para definir um cabeçalho de solicitação HTTP.

Confira também

• UploadOperation
• Tratamento de exceções em aplicativos de rede
• Como aceitar notificações do sistema
• Início Rápido: Carregar um arquivo
• Exemplo de transferência em segundo plano
• Exemplo de transferência em segundo plano (Windows 8.x)