BackgroundUploader 类

定义

命名空间:

Windows.Networking.BackgroundTransfer

用于使用 CreateUpload 在实际创建上传操作之前配置上传。 有关后台传输功能的概述，请参阅 在后台传输数据。 下载代码示例的 后台传输示例 。

注意

后台传输主要用于视频、音乐和大型图像等资源的长期传输操作。 对于涉及传输较小资源的短期操作 (（即几个 KB) ），请使用 Windows.Web.Http 命名空间。

public ref class BackgroundUploader sealed

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

继承

Object Platform::Object IInspectable BackgroundUploader

属性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

实现

IBackgroundTransferBase

Windows 要求

设备系列	Windows 10 (在 10.0.10240.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v1.0 中引入)
应用功能	internetClient internetClientServer privateNetworkClientServer

示例

以下示例演示如何配置和开始基本上传操作。

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

注解

应用终止后，应用应在下次启动时使用 GetCurrentUploadsAsync 枚举所有现有的 UploadOperation 实例。 终止使用后台传输的 UWP 应用时，未完成的上传将保留在后台。 如果在终止后重启应用，并且未枚举上一个会话的操作并重新附加到当前会话，则这些操作将保持不完整并继续占用资源。 枚举后，PUT 上传操作会自动重启，POST 上传操作将终止。

注意

卸载应用时，将清除与其关联的任何当前或持久后台传输操作。

为后台传输操作实现库，并且此库由其他应用或组件使用时，请指定唯一的组 名字符串 (例如，在创建上传时) GUID 。 只有向 GetCurrentDownloadsAsync 提供匹配的字符串 (String) ，才能枚举具有组名字符串的上传，并且不会显示在没有 的 GetCurrentDownloadsAsync 调用中。 这将确保为上传实现同一库的其他应用不会看到你的上传

不支持通过 FTP 执行上传操作。

上传操作需要用户名和密码进行身份验证时，可能存在安全问题。 如果 WinINet 支持要使用的身份验证模型，请使用 ServerCredential 或 ProxyCredential 属性。 这些值将安全地保存在 WinVault 中。 有关支持的身份验证方法的信息，请参阅 处理身份验证。

如果 WinINet 不支持身份验证模型，请使用 HttpClient 实现自定义身份验证，并获取特定于上传的安全令牌 (cookie) 。 设置适当的标头，使其具有用于后台传输的安全令牌值。 服务应将安全令牌的有效性限制为上传的文件。

注意

安全令牌将以明文形式存储在应用程序的 文件夹中。

需要在每个上传文件的自定义标头中以明文格式设置用户名和密码的上传服务是不安全的。 后台传输将在应用文件夹内操作期间以明文形式缓存标头。

Toast 通知

Windows 8.1 和 Windows Server 2012 R2 中的 BackgroundUploader 类支持用户在传输成功完成或无法完成时接收磁贴和 Toast 通知的选项。

使用 Windows.Networking.BackgroundTransfer 通过 Toast 通知进行通信的应用必须在应用清单文件中声明它 支持 Toast 。 支持 Toast 的设置位于“应用程序”选项卡的“通知”部分下。将“支持 Toast”选项设置为“是”，以便应用可以接收 Toast 通知。

如果在应用清单中未启用 Toast 功能 ，则 Windows.Networking.BackgroundTransfer 命名空间中的任何 Toast 设置都将以无提示方式被忽略，并且应用不会收到任何 Toast 通知。

注意

用户可以随时为应用手动禁用或启用 Toast 通知。

有关 Toast 通知的详细信息，请参阅 发送 Toast 通知 和 如何选择加入 Toast 通知。

处理异常

许多错误可能会导致上传操作期间发生异常。 在此类上调用方法时，应编写代码来处理异常。 异常可能由参数验证错误、名称解析失败和网络错误引起。 网络错误 (连接丢失、连接故障和其他 HTTP 错误（例如，随时可能发生) ）的异常。 这些错误将引发异常。 如果应用未处理，异常可能会导致整个应用被运行时终止。

应用可以使用异常中的 HRESULT 来确定导致异常的错误。 然后，应用可以根据错误代码决定如何处理异常。 BackgroundTransferError.GetStatus 方法可以将返回的大多数 HRESULT 值转换为 WebErrorStatus 枚举值。 大部分 WebErrorStatus 枚举值对应由本机 HTTP 或 FTP 客户端操作返回的错误。 应用可以筛选特定 WebErrorStatus 枚举值来基于异常原因修改应用行为。

某些 HRESULT 值无法转换为 WebErrorStatus 枚举值。 取消后台 POST 操作时，将引发异常。 操作不会重启。 有关详细信息，请参阅 UploadOperation.StartAsync

有关网络异常的信息，请参阅 处理网络应用中的异常。

调试指南

在 Microsoft Visual Studio 中停止调试会话与关闭你的应用相似；PUT 上载将暂停，POST 上载将终止。 即使在调试时，你的应用也应该枚举，然后重新启动或取消任何保持的上载。 例如，如果对该调试会话之前的操作没有兴趣，你可以使应用在应用启动时取消已枚举的持续上载操作。

