BackgroundUploader Classe

Définition

Espace de noms:

Windows.Networking.BackgroundTransfer

Permet de configurer le chargement avant la création réelle de l’opération de chargement à l’aide de CreateUpload. Pour obtenir une vue d’ensemble des fonctionnalités de transfert en arrière-plan, consultez Transfert de données en arrière-plan. Téléchargez l’exemple de transfert en arrière-plan pour un exemple de code.

Notes

Le transfert en arrière-plan est principalement conçu pour les opérations de transfert à long terme pour des ressources telles que la vidéo, la musique et les images volumineuses. Pour les opérations à court terme impliquant des transferts de ressources plus petites (c’est-à-dire quelques Ko), utilisez l’espace de noms 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

Héritage

Object Platform::Object IInspectable BackgroundUploader

Attributs

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implémente

IBackgroundTransferBase

Configuration requise pour Windows

Famille d’appareils	Windows 10 (introduit dans 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduit dans v1.0)
Fonctionnalités de l’application	internetClient internetClientServer privateNetworkClientServer

Exemples

L’exemple suivant montre comment configurer et commencer une opération de chargement de 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);
    }
}

Remarques

Après l’arrêt de l’application, une application doit énumérer toutes les instances UploadOperation existantes au prochain démarrage à l’aide de GetCurrentUploadsAsync. Lorsqu’une application UWP utilisant le transfert en arrière-plan est arrêtée, les téléchargements incomplets persistent en arrière-plan. Si l’application est redémarrée après l’arrêt et que les opérations de la session précédente ne sont pas énumérées et re-attachées à la session actuelle, elles restent incomplètes et continuent d’occuper les ressources. Une fois énumérées, les opérations de chargement PUT sont automatiquement redémarrées et les opérations de chargement POST sont terminées.

Notes

Lorsqu’une application est désinstallée, toutes les opérations de transfert en arrière-plan actuelles ou persistantes qui lui sont associées sont nettoyées.

Lorsque vous implémentez une bibliothèque pour les opérations de transfert en arrière-plan, et que cette même bibliothèque est utilisée par d’autres applications ou composants, spécifiez une chaîne de nom degroupe unique (par exemple, un GUID) lors de la création de chargements. Un chargement avec une chaîne de nom de groupe ne peut être énuméré qu’en fournissant la chaîne correspondante à GetCurrentDownloadsAsync(String), et n’apparaîtra pas dans les appels GetCurrentDownloadsAsync sans. Cela garantit que les autres applications qui implémentent cette même bibliothèque pour les chargements ne verront pas vos chargements

Les opérations de chargement via FTP ne sont pas prises en charge.

Des problèmes de sécurité peuvent exister lorsque les opérations de chargement nécessitent un nom d’utilisateur et un mot de passe pour l’authentification. Si le modèle d’authentification à utiliser est pris en charge par WinINet, utilisez les propriétés ServerCredential ou ProxyCredential . Ces valeurs seront enregistrées en toute sécurité dans WinVault. Pour plus d’informations sur les méthodes d’authentification prises en charge, consultez Gestion de l’authentification.

Si le modèle d’authentification n’est pas pris en charge par WinINet, utilisez HttpClient pour implémenter l’authentification personnalisée et obtenir un jeton sécurisé (cookie) spécifique au chargement. Définissez l’en-tête approprié pour que la valeur du jeton sécurisé soit utilisée pour le transfert en arrière-plan. Le service doit limiter la validité du jeton sécurisé uniquement au fichier en cours de chargement.

Notes

Le jeton sécurisé sera stocké en texte clair dans le dossier de l’application.

Les services de chargement qui nécessitent que le nom d’utilisateur et le mot de passe soient définis en texte clair dans un en-tête personnalisé pour chaque fichier de chargement ne sont pas sécurisés. Le transfert en arrière-plan met en cache les en-têtes en texte clair pendant la durée de l’opération dans le dossier de l’application.

Notifications toast

La classe BackgroundUploader dans Windows 8.1 et Windows Server 2012 R2 prend en charge les options permettant à l’utilisateur de recevoir des notifications de vignette et de toast lorsqu’un transfert est terminé ou échoue.

Une application qui utilise Windows.Networking.BackgroundTransfer pour communiquer via une notification toast doit déclarer qu’elle est compatible Toast dans le fichier manifeste de l’application. Le paramètre compatible Toast se trouve sous la section Notifications de l’onglet Application . Définissez l’option compatible Toast sur « Oui » afin que l’application puisse recevoir des notifications toast.

Si la prise en charge toast n’est pas activée dans le manifeste de l’application, tous les paramètres toast de l’espace de noms Windows.Networking.BackgroundTransfer seront ignorés en mode silencieux et aucune notification toast ne sera reçue par l’application.

