BackgroundDownloader クラス

定義

public ref class BackgroundDownloader sealed

/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class BackgroundDownloader final

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

[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 の要件

例

次の例では、基本的なダウンロード操作を構成して開始する方法を示します。

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 名前空間のトースト設定は無視され、アプリによってトースト通知は受信されません。

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

例外の処理

多くのエラーにより、ダウンロード操作中に例外が発生する可能性があります。 このクラスでメソッドを呼び出すときに例外を処理するコードを記述する必要があります。 例外は、パラメーター検証エラー、名前解決エラー、およびネットワーク エラーによって発生する可能性があります。 ネットワーク エラーの例外 (接続の損失、接続エラー、その他の 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 使用して実行できます。

コンストラクター

プロパティ

メソッド

適用対象

こちらもご覧ください

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