DownloadOperation Classe

Riferimento

Definizione

Spazio dei nomi:: Windows.Networking.BackgroundTransfer

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

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

Quando si stabilisce una nuova connessione per un download tramite TCP/SSL, il tentativo di connessione viene interrotto se non stabilito entro cinque minuti.
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

Condividi tramite