BackgroundDownloader Classe

Definizione

public ref class BackgroundDownloader sealed

/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class BackgroundDownloader final

/// [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.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[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)]
public sealed class BackgroundDownloader

[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

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.

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.

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.

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

Proprietà

Metodi

Si applica a

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)