BackgroundUploader Class

Definition

public ref class BackgroundUploader sealed

/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class BackgroundUploader final

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundUploader final

[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class BackgroundUploader

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundUploader

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

Inheritance

Object Platform::Object IInspectable BackgroundUploader

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements

IBackgroundTransferBase

Windows requirements

Examples

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

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 operations from the previous session are not enumerated and re-attached to the current session, they will remain incomplete and continue to occupy resources. Once enumerated, PUT upload operations are automatically restarted, and POST upload operations are terminated.

When implementing a library for Background Transfer operations, and this same library is used by other apps or components, specify a uniquegroup name string (for example, a GUID) when creating uploads. An upload 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 uploads will not see your uploads

Upload operations via FTP are not supported.

Security concerns can exist when upload 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 an upload-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 uploaded.

Upload services that require the username and password be set in clear text in a custom header for each upload file are insecure. Background transfer will cache the headers in clear text for the duration of the operation within the app's folder.

Toast notifications

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

For more information on toast notifications, see Sending toast notifications and How to opt in for toast notifications.

Handling Exceptions

A number of errors can cause exceptions to occur during an upload 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.

Some HRESULT values cannot be converted to a WebErrorStatus enumeration value. When a background POST operation is canceled, an exception is thrown. The operation is not restarted. For more information, see UploadOperation.StartAsync

For information on network exceptions, see Handling exceptions in network apps.

Debugging Guidance

Stopping a debugging session in Microsoft Visual Studio is comparable to closing your app; PUT uploads are paused and POST uploads are terminated. Even while debugging, your app should enumerate and then restart or cancel any persisted uploads. For example, you can have your app cancel enumerated persisted upload operations at app startup if there is no interest in previous operations for that debug session.

While enumerating downloads/uploads on app startup during a debug session, you can have your app cancel them if there is no interest in previous operations for that debug session. Note that if there are Microsoft 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 UWP apps for more information.

When using Background Transfer during development, you may get into a situation where the internal caches of active and completed transfer operations can get out of sync. This may result in the inability to start new transfer operations or interact with existing operations and BackgroundTransferGroup objects. In some cases, attempting to interact with existing operations may trigger a crash. This result can occur if the TransferBehavior property is set to Parallel. This issue occurs only in certain scenarios during development and is not applicable to end users of your app.

Four scenarios using Microsoft Visual Studio can cause this issue.

• You create a new project with the same app name as an existing project, but a different language (from C++ to C#, for example).
• You change the target architecture (from x86 to x64, for example) in an existing project.
• You change the culture (from neutral to en-US, for example) in an existing project.
• You add or remove a capability in the package manifest (adding Enterprise Authentication, for example) in an existing project. Regular app servicing, including manifest updates which add or remove capabilities, do not trigger this issue on end user deployments of your app.

To work around this issue, completely uninstall all versions of the app and re-deploy with the new language, architecture, culture, or capability. This can be done via the Start screen or using PowerShell and the Remove-AppxPackage cmdlet.

Constructors

Properties

Methods

Applies to

See also

• UploadOperation
• Handling exceptions in network apps
• How to opt in for toast notifications
• Quickstart: Upload a file
• Background transfer sample
• Background transfer sample (Windows 8.x)