BackgroundDownloader Classe

Definizione

Spazio dei nomi:

Windows.Networking.BackgroundTransfer

Usato per configurare i download prima della creazione effettiva dell'operazione di download tramite CreateDownload. Per una panoramica delle funzionalità di trasferimento in background, vedere Trasferimento dei dati in background. Scaricare l'esempio di trasferimento in background per un esempio di codice.

Nota

Il trasferimento in background è progettato principalmente per operazioni di trasferimento a lungo termine per risorse come video, musica e immagini di grandi dimensioni. Per le operazioni a breve termine che coinvolgono trasferimenti di risorse più piccole (ad esempio un paio di KB), usare lo spazio dei nomi 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

Ereditarietà

Object Platform::Object IInspectable BackgroundDownloader

Attributi

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementazioni

IBackgroundTransferBase

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

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

Dopo la terminazione dell'app, un'app deve enumerare tutte le istanze downloadoperation esistenti all'avvio successivo usando GetCurrentDownloadsAsync. Quando un'app UWP con Trasferimento in background viene terminata, i download incompleti verranno mantenuti in background. Se l'app viene riavviata dopo la terminazione e le operazioni della sessione precedente non vengono enumerate e rinesse alla sessione corrente, rimarranno incompleti e continueranno a occupare le risorse.

Nota

Quando un'app viene disinstallata qualsiasi operazione di trasferimento in background corrente o persistente associata a questa operazione viene pulita.

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.

Quando si implementa una libreria per le operazioni di trasferimento in background e questa stessa libreria viene usata da altre app o componenti, specificare una stringa di nomegruppo univoca (ad esempio, un GUID) durante la creazione di download. Un download con una stringa di nome di gruppo può essere enumerato solo fornendo la stringa corrispondente a GetCurrentDownloadsAsync(String) e non verrà visualizzato nelle chiamate GetCurrentDownloadsAsync senza. In questo modo, altre app che implementano la stessa libreria per i download non visualizzeranno i download.

Le operazioni di download tramite FTP sono supportate. Tuttavia, per le operazioni FTP, le credenziali di autenticazione devono essere fornite all'interno dell'URI specificato. Ad esempio, ftp://user:password@server/file.txt.

I problemi di sicurezza possono esistere quando le operazioni di download richiedono un nome utente e una password per l'autenticazione. Se il modello di autenticazione da usare è supportato da WinINet, usare le proprietà ServerCredential o ProxyCredential. Questi valori verranno salvati in modo sicuro in WinVault. Per informazioni sui metodi di autenticazione supportati, vedere Gestione dell'autenticazione.

Se il modello di autenticazione non è supportato da WinINet, usare HttpClient per implementare l'autenticazione personalizzata e ottenere un token sicuro specifico per il download (cookie). Impostare l'intestazione appropriata per avere il valore del token sicuro usato per il trasferimento in background. Il servizio deve limitare la validità del token sicuro solo al file scaricato.

Nota

Il token sicuro verrà archiviato in testo chiaro nella cartella dell'applicazione.

Caricare i servizi che richiedono il nome utente e la password siano impostati in testo chiaro in un'intestazione personalizzata per ogni file di download non sicuro. Il trasferimento in background memorizza nella cache le intestazioni in testo chiaro per la durata dell'operazione all'interno della cartella dell'app.

Notifiche di tipo avviso popup

La classe BackgroundDownloader in Windows 8.1 e Windows Server 2012 R2 supporta le opzioni per l'utente per ricevere notifiche di riquadro e avviso popup quando un trasferimento viene completato correttamente o non riesce a completare.

Un'app che usa Windows.Networking.BackgroundTransfer per comunicare tramite una notifica di tipo avviso popup deve dichiarare che è compatibile con avviso popup nel file manifesto dell'app. L'impostazione In grado di avviso popup si trova nella sezione Notifiche della scheda Applicazione . Impostare l'opzione Avviso popup su "Sì" in modo che l'app possa ricevere notifiche di tipo avviso popup.

Se l'opzione Popup non è abilitata nel manifesto dell'app, tutte le impostazioni di tipo avviso popup nello spazio dei nomi Windows.Networking.BackgroundTransfer verranno ignorate in modo automatico e non verranno ricevute notifiche di tipo avviso popup dall'app.

Nota

Un utente può disabilitare manualmente o abilitare le notifiche popup per l'app in qualsiasi momento.

