BackgroundUploader Classe

Definizione

Spazio dei nomi:

Windows.Networking.BackgroundTransfer

Usato per configurare il caricamento prima della creazione effettiva dell'operazione di caricamento usando CreateUpload. 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 BackgroundUploader 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(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundUploader 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(typeof(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundUploader

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

Ereditarietà

Object Platform::Object IInspectable BackgroundUploader

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 caricamento di base.

using Windows.Foundation; 
using Windows.Networking.BackgroundTransfer;
using Windows.Storage.Pickers;
using Windows.Storage;

private async void StartUpload_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri uri = new Uri(serverAddressField.Text.Trim());
        FileOpenPicker picker = new FileOpenPicker();
        picker.FileTypeFilter.Add("*");
        StorageFile file = await picker.PickSingleFileAsync();

        BackgroundUploader uploader = new BackgroundUploader();
        uploader.SetRequestHeader("Filename", file.Name);

        UploadOperation upload = uploader.CreateUpload(uri, file);

        // Attach progress and completion handlers.
        HandleUploadAsync(upload, true);
    }
    catch (Exception ex)
    {
        LogException("Upload Error", ex);
    }
}

Commenti

Dopo la terminazione dell'app, un'app deve enumerare tutte le istanze di UploadOperation esistenti all'avvio successivo usando GetCurrentUploadsAsync. Quando un'app UWP con Trasferimento in background viene terminata, i caricamenti 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. Dopo l'enumerazione, le operazioni di caricamento PUT vengono riavviate automaticamente e le operazioni di caricamento POST vengono terminate.

Nota

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

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 caricamenti. Un caricamento con una stringa di nome gruppo può essere enumerato solo fornendo la stringa corrispondente a GetCurrentDownloadsAsync(String) e non verrà visualizzato nelle chiamate GetCurrentDownloadsAsync senza. Ciò garantisce che altre app che implementano la stessa libreria per i caricamenti non visualizzeranno i caricamenti

Le operazioni di caricamento tramite FTP non sono supportate.

I problemi di sicurezza possono esistere quando le operazioni di caricamento 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 caricamento (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 caricato.

Nota

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

I servizi di caricamento che richiedono il nome utente e la password vengono impostati in testo chiaro in un'intestazione personalizzata per ogni file di caricamento sono insicuri. 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 BackgroundUploader 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 caricamento. È 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. 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 gestito dall'app, un'eccezione può causare la chiusura dell'intera app dal 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.

Alcuni valori HRESULT non possono essere convertiti in un valore di enumerazione WebErrorStatus . Quando viene annullata un'operazione POST in background, viene generata un'eccezione. L'operazione non viene riavviata. Per altre informazioni, vedere UploadOperation.StartAsync

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: i caricamenti PUT vengono sospesi e i caricamenti POST vengono terminati. Anche durante il debug, l'app deve enumerare e quindi riavviare o annullare qualsiasi caricamento persistente. Puoi fare in modo, ad esempio, che l'app annulli le operazioni di caricamento persistenti enumerate all'avvio dell'app se le operazioni precedenti non sono interessanti per tale sessione di debug.

Mente si enumerano i download/caricamenti all'avvio dell'app durante una sessione di debug, puoi fare in modo che l'app li annulli se le operazioni precedenti non sono interessanti per tale sessione di debug. Si noti che 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

BackgroundUploader()	Crea un'istanza di un nuovo oggetto BackgroundUploader .
BackgroundUploader(BackgroundTransferCompletionGroup)	Crea un'istanza di un nuovo oggetto BackgroundUploader come membro di un gruppo di completamento.

Proprietà

CompletionGroup	Ottiene backgroundTransferCompletionGroup associato a BackgroundUploader.
CostPolicy	Ottiene o imposta i criteri di costo per l'operazione di caricamento in background.
FailureTileNotification	Ottiene e 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'errore di un caricamento 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 caricamento 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 caricamento. Un'operazione di caricamento con un ID gruppo verrà visualizzata solo nelle enumerazioni dell'operazione usando GetCurrentDownloadsAsync(String) con il valore di stringa di gruppo specifico.
Method	Ottiene o imposta il metodo HTTP usato per il caricamento. Il metodo predefinito usato per le operazioni di caricamento è POST.
ProxyCredential	Ottiene o imposta le credenziali proxy per il caricamento.
ServerCredential	Ottiene o imposta le credenziali da usare per l'autenticazione con il server di origine.
SuccessTileNotification	Ottiene e imposta la proprietà TileNotification utilizzata 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 caricamento all'utente.
SuccessToastNotification	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'esito positivo di un caricamento all'utente.
TransferGroup	Ottiene o imposta il gruppo a cui appartiene un'operazione di caricamento.

Metodi

CreateUpload(Uri, IStorageFile)	Inizializza un uploadOperation che indica il percorso per e il file per il caricamento.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Restituisce un'operazione asincrona che, al termine, restituisce un'operazione UploadOperation con l'URI specificato e uno o più oggetti BackgroundTransferContentPart .
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Restituisce un'operazione asincrona che, al termine, restituisce un oggetto UploadOperation con l'URI specificato, uno o più oggetti BackgroundTransferContentPart e il sottotipo multipart.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Restituisce un'operazione asincrona che, al termine, restituisce un'operazione UploadOperation con l'URI, il sottotipo multipart specificato, uno o più oggetti BackgroundTransferContentPart e il valore limite delimitatore utilizzato per separare ogni parte.
CreateUploadFromStreamAsync(Uri, IInputStream)	Restituisce un'operazione asincrona che, al termine, restituisce un'operazione UploadOperation con l'URI specificato e il flusso di origine.
GetCurrentUploadsAsync()	Restituisce una raccolta di caricamenti in sospeso non associati a un gruppo.
GetCurrentUploadsAsync(String)	Nota GetCurrentUploadsAsync(group) può essere modificato o non disponibile per le versioni dopo Windows 8.1. Usare invece GetCurrentUploadsForTransferGroupAsync. Restituisce una raccolta di caricamenti in sospeso per un gruppo specifico.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Ottiene tutti i caricamenti associati all'oggetto BackgroundTransferGroup specificato.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Nota RequestUnconstrainedUploadsAsync può essere modificato o non disponibile per le versioni dopo Windows 10, versione 1607. Usare invece CreateUploadAsync. Usato per richiedere un'operazione di caricamento 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

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