DownloadOperation Classe

Definição

Namespace:

Windows.Networking.BackgroundTransfer

Executa uma operação de download assíncrona. O exemplo de transferência em segundo plano demonstra essa funcionalidade. Para obter uma visão geral dos recursos de Transferência em Segundo Plano, confira Como transferir dados em segundo plano.

public ref class DownloadOperation sealed : IBackgroundTransferOperationPriority

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class DownloadOperation final : IBackgroundTransferOperationPriority

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class DownloadOperation : IBackgroundTransferOperationPriority

Public NotInheritable Class DownloadOperation
Implements IBackgroundTransferOperationPriority

Herança

Object Platform::Object IInspectable DownloadOperation

Atributos

ContractVersionAttribute MarshalingBehaviorAttribute

Implementações

IBackgroundTransferOperation IBackgroundTransferOperationPriority

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

Os aplicativos de exemplo que usam essa classe incluem o exemplo de transferência em segundo plano.

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

Na próxima inicialização após o encerramento do aplicativo, seu aplicativo deve enumerar todas as instâncias DownloadOperation existentes usando GetCurrentDownloadsAsync. Quando um aplicativo UWP que usa a Transferência em Segundo Plano é encerrado, os downloads incompletos persistem em segundo plano. Se o aplicativo for reiniciado após o encerramento e essas operações incompletas não forem enumeradas e introduzidas novamente na sessão atual, elas ficarão obsoletas e continuarão ocupando os recursos do dispositivo.

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.

Observação

As operações de download pausadas ou incompletas só poderão ser retomadas se o servidor aceitar solicitações de intervalo.

Considerações sobre tempo limite

1. Ao estabelecer uma nova conexão para um download por TCP/SSL, a tentativa de conexão será anulada se não for estabelecida dentro de cinco minutos.
2. Depois que a conexão for estabelecida, uma mensagem de solicitação HTTP que não recebeu uma resposta dentro de dois minutos será anulada. Supondo que haja conectividade com a Internet, a Transferência em Segundo Plano repetirá um download até três vezes. Caso a conectividade com a Internet não seja detectada, não serão feitas tentativas adicionais até que ela seja.

Diretrizes de depuração

Interromper uma sessão de depuração no Microsoft Visual Studio é comparável ao fechamento do aplicativo; os downloads são pausados e os uploads POST são encerrados. Mesmo durante a depuração, seu aplicativo deve enumerar e, em seguida, pausar, retomar, reiniciar ou cancelar quaisquer downloads persistentes.

No entanto, se o projeto do Microsoft Visual Studio for atualizado, como alterações no manifesto do aplicativo, exigir que o aplicativo seja desinstalado e implantado novamente para depuração, GetCurrentDownloadsAsync não poderá enumerar as operações persistentes criadas usando a implantação anterior do aplicativo.

Histórico de versão

Versão do Windows	Versão do SDK	Valor adicionado
1.709	16299	CurrentWebErrorStatus
1.709	16299	GetDownloadedRanges
1.709	16299	GetResultRandomAccessStreamReference
1.709	16299	IsRandomAccessRequired
1.709	16299	IntervalosDownloaded
1.709	16299	RecoverableWebErrorStatuses
1803	17134	MakeCurrentInTransferGroup
2004	19041	RemoveRequestHeader
2004	19041	SetRequestHeader

Propriedades

CostPolicy	Obtém e define a política de custo para o download.
CurrentWebErrorStatus	O WebErrorStatus de uma transferência, que pode ser monitorado durante o tempo de vida da DownloadOperation.
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 um valor de cadeia de caracteres que indica o grupo ao qual a transferência pertence.
Guid	Esse é um identificador exclusivo para uma operação de download específica. Um GUID associado a uma operação de download não será alterado durante o download.
IsRandomAccessRequired	Uma propriedade booliana para habilitar o acesso aleatório. A propriedade deve ser definida como TRUE antes de chamar StartAsync() em um objeto DownloadOperation para usar o recurso de acesso aleatório. Depois de chamar StartAsync(), chame GetResultRandomAccessStreamReference para obter uma referência ao fluxo de acesso aleatório e lê-lo.
Method	Obtém o método a ser usado para o download.
Priority	Obtém ou define a prioridade de transferência dessa operação de download quando está em um BackgroundTransferGroup. Os valores possíveis são definidos por BackgroundTransferPriority.
Progress	Obtém o progresso atual da operação.
RecoverableWebErrorStatuses	Um conjunto de valores WebErrorStatus que os aplicativos antecipam que o download será atingido e que os aplicativos sabem como lidar.
RequestedUri	Obtém o URI do qual baixar o arquivo.
ResultFile	Retorna o objeto IStorageFile fornecido pelo chamador ao criar o objeto DownloadOperation usando CreateDownload.
TransferGroup	Obtém o grupo ao qual esta operação de download pertence.

Métodos

AttachAsync()	Retorna uma operação assíncrona que pode ser usada para monitorar o progresso e a conclusão do download anexado. Chamar esse método permite que um aplicativo anexe operações de download iniciadas em uma instância de aplicativo anterior.
GetDownloadedRanges()	Retorna a lista completa de intervalos de arquivos que foram baixados até agora.
GetResponseInformation()	Obtém as informações de resposta.
GetResultRandomAccessStreamReference()	Obtém uma referência ao fluxo de acesso aleatório e lê dele. É necessário definir IsRandomAccessRequired como TRUE antes de chamar GetResultRandomAccessStreamReference.
GetResultStreamAt(UInt64)	Obtém a resposta parcialmente baixada na posição especificada.
MakeCurrentInTransferGroup()	Prioriza a operação de transferência de download (e todas as transferências que a seguem no mesmo grupo de transferência). Chamar esse método em uma transferência que não pertence a um grupo de transferência não tem efeito.
Pause()	Pausa uma operação de download.
RemoveRequestHeader(String)	Usado para remover um cabeçalho de solicitação HTTP.
Resume()	Retoma uma operação de download pausada.
SetRequestHeader(String, String)	Usado para definir um cabeçalho de solicitação HTTP.
StartAsync()	Inicia uma operação de download assíncrona.

Eventos

RangesDownloaded

Fornece acesso ao progresso do download incremental.

Confira também

• Início Rápido: Baixar um arquivo
• Exemplo de transferência em segundo plano
• Exemplo de transferência em segundo plano (Windows 8.x)