共用方式為


DownloadOperation 類別

定義

執行非同步下載作業。 背景傳輸範例示範這項功能。 如需背景傳輸功能的概觀,請參閱 在背景傳輸資料

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
屬性
實作

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 的兩個下載,因為這可能會導致截斷的檔案。

注意

只有在伺服器接受範圍要求時,才能繼續暫停或不完整的下載作業。

逾時考慮

  1. 建立透過 TCP/SSL 下載的新連線時,如果在五分鐘內未建立連線,就會中止連線嘗試。
  2. 建立連線之後,系統會中止在兩分鐘內未收到回應的 HTTP 要求訊息。 假設有網際網路連線能力,背景傳輸最多會重試下載三次。 在未偵測到網際網路連線的情況下,除非進行其他嘗試,否則不會進行其他嘗試。

偵錯指引

在 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

提供累加式下載進度的存取權。

適用於

另請參閱