DownloadOperation 类

参考

定义

命名空间:: Windows.Networking.BackgroundTransfer

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

编辑

执行异步下载操作。后台传输示例演示了此功能。有关后台传输功能的概述，请参阅在后台传输数据。

public ref class DownloadOperation sealed : IBackgroundTransferOperationPriority

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class DownloadOperation final : IBackgroundTransferOperationPriority

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class DownloadOperation : IBackgroundTransferOperationPriority

Public NotInheritable Class DownloadOperation
Implements IBackgroundTransferOperationPriority

继承: Object Platform::Object IInspectable DownloadOperation

属性: ContractVersionAttribute MarshalingBehaviorAttribute

实现: IBackgroundTransferOperation IBackgroundTransferOperationPriority

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 的两次下载，因为这可能会导致文件被截断。

注意

仅当服务器接受范围请求时，才能恢复已暂停或不完整的下载操作。

超时注意事项

通过 TCP/SSL 为下载建立新连接时，如果未在五分钟内建立连接尝试，则会中止连接尝试。
建立连接后，两分钟内未收到响应的 HTTP 请求消息将中止。假设有 Internet 连接，后台传输将重试下载最多三次。如果未检测到 Internet 连接，则在检测到 Internet 连接之前，不会进行其他尝试。

调试指南

在 Microsoft Visual Studio 中停止调试会话相当于关闭应用;暂停下载并终止 POST 上传。即使在调试时，应用也应枚举，然后暂停、继续、重启或取消任何持久下载。

但是，如果 Microsoft Visual Studio 项目更新（如对应用清单的更改）要求卸载并重新部署应用进行调试，则 GetCurrentDownloadsAsync 无法枚举使用以前的应用部署创建的持久操作。

版本历史记录

Windows 版本	SDK 版本	增值
1709	16299	CurrentWebErrorStatus
1709	16299	GetDownloadedRanges
1709	16299	GetResultRandomAccessStreamReference
1709	16299	IsRandomAccessRequired
1709	16299	RangesDownloaded
1709	16299	RecoverableWebErrorStatuses
1803	17134	MakeCurrentInTransferGroup
2004	19041	RemoveRequestHeader
2004	19041	SetRequestHeader

属性

CostPolicy	获取并设置下载的成本策略。
CurrentWebErrorStatus	传输的 WebErrorStatus，可在 DownloadOperation 的生存期内对其进行监视。
Group	注意 Windows 8.1后，组可能会更改或不可用于发布。请改用 TransferGroup。获取一个字符串值，该值指示传输所属的组。
Guid	这是特定下载操作的唯一标识符。与下载操作关联的 GUID 在下载期间不会更改。
IsRandomAccessRequired	用于启用随机访问的布尔属性。在调用 DownloadOperation 对象上的 StartAsync () 才能使用随机访问功能之前，属性必须设置为 TRUE。调用 StartAsync () 后，调用 GetResultRandomAccessStreamReference 以获取对随机访问流的引用并从中进行读取。
Method	获取要用于下载的方法。
Priority	获取或设置在 BackgroundTransferGroup 中时此下载操作的传输优先级。可能的值由 BackgroundTransferPriority 定义。
Progress	获取操作的当前进度。
RecoverableWebErrorStatuses	一组 WebErrorStatus 值，应用程序预计下载将命中这些值，并且应用程序知道如何处理这些值。
RequestedUri	获取从中下载文件的 URI。
ResultFile	返回使用 CreateDownload 创建 DownloadOperation 对象时调用方提供的 IStorageFile 对象。
TransferGroup	获取此下载操作所属的组。

方法

AttachAsync()	返回可用于监视附加下载的进度和完成情况的异步操作。调用此方法允许应用附加在以前的应用实例中启动的下载操作。
GetDownloadedRanges()	返回到目前为止已下载的文件范围的完整列表。
GetResponseInformation()	获取响应信息。
GetResultRandomAccessStreamReference()	获取对随机访问流的引用并从中进行读取。在调用 GetResultRandomAccessStreamReference 之前，必须将 IsRandomAccessRequired 设置为 TRUE。
GetResultStreamAt(UInt64)	获取指定位置的部分下载响应。
MakeCurrentInTransferGroup()	确定下载传输操作 (的优先级，并在同一传输组) 之后的任何传输。对不属于传输组的传输调用此方法不起作用。
Pause()	暂停下载操作。
RemoveRequestHeader(String)	用于删除 HTTP 请求标头。
Resume()	恢复暂停的下载操作。
SetRequestHeader(String, String)	用于设置 HTTP 请求标头。
StartAsync()	启动异步下载操作。

事件

RangesDownloaded

提供对增量下载进度的访问。

适用于

通过

DownloadOperation 类

定义

Windows 要求

示例

注解

版本历史记录

属性

方法

事件

适用于

另请参阅

反馈

其他资源