DownloadOperation DownloadOperation DownloadOperation DownloadOperation DownloadOperation Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

[Contains prerelease APIs.]
Performs an asynchronous download operation. The Background Transfer sample demonstrates this functionality. 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++.

public : sealed class DownloadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority, IDownloadOperation, IDownloadOperation2
struct winrt::Windows::Networking::BackgroundTransfer::DownloadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority, IDownloadOperation, IDownloadOperation2
public sealed class DownloadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority, IDownloadOperation, IDownloadOperation2
Public NotInheritable Class DownloadOperation Implements IBackgroundTransferOperation, IBackgroundTransferOperationPriority, IDownloadOperation, IDownloadOperation2
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

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);
            }
        };
       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);
            }
        }

Remarks

After app termination, an app should enumerate all existing DownloadOperation instances at next start-up using GetCurrentDownloadsAsync. When a UWP 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-introduced to the current session, they will go stale and continue to occupy device resources.

Background transfer doesn't support concurrent downloads of the same Uri. So an app can download http://example.com/myfile.wmv once, or download it again after a previous download completed. An app shouldn't start two downloads of the same Uri concurrently, since this may result in truncated files.

Note

Paused or incomplete download operations can only be resumed if the server accepts range-requests.

Timeout considerations

  • 1.) When establishing a new connection for a download over TCP/SSL, the connection attempt is aborted if not established within five minutes.
  • 2.) After the connection has been established, an HTTP request message that has not received a response within two minutes is aborted. Assuming there is Internet connectivity, Background Transfer will retry a download up to three times. In the event Internet connectivity is not detected, additional attempts will not be made until it is.

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 Microsoft 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.

Properties

CostPolicy CostPolicy CostPolicy CostPolicy CostPolicy

Gets and sets the cost policy for the download.

CurrentWebErrorStatus CurrentWebErrorStatus CurrentWebErrorStatus CurrentWebErrorStatus CurrentWebErrorStatus

A transfer's WebErrorStatus, which can be monitored during the lifetime of the DownloadOperation.

Group Group Group Group Group

Note

Group may be altered or unavailable for releases after Windows 8.1. Instead, use TransferGroup.

Gets a string value indicating the group the transfer belongs to.

Guid Guid Guid Guid Guid

This is a unique identifier for a specific download operation. A GUID associated to a download operation will not change for the duration of the download.

IsRandomAccessRequired IsRandomAccessRequired IsRandomAccessRequired IsRandomAccessRequired IsRandomAccessRequired

A boolean property to enable random access. The property must be set to TRUE before calling StartAsync() on a DownloadOperation object to use the random access feature. After calling StartAsync(), call GetResultRandomAccessStreamReference to get a reference to the random access stream and read from it.

Method Method Method Method Method

Gets the method to use for the download.

Priority Priority Priority Priority Priority

Gets or sets the transfer priority of this download operation when within a BackgroundTransferGroup. Possible values are defined by BackgroundTransferPriority.

Progress Progress Progress Progress Progress

Gets the current progress of the upload operation.

RecoverableWebErrorStatuses RecoverableWebErrorStatuses RecoverableWebErrorStatuses RecoverableWebErrorStatuses RecoverableWebErrorStatuses

A set of WebErrorStatus values that applications anticipate the download will hit, and that the applications know how to handle.

RequestedUri RequestedUri RequestedUri RequestedUri RequestedUri

Gets the URI from which to download the file.

ResultFile ResultFile ResultFile ResultFile ResultFile

Returns the IStorageFile object provided by the caller when creating the DownloadOperation object using CreateDownload.

TransferGroup TransferGroup TransferGroup TransferGroup TransferGroup

Gets the group that this download operation belongs to.

Methods

AttachAsync() AttachAsync() AttachAsync() AttachAsync() AttachAsync()

Returns an asynchronous operation that can be used to monitor progress and completion of the attached download. Calling this method allows an app to attach download operations that were started in a previous app instance.

GetDownloadedRanges() GetDownloadedRanges() GetDownloadedRanges() GetDownloadedRanges() GetDownloadedRanges()

Returns the full list of file ranges that have been downloaded so far.

GetResponseInformation() GetResponseInformation() GetResponseInformation() GetResponseInformation() GetResponseInformation()

Gets the response information.

GetResultRandomAccessStreamReference() GetResultRandomAccessStreamReference() GetResultRandomAccessStreamReference() GetResultRandomAccessStreamReference() GetResultRandomAccessStreamReference()

Gets a reference to the random access stream and reads from it. It's necessary to set IsRandomAccessRequired to TRUE before calling GetResultRandomAccessStreamReference.

GetResultStreamAt(UInt64) GetResultStreamAt(UInt64) GetResultStreamAt(UInt64) GetResultStreamAt(UInt64) GetResultStreamAt(UInt64)

Gets the partially downloaded response at the specified position.

MakeCurrentInTransferGroup() MakeCurrentInTransferGroup() MakeCurrentInTransferGroup() MakeCurrentInTransferGroup() MakeCurrentInTransferGroup()

Prerelease. Prioritizes the download transfer operation (and any transfers that follow it in the same transfer group). Calling this method on a transfer that doesn't belong to a transfer group has no effect.

Pause() Pause() Pause() Pause() Pause()

Pauses a download operation.

Resume() Resume() Resume() Resume() Resume()

Resumes a paused download operation.

StartAsync() StartAsync() StartAsync() StartAsync() StartAsync()

Starts an asynchronous download operation.

Events

RangesDownloaded RangesDownloaded RangesDownloaded RangesDownloaded RangesDownloaded

Provides access to to incremental download progress.

See Also