DownloadOperation Classe

  • Riferimento

Definizione

Spazio dei nomi:
Windows.Networking.BackgroundTransfer
Modifica

Esegue un'operazione di download asincrona. L'esempio di trasferimento in background illustra questa funzionalità. Per una panoramica delle funzionalità di trasferimento in background, vedere Trasferimento dei dati in background.

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
Ereditarietà
Object Platform::Object IInspectable DownloadOperation
Attributi
ContractVersionAttribute MarshalingBehaviorAttribute
Implementazioni
IBackgroundTransferOperation IBackgroundTransferOperationPriority

Requisiti Windows

Famiglia di dispositivi
Windows 10 (è stato introdotto in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (è stato introdotto in v1.0)
Funzionalità dell'app
internetClient internetClientServer privateNetworkClientServer

Esempio

Le applicazioni di esempio che usano questa classe includono l'esempio di trasferimento in background.

Nell'esempio seguente viene illustrato come configurare e avviare un'operazione di download di base.

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

Commenti

All'avvio successivo dopo la terminazione dell'applicazione, l'applicazione deve enumerare tutte le istanze DownloadOperation esistenti usando GetCurrentDownloadsAsync. Quando un'applicazione UWP con Trasferimento in background viene terminata, i download incompleti vengono mantenuti in background. Se l'applicazione viene riavviata dopo la terminazione e queste operazioni incomplete non vengono enumerate e introdotte nuovamente alla sessione corrente, verranno interrotte e continueranno a occupare le risorse del dispositivo.

Il trasferimento in background non supporta download simultanei dello stesso URI. Quindi un'app può scaricare http://example.com/myfile.wmv una volta o scaricarla nuovamente dopo il completamento di un download precedente. Un'app non deve avviare due download dello stesso URI simultaneamente, poiché questo potrebbe causare file troncati.

Nota

Le operazioni di download sospese o incomplete possono essere riprese solo se il server accetta richieste di intervallo.

Considerazioni sul timeout

  1. Quando si stabilisce una nuova connessione per un download tramite TCP/SSL, il tentativo di connessione viene interrotto se non stabilito entro cinque minuti.
  2. Dopo aver stabilito la connessione, viene interrotto un messaggio di richiesta HTTP che non ha ricevuto una risposta entro due minuti. Supponendo che sia presente connettività Internet, Il trasferimento in background riprova a un download fino a tre volte. Se la connettività Internet non viene rilevata, non verranno effettuati tentativi aggiuntivi fino a quando non è.

Linee guida per il debug

L'arresto di una sessione di debug in Microsoft Visual Studio è paragonabile alla chiusura dell'app; i download vengono sospesi e i caricamenti POST vengono terminati. Anche durante il debug, l'app deve enumerare e quindi sospendere, riprendere, riavviare o annullare eventuali download persistenti.

Tuttavia, se gli aggiornamenti del progetto di Microsoft Visual Studio, ad esempio le modifiche al manifesto dell'app, richiedono che l'app venga disinstallata e ridistribuiti per il debug, GetCurrentDownloadsAsync non può enumerare operazioni persistenti create usando la distribuzione dell'app precedente.

Cronologia delle versioni

Versione di Windows Versione dell'SDK Valore aggiunto
1709 16299 CurrentWebErrorStatus
1709 16299 GetDownloadedRanges
1709 16299 GetResultRandomAccessStreamReference
1709 16299 IsRandomAccessRequired
1709 16299 RangeDownloaded
1709 16299 RecuperaableWebErrorStatuses
1803 17134 MakeCurrentInTransferGroup
2004 19041 RemoveRequestHeader
2004 19041 SetRequestHeader

Proprietà

CostPolicy

Ottiene e imposta i criteri di costo per il download.
CurrentWebErrorStatus

WebErrorStatus di un trasferimento, che può essere monitorato durante la durata di DownloadOperation.
Group

Nota

Il gruppo può essere modificato o non disponibile per le versioni dopo Windows 8.1. Usare invece TransferGroup.

Ottiene un valore stringa che indica il gruppo a cui appartiene il trasferimento.
Guid

Si tratta di un identificatore univoco per un'operazione di download specifica. Un GUID associato a un'operazione di download non cambierà per la durata del download.
IsRandomAccessRequired

Proprietà booleana per abilitare l'accesso casuale. La proprietà deve essere impostata su TRUE prima di chiamare StartAsync() in un oggetto DownloadOperation per usare la funzionalità di accesso casuale. Dopo aver chiamato StartAsync(), chiamare GetResultRandomAccessStreamReference per ottenere un riferimento al flusso di accesso casuale e leggerlo.
Method

Ottiene il metodo da usare per il download.
Priority

Ottiene o imposta la priorità di trasferimento di questa operazione di download all'interno di backgroundTransferGroup. I valori possibili sono definiti da BackgroundTransferPriority.
Progress

Ottiene lo stato di avanzamento corrente dell'operazione.
RecoverableWebErrorStatuses

Un set di valori WebErrorStatus che le applicazioni prevedono che il download verrà raggiunto e che le applicazioni sanno gestire.
RequestedUri

Ottiene l'URI da cui scaricare il file.
ResultFile

Restituisce l'oggetto IStorageFile fornito dal chiamante durante la creazione dell'oggetto DownloadOperation usando CreateDownload.
TransferGroup

Ottiene il gruppo a cui appartiene l'operazione di download.

Metodi

AttachAsync()

Restituisce un'operazione asincrona che può essere usata per monitorare lo stato di avanzamento e il completamento del download collegato. La chiamata a questo metodo consente a un'app di collegare le operazioni di download avviate in un'istanza precedente dell'app.
GetDownloadedRanges()

Restituisce l'elenco completo degli intervalli di file scaricati finora.
GetResponseInformation()

Ottiene le informazioni sulla risposta.
GetResultRandomAccessStreamReference()

Ottiene un riferimento al flusso di accesso casuale e legge da esso. È necessario impostare IsRandomAccessRequired su TRUE prima di chiamare GetResultRandomAccessStreamReference.
GetResultStreamAt(UInt64)

Ottiene la risposta parzialmente scaricata nella posizione specificata.
MakeCurrentInTransferGroup()

Assegna priorità all'operazione di trasferimento di download (e tutti i trasferimenti che seguono nello stesso gruppo di trasferimento). La chiamata di questo metodo a un trasferimento che non appartiene a un gruppo di trasferimento non ha alcun effetto.
Pause()

Sospende un'operazione di download.
RemoveRequestHeader(String)

Usato per rimuovere un'intestazione di richiesta HTTP.
Resume()

Riprende un'operazione di download sospesa.
SetRequestHeader(String, String)

Usato per impostare un'intestazione di richiesta HTTP.
StartAsync()

Avvia un'operazione di download asincrona.

Eventi

RangesDownloaded

Fornisce l'accesso allo stato di avanzamento del download incrementale.

Si applica a

Vedi anche