BackgroundDownloader クラス

定義

名前空間:

Windows.Networking.BackgroundTransfer

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

注意

バックグラウンド転送は、主に、ビデオ、音楽、大きな画像などのリソースの長期的な転送操作用に設計されています。 小規模なリソース (つまり、2 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 アプリが終了すると、不完全なダウンロードはバックグラウンドで保持されます。 終了後にアプリが再起動され、前のセッションからの操作が列挙されず、現在のセッションに再アタッチされない場合、それらは不完全なままになり、リソースを占有し続けます。

注意

アプリがアンインストールされると、それに関連付けられている現在または永続化されたバックグラウンド転送操作がクリーンアップされます。

バックグラウンド転送では、同じ Uri の同時ダウンロードはサポートされていません。 そのため、アプリは 1 回ダウンロード http://example.com/myfile.wmv することも、以前のダウンロードが完了した後にもう一度ダウンロードすることもできます。 アプリは同じ Uri の 2 つのダウンロードを同時に開始しないでください。これは、ファイルが切り捨てられる可能性があるためです。

バックグラウンド転送操作用のライブラリを実装し、この同じライブラリを他のアプリまたはコンポーネントで使用する場合は、ダウンロードの作成時に一意のグループ 名文字列 (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 を使用してトースト通知を介して通信するアプリは、アプリ マニフェスト ファイルでトースト対応であることを宣言する必要があります。 トースト対応の設定は、[アプリケーション] タブの [通知] セクションにあります。アプリがトースト通知を受信できるように、[トースト対応] オプションを [はい] に設定します。

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

Note

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

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

例外の処理

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

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

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

デバッグ ガイダンス

Microsoft Visual Studio でのデバッグ セッションの停止は、アプリを閉じるのと同じです。 デバッグ中でも、アプリは前のセッションから永続化されたダウンロードを列挙してから再開、再起動、または取り消す必要があります。 たとえば、現在のデバッグ セッションの以前の操作に関心がない場合は、アプリの起動時に列挙された永続化されたダウンロード操作を取り消すことができます。

アプリ マニフェストの変更など、Microsoft Visual Studio プロジェクトの更新プログラムがあり、アプリがアンインストールされて再デプロイされた場合、 GetCurrentUploadsAsync は、前のアプリ展開を使用して作成された操作を列挙できません。

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

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

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

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

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

コンストラクター

BackgroundDownloader()	新しい BackgroundDownloader オブジェクトを 作成します。
BackgroundDownloader(BackgroundTransferCompletionGroup)	BackgroundTransferCompletionGroup を使用して、新しい BackgroundDownloader オブジェクトを作成します。

プロパティ

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

メソッド

CreateDownload(Uri, IStorageFile)	指定した Uri と応答の書き込み対象のファイルを含む DownloadOperation オブジェクトを初期化します。
CreateDownload(Uri, IStorageFile, IStorageFile)	リソース Uri、応答が書き込まれるファイル、および要求エンティティ本文を使用して DownloadOperation オブジェクトを初期化します。
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	URI、応答の書き込み先となるファイル、およびファイルの内容の読み取り元の IInputStream オブジェクトを含む非同期ダウンロード操作を作成します。
GetCurrentDownloadsAsync()	BackgroundTransferGroup に関連付けられていない保留中のダウンロードのコレクションを返します。
GetCurrentDownloadsAsync(String)	注意 GetCurrentDownloadsAsync(group) は、Windows 8.1後のリリースで変更または使用できない場合があります。 代わりに、 GetCurrentDownloadsForTransferGroupAsync を使用します。 特定のグループの保留中のダウンロードのコレクションを返 します。
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	指定された BackgroundTransferGroup に関連付けられているすべてのダウンロードを取得します。
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	注意 RequestUnconstrainedDownloadsAsync は、Windows 10 バージョン 1607 以降のリリースでは変更または使用できない場合があります。 代わりに、 CreateDownloadAsync を使用します。 制約のないダウンロード操作を要求するために使用されます。 このメソッドが呼び出されると、ユーザーには、制約のない操作に対する同意を示すために使用できる UI プロンプトが表示されます。制約のない転送操作は、デバイスがバッテリで実行されている間、通常はバックグラウンド ネットワーク操作に関連付けられているリソース制限なしで実行されます。
SetRequestHeader(String, String)	HTTP 要求ヘッダーを設定するために使用されます。

こちらもご覧ください

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