Per altre informazioni sulle notifiche di tipo avviso popup, vedere Invio di notifiche di tipo avviso popup e Come acconsentire esplicitamente alle notifiche di tipo avviso popup.

Gestione delle eccezioni

Un numero di errori può causare eccezioni durante un'operazione di download. È consigliabile scrivere codice per gestire le eccezioni quando si chiamano metodi in questa classe. Le eccezioni possono causare errori di convalida dei parametri, errori di risoluzione dei nomi e errori di rete. Le eccezioni da errori di rete (perdita di connettività, errori di connessione e altri errori HTTP, ad esempio) possono verificarsi in qualsiasi momento. Questi errori causano la generazione di eccezioni. Se non viene gestita dall'app, un'eccezione può causare la terminazione dell'intera app da parte del runtime.

Un'app può usare HRESULT dall'eccezione per determinare l'errore che ha causato l'eccezione. Un'app può quindi decidere come gestire l'eccezione in base al codice di errore. Il metodo BackgroundTransferError.GetStatus può convertire la maggior parte dei valori HRESULT restituiti in un valore di enumerazione WebErrorStatus . La maggior parte dei valori di enumerazione WebErrorStatus corrisponde a un errore restituito dall'operazione client HTTP o FTP nativa. È possibile applicare filtri per specifici valori di WebErrorStatus allo scopo di modificare il comportamento dell'app a seconda della causa dell'eccezione.

Per informazioni sulle eccezioni di rete, vedere Gestione delle eccezioni nelle app di rete.

Linee guida per il debug

L'arresto di una sessione di debug in Microsoft Visual Studio è paragonabile alla chiusura dell'app. Anche durante il debug, l'app deve enumerare e quindi riprendere, riavviare o annullare eventuali download salvati in modo permanente dalla sessione precedente. Ad esempio, è possibile che l'app annulla le operazioni di download persistenti enumerate all'avvio dell'app se non vi è alcun interesse per le operazioni precedenti per la sessione di debug corrente.

Se sono presenti aggiornamenti del progetto di Microsoft Visual Studio, ad esempio le modifiche al manifesto dell'app e l'app viene disinstallata e ridistribuiti, GetCurrentUploadsAsync non può enumerare le operazioni create usando la distribuzione precedente dell'app.

Per altre informazioni, vedi Debug e test delle app UWP .

Quando si usa trasferimento in background durante lo sviluppo, è possibile che si verifichi una situazione in cui le cache interne delle operazioni di trasferimento attive e completate possono uscire dalla sincronizzazione. Ciò può comportare l'impossibilità di avviare nuove operazioni di trasferimento o di interagire con le operazioni esistenti e gli oggetti BackgroundTransferGroup . In alcuni casi il tentativo di interagire con le operazioni esistenti può generare un arresto anomalo. Questo esito può verificarsi se la proprietà TransferBehavior è impostata su Parallel. Questo problema si verifica solo in alcuni scenari durante lo sviluppo e non è applicabile agli utenti finali dell'app.

Quattro scenari che usano Microsoft Visual Studio possono causare questo problema.

