BackgroundUploader 類別

定義

命名空間:

Windows.Networking.BackgroundTransfer

用來使用 CreateUpload在實際建立上傳作業之前設定上傳。 如需背景傳輸功能的概觀，請參閱 在背景傳輸資料。 下載 程式碼範例的背景傳輸範例 。

注意

背景傳輸主要是針對視訊、音樂和大型影像等資源的長期傳輸作業所設計。 對於涉及較小資源傳輸的短期作業 (，例如幾個 KB) ，請使用 Windows.Web.Http 命名空間。

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

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

繼承

Object Platform::Object IInspectable BackgroundUploader

屬性

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.Pickers;
using Windows.Storage;

private async void StartUpload_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri uri = new Uri(serverAddressField.Text.Trim());
        FileOpenPicker picker = new FileOpenPicker();
        picker.FileTypeFilter.Add("*");
        StorageFile file = await picker.PickSingleFileAsync();

        BackgroundUploader uploader = new BackgroundUploader();
        uploader.SetRequestHeader("Filename", file.Name);

        UploadOperation upload = uploader.CreateUpload(uri, file);

        // Attach progress and completion handlers.
        HandleUploadAsync(upload, true);
    }
    catch (Exception ex)
    {
        LogException("Upload Error", ex);
    }
}

備註

應用程式終止之後，應用程式應該使用GetCurrentUploadsAsync在下一次啟動時列舉所有現有的UploadOperation實例。 使用背景傳輸的 UWP app 終止時，不完整的上傳將會保存在背景中。 如果應用程式在終止之後重新開機，而且不會列舉上一個會話的作業並重新附加至目前的會話，它們將會維持不完整並繼續佔用資源。 列舉之後，PUT 上傳作業會自動重新開機，並終止 POST 上傳作業。

注意

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

實作背景傳輸作業的程式庫時，其他應用程式或元件會使用此相同的程式庫，例如，在建立上傳時指定唯一的組 名字串 (GUID) 。 只有提供相符字串給 GetCurrentDownloadsAsync (String) ，且不會出現在 GetCurrentDownloadsAsync 呼叫中，才能列舉具有組名字串的上傳。 這可確保其他針對上傳實作相同程式庫的應用程式不會看到您的上傳

不支援透過 FTP 上傳作業。

上傳作業需要使用者名稱和密碼進行驗證時，可能會有安全性考慮。 如果 WinINet支援要使用的驗證模型，請使用 ServerCredential 或 ProxyCredential 屬性。 這些值會安全地儲存在 WinVault 中。 如需支援驗證方法的資訊，請參閱 處理驗證。

如果 WinINet不支援驗證模型，請使用 HttpClient 來實作自訂驗證，並取得上傳特定的安全權杖 (Cookie) 。 設定適當的標頭，讓用於背景傳輸的安全權杖值。 服務應該只會將安全權杖的有效性限制為正在上傳的檔案。

注意

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

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

快顯通知

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

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

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

注意

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

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

處理例外狀況

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

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

某些 HRESULT 值無法轉換成 WebErrorStatus 列舉值。 取消背景 POST 作業時，會擲回例外狀況。 作業不會重新開機。 如需詳細資訊，請參閱 UploadOperation.StartAsync

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

偵錯指引

在 Microsoft Visual Studio 中停止偵錯工作階段就等同於關閉 app；PUT 上傳會被暫停，POST 上傳會被終止。 即使在偵錯時，應用程式應該列舉然後重新啟動或取消任何之前仍然存在的下載。 例如，如果偵錯工作階段與之前的操作無關，您可以在應用程式啟動時，讓應用程式取消已列舉的持續上傳作業。

偵錯工作階段期間在應用程式啟動時列舉下載/上傳，如果該偵錯工作階段與之前的作業無關，您可以讓應用程式取消它們。 請注意，如果有 Microsoft Visual Studio 專案更新，例如應用程式資訊清單的變更，而且應用程式已卸載並重新部署， GetCurrentUploadsAsync 就無法列舉使用先前的應用程式部署所建立的作業。

如需詳細資訊，請參閱 偵錯和測試 UWP 應用程式 。

開發期間使用背景傳送時，您可能會面臨使用中及已完成傳送作業的內部快取不同步的情況。這會導致無法開始新的傳送作業或無法與現有的作業和 BackgroundTransferGroup 物件互動。 在某些情況下，嘗試與現有作業互動會造成當機。 如果 TransferBehavior 屬性設為 Parallel，就會發生這種結果。 這個問題只在開發期間的特定情況下發生，不適用於您應用程式的一般使用者。

