BackgroundDownloader Classe

Définition

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

Héritage

Object Platform::Object IInspectable BackgroundDownloader

Attributs

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implémente

IBackgroundTransferBase

Configuration requise pour Windows

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.

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.

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.

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

Propriétés

Méthodes

S’applique à

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)