BackgroundDownloader.CreateDownload Method

Definition

Namespace:

Windows.Networking.BackgroundTransfer

Overloads

CreateDownload(Uri, IStorageFile)	Initializes a DownloadOperation object that contains the specified Uri and the file that the response is written to.
CreateDownload(Uri, IStorageFile, IStorageFile)	Initializes a DownloadOperation object with the resource Uri, the file that the response is written to, and the request entity body.

CreateDownload(Uri, IStorageFile)

Initializes a DownloadOperation object that contains the specified Uri and the file that the response is written to.

public:
 virtual DownloadOperation ^ CreateDownload(Uri ^ uri, IStorageFile ^ resultFile) = CreateDownload;

/// [Windows.Foundation.Metadata.Overload("CreateDownload")]
DownloadOperation CreateDownload(Uri const& uri, IStorageFile const& resultFile);

[Windows.Foundation.Metadata.Overload("CreateDownload")]
public DownloadOperation CreateDownload(System.Uri uri, IStorageFile resultFile);

function createDownload(uri, resultFile)

Public Function CreateDownload (uri As Uri, resultFile As IStorageFile) As DownloadOperation

Parameters

uri

Uri Uri

The location of the resource.

resultFile

IStorageFile

The file that the response will be written to.

Returns

DownloadOperation

The resultant download operation.

Attributes

OverloadAttribute

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.

Important

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

operation = await Task.Run(() => { return myDownloader.CreateDownload(uri, file); });

Note

Some file systems have file size limits. Background transfer has special logic to fast-fail transfers that exceed the destination drive's file size limits (for example, files that exceed 4GB in size for FAT32 file systems). If the server responds with a Content-Length header value greater than the file system's maximum file size, then the download operation immediately fails with HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_LIMITATION).

See also

• CreateDownload(Uri, IStorageFile, IStorageFile)

CreateDownload(Uri, IStorageFile, IStorageFile)

Initializes a DownloadOperation object with the resource Uri, the file that the response is written to, and the request entity body.

public:
 virtual DownloadOperation ^ CreateDownload(Uri ^ uri, IStorageFile ^ resultFile, IStorageFile ^ requestBodyFile) = CreateDownload;

/// [Windows.Foundation.Metadata.Overload("CreateDownloadFromFile")]
DownloadOperation CreateDownload(Uri const& uri, IStorageFile const& resultFile, IStorageFile const& requestBodyFile);

[Windows.Foundation.Metadata.Overload("CreateDownloadFromFile")]
public DownloadOperation CreateDownload(System.Uri uri, IStorageFile resultFile, IStorageFile requestBodyFile);

function createDownload(uri, resultFile, requestBodyFile)

Public Function CreateDownload (uri As Uri, resultFile As IStorageFile, requestBodyFile As IStorageFile) As DownloadOperation

Parameters

uri

Uri Uri

The location of the resource.

resultFile

IStorageFile

The file that the response will be written to.

requestBodyFile

IStorageFile

A file that represents the request entity body, which contains additional data the server requires before the download can begin. The file this object points to must be valid for the duration of the download.

Returns

DownloadOperation

The resultant download operation.

Attributes

OverloadAttribute

Remarks

The resultant DownloadOperation supports scenarios where a valid download request contains specific data required by the server. For example, a website requires a filled out form before the download can take place.

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.

Important

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

operation = await Task.Run(() => { return myDownloader.CreateDownload(uri, file); });

Note

Some file systems have file size limits. Background transfer has special logic to fast-fail transfers that exceed the destination drive's file size limits (for example, files that exceed 4GB in size for FAT32 file systems). If the server responds with a Content-Length header value greater than the file system's maximum file size, then the download operation immediately fails with HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_LIMITATION).

See also

• CreateDownload(Uri, IStorageFile)