DownloadOperation DownloadOperation DownloadOperation DownloadOperation Class

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

Syntax

Declaration

public sealed class DownloadOperationpublic sealed class DownloadOperationPublic NotInheritable Class DownloadOperationpublic sealed class DownloadOperation

Remarks

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

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

Properties summary

Gets and sets the cost policy for the download.

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.

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.

Gets the method to use for the download.

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

Gets the current progress of the upload operation.

Gets the URI from which to download the file.

Returns the IStorageFile object provided by the caller when creating the DownloadOperation object using CreateDownload(Uri, IStorageFile, IStorageFile).

Gets the group that this download operation belongs to.

Methods summary

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.

Gets the response information.

Gets the partially downloaded response at the specified position.

Pauses a download operation.

Resumes a paused download operation.

Starts an asynchronous download operation.

Properties

  • CostPolicy
    CostPolicy
    CostPolicy
    CostPolicy

    Gets and sets the cost policy for the download.

    public BackgroundTransferCostPolicy CostPolicy { get; set; }public BackgroundTransferCostPolicy CostPolicy { get; set; }Public ReadWrite Property CostPolicy As BackgroundTransferCostPolicypublic BackgroundTransferCostPolicy CostPolicy { get; set; }

    Property Value

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

    public string Group { get; }public string Group { get; }Public ReadOnly Property Group As stringpublic string Group { get; }

    Property Value

    • string
      string
      string
      string

      The group name.

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

    public Guid Guid { get; }public Guid Guid { get; }Public ReadOnly Property Guid As Guidpublic Guid Guid { get; }

    Property Value

    • System.Guid
      System.Guid
      System.Guid
      System.Guid

      The unique ID for this download operation.

  • Method
    Method
    Method
    Method

    Gets the method to use for the download.

    public string Method { get; }public string Method { get; }Public ReadOnly Property Method As stringpublic string Method { get; }

    Property Value

    • string
      string
      string
      string

      The method to use for the download. This value can be GET, PUT, RETR, or STOR.

  • Priority
    Priority
    Priority
    Priority

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

    public BackgroundTransferPriority Priority { get; set; }public BackgroundTransferPriority Priority { get; set; }Public ReadWrite Property Priority As BackgroundTransferPrioritypublic BackgroundTransferPriority Priority { get; set; }

    Property Value

  • Progress
    Progress
    Progress
    Progress

    Gets the current progress of the upload operation.

    public BackgroundDownloadProgress Progress { get; }public BackgroundDownloadProgress Progress { get; }Public ReadOnly Property Progress As BackgroundDownloadProgresspublic BackgroundDownloadProgress Progress { get; }

    Property Value

    Remarks

    The value of the Progress property is updated in real time, which means that the value can change while a progress handler is executing. As a best practice, create a local copy of the Progress property at the beginning of your progress handler, and use only that copy in your progress handler, to maintain a consistent view of progress as your handler executes.

  • RequestedUri
    RequestedUri
    RequestedUri
    RequestedUri

    Gets the URI from which to download the file.

    public Uri RequestedUri { get; }public Uri RequestedUri { get; }Public ReadOnly Property RequestedUri As Uripublic Uri RequestedUri { get; }

    Property Value

  • ResultFile
    ResultFile
    ResultFile
    ResultFile

    Returns the IStorageFile object provided by the caller when creating the DownloadOperation object using CreateDownload(Uri, IStorageFile, IStorageFile).

    public IStorageFile ResultFile { get; }public IStorageFile ResultFile { get; }Public ReadOnly Property ResultFile As IStorageFilepublic IStorageFile ResultFile { get; }

    Property Value

  • TransferGroup
    TransferGroup
    TransferGroup
    TransferGroup

    Gets the group that this download operation belongs to.

    public BackgroundTransferGroup TransferGroup { get; }public BackgroundTransferGroup TransferGroup { get; }Public ReadOnly Property TransferGroup As BackgroundTransferGrouppublic BackgroundTransferGroup TransferGroup { get; }

    Property Value