• Crei un nuovo progetto con lo stesso nome di app di un progetto esistente ma in un linguaggio diverso (ad esempio, da C++ a C#).
• Modifichi l'architettura di destinazione (ad esempio, da x86 a x64) in un progetto esistente.
• Modifichi la lingua (ad esempio, da una lingua non associata ad alcun paese a en-US) in un progetto esistente.
• Aggiungi o rimuovi una funzionalità nel manifesto del pacchetto (ad esempio, aggiungendo Autenticazione Enterprise) in un progetto esistente. Le normali operazioni di manutenzione dell'app, inclusi gli aggiornamenti del manifesto che aggiungono o rimuovono funzionalità, non attivano questo problema nelle distribuzioni dell'app per l'utente finale.

Per evitare il problema, disinstalla completamente tutte le versioni dell'app e ridistribuiscila con il nuovo linguaggio, la nuova architettura, la nuova lingua o la nuova funzionalità. Questa operazione può essere eseguita tramite la schermata Start o tramite PowerShell e il Remove-AppxPackage cmdlet .

Costruttori

BackgroundDownloader()	Crea un nuovo oggetto BackgroundDownloader .
BackgroundDownloader(BackgroundTransferCompletionGroup)	Crea un nuovo oggetto BackgroundDownloader con backgroundTransferCompletionGroup.

Proprietà

CompletionGroup	Ottiene backgroundTransferCompletionGroup associato a BackgroundDownloader.
CostPolicy	Ottiene o imposta i criteri di costo per l'operazione di download in background.
FailureTileNotification	Ottiene o imposta l'oggetto TileNotification usato per definire gli oggetti visivi, il tag di identificazione e l'ora di scadenza di una notifica di riquadro usata per aggiornare il riquadro dell'app quando indica un errore di un download all'utente.
FailureToastNotification	Ottiene o imposta l'oggetto ToastNotification che definisce il contenuto, i metadati associati e gli eventi usati in una notifica di tipo avviso popup per indicare l'errore di un download all'utente.
Group	Nota Il gruppo può essere modificato o non disponibile per le versioni dopo Windows 8.1. Usare invece TransferGroup. Ottiene o imposta un valore stringa ,ad esempio un GUID, che indica che il gruppo a cui appartiene il trasferimento. Un'operazione di download con un ID gruppo verrà visualizzata solo nelle enumerazioni dell'operazione usando GetCurrentDownloadsAsync(String) con il valore della stringa di gruppo specifico.
Method	Ottiene o imposta il metodo HTTP usato per il download in background. Il metodo predefinito usato per le operazioni di download è GET.
ProxyCredential	Ottiene o imposta le credenziali proxy per il trasferimento in background.
ServerCredential	Ottiene o imposta le credenziali da usare per l'autenticazione con il server di origine. Nota Per i download tramite FTP, le credenziali di autenticazione devono essere fornite all'interno dell'URI specificato. Ad esempio, ftp://user:password@server/file.txt.
SuccessTileNotification	Ottiene o imposta l'oggetto TileNotification usato per definire gli oggetti visivi, il tag di identificazione e l'ora di scadenza di una notifica di riquadro usata per aggiornare il riquadro dell'app quando indica l'esito positivo di un download all'utente.
SuccessToastNotification	Ottiene o imposta toastNotification che definisce il contenuto, i metadati associati e gli eventi usati in una notifica di tipo avviso popup per indicare l'esito positivo di un download all'utente.
TransferGroup	Ottiene o imposta il gruppo a cui appartiene un'operazione di download.

Metodi

CreateDownload(Uri, IStorageFile)	Inizializza un oggetto DownloadOperation che contiene l'URI specificato e il file a cui viene scritta la risposta.
CreateDownload(Uri, IStorageFile, IStorageFile)	Inizializza un oggetto DownloadOperation con l'URI della risorsa, il file in cui viene scritta la risposta e il corpo dell'entità richiesta.
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	Crea un'operazione di download asincrona che include un URI, il file in cui verrà scritta la risposta e l'oggetto IInputStream da cui vengono letti i contenuti del file.
GetCurrentDownloadsAsync()	Restituisce una raccolta di download in sospeso non associati a backgroundTransferGroup.
GetCurrentDownloadsAsync(String)	Nota GetCurrentDownloadsAsync(group) può essere modificato o non disponibile per le versioni dopo Windows 8.1. Usare invece GetCurrentDownloadsForTransferGroupAsync. Restituisce una raccolta di download in sospeso per un gruppo specifico.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	Ottiene tutti i download associati all'oggetto BackgroundTransferGroup specificato.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	Nota RequestUnconstrainedDownloadsAsync può essere modificato o non disponibile per le versioni dopo Windows 10, versione 1607. Usare invece CreateDownloadAsync. Usato per richiedere un'operazione di download senza vincoli. Quando questo metodo viene chiamato l'utente viene fornito con un prompt dell'interfaccia utente che può usare per indicare il consenso per un'operazione non vincolata. Un'operazione di trasferimento non vincolata verrà eseguita senza restrizioni di risorse normalmente associate alle operazioni di rete in background mentre un dispositivo è in esecuzione sulla batteria.
SetRequestHeader(String, String)	Usato per impostare un'intestazione di richiesta HTTP.

Vedi anche

• DownloadOperation
• Gestione delle eccezioni nelle app di rete
• Come acconsentire esplicitamente alle notifiche di tipo avviso popup
• Guida introduttiva: Scaricare un file
• Esempio di trasferimento in background
• Esempio di trasferimento in background (Windows 8.x)