Notes

Un utilisateur peut désactiver ou activer manuellement les notifications toast pour votre application à tout moment.

Pour plus d’informations sur les notifications toast, consultez Envoi de notifications toast et Comment accepter des notifications toast.

Gestion des exceptions

Un certain nombre d’erreurs peuvent provoquer des exceptions lors d’une opération de chargement. Vous devez écrire du code pour gérer les exceptions lorsque vous appelez des méthodes sur cette classe. Les exceptions peuvent résulter d’erreurs de validation de paramètres, d’échecs de résolution de noms et d’erreurs réseau. Des exceptions aux erreurs réseau (perte de connectivité, échecs de connexion et autres erreurs HTTP, par exemple) peuvent se produire à tout moment. Ces erreurs donnent lieu à la levée d’exceptions. Si elle n’est pas gérée par votre application, une exception peut entraîner l’arrêt de l’ensemble de votre application par le runtime.

Une application peut utiliser hresult de l’exception pour déterminer l’erreur qui a provoqué l’exception. Une application peut ensuite décider comment gérer l’exception en fonction du code d’erreur. La méthode BackgroundTransferError.GetStatus peut convertir la plupart des valeurs HRESULT retournées en valeur d’énumération WebErrorStatus . La plupart des valeurs d’énumération WebErrorStatus correspondent à une erreur retournée par l’opération cliente HTTP ou FTP native. Une application peut filtrer sur des valeurs d’énumération WebErrorStatus spécifiques pour modifier son comportement en fonction de la cause de l’exception.

Certaines valeurs HRESULT ne peuvent pas être converties en valeur d’énumération WebErrorStatus . Lorsqu’une opération POST en arrière-plan est annulée, une exception est levée. L’opération n’est pas redémarrée. Pour plus d’informations, consultez UploadOperation.StartAsync

Pour plus d’informations sur les exceptions réseau, consultez Gestion des exceptions dans les applications réseau.

Conseils de débogage

L’arrêt d’une session de débogage dans Microsoft Visual Studio est comparable à la fermeture de votre application ; les chargements PUT sont mis en pause et les chargements POST sont arrêtés. Même pendant le débogage, votre application doit énumérer, puis redémarrer ou annuler les chargements persistants. Par exemple, votre application peut annuler l’énumération des opérations de chargement persistantes, au démarrage, si les opérations précédentes n’ont pas d’intérêt pour cette session de débogage.

Vous pouvez faire en sorte que votre application annule l’énumération des opérations de téléchargement/chargement au démarrage durant une session de débogage, si les opérations précédentes n’ont pas d’intérêt pour cette session de débogage. Notez que s’il existe des mises à jour de projet Microsoft Visual Studio, telles que des modifications apportées au manifeste de l’application, et que l’application est désinstallée et redéployée, GetCurrentUploadsAsync ne peut pas énumérer les opérations créées à l’aide du déploiement d’application précédent.

Pour plus d’informations, consultez Débogage et test d’applications UWP .

Quand vous utilisez le transfert en arrière-plan durant le développement, il arrive que les caches internes des opérations de transfert actives et terminées se désynchronisent. Cela peut entraîner l’incapacité à démarrer de nouvelles opérations de transfert ou à interagir avec les opérations et les objets BackgroundTransferGroup existants. Dans certains cas, toute tentative d’interaction avec des opérations existantes peut déclencher un blocage. Cela peut se produire si la propriété TransferBehavior a la valeur Parallel. Ce problème ne se produit que dans certains scénarios de développement et n’est pas applicable à l’utilisateur final de votre application.

Quatre scénarios d’utilisation de Microsoft Visual Studio peuvent provoquer ce problème.

