BackgroundUploader class

Used to configure upload prior to the actual creation of the upload operation using CreateUpload. 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 backgroundUploader = new Windows.Networking.BackgroundTransfer.BackgroundUploader();

Attributes

ActivatableAttribute(NTDDI_WIN8)

MarshalingBehaviorAttribute(Agile)

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

ThreadingAttribute(Both)

VersionAttribute(NTDDI_WIN8)

Members

The BackgroundUploader class has these types of members:

• Constructors
• Methods
• Properties

Constructors

The BackgroundUploader class has these constructors.

Methods

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

Properties

The BackgroundUploader class has these properties.

Remarks

Upload operations via FTP are not supported.

After app termination, an app should enumerate all existing UploadOperation instances at next start-up using GetCurrentUploadsAsync. When a Windows Store app using Background Transfer is terminated, incomplete uploads 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. Once enumerated, PUT upload operations are automatically restarted, and POST upload operations are terminated.

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 upload operation, and is based on the Background Transfer sample offered in the Windows Sample Gallery.

        var upload = null;
        var promise = null;

        function UploadFile (uriString, file) {
            try {

                var uri = Windows.Foundation.Uri(uriString);
                var uploader = new Windows.Networking.BackgroundTransfer.BackgroundUploader();

                // Set a header, so the server can save the file (this is specific to the sample server).
                uploader.setRequestHeader("Filename", file.name);

                // Create a new upload operation.
                upload = uploader.createUpload(uri, file);

                // Start the upload and persist the promise to be able to cancel the upload.
                promise = upload.startAsync().then(complete, error, progress);
            } catch (err) {
                displayError(err);
            }
        };

Requirements

See also

Quickstart: Upload a file

Background Transfer sample

Build date: 12/4/2012