在调试会话期间，当系统随着应用启动开始枚举下载/上载时，如果对该调试会话之前的操作没有兴趣，你可以让应用取消它们。 请注意，如果有 Microsoft Visual Studio 项目更新（如对应用清单的更改），并且应用已卸载并重新部署， 则 GetCurrentUploadsAsync 无法枚举使用以前的应用部署创建的操作。

有关详细信息 ，请参阅调试和测试 UWP 应用 。

如果在开发过程中使用后台传输功能，则你可能会遇到活动和已完成传输操作的内部缓存不同步的情况。这可能会导致无法启动新的传输操作或者无法与现有操作和 BackgroundTransferGroup 对象交互。 在某些情况下，尝试与现有操作交互可能引发崩溃。 如果 TransferBehavior 属性设置为 Parallel，则可能产生该结果。 该问题仅在开发期间的某些应用场景中发生，该情况不适用于应用的最终用户。

使用 Microsoft Visual Studio 的四种方案可能会导致此问题。

• 你用于创建新项目的应用名称与现有项目相同，但语言不同（例如从 C++ 改为 C#）。
• 你更改了现有项目中的目标体系结构（例如，从 x86 改为 x64）。
• 你更改了现有项目中的区域性（例如，从中性改为 en-US）。
• 你在现有项目的程序包清单中添加或删除了一项功能（例如，添加企业身份验证）。 常规应用服务（包含可添加或删除功能的清单更新）不会在应用的最终用户部署时导致该问题。

若要解决该问题，请彻底卸载应用的所有版本，并采用新的语言、体系结构、区域性或功能重新部署。 这可以通过 “开始” 屏幕或使用 PowerShell 和 Remove-AppxPackage cmdlet 来完成。

构造函数

BackgroundUploader()	实例化新的 BackgroundUploader 对象。
BackgroundUploader(BackgroundTransferCompletionGroup)	将新的 BackgroundUploader 对象实例化为完成组的成员。

属性

CompletionGroup	获取与 BackgroundUploader 关联的 BackgroundTransferCompletionGroup。
CostPolicy	获取或设置后台上传操作的成本策略。
FailureTileNotification	获取并设置用于定义磁贴通知的视觉对象、标识标记和过期时间的 TileNotification ，该通知用于在指示向用户上载失败时更新应用磁贴。
FailureToastNotification	获取或设置 ToastNotification ，它定义 Toast 通知中使用的内容、关联的元数据和事件，以指示向用户上传失败。
Group	注意 Windows 8.1后，组可能会更改或不可用于发布。 请改用 TransferGroup。 获取或设置一个字符串值， (例如 GUID) 指示上传所属的组。 具有组 ID 的上传操作只会显示在使用具有特定组字符串值的 GetCurrentDownloadsAsync (String) 的操作枚举中。
Method	获取或设置用于上传的 HTTP 方法。 用于上传操作的默认方法是 POST。
ProxyCredential	获取或设置上传的代理凭据。
ServerCredential	获取或设置用于向源服务器进行身份验证的凭据。
SuccessTileNotification	获取并设置用于定义磁贴通知的视觉对象、标识标记和过期时间的 TileNotification ，该通知用于在指示成功上载到用户时更新应用磁贴。
SuccessToastNotification	获取或设置 ToastNotification ，它定义 Toast 通知中使用的内容、关联的元数据和事件，以指示成功上载到用户。
TransferGroup	获取或设置上传操作所属的组。

方法

CreateUpload(Uri, IStorageFile)	初始化一个 UploadOperation ，该操作指示要上传的 和 文件的位置。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	返回一个异步操作，该操作在完成时返回具有指定 URI 和一个或多个 BackgroundTransferContentPart 对象的 UploadOperation。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	返回一个异步操作，该操作在完成时返回具有指定 URI、一个或多个 BackgroundTransferContentPart 对象和多部分子类型的 UploadOperation。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	返回一个异步操作，该操作在完成时返回 UploadOperation ，其中包含指定的 URI、多部分子类型、一个或多个 BackgroundTransferContentPart 对象以及用于分隔每个部分的分隔符边界值。
CreateUploadFromStreamAsync(Uri, IInputStream)	返回一个异步操作，该操作在完成后返回具有指定 URI 和源流的 UploadOperation 。
GetCurrentUploadsAsync()	返回未与组关联的挂起上传的集合。
GetCurrentUploadsAsync(String)	注意 getCurrentUploadsAsync (组) 可能在Windows 8.1后更改或不可用。 请改用 GetCurrentUploadsForTransferGroupAsync。 返回特定 组的挂起上载的集合。
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	获取与提供的 BackgroundTransferGroup 关联的所有上传。
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	注意 RequestUnconstrainedUploadsAsync 可能在Windows 10版本 1607 之后更改或不可用。 请改用 CreateUploadAsync。 用于请求不受约束的上传操作。 调用此方法时，会向用户提供 UI 提示，用户可以使用该提示来指示他们对不受约束的操作的同意。在设备使用电池运行时，不受约束的传输操作将不受通常与后台网络操作相关的资源限制。
SetRequestHeader(String, String)	用于设置 HTTP 请求标头。

另请参阅

• UploadOperation
• 处理网络应用中的异常
• 如何选择加入 Toast 通知
• 快速入门：上传文件
• 后台传输示例
• Windows 8.x) (后台传输示例