• Vous créez un projet avec le même nom d’application qu’un projet existant, mais dans un autre langage (en passant du C++ au C#, par exemple).
• Vous modifiez l’architecture cible (en passant de l’architecture x86 à x64, par exemple) dans un projet existant.
• Vous modifiez la culture (en passant de la culture neutre à fr-FR, par exemple) dans un projet existant.
• Vous ajoutez ou supprimez une fonctionnalité du manifeste du package (en ajoutant l’authentification en entreprise, par exemple) dans un projet existant. La maintenance régulière de l’application, notamment les mises à jour du manifeste qui entraînent l’ajout ou la suppression de fonctionnalités, ne déclenche pas ce problème pour les déploiements de votre application destinés à l’utilisateur final.

Pour contourner ce problème, désinstallez complètement toutes les versions de l’application, puis redéployez-la en utilisant le nouveau langage, la nouvelle architecture, la nouvelle culture ou la nouvelle fonctionnalité. Cela peut être effectué via l’écran d’accueil ou à l’aide de PowerShell et de l’applet de Remove-AppxPackage commande.

Constructeurs

BackgroundUploader()	Instancie un nouvel objet BackgroundUploader .
BackgroundUploader(BackgroundTransferCompletionGroup)	Instancie un nouvel objet BackgroundUploader en tant que membre d’un groupe d’achèvement.

Propriétés

CompletionGroup	Obtient le BackgroundTransferCompletionGroup associé à BackgroundUploader.
CostPolicy	Obtient ou définit la stratégie de coût pour l’opération de chargement en arrière-plan.
FailureTileNotification	Obtient et définit la vignette TileNotification utilisée pour définir les visuels, la balise d’identification et l’heure d’expiration d’une notification de vignette utilisée pour mettre à jour la vignette d’application lors de l’indication de l’échec d’un chargement vers l’utilisateur.
FailureToastNotification	Obtient ou définit la toastNotification qui définit le contenu, les métadonnées associées et les événements utilisés dans une notification toast pour indiquer l’échec d’un chargement vers l’utilisateur.
Group	Notes Le groupe peut être modifié ou indisponible pour les versions après Windows 8.1. Utilisez plutôt TransferGroup. Obtient ou définit une valeur de chaîne (par exemple, un GUID) indiquant le groupe auquel le chargement appartiendra. Une opération de chargement avec un ID de groupe apparaît uniquement dans les énumérations d’opération à l’aide de GetCurrentDownloadsAsync(String) avec la valeur de chaîne de groupe spécifique.
Method	Obtient ou définit la méthode HTTP utilisée pour le chargement. La méthode par défaut utilisée pour les opérations de chargement est POST.
ProxyCredential	Obtient ou définit les informations d’identification du proxy pour le chargement.
ServerCredential	Obtient ou définit les informations d’identification à utiliser pour l’authentification auprès du serveur d’origine.
SuccessTileNotification	Obtient et définit la vignette TileNotification utilisée pour définir les visuels, la balise d’identification et l’heure d’expiration d’une notification de vignette utilisée pour mettre à jour la vignette d’application lors de l’indication de la réussite d’un chargement vers l’utilisateur.
SuccessToastNotification	Obtient ou définit la valeur ToastNotification qui définit le contenu, les métadonnées associées et les événements utilisés dans une notification toast pour indiquer la réussite d’un chargement vers l’utilisateur.
TransferGroup	Obtient ou définit le groupe auquel une opération de chargement appartiendra.

Méthodes

CreateUpload(Uri, IStorageFile)	Initialise un UploadOperation qui indique l’emplacement pour et le fichier à charger.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Renvoie une opération asynchrone qui, à l’achèvement, retourne un UploadOperation avec l’URI spécifié et un ou plusieurs objets BackgroundTransferContentPart .
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Renvoie une opération asynchrone qui, une fois terminée, retourne un UploadOperation avec l’URI spécifié, un ou plusieurs objets BackgroundTransferContentPart et le sous-type multipart.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Renvoie une opération asynchrone qui, à l’achèvement, retourne une UploadOperation avec l’URI spécifié, le sous-type multipart, un ou plusieurs objets BackgroundTransferContentPart et la valeur de limite de délimiteur utilisée pour séparer chaque partie.
CreateUploadFromStreamAsync(Uri, IInputStream)	Retourne une opération asynchrone qui, une fois terminée, retourne une opération UploadOperation avec l’URI et le flux source spécifiés.
GetCurrentUploadsAsync()	Retourne une collection de chargements en attente qui ne sont pas associés à un groupe.
GetCurrentUploadsAsync(String)	Notes GetCurrentUploadsAsync(group) peut être modifié ou indisponible pour les versions après Windows 8.1. Utilisez plutôt GetCurrentUploadsForTransferGroupAsync. Retourne une collection de chargements en attente pour un groupe spécifique.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Obtient tous les chargements associés au BackgroundTransferGroup fourni.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Notes RequestUnconstrainedUploadsAsync peut être modifié ou indisponible pour les versions après Windows 10, version 1607. Utilisez plutôt CreateUploadAsync. Utilisé pour demander une opération de chargement sans contrainte. Lorsque cette méthode est appelée, l’utilisateur reçoit une invite d’interface utilisateur qu’il peut utiliser pour indiquer son consentement pour une opération sans contrainte. Une opération de transfert sans contrainte s’exécute sans les restrictions de ressources normalement associées aux opérations réseau en arrière-plan pendant qu’un appareil fonctionne sur batterie.
SetRequestHeader(String, String)	Utilisé pour définir un en-tête de requête HTTP.

Voir aussi

• UploadOperation
• Gestion des exceptions dans les applications réseau
• Comment opter pour les notifications toast
• Démarrage rapide : Charger un fichier
• Exemple de transfert en arrière-plan
• Exemple de transfert en arrière-plan (Windows 8.x)