BackgroundDownloader Classe

Definição

Namespace:

Windows.Networking.BackgroundTransfer

Usado para configurar downloads antes da criação real da operação de download usando CreateDownload. 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 BackgroundDownloader 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(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundDownloader 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(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundDownloader

function BackgroundDownloader(completionGroup)

Public NotInheritable Class BackgroundDownloader

Herança

Object Platform::Object IInspectable BackgroundDownloader

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 básica de download.

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

private async void StartDownload_Click(object sender, RoutedEventArgs e)
 {
     try
     {
         Uri source = new Uri(serverAddressField.Text.Trim());
         string destination = fileNameField.Text.Trim();

         StorageFile destinationFile = await KnownFolders.PicturesLibrary.CreateFileAsync(
             destination, CreationCollisionOption.GenerateUniqueName);

         BackgroundDownloader downloader = new BackgroundDownloader();
         DownloadOperation download = downloader.CreateDownload(source, destinationFile);

         // Attach progress and completion handlers.
         HandleDownloadAsync(download, true);
     }
     catch (Exception ex)
     {
         LogException("Download Error", ex);
     }
 }

Comentários

Após o encerramento do aplicativo, um aplicativo deve enumerar todas as instâncias downloadOperation existentes na próxima inicialização usando GetCurrentDownloadsAsync. Quando um aplicativo UWP que usa a Transferência em Segundo Plano é encerrado, os downloads 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.

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.

A transferência em segundo plano não dá suporte a downloads simultâneos do mesmo URI. Portanto, um aplicativo pode baixar http://example.com/myfile.wmv uma vez ou baixá-lo novamente após a conclusão de um download anterior. Um aplicativo não deve iniciar dois downloads do mesmo Uri simultaneamente, pois isso pode resultar em arquivos truncados.

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 downloads. Um download 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 downloads não vejam seus downloads.

Há suporte para operações de download via FTP. No entanto, para operações ftp, as credenciais de autenticação devem ser fornecidas dentro do URI especificado. Por exemplo, ftp://user:password@server/file.txt.

As preocupações de segurança podem existir quando as operações de download 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 do download (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 baixado.

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 download 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 BackgroundDownloader no Windows 8.1 e no Windows Server 2012 R2 dá suporte a opções para o usuário receber notificações de 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 download. 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.

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

Diretrizes de depuração

Interromper uma sessão de depuração no Microsoft Visual Studio é comparável ao fechamento do aplicativo. Mesmo durante a depuração, seu aplicativo deve enumerar e, em seguida, retomar, reiniciar ou cancelar quaisquer downloads persistentes da sessão anterior. Por exemplo, você pode fazer com que seu aplicativo cancele operações de download persistentes enumeradas na inicialização do aplicativo se não houver interesse em operações anteriores para a sessão de depuração atual.

Se houver atualizações de projeto do Microsoft Visual Studio, como alterações no manifesto do aplicativo, e o aplicativo for 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

BackgroundDownloader()	Cria um novo objeto BackgroundDownloader .
BackgroundDownloader(BackgroundTransferCompletionGroup)	Cria um novo objeto BackgroundDownloader com um BackgroundTransferCompletionGroup.

Propriedades

CompletionGroup	Obtém o BackgroundTransferCompletionGroup associado ao BackgroundDownloader.
CostPolicy	Obtém ou define a política de custo para a operação de download em segundo plano.
FailureTileNotification	Obtém ou 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 a falha de um download 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 download 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 a transferência pertencerá. Uma operação de download 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 download em segundo plano. O método padrão usado para operações de download é GET.
ProxyCredential	Obtém ou define as credenciais de proxy para a transferência em segundo plano.
ServerCredential	Obtém ou define as credenciais a serem usadas para autenticar com o servidor de origem. Observação Para downloads via FTP, as credenciais de autenticação devem ser fornecidas dentro do URI especificado. Por exemplo, ftp://user:password@server/file.txt.
SuccessTileNotification	Obtém ou 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 download 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 download para o usuário.
TransferGroup	Obtém ou define o grupo ao qual uma operação de download pertencerá.

Métodos

CreateDownload(Uri, IStorageFile)	Inicializa um objeto DownloadOperation que contém o Uri especificado e o arquivo no qual a resposta é gravada.
CreateDownload(Uri, IStorageFile, IStorageFile)	Inicializa um objeto DownloadOperation com o URI do recurso, o arquivo no qual a resposta é gravada e o corpo da entidade de solicitação.
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	Cria uma operação de download assíncrona que inclui um URI, o arquivo no qual a resposta será gravada e o objeto IInputStream do qual o conteúdo do arquivo é lido.
GetCurrentDownloadsAsync()	Retorna uma coleção de downloads pendentes que não estão associados a um BackgroundTransferGroup.
GetCurrentDownloadsAsync(String)	Observação GetCurrentDownloadsAsync(group) pode ser alterado ou indisponível para versões após Windows 8.1. Em vez disso, use GetCurrentDownloadsForTransferGroupAsync. Retorna uma coleção de downloads pendentes para um Grupo específico.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	Obtém todos os downloads associados ao BackgroundTransferGroup fornecido.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	Observação RequestUnconstrainedDownloadsAsync pode ser alterado ou indisponível para versões após o Windows 10, versão 1607. Em vez disso, use CreateDownloadAsync. Usado para solicitar uma operação de download 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

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