Comment télécharger un fichier (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Cette rubrique vous explique comment télécharger un fichier.

Les applications peuvent faire appel aux API abordées dans cette rubrique pour permettre à leur application d’interagir avec les services Web dans le but d’exploiter ou de partager des formats multimédias courants, tels que des photos, de la musique et des vidéos.

Lorsque vous développez une application Windows Runtime en JavaScript, il existe deux options principales pour obtenir des fichiers à divers emplacements sur Internet. Les petits fichiers, notamment les ressources de site qui sont fréquemment récupérées, peuvent être téléchargés à l’aide de la fonction XHR pour soumettre la demande HTTP GET asynchrone. Cette fonction encapsule un appel XMLHttpRequest dans une promesse, c’est-à-dire le modèle de programmation qui autorise un comportement asynchrone dans JavaScript.

Pour garantir une expérience bien plus agréable lorsque vous téléchargez des éléments multimédias plus volumineux (vidéo et musique) avec une durée de vie opérationnelle pouvant aller au-delà de plusieurs applications suspendues et/ou de changements de disponibilité du réseau, votre application Windows Runtime peut utiliser la fonction Background Transfer. Pour avoir une idée globale de ce qu’est le transfert en arrière-plan, voir Transfert de données en arrière-plan.

Prérequis

Pour obtenir une aide générale sur la création d’une application Windows Runtime en JavaScript, voir Créer votre première application Windows Runtime en JavaScript. De plus, les promesses JavaScript sont utilisées dans cette rubrique pour mener des opérations asynchrones. Pour plus d’informations sur ce modèle de programmation, voir Programmation asynchrone en JavaScript à l’aide de promesses.

Pour préparer votre application à une mise en réseau, vous devez définir cette fonctionnalité dans le fichier Package.appxmanifest du projet. Pour obtenir une définition de chaque fonctionnalité réseau, voir Comment configurer les fonctionnalités d’isolement réseau.

Les exemples de transfert en arrière-plan présentés dans cette rubrique reposent sur l’exemple de transfert en arrière-plan.

Téléchargement d’un fichier à l’aide de la fonction XHR

Pour soumettre une demande HTTP asynchrone de base en JavaScript, appelez la fonction XHR et associez-y des données de demande pertinentes à l’aide du paramètre Option. Par défaut, cet appel de méthode est une demande GET. Les seules valeurs requises par le biais du paramètre Option sont donc l’URL et responseType. Cependant, de nombreux services Web nécessitent une authentification et ces informations d’identification doivent être incluses lorsque vous appelez la fonction XHR pour solliciter des ressources auprès d’un service Web sécurisé.

Une opération GET XHR exige également que le type de contenu attendu dans la réponse soit précisé à l’aide de la valeur responseType dans le paramètre Option. Dans notre exemple, nous avons demandé un fichier .png. La valeur responseType renvoyée est donc « blob ». Pour obtenir la liste complète des types de contenus pris en charge et des exemples montrant comment les demander, voir Comment télécharger un fichier à l’aide de WinJS.xhr.


WinJS.xhr({ url: "https://www.microsoft.com/windows/Framework/images/win_logo.png", responseType: "blob" })
    .done(
        function (request) {
            var imageBlob = URL.createObjectURL(request.response);
            var imageTag = xhrDiv.appendChild(document.createElement("image"));
      imageTag.src = imageBlob;
     });

Dans JavaScript, chaque promesse possède deux fonctions qui vous permettent de gérer les résultats d’une opération asynchrone : then et done. Les deux fonctions acceptent trois paramètres : une fonction qui est appelée lorsque le téléchargement est terminé (à savoir lorsque readyState a la valeur 4), une fonction qui est appelée lorsqu’une erreur se produit et une fonction appelée lorsque le téléchargement est en cours d’exécution (quand readyState a la valeur 2 ou 3). Seule la fonction done lève une exception si une erreur n’est pas gérée. Cette fonction est préférable en l’absence d’une fonction d’erreur.

Téléchargement d’un fichier à l’aide de la fonctionnalité de transfert en arrière-plan

Lorsque vous faites appel à la fonctionnalité de transfert en arrière-plan, chaque téléchargement qui en résulte existe sous la forme d’une opération DownloadOperation qui dévoile de nombreuses méthodes de contrôle servant à suspendre, reprendre, redémarrer et annuler l’opération. Les événements d’application (par exemple, une suspension ou un arrêt) et les changements de connectivité sont gérés automatiquement par le système pour chaque opération DownloadOperation. Les téléchargements se poursuivent lors des périodes de suspension des applications et perdurent après l’arrêt des applications. Dans le cadre des scénarios de réseau mobile, la propriété CostPolicy peut être définie pour indiquer si oui ou non votre application entamera ou poursuivra un téléchargement tandis qu’une connexion réseau limitée est utilisée pour la connectivité Internet.

Les exemples qui suivent vous guident tout au long du processus de création et d’initialisation d’un téléchargement de base et décrivent comment énumérer des opérations de chargement issues d’une session d’application précédente.

Hh700370.wedge(fr-fr,WIN.10).gif Configurer et démarrer un téléchargement de fichier à l’aide de la fonctionnalité de transfert en arrière-plan

L’exemple qui suit montre comment des chaînes représentant un URI et un nom de fichier peuvent être utilisées pour créer un objet Uri et le StorageFile qui contiendra la ressource demandée. Dans cet exemple, le nouveau fichier est automatiquement placé à un emplacement prédéfini. La classe FileSavePicker peut également servir aux utilisateurs pour indiquer où enregistrer le fichier sur l’appareil. Notez que la méthode load appelée pour réaffecter les rappels vers DownloadOperation, si elle persiste après l’arrêt de l’application, se trouve dans la classe DownloadOp définie plus loin dans cette section.

function DownloadOp() {
    var download = null;
    var promise = null;
    var imageStream = null;

    this.start = function (uriString, fileName) {
        try {
            // Asynchronously create the file in the pictures folder.
            Windows.Storage.KnownFolders.picturesLibrary.createFileAsync(fileName, Windows.Storage.CreationCollisionOption.generateUniqueName).done(function (newFile) {
                var uri = Windows.Foundation.Uri(uriString);
                var downloader = new Windows.Networking.BackgroundTransfer.BackgroundDownloader();

                // Create a new download operation.
                download = downloader.createDownload(uri, newFile);

                // Start the download and persist the promise to be able to cancel the download.
                promise = download.startAsync().then(complete, error, progress);
            }, error);
        } catch (err) {
            displayException(err);
        }
    };
    // On application activation, reassign callbacks for a download
    // operation persisted from previous application state.
    this.load = function (loadedDownload) {
        try {
            download = loadedDownload;
            printLog("Found download: " + download.guid + " from previous application run.<br\>");
            promise = download.attachAsync().then(complete, error, progress);
        } catch (err) {
            displayException(err);
        }
    };
}

Notez les appels de méthode asynchrone définis à l’aide de promesses JavaScript. Examinons la ligne 17 du dernier échantillon de code :

promise = download.startAsync().then(complete, error, progress);

L’appel de méthode asynchrone est suivi d’une instruction then indiquant les méthodes, définies par l’application, qui sont appelées lorsqu’un résultat de l’appel de méthode asynchrone est retourné. Pour plus d’informations sur ce modèle de programmation, voir Programmation asynchrone en JavaScript à l’aide de promesses.

Hh700370.wedge(fr-fr,WIN.10).gif Ajout de méthodes de contrôle des opérations supplémentaires

Le niveau de contrôle peut être augmenté en implémentant des méthodes DownloadOperation supplémentaires. Par exemple, en intégrant le code suivant à l’exemple ci-dessus, nous pouvons inclure la possibilité d’annuler l’opération.

// Cancel download.
this.cancel = function () {
    try {
        if (promise) {
            promise.cancel();
            promise = null;
            printLog("Canceling download: " + download.guid + "<br\>");
            if (imageStream) {
                imageStream.close();
            }
        }
        else {
            printLog("Download " + download.guid + " already canceled.<br\>");
        }
    } catch (err) {
        displayException(err);
    }
};

Lors de l’achèvement ou de l’annulation d’une opération DownloadOperation, toutes les ressources système associées sont libérées. Toutefois, si votre application est arrêtée avant que l’un de ces événements ne se produise, les téléchargements sont suspendus et persistent en arrière-plan. Les exemples qui suivent expliquent comment réintroduire des téléchargements persistants dans une nouvelle session d’application.

Hh700370.wedge(fr-fr,WIN.10).gif Énumérer des opérations persistantes au démarrage

Avant de définir la fonction chargée d’énumérer les opérations persistantes, nous devons créer un tableau pour y stocker les objets DownloadOperation que cette fonction renverra :
```
var downloadOps = [];
```
Il nous faut ensuite définir la fonction qui énumère les opérations persistantes et les stocke dans notre tableau. Notez que la méthode load appelée pour réaffecter les rappels pour une opération DownloadOperation persistante se trouve dans l’exemple DownloadOp défini plus loin dans cette section.
```
// Enumerate outstanding downloads.
Windows.Networking.BackgroundTransfer.BackgroundDownloader.getCurrentDownloadsAsync().done(function (downloads) {

    for (var i = 0; i < downloads.size; i++) {
        var download = new DownloadOp();
        download.load(downloads[i]);
        downloadOps.push(download);
    }
});
```
Remarque

Dans les applications du Windows Phone Store, les transferts en arrière-plan se poursuivent alors que votre application ne se trouve pas au premier plan. Comme votre application n’est pas en cours d’exécution dans ce scénario, elle ne recevra pas de notification une fois le transfert terminé. Lorsque votre application reprend, si vous vérifiez la progression d’un transfert terminé, l’état sera BackgroundTransferStatus.Running. Toutefois, lorsque vous effectuez un attachement au transfert, comme dans l’exemple de code ci-dessus, le gestionnaire d’achèvement de tâche se déclenche et l’état du transfert est mis à jour.

Délai d’expiration des demandes

Il existe deux scénarios majeurs de délai de connexion à prendre en considération.

Lorsque vous établissez une nouvelle connexion pour un transfert, la demande de connexion est annulée si la connexion n’est pas établie dans un délai de cinq minutes.
Une fois la connexion établie, un message de requête HTTP qui n’a reçu aucune réponse au bout de deux minutes est annulé.

Quel que soit le scénario, la fonctionnalité de transfert en arrière-plan part du principe qu’aucune connectivité Internet n’existe et tente automatiquement jusqu’à trois fois de soumettre une demande. Si aucune connectivité Internet n’est décelée, les demandes supplémentaires attendront jusqu’à ce qu’elle le soit.

Pour des opérations XHR, des valeurs de délai spécifiques peuvent être définies à l’aide de la propriété WinJS.Promise.timeout. Pour plus d’informations sur la procédure à suivre pour cette opération, voir la rubrique consacrée à la définition de valeurs de délai d’attente à l’aide de la fonction WinJS.xhr.

Aide au 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 de la session précédente. Par exemple, votre application peut annuler l’énumération des opérations de téléchargement persistantes, au démarrage, si les opérations précédentes n’ont pas d’intérêt pour la session de débogage active.

S’il existe des mises à jour du projet Visual Studio, par exemple des modifications du 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, voir Débogage et test des applications du Windows Store.

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 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é. Vous pouvez l’effectuer via l’écran d’accueil ou à l’aide de PowerShell et de l’applet de commande Remove-AppxPackage.

Récapitulatif et étapes suivantes

Dans cette rubrique, nous avons étudié comment télécharger des fichiers à l’aide des API XHR et Background Transfer dans JavaScript. Nous avons examiné les différences entre ces deux API et souligné dans quelle mesure leur application pratique dépend de la taille et de la durée d’un téléchargement de fichier.

Vous pouvez également faire appel à la fonction XHR et à la fonctionnalité de transfert en arrière-plan pour charger des fichiers. Pour obtenir une explication des principes clés, ainsi que des exemples, voir Comment charger un fichier.