DownloadOperation クラス

定義

名前空間:

Windows.Networking.BackgroundTransfer

非同期ダウンロード操作を実行します。 バックグラウンド転送サンプルでは、この機能を示します。 バックグラウンド転送機能の概要については、「 バックグラウンドでのデータの転送」を参照してください。

public ref class DownloadOperation sealed : IBackgroundTransferOperationPriority

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class DownloadOperation final : IBackgroundTransferOperationPriority

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class DownloadOperation : IBackgroundTransferOperationPriority

Public NotInheritable Class DownloadOperation
Implements IBackgroundTransferOperationPriority

継承

Object Platform::Object IInspectable DownloadOperation

属性

ContractVersionAttribute MarshalingBehaviorAttribute

実装

IBackgroundTransferOperation IBackgroundTransferOperationPriority

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 つのダウンロードを同時に開始しないでください。これは、ファイルが切り捨てられる可能性があるためです。

注意

一時停止または不完全なダウンロード操作は、サーバーが範囲要求を受け入れる場合にのみ再開できます。

タイムアウトに関する考慮事項

1. TCP/SSL 経由でダウンロードするための新しい接続を確立すると、5 分以内に接続が確立されない場合、接続試行は中止されます。
2. 接続が確立されると、2 分以内に応答を受信していない HTTP 要求メッセージが中止されます。 インターネット接続があると仮定すると、バックグラウンド転送は最大 3 回ダウンロードを再試行します。 インターネット接続が検出されない場合、インターネット接続が検出されるまで、追加の試行は行われません。

デバッグ ガイダンス

Microsoft Visual Studio でのデバッグ セッションの停止は、アプリを閉じるのと同じです。ダウンロードが一時停止され、POST アップロードが終了します。 デバッグ中でも、アプリは永続化されたダウンロードを列挙してから一時停止、再開、再起動、または取り消す必要があります。

ただし、Microsoft Visual Studio プロジェクトの更新 (アプリ マニフェストの変更など) で、アプリをアンインストールしてデバッグ用に再デプロイする必要がある場合、 GetCurrentDownloadsAsync は、前のアプリ展開を使用して作成された永続化された操作を列挙できません。

バージョン履歴

Windows のバージョン	SDK バージョン	追加された値
1709	16299	CurrentWebErrorStatus
1709	16299	GetDownloadedRanges
1709	16299	GetResultRandomAccessStreamReference
1709	16299	IsRandomAccessRequired
1709	16299	RangesDownloaded
1709	16299	RecoverableWebErrorStatuses
1803	17134	MakeCurrentInTransferGroup
2004	19041	RemoveRequestHeader
2004	19041	SetRequestHeader

プロパティ

CostPolicy	ダウンロードのコスト ポリシーを取得および設定します。
CurrentWebErrorStatus	転送の WebErrorStatus。 DownloadOperation の有効期間中に監視できます。
Group	注意 Windows 8.1後のリリースでは、グループが変更されたり、使用できなくなったりする場合があります。 代わりに、 TransferGroup を使用します。 転送が属するグループを示す文字列値を取得します。
Guid	これは、特定のダウンロード操作の一意の識別子です。 ダウンロード操作に関連付けられている GUID は、ダウンロードの期間中は変更されません。
IsRandomAccessRequired	ランダム アクセスを有効にするブール値プロパティ。 ランダム アクセス機能を使用するには、 DownloadOperation オブジェクトで StartAsync() を呼び出す前に、 プロパティを TRUE に設定する必要があります。 StartAsync() を呼び出した後、 GetResultRandomAccessStreamReference を呼び出して、ランダム アクセス ストリームへの参照を取得し、そこから読み取ります。
Method	ダウンロードに使用するメソッドを取得します。
Priority	BackgroundTransferGroup 内にある場合の、このダウンロード操作の転送優先度を取得または設定します。 使用できる値は BackgroundTransferPriority によって定義されます。
Progress	操作の現在の進行状況を取得します。
RecoverableWebErrorStatuses	アプリケーションがダウンロードにヒットすると予測し、アプリケーションが処理方法を知っている WebErrorStatus 値のセット。
RequestedUri	ファイルのダウンロード元の URI を取得します。
ResultFile	CreateDownload を使用して DownloadOperation オブジェクトを作成するときに呼び出し元によって提供される IStorageFile オブジェクトを返します。
TransferGroup	このダウンロード操作が属するグループを取得します。

メソッド

AttachAsync()	アタッチされたダウンロードの進行状況と完了を監視するために使用できる非同期操作を返します。 このメソッドを呼び出すと、アプリは、前のアプリ インスタンスで開始されたダウンロード操作をアタッチできます。
GetDownloadedRanges()	これまでにダウンロードされたファイル範囲の完全な一覧を返します。
GetResponseInformation()	応答情報を取得します。
GetResultRandomAccessStreamReference()	ランダム アクセス ストリームへの参照を取得し、そこから読み取ります。 GetResultRandomAccessStreamReference を呼び出す前に 、IsRandomAccessRequired を TRUE に設定する必要があります。
GetResultStreamAt(UInt64)	指定した位置にある部分的にダウンロードされた応答を取得します。
MakeCurrentInTransferGroup()	ダウンロード転送操作 (および同じ転送グループ内の転送) に優先順位を付けます。 転送グループに属していない転送でこのメソッドを呼び出しても効果はありません。
Pause()	ダウンロード操作を一時停止します。
RemoveRequestHeader(String)	HTTP 要求ヘッダーを削除するために使用されます。
Resume()	一時停止したダウンロード操作を再開します。
SetRequestHeader(String, String)	HTTP 要求ヘッダーを設定するために使用されます。
StartAsync()	非同期ダウンロード操作を開始します。

イベント

RangesDownloaded

増分ダウンロードの進行状況へのアクセスを提供します。

こちらもご覧ください

• クイック スタート: ファイルをダウンロードする
• バックグラウンド転送のサンプル
• バックグラウンド転送のサンプル (Windows 8.x)