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 app 終止時，不完整的下載將會保存在背景中。 如果應用程式在終止之後重新開機，而且不會列舉上一個會話的作業並重新附加至目前的會話，它們將會維持不完整並繼續佔用資源。

注意

當應用程式卸載任何與應用程式相關聯的目前或持續性背景傳輸作業時，即會加以清除。

背景傳輸不支援相同 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) 取得下載特定的安全權杖 (。 設定適當的標頭，讓用於背景傳輸的安全權杖值。 服務應該只會將安全權杖的有效性限制為正在下載的檔案。

注意

安全權杖會以純文字形式儲存在應用程式的 資料夾中。

上傳需要以純文字方式設定每個下載檔案之自訂標頭中使用者名稱和密碼的服務不安全。 背景傳輸會在應用程式資料夾內的作業期間，以純文字快取標頭。

快顯通知

Windows 8.1 和 Windows Server 2012 R2 中的 BackgroundDownloader 類別支援使用者在傳輸順利完成或無法完成時接收磚和快顯通知的選項。

使用 Windows.Networking.BackgroundTransfer 透過快顯通知進行通訊的應用程式，必須宣告它在應用程式資訊清單檔案中 具有 Toast 功能 。 [支援快顯通知] 設定位於 [應用程式] 索引標籤的 [通知] 區段底下。將[支援快顯通知]選項設定為 [是]，讓應用程式可以接收快顯通知。

如果 應用程式 資訊清單中未啟用快顯通知，則會以無訊息方式忽略 Windows.Networking.BackgroundTransfer 命名空間中的任何快顯通知，且應用程式不會收到任何快顯通知。

注意

使用者可以隨時手動停用或啟用應用程式的快顯通知。

如需快顯通知的詳細資訊，請參閱傳送快 顯通知 和 如何加入宣告快顯通知。

處理例外狀況

許多錯誤可能會導致下載作業期間發生例外狀況。 當您在此類別上呼叫方法時，您應該撰寫程式碼來處理例外狀況。 例外狀況可能是因為參數驗證錯誤、名稱解析失敗和網路錯誤所造成。 網路錯誤 (連線中斷、連線失敗和其他 HTTP 錯誤的例外狀況，例如) 隨時都可能發生。 這些錯誤會造成擲出例外狀況。 如果應用程式未處理，例外狀況可能會導致整個應用程式由執行時間終止。

應用程式可以使用來自例外狀況的 HRESULT 來判斷造成例外狀況的錯誤。 然後，應用程式可以決定如何根據錯誤碼處理例外狀況。 BackgroundTransferError.GetStatus方法可以將傳回的大部分HRESULT值轉換為WebErrorStatus列舉值。 大多數 WebErrorStatus 列舉值都會對應到原始 HTTP 或 FTP 用戶端作業所傳回的錯誤。 app 可以篩選特定 WebErrorStatus 列舉值，依據例外狀況的發生原因來修改 app 行為。

如需網路例外狀況的資訊，請參閱 處理網路應用程式中的例外狀況。

偵錯指引

在 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 ，定義快顯通知中用來指出下載失敗給使用者的內容、相關聯的中繼資料和事件。
Group	注意 在Windows 8.1之後，群組可能會變更或無法使用。 請改用 TransferGroup。 取得或設定字串值 (例如， GUID) 指出傳輸將屬於的群組。 具有群組識別碼的下載作業只會出現在具有特定群組字串值的 GetCurrentDownloadsAsync (String) 作業列舉中。
Method	取得或設定用於背景下載的 HTTP 方法。 用於下載作業的預設方法是 GET。
ProxyCredential	取得或設定背景傳輸的 Proxy 認證。
ServerCredential	取得或設定要用來向源伺服器進行驗證的認證。 注意 若要透過 FTP 下載，必須在指定的 URI 內提供驗證認證。 例如， ftp://user:password@server/file.txt。
SuccessTileNotification	取得或設定 TileNotification ，用來定義磚通知的視覺效果、識別標記和到期時間，用來在指出使用者下載成功時更新應用程式磚。
SuccessToastNotification	取得或設定 ToastNotification ，定義快顯通知中用來指出下載成功給使用者的內容、相關聯的中繼資料和事件。
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
• 處理網路應用程式中的例外狀況
• 如何加入宣告快顯通知
• 快速入門：下載檔案
• 背景傳輸範例
• Windows 8.x) 背景傳輸 (範例