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), use the Windows.Web.Http namespace.
The BackgroundDownloader class has these types of members:
The BackgroundDownloader class has these constructors.
|BackgroundDownloader||Instantiates a new BackgroundDownloader object.|
The BackgroundDownloader class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.
|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.|
|CreateDownloadAsync||Creates an asynchronous download operation that includes a URI, the file that the response will be written to, and the IInputStream object from which the file contents are read.|
|GetCurrentDownloadsAsync()||Returns a collection of pending downloads that are not associated with a group.|
|GetCurrentDownloadsAsync(String)||Returns a collection of pending downloads for a specific Group.|
|GetCurrentDownloadsForTransferGroupAsync||Gets all downloads associated with the provided BackgroundTransferGroup|
|RequestUnconstrainedDownloadsAsync||Used to request an unconstrained download operation. When this method is called the user is provided with a UI prompt that they can use to indicate their consent for an unconstrained operation.|
|SetRequestHeader||Used to set an HTTP request header.|
The BackgroundDownloader class has these properties.
|Read/write||Gets or sets the cost policy for the background download operation.|
|Read/write||Gets or sets the TileNotification used to define the visuals, identification tag, and expiration time of a tile notification used to update the app tile when indicating failure of a download to the user.|
|Read/write||Gets or sets the ToastNotification that defines the content, associated metadata, and events used in a toast notification to indicate failure of a download to the user.|
|Read/write||Gets or sets a string value (e.g. a GUID) indicating the group the transfer will belong to. A download operation with a group ID will only appear in operation enumerations using GetCurrentDownloadsAsync(String)|
|Read/write||Gets or sets the HTTP method used for the background download|
|Read/write||Gets or sets the proxy credentials for the background transfer.|
|Read/write||Gets or sets the credentials to use to authenticate with the origin server.|
|Read/write||Gets or sets the TileNotification used to define the visuals, identification tag, and expiration time of a tile notification used to update the app tile when indicating success of a download to the user.|
|Read/write||Gets or sets the ToastNotification that defines the content, associated metadata, and events used in a toast notification to indicate success of a download to the user.|
|Read/write||Gets or sets the group that a download operation will belong to.|
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 operations from the previous session are not enumerated and re-attached to the current session, they will remain incomplete and continue to occupy resources.
Note When an app is uninstalled any current or persisted Background Transfer operations associated with it are cleaned up.
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.
When implementing a library for Background Transfer operations, and this same library is used by other apps or components, specify a uniquegroup name string (e.g. a GUID) when creating downloads. An download with a group name string can only be enumerated by providing the matching string to GetCurrentDownloadsAsync(String), and will not appear in GetCurrentDownloadsAsync calls without. This will ensure that other apps implementing that same library for downloads will not see your downloads.
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.
Security concerns can exist when download operations require a username and password for authentication. If the authentication model to be used is supported by WinINet, use the ServerCredential or ProxyCredential properties. These values will be securely saved in WinVault. For information on supported authentication methods, see Handling Authentication.
If the authentication model is not supported by WinINet, use HttpClient to implement custom authentication and obtain a download-specific secure token (cookie). Set the appropriate header to have the secure token value used for background transfer. The service should limit the validity of the secure token only to the file that is being downloaded.
Note The secure token will be stored in clear text within the application’s folder.
Upload services that require the username and password be set in clear text in a custom header for each download file are insecure. Background transfer will cache the headers in clear text for the duration of the operation within the app’s folder.
The BackgroundDownloader class in Windows 8.1 and Windows Server 2012 R2 supports options for the user to receive tile and toast notifications when a transfer is completed successfully or fails to complete.
An app that uses Windows.Networking.BackgroundTransfer to communicate through a toast notification must declare that it is Toast capable in the app manifest file. The Toast capable setting is located under the Notifications section of Application tab. Set the Toast capable option to "Yes" so the app can receive toast notifications.
If Toast capable is not enabled in the app manifest, then any toast settings in the Windows.Networking.BackgroundTransfer namespace will be silently ignored and no toasts notifications will be received by the app.
Note A user can manually disable or enable toast notifications for your app at any time.
A number of errors can cause exceptions to occur during a download operation. You should write code to handle exceptions when you call methods on this class. Exceptions can result from parameter validation errors, name resolution failures, and network errors. Exceptions from network errors (loss of connectivity, connection failures, and other HTTP errors, for example) can happen at any time. These errors result in exceptions being thrown. If not handled by your app, an exception can cause your entire app to be terminated by the runtime.
An app can use the HRESULT from the exception to determine the error that caused the exception. An app can then decide how to handle the exception based on the error code. The BackgroundTransferError.GetStatus method can convert most HRESULT values returned to a WebErrorStatus enumeration value. Most of the WebErrorStatus enumeration values correspond to an error returned by the native HTTP or FTP client operation. An app can filter on specific WebErrorStatus enumeration values to modify app behavior depending on the cause of the exception.
For information on network exceptions, see Handling exceptions in network apps.
Stopping a debugging session in Microsoft Visual Studio is comparable to closing your app. Even while debugging, your app should enumerate and then, resume, restart, or cancel any downloads persisted from the previous session. For example, you can have your app cancel enumerated persisted download operations at app startup if there is no interest in previous operations for the current debug session.
If there are Visual Studio project updates, like changes to the app manifest, and the app is uninstalled and re-deployed, GetCurrentUploadsAsync cannot enumerate operations created using the previous app deployment.
See Debugging and testing Windows Store apps for more information.
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.
Minimum supported client
|Windows 8 [Windows Store apps only]|
Minimum supported server
|Windows Server 2012 [Windows Store apps only]|
- Handling exceptions in network apps
- How to opt in for toast notifications
- Quickstart: Download a file
- Background Transfer sample
Build date: 11/16/2013