UploadOperation Class

Definition

Performs an asynchronous upload operation. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background transfer sample for a code example.

public ref class UploadOperation sealed : IBackgroundTransferOperationPriority
class UploadOperation sealed : IBackgroundTransferOperationPriority
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class UploadOperation : IBackgroundTransferOperationPriority
Public NotInheritable Class UploadOperation
Implements IBackgroundTransferOperationPriority
Inheritance
UploadOperation
Attributes
Implements

Windows 10 requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)
App capabilities
internetClient internetClientServer privateNetworkClientServer

Examples

The following example demonstrates how to configure and begin a basic upload operation.

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

        using Windows.Foundation; 
        using Windows.Networking.BackgroundTransfer;
        using Windows.Storage.Pickers;
        using Windows.Storage;

        private async void StartUpload_Click(object sender, RoutedEventArgs e)
        {
            try
            {
                Uri uri = new Uri(serverAddressField.Text.Trim());
                FileOpenPicker picker = new FileOpenPicker();
                picker.FileTypeFilter.Add("*");
                StorageFile file = await picker.PickSingleFileAsync();

                BackgroundUploader uploader = new BackgroundUploader();
                uploader.SetRequestHeader("Filename", file.Name);

                UploadOperation upload = uploader.CreateUpload(uri, file);

                // Attach progress and completion handlers.
                HandleUploadAsync(upload, true);
            }
            catch (Exception ex)
            {
                LogException("Upload Error", ex);
            }
        }

Remarks

After app termination, an app should enumerate all existing UploadOperation instances at next start-up using GetCurrentUploadsAsync. When a UWP 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.Timeout considerations

  • 1.) When establishing a new connection for an upload 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 an upload 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; PUT uploads are paused and POST uploads are aborted. Even while debugging, your app should enumerate and then pause, restart, or cancel any persisted uploads.

However, if Microsoft Visual Studio project updates, like changes to the app manifest, require that the app is uninstalled and re-deployed for debugging, GetCurrentUploadsAsync cannot enumerate persisted operations created using the previous app deployment.

Version history

Windows version SDK version Value added
1803 17134 MakeCurrentInTransferGroup

Properties

CostPolicy

Gets and sets the cost policy for the upload.

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 upload belongs to.

Guid

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

Method

Gets the method to use for the upload.

Priority

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

Progress

Gets the current progress of the upload operation.

RequestedUri

Gets the URI to upload from.

SourceFile

Specifies the IStorageFile to upload.

TransferGroup

Gets the group that this upload operation belongs to.

Methods

AttachAsync()

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

GetResponseInformation()

Gets the response information.

GetResultStreamAt(UInt64)

Gets the partially uploaded response at the specified location.

MakeCurrentInTransferGroup()

Prioritizes the upload 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.

RemoveRequestHeader(String)

Used to remove an HTTP request header.

SetRequestHeader(String, String)

Used to set an HTTP request header.

StartAsync()

Starts an asynchronous upload operation.

Applies to

See also