Methods

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

    public IAsyncOperationWithProgress<DownloadOperation, DownloadOperation> AttachAsync()public IAsyncOperationWithProgress<DownloadOperation, DownloadOperation> AttachAsync()Public Function AttachAsync() As IAsyncOperationWithProgress( Of DownloadOperation, DownloadOperation )public IAsyncOperationWithProgress<DownloadOperation, DownloadOperation> AttachAsync()

    Returns

    • Download operation with callback.

    Remarks

    While, this method can be called from multiple app instances, developers should not attach callbacks from the primary app instance in a background task. This will cause BackgroundTransferHost.exe to hang.

    Examples

    
            function AttachDownload (loadedDownload) {
                try {
                    download = loadedDownload;
                    promise = download.attachAsync().then(complete, error, progress);
                } catch (err) {
                    displayException(err);
                }
            };
    
  • GetResponseInformation()
    GetResponseInformation()
    GetResponseInformation()
    GetResponseInformation()

    Gets the response information.

    public ResponseInformation GetResponseInformation()public ResponseInformation GetResponseInformation()Public Function GetResponseInformation() As ResponseInformationpublic ResponseInformation GetResponseInformation()

    Returns

    Remarks

    This method returns an object that contains information about the current server response. When calling this method multiple times, the object returned will be the same as long as there is no new server response information available. Sometimes however, one download consists of multiple requests to a server. If a request gets aborted due to some non-fatal error (e.g. machine lost internet connectivity, cost policy required download to pause, application called Pause(), etc.), Download API will invoke a new request and try to resume/restart the download. The response information from the server for this second request may be different than the one returned by the first request.

    Returns null if any of the following conditions is true.

    • The transfer associated with the DownloadOperation is being made using a protocol other than HTTP (e.g., FTP).
    • The DownloadOperation hasn't yet begun.
    • There was a failure before any response from the server was received (e.g., connection couldn't be established).
  • GetResultStreamAt(UInt64)
    GetResultStreamAt(UInt64)
    GetResultStreamAt(UInt64)
    GetResultStreamAt(UInt64)

    Gets the partially downloaded response at the specified position.

    public IInputStream GetResultStreamAt(UInt64 position)public IInputStream GetResultStreamAt(UInt64 position)Public Function GetResultStreamAt(position As UInt64) As IInputStreampublic IInputStream GetResultStreamAt(UInt64 position)

    Parameters

    • position
      System.UInt64
      System.UInt64
      System.UInt64
      System.UInt64

      The position at which to start reading.

    Returns

  • Pause()
    Pause()
    Pause()
    Pause()

    Pauses a download operation.

    public void Pause()public void Pause()Public Function Pause() As voidpublic void Pause()

    Remarks

    Calling this method will abort the HTTP request but preserve state for the download and the partially downloaded response. This method will fail when called for operations that haven't been started yet, are already paused, or use POST requests.

  • Resume()
    Resume()
    Resume()
    Resume()

    Resumes a paused download operation.

    public void Resume()public void Resume()Public Function Resume() As voidpublic void Resume()

    Remarks

    This method can be called on a paused download operation to resume the download. The download operation will try to resume the download if possible. Only requests where the server accepts range-requests can resume. Otherwise the download is restarted.

  • StartAsync()
    StartAsync()
    StartAsync()
    StartAsync()

    Starts an asynchronous download operation.

    public IAsyncOperationWithProgress<DownloadOperation, DownloadOperation> StartAsync()public IAsyncOperationWithProgress<DownloadOperation, DownloadOperation> StartAsync()Public Function StartAsync() As IAsyncOperationWithProgress( Of DownloadOperation, DownloadOperation )public IAsyncOperationWithProgress<DownloadOperation, DownloadOperation> StartAsync()

    Returns

    • An asynchronous download operation that includes progress updates.

    Remarks

    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.

    A download operation must be scheduled using one of the CreateDownload(Uri, IStorageFile, IStorageFile) or CreateDownloadAsync(Uri, IStorageFile, IInputStream) methods before the StartAsync() method is called.

    Important

    Queuing up a large number of transfers on the main UI thread can result in degraded performance of your app's UI, even though the call is awaitable. If you are queuing up a large number of transfers, it is recommended that you call StartAsync on a background worker thread as in the following example.

    operation = await Task.Run(() => { return myDownloadOperation.StartAsync(); });
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Capabilities

internetClientServer
privateNetworkClientServer
internetClient

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.Networking.BackgroundTransfer.dll