BackgroundUploader クラス

定義

名前空間:

Windows.Networking.BackgroundTransfer

CreateUpload を使用してアップロード操作を実際に作成する前にアップロードを構成するために使用します。 バックグラウンド転送機能の概要については、「 バックグラウンドでのデータの転送」を参照してください。 コード例の バックグラウンド転送サンプル をダウンロードします。

注意

バックグラウンド転送は、主にビデオ、音楽、大きな画像などのリソースの長期的な転送操作用に設計されています。 小規模なリソース (つまり、2 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 アプリが終了すると、不完全なアップロードはバックグラウンドで保持されます。 終了後にアプリが再起動され、前のセッションからの操作が列挙されず、現在のセッションに再アタッチされない場合、それらは不完全なままになり、リソースを占有し続けます。 列挙すると、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 を使用してトースト通知を介して通信するアプリは、アプリ マニフェスト ファイルでトースト対応であることを宣言する必要があります。 トースト対応の設定は、[アプリケーション] タブの [通知] セクションにあります。アプリがトースト通知を受信できるように、[トースト対応] オプションを [はい] に設定します。

アプリ マニフェストで トースト対応 が有効になっていない場合、 Windows.Networking.BackgroundTransfer 名前空間のトースト設定は無視され、アプリによってトースト通知は受信されません。

Note

ユーザーは、いつでもアプリのトースト通知を手動で無効または有効にすることができます。

トースト通知の詳細については、「トースト通知の送信」および「トースト通知をオプトインする方法」を参照してください。

例外処理

アップロード操作中に例外が発生するエラーが多数発生する可能性があります。 このクラスでメソッドを呼び出すときに例外を処理するコードを記述する必要があります。 例外は、パラメーター検証エラー、名前解決エラー、およびネットワーク エラーによって発生する可能性があります。 ネットワーク エラーの例外 (接続の損失、接続エラー、その他の HTTP エラーなど) は、いつでも発生する可能性があります。 これらのエラーが起きると、例外がスローされます。 アプリによって処理されない場合、例外によってアプリ全体がランタイムによって終了する可能性があります。

アプリは、例外の HRESULT を使用して、例外の原因となったエラーを特定できます。 アプリは、エラー コードに基づいて例外を処理する方法を決定できます。 BackgroundTransferError.GetStatus メソッドは、返されるほとんどの HRESULT 値を WebErrorStatus 列挙値に変換できます。 WebErrorStatus 列挙値のほとんどは、ネイティブ HTTP または FTP クライアント操作から返されるエラーに対応しています。 アプリは特定の WebErrorStatus 列挙値に対するフィルター処理を行い、例外の原因に応じてアプリの動作を変更できます。

一部 の HRESULT 値は 、WebErrorStatus 列挙値に変換できません。 バックグラウンド POST 操作が取り消されると、例外がスローされます。 操作は再起動されません。 詳細については、「UploadOperation.StartAsync」を参照してください。

ネットワーク例外の詳細については、「ネットワーク アプリでの例外の処理」を参照してください。

デバッグ ガイダンス

Microsoft Visual Studio でデバッグ セッションを停止することは、アプリを閉じることに相当します。PUT によるアップロードは一時停止され、POST によるアップロードは終了されます。 デバッグ時であっても、アプリでは、持続しているアップロードを列挙し、再実行や取り消しを行うことができる必要があります。 たとえば、そのデバッグ セッションで以前の操作が重要ではない場合、アプリの起動時に、列挙された持続しているアップロード操作をアプリで取り消すことができます。

デバッグ セッションでアプリの起動時にダウンロードやアップロードを列挙する際、そのデバッグ セッションで以前の操作が重要ではない場合、列挙された操作をアプリで取り消すことができます。 アプリ マニフェストの変更など、Microsoft Visual Studio プロジェクトの更新プログラムがあり、アプリがアンインストールされて再展開された場合、 GetCurrentUploadsAsync は、前のアプリの展開を使用して作成された操作を列挙できないことに注意してください。

詳細については、「 UWP アプリのデバッグとテスト 」を参照してください。

開発時にバックグラウンド転送を使うと、完了したアクティブな転送操作の内部キャッシュが同期しなくなる状況が発生する可能性があります。このため、新しい転送操作を開始できない場合や、既存の操作や BackgroundTransferGroup オブジェクトを処理できない場合があります。 状況によっては、既存の操作を処理しようとすると、クラッシュの原因となる可能性があります。 これは、TransferBehavior プロパティが Parallel に設定されている場合に発生する可能性があります。 この問題は、開発中に特定のシナリオでのみ発生し、アプリのエンド ユーザーには適用されません。

Microsoft Visual Studio を使用する 4 つのシナリオで、この問題が発生する可能性があります。

• 既にあるプロジェクトと同じアプリ名を持つ新しいプロジェクトを、別の言語で作成する (C++ から C# など)。
• 既にあるプロジェクトのターゲット アーキテクチャを変更する (x86 から x64 など)。
• 既にあるプロジェクトのカルチャを変更する (ニュートラルから en-US など)。
• 既にあるプロジェクトのパッケージ マニフェストで機能を追加または削除する (エンタープライズ認証を追加するなど)。 機能を追加または削除するマニフェストの更新など、通常のアプリのサービスでは、アプリのエンド ユーザーに対する展開でこの問題は発生しません。

この問題を回避するには、アプリのすべてのバージョンを完全にアンインストールし、新しい言語、アーキテクチャ、カルチャ、または機能をもう一度展開します。 これは、[ スタート] 画面で行うか、PowerShell と コマンドレットを Remove-AppxPackage 使用して行うことができます。

コンストラクター

BackgroundUploader()	新しい BackgroundUploader オブジェクトを インスタンス化します。
BackgroundUploader(BackgroundTransferCompletionGroup)	新しい BackgroundUploader オブジェクトを完了グループのメンバーとしてインスタンス化します。

プロパティ

CompletionGroup	BackgroundUploader に関連付けられている BackgroundTransferCompletionGroup を取得します。
CostPolicy	バックグラウンド アップロード操作のコスト ポリシーを取得または設定します。
FailureTileNotification	ユーザーへのアップロードの失敗を示すときにアプリ タイルの更新に使用されるタイル通知のビジュアル、識別タグ、有効期限を定義するために使用される TileNotification を取得および設定します。
FailureToastNotification	ユーザーへのアップロードの失敗を示すためにトースト通知で使用されるコンテンツ、関連付けられたメタデータ、およびイベントを定義する ToastNotification を取得または設定します。
Group	注意 Windows 8.1後のリリースでは、グループが変更されたり、使用できなくなったりする場合があります。 代わりに、 TransferGroup を使用します。 アップロードが属するグループを示す文字列値 ( GUID など) を取得または設定します。 グループ ID を持つアップロード操作は、特定のグループ文字列値を持つ GetCurrentDownloadsAsync(String) を使用する操作列挙にのみ表示されます。
Method	アップロードに使用される HTTP メソッドを取得または設定します。 アップロード操作に使用される既定のメソッドは POST です。
ProxyCredential	アップロードのプロキシ資格情報を取得または設定します。
ServerCredential	配信元サーバーでの認証に使用する資格情報を取得または設定します。
SuccessTileNotification	ユーザーへのアップロードの成功を示すときにアプリ タイルの更新に使用されるタイル通知のビジュアル、識別タグ、有効期限を定義するために使用される TileNotification を取得および設定します。
SuccessToastNotification	ユーザーへのアップロードの成功を示すためにトースト通知で使用されるコンテンツ、関連付けられたメタデータ、およびイベントを定義する ToastNotification を取得または設定します。
TransferGroup	アップロード操作が属するグループを取得または設定します。

メソッド

CreateUpload(Uri, IStorageFile)	アップロードの場所とファイルを示す UploadOperation を初期化します。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	完了時に、指定した URI と 1 つ以上の BackgroundTransferContentPart オブジェクトを持つ UploadOperation を返す非同期操作を返します。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	完了時に、指定した URI、1 つ以上の BackgroundTransferContentPart オブジェクト、およびマルチパート サブタイプを持つ UploadOperation を返す非同期操作を返します。
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	完了時に、指定された URI、マルチパート サブタイプ、1 つ以上の BackgroundTransferContentPart オブジェクト、および各部分を区切るために使用される区切り記号境界値を持つ UploadOperation を返す非同期操作を返します。
CreateUploadFromStreamAsync(Uri, IInputStream)	完了時に、指定した URI とソース ストリームを含む UploadOperation を返す非同期操作を返します。
GetCurrentUploadsAsync()	グループに関連付けられていない保留中のアップロードのコレクションを返します。
GetCurrentUploadsAsync(String)	注意 getCurrentUploadsAsync(group) は、Windows 8.1後のリリースで変更または使用できない場合があります。 代わりに、 GetCurrentUploadsForTransferGroupAsync を使用します。 特定のグループの保留中のアップロードのコレクションを返 します。
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	指定された BackgroundTransferGroup に関連付けられているすべてのアップロードを取得します。
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	注意 RequestUnconstrainedUploadsAsync は、Windows 10 バージョン 1607 以降のリリースでは変更または使用できない場合があります。 代わりに、 CreateUploadAsync を使用します。 制約のないアップロード操作を要求するために使用されます。 このメソッドが呼び出されると、ユーザーには、制約のない操作に対する同意を示すために使用できる UI プロンプトが表示されます。制約のない転送操作は、デバイスがバッテリで実行されている間、通常はバックグラウンド ネットワーク操作に関連付けられているリソース制限なしで実行されます。
SetRequestHeader(String, String)	HTTP 要求ヘッダーを設定するために使用されます。

こちらもご覧ください

• UploadOperation
• ネットワーク アプリでの例外の処理
• トースト通知をオプトインする方法
• クイック スタート: ファイルをアップロードする
• バックグラウンド転送のサンプル
• バックグラウンド転送のサンプル (Windows 8.x)