使用 Microsoft Visual Studio 的四個案例可能會導致此問題。

• 您使用與現有專案相同的名稱但不同的語言 (例如，從 C++ 變更為 C#) 建立新的專案。
• 您變更現有專案中的目標架構 (例如，從 x86 變更為 x64)。
• 您變更現有專案中的文化特性 (例如，從中性變更為 en-US)。
• 您在現有專案的套件資訊清單中新增或移除功能 (例如，新增 \[企業驗證\])。 一般應用程式服務，包括新增或移除功能的資訊清單更新，並不會在應用程式的一般使用者部署上引起這個問題。

若要解決這個問題，請完整解除安裝應用程式的所有版本，然後使用新的語言、架構、文化特性或功能來重新部署。 這可以透過 [開始 ] 畫面或使用 PowerShell 和 Remove-AppxPackage Cmdlet 來完成。

建構函式

BackgroundUploader()	具現化新的 BackgroundUploader 物件。
BackgroundUploader(BackgroundTransferCompletionGroup)	將新的 BackgroundUploader 物件具現化為完成群組的成員。

屬性

CompletionGroup	取得與BackgroundUploader相關聯的BackgroundTransferCompletionGroup。
CostPolicy	取得或設定背景上傳作業的成本原則。
FailureTileNotification	取得和設定 TileNotification ，用來定義顯示上傳至使用者失敗時用來更新應用程式磚之磚通知的視覺效果、識別標記和到期時間。
FailureToastNotification	取得或設定 ToastNotification ，定義快顯通知中使用的內容、相關聯的中繼資料和事件，以指出上傳至使用者的失敗。
Group	注意 在Windows 8.1之後，群組可能會變更或無法使用。 請改用 TransferGroup。 取得或設定 (字串值，例如 GUID) 指出上傳將屬於的群組。 具有群組識別碼的上傳作業只會出現在具有特定群組字串值的 GetCurrentDownloadsAsync (String) 作業列舉中。
Method	取得或設定用於上傳的 HTTP 方法。 用於上傳作業的預設方法是 POST。
ProxyCredential	取得或設定上傳的 Proxy 認證。
ServerCredential	取得或設定要用來向源伺服器進行驗證的認證。
SuccessTileNotification	取得和設定 TileNotification ，用來定義用來在指出上傳至使用者成功時，用來更新應用程式磚之磚通知的視覺效果、識別標記和到期時間。
SuccessToastNotification	取得或設定 ToastNotification ，定義快顯通知中使用的內容、相關聯的中繼資料和事件，以指出上傳至使用者是否成功。
TransferGroup	取得或設定上傳作業所屬的群組。

方法

CreateUpload(Uri, IStorageFile)	初始化 UploadOperation ，指出上傳的位置和檔案。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	傳回非同步作業，完成時會傳回具有指定 URI 和一或多個BackgroundTransferContentPart物件的UploadOperation。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	傳回非同步作業，完成時會傳回具有指定 URI、一或多個BackgroundTransferContentPart物件的UploadOperation，以及多部分子類型。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	傳回非同步作業，完成時會傳回具有指定 URI、多部分子類型、一個或多個BackgroundTransferContentPart物件的UploadOperation，以及用來分隔每個元件的分隔符號界限值。
CreateUploadFromStreamAsync(Uri, IInputStream)	傳回非同步作業，完成時會傳回具有指定 URI 和來來源資料流的 UploadOperation 。
GetCurrentUploadsAsync()	傳回未與群組相關聯的擱置上傳集合。
GetCurrentUploadsAsync(String)	注意 getCurrentUploadsAsync (群組) 可能會在Windows 8.1之後變更或無法使用。 請改用 GetCurrentUploadsForTransferGroupAsync。 傳回特定 群組的擱置上傳集合。
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	取得與所提供 BackgroundTransferGroup相關聯的所有上傳。
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	注意 RequestUnconstrainedUploadsAsync 可能會在 Windows 10 1607 版之後變更或無法使用。 請改用 CreateUploadAsync。 用來要求不受限制的上傳作業。 呼叫此方法時，會提供使用者 UI 提示，讓他們可用來表示同意未受限制的作業。當裝置在電池上執行時，不會執行不受限制的傳輸作業，且通常與背景網路作業相關聯的資源限制。
SetRequestHeader(String, String)	用來設定 HTTP 要求標頭。

另請參閱

• UploadOperation
• 處理網路應用程式中的例外狀況
• 如何加入宣告快顯通知
• 快速入門：上傳檔案
• 背景傳輸範例
• Windows 8.x) 背景傳輸範例 (