BackgroundDownloader 类

定义

命名空间:

Windows.Networking.BackgroundTransfer

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

注意

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

public ref class BackgroundDownloader 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(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundDownloader 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(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundDownloader

function BackgroundDownloader(completionGroup)

Public NotInheritable Class BackgroundDownloader

继承

Object Platform::Object IInspectable BackgroundDownloader

属性

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;

private async void StartDownload_Click(object sender, RoutedEventArgs e)
 {
     try
     {
         Uri source = new Uri(serverAddressField.Text.Trim());
         string destination = fileNameField.Text.Trim();

         StorageFile destinationFile = await KnownFolders.PicturesLibrary.CreateFileAsync(
             destination, CreationCollisionOption.GenerateUniqueName);

         BackgroundDownloader downloader = new BackgroundDownloader();
         DownloadOperation download = downloader.CreateDownload(source, destinationFile);

         // Attach progress and completion handlers.
         HandleDownloadAsync(download, true);
     }
     catch (Exception ex)
     {
         LogException("Download Error", ex);
     }
 }

注解

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

注意

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

后台传输不支持并发下载同一 URI。 因此，应用可以下载 http://example.com/myfile.wmv 一次，也可以在上一次下载完成后再次下载。 应用不应同时启动同一 Uri 的两次下载，因为这可能会导致文件被截断。

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

支持通过 FTP 进行下载操作。 但是，对于 FTP 操作，必须在指定的 URI 中提供身份验证凭据。 例如， ftp://user:password@server/file.txt。

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

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

注意

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

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

Toast 通知

Windows 8.1 和 Windows Server 2012 R2 中的 BackgroundDownloader 类支持用户在传输成功完成或无法完成时接收磁贴和 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 枚举值来基于异常原因修改应用行为。

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

调试指南

在 Microsoft Visual Studio 中停止调试会话相当于关闭应用。 即使在调试时，应用也应枚举 ，然后继续、重启或取消上一会话中保留的任何下载。 例如，如果对当前调试会话的先前操作不感兴趣，则可以在应用启动时让应用取消枚举持久下载操作。

如果存在 Microsoft Visual Studio 项目更新（如对应用清单的更改），并且应用已卸载并重新部署， 则 GetCurrentUploadsAsync 无法枚举使用以前的应用部署创建的操作。

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

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

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

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

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

构造函数

BackgroundDownloader()	创建新的 BackgroundDownloader 对象。
BackgroundDownloader(BackgroundTransferCompletionGroup)	使用 BackgroundTransferCompletionGroup 创建新的 BackgroundDownloader 对象。

属性

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

方法

CreateDownload(Uri, IStorageFile)	初始化一个 DownloadOperation 对象，该对象包含指定的 URI 和将响应写入到的文件。
CreateDownload(Uri, IStorageFile, IStorageFile)	使用资源 URI、写入响应的文件以及请求实体正文初始化 DownloadOperation 对象。
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	创建一个异步下载操作，其中包含 URI、将写入响应的文件以及从中读取文件内容的 IInputStream 对象。
GetCurrentDownloadsAsync()	返回未与 BackgroundTransferGroup 关联的挂起下载的集合。
GetCurrentDownloadsAsync(String)	注意 getCurrentDownloadsAsync (组) 在Windows 8.1后可能会更改或不可用。 请改用 GetCurrentDownloadsForTransferGroupAsync。 返回特定 组的挂起下载的集合。
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	获取与提供的 BackgroundTransferGroup 关联的所有下载。
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	注意 RequestUnconstrainedDownloadsAsync 可能会在Windows 10版本 1607 之后被更改或不可用。 请改用 CreateDownloadAsync。 用于请求不受约束的下载操作。 调用此方法时，会向用户提供一个 UI 提示，用户可以使用该提示来指示他们对不受限制的操作的同意。当设备使用电池运行时，不受约束的传输操作将运行，且没有通常与后台网络操作相关的资源限制。
SetRequestHeader(String, String)	用于设置 HTTP 请求标头。

另请参阅

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