UploadOperation UploadOperation UploadOperation 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 examples in JavaScript, C#, and C++.

public sealed class UploadOperationpublic sealed class UploadOperationPublic NotInheritable Class UploadOperationpublic sealed class UploadOperation
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

Remarks

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

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

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

Properties

CostPolicy CostPolicy CostPolicy CostPolicy

Gets and sets the cost policy for the upload.

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

Specifies whether the transfer can happen over costed networks.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

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

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

The group name.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

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

public Guid Guid { get; }public Guid Guid { get; }Public ReadOnly Property Guid As Guidpublic Guid Guid { get; }
Value
System.Guid System.Guid System.Guid System.Guid

The unique ID for this upload operation.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

Method Method Method Method

Gets the method to use for the upload.

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

The method to use for the upload. This value can be GET, PUT, POST, RETR, STOR, or any custom value supported by the server.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

Priority Priority Priority Priority

Gets or sets the transfer priority of this upload 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; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

Progress Progress Progress Progress

Gets the current progress of the upload operation.

public BackgroundUploadProgress Progress { get; }public BackgroundUploadProgress Progress { get; }Public ReadOnly Property Progress As BackgroundUploadProgresspublic BackgroundUploadProgress Progress { get; }
Value
BackgroundUploadProgress BackgroundUploadProgress BackgroundUploadProgress BackgroundUploadProgress

The delegate to invoke when progress is available for a transfer operation.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

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

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

The URI to upload from.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

SourceFile SourceFile SourceFile SourceFile

Specifies the IStorageFile to upload.

public IStorageFile SourceFile { get; }public IStorageFile SourceFile { get; }Public ReadOnly Property SourceFile As IStorageFilepublic IStorageFile SourceFile { get; }
Value
IStorageFile IStorageFile IStorageFile IStorageFile

The file item to upload.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

TransferGroup TransferGroup TransferGroup TransferGroup

Gets the group that this upload operation belongs to.

public BackgroundTransferGroup TransferGroup { get; }public BackgroundTransferGroup TransferGroup { get; }Public ReadOnly Property TransferGroup As BackgroundTransferGrouppublic BackgroundTransferGroup TransferGroup { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

Methods

AttachAsync() AttachAsync() AttachAsync() 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.

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

Upload operation with callback.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

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 AttachUpload (loadedUpload) {
            try {
                upload = loadedUpload;
                promise = upload.attachAsync().then(complete, error, progress);
            } catch (err) {
                displayError(err);
            }
        };

GetResponseInformation() GetResponseInformation() GetResponseInformation() GetResponseInformation()

Gets the response information.

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

Contains the data returned by a server response.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

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 upload 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 upload to pause, application called Pause(), etc.), Background Transfer will invoke a new request and try to restart the upload. 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 UploadOperation is being made using a protocol other than HTTP (e.g., FTP).
  • The UploadOperation 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 uploaded response at the specified location.

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
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

StartAsync() StartAsync() StartAsync() StartAsync()

Starts an asynchronous upload operation.

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

An asynchronous upload operation that includes progress updates.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
internetClientServer privateNetworkClientServer internetClient

Remarks

An upload operation must be scheduled using one of the CreateUpload(Uri, IStorageFile), CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>) , or CreateUploadFromStreamAsync(Uri, 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 myUploadOperation.StartAsync(); });