BackgroundDownloader class

Used to configure downloads prior to the actual creation of the download operation using CreateDownload. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background Transfer sample for examples in JavaScript, C#, and C++.

Note  Background Transfer is primarily designed for long-term transfer operations for resources like video, music, and large images. For short-term operations involving transfers of smaller resources (i.e. a couple KB), the use of provided HTTP APIs (XHR in JavaScript, HttpClient in .NET, and IXHR2 in C++) is recommended.

Syntax

var backgroundDownloader = new Windows.Networking.BackgroundTransfer.BackgroundDownloader();

Attributes

ActivatableAttribute(NTDDI_WIN8)

MarshalingBehaviorAttribute(Agile)

StaticAttribute(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderStaticMethods, NTDDI_WIN8)

ThreadingAttribute(Both)

VersionAttribute(NTDDI_WIN8)

Members

The BackgroundDownloader class has these types of members:

• Constructors
• Methods
• Properties

Constructors

The BackgroundDownloader class has these constructors.

Methods

The BackgroundDownloader class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

Properties

The BackgroundDownloader class has these properties.

Remarks

Download operations via FTP are supported. However, for FTP operations, authentication credentials must be provided within the specified URI. For example, ftp://user:password@server/file.txt.

After app termination, an app should enumerate all existing DownloadOperation instances at next start-up using GetCurrentDownloadsAsync. When a Windows Store app using Background Transfer is terminated, incomplete downloads will persist in the background. If the app is restarted after termination and these incomplete operations are not enumerated and re-attached to the current session, they will go stale and continue to occupy device resources.

Debugging Guidance

Stopping a debugging session in Microsoft Visual Studio is comparable to closing your app; downloads are paused and POST uploads are terminated. Even while debugging, your app should enumerate and then pause, resume, restart, or cancel any persisted downloads.

However, if Visual Studio project updates, like changes to the app manifest, require that the app is uninstalled and re-deployed for debugging, GetCurrentDownloadsAsync cannot enumerate persisted operations created using the previous app deployment.

Examples

The following example demonstrates how to configure and begin a basic download operation, and is based on the Background Transfer sample offered in the Windows Sample Gallery.

        var download = null;
        var promise = null;

        function DownloadFile (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);
            }
        };

Requirements

See also

Quickstart: Download a file

Background Transfer sample

Build date: 12/4/2012