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 要求訊息。假設有網際網路連線能力，背景傳輸最多會重試下載三次。在未偵測到網際網路連線的情況下，除非進行其他嘗試，否則不會進行其他嘗試。

偵錯指引

在 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 需求

範例

備註

版本歷程記錄

屬性

方法

事件

適用於

另請參閱

意見反應

意見反應

其他資源