BackgroundDownloader Classe

Définition

Espace de noms:

Windows.Networking.BackgroundTransfer

Permet de configurer les téléchargements avant la création réelle de l’opération de téléchargement à l’aide de CreateDownload. 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 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

Héritage

Object Platform::Object IInspectable BackgroundDownloader

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 téléchargement de 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);
     }
 }

Remarques

Après l’arrêt de l’application, une application doit énumérer toutes les instances DownloadOperation existantes au prochain démarrage à l’aide de GetCurrentDownloadsAsync. Lorsqu’une application UWP utilisant le transfert en arrière-plan est terminée, les téléchargements incomplets sont conservés 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 active, elles restent incomplètes et continuent d’occuper les ressources.

Notes

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

Le transfert en arrière-plan ne prend pas en charge les téléchargements simultanés du même URI. Ainsi, une application peut télécharger http://example.com/myfile.wmv une seule fois, ou la télécharger à nouveau une fois le téléchargement précédent terminé. Une application ne doit pas démarrer simultanément deux téléchargements du même URI , car cela peut entraîner des fichiers tronqués.

Lors de l’implémentation d’une bibliothèque pour les opérations de transfert en arrière-plan, et 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 téléchargements. Un télé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ît pas dans les appels GetCurrentDownloadsAsync sans. Cela garantit que les autres applications qui implémentent cette même bibliothèque pour les téléchargements ne verront pas vos téléchargements.

Les opérations de téléchargement via FTP sont prises en charge. Toutefois, pour les opérations FTP, les informations d’identification d’authentification doivent être fournies dans l’URI spécifié. Par exemple, ftp://user:password@server/file.txt.

Des problèmes de sécurité peuvent exister lorsque les opérations de télé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 télé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 téléchargement.

Notes

Le jeton sécurisé est 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 télé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 BackgroundDownloader dans Windows 8.1 et Windows Server 2012 R2 prend en charge les options permettant à l’utilisateur de recevoir des notifications par vignette et toast lorsqu’un transfert est terminé correctement 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 toast compatible se trouve sous la section Notifications de l’onglet Application . Définissez l’option compatible Toast sur « Oui » pour que l’application puisse recevoir des notifications toast.

Si la fonctionnalité Toast n’est pas activée dans le manifeste de l’application, tous les paramètres toast dans l’espace de noms Windows.Networking.BackgroundTransfer sont ignorés en mode silencieux et aucune notification toasts n’est 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 télé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.

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. Même pendant le débogage, votre application doit énumérer, puis reprendre, redémarrer ou annuler les téléchargements persistants à partir de la session précédente. Par exemple, vous pouvez demander à votre application d’annuler les opérations de téléchargement persistantes énumérées au démarrage de l’application si les opérations précédentes pour la session de débogage actuelle ne présentent aucun intérêt.

S’il existe des mises à jour de projet Microsoft Visual Studio, telles que des modifications apportées au manifeste de l’application, et si 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

BackgroundDownloader()	Crée un objet BackgroundDownloader .
BackgroundDownloader(BackgroundTransferCompletionGroup)	Crée un objet BackgroundDownloader avec un BackgroundTransferCompletionGroup.

Propriétés

CompletionGroup	Obtient le BackgroundTransferCompletionGroup associé à BackgroundDownloader.
CostPolicy	Obtient ou définit la stratégie de coût pour l’opération de téléchargement en arrière-plan.
FailureTileNotification	Obtient ou définit la vignette TileNotification utilisée pour définir les visuels, la balise d’identification et l’heure d’expiration d’une notification par vignette utilisée pour mettre à jour la vignette de l’application lorsque l’utilisateur a échoué à télécharger.
FailureToastNotification	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 l’échec d’un téléchargement pour 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 transfert appartiendra. Une opération de télé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 téléchargement en arrière-plan. La méthode par défaut utilisée pour les opérations de téléchargement est GET.
ProxyCredential	Obtient ou définit les informations d’identification du proxy pour le transfert en arrière-plan.
ServerCredential	Obtient ou définit les informations d’identification à utiliser pour l’authentification auprès du serveur d’origine. Notes Pour les téléchargements via FTP, les informations d’identification d’authentification doivent être fournies dans l’URI spécifié. Par exemple, ftp://user:password@server/file.txt.
SuccessTileNotification	Obtient ou définit la vignette TileNotification utilisée pour définir les visuels, la balise d’identification et l’heure d’expiration d’une notification par vignette utilisée pour mettre à jour la vignette de l’application lors de l’indication de la réussite d’un téléchargement à 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 téléchargement à l’utilisateur.
TransferGroup	Obtient ou définit le groupe auquel appartiendra une opération de téléchargement.

Méthodes

CreateDownload(Uri, IStorageFile)	Initialise un objet DownloadOperation qui contient l’URI spécifié et le fichier dans lequel la réponse est écrite.
CreateDownload(Uri, IStorageFile, IStorageFile)	Initialise un objet DownloadOperation avec l’URI de ressource, le fichier dans lequel la réponse est écrite et le corps de l’entité de demande.
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	Crée une opération de téléchargement asynchrone qui inclut un URI, le fichier dans lequel la réponse sera écrite et l’objet IInputStream à partir duquel le contenu du fichier est lu.
GetCurrentDownloadsAsync()	Retourne une collection de téléchargements en attente qui ne sont pas associés à un BackgroundTransferGroup.
GetCurrentDownloadsAsync(String)	Notes GetCurrentDownloadsAsync(group) peut être modifié ou indisponible pour les versions après Windows 8.1. Utilisez plutôt GetCurrentDownloadsForTransferGroupAsync. Retourne une collection de téléchargements en attente pour un groupe spécifique.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	Obtient tous les téléchargements associés au BackgroundTransferGroup fourni.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	Notes RequestUnconstrainedDownloadsAsync peut être modifié ou indisponible pour les versions après Windows 10, version 1607. Utilisez plutôt CreateDownloadAsync. Permet de demander une opération de télé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 s’exécute sur batterie.
SetRequestHeader(String, String)	Utilisé pour définir un en-tête de requête HTTP.

Voir aussi

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