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의 동시 다운로드를 지원하지 않습니다. 따라서 앱은 한 번 다운로드하거나 이전 다운로드 http://example.com/myfile.wmv 가 완료된 후 다시 다운로드할 수 있습니다. 이 경우 파일이 잘릴 수 있으므로 앱에서 동일한 Uri 의 두 다운로드를 동시에 시작해서는 안 됩니다.

참고

일시 중지되거나 불완전한 다운로드 작업은 서버가 range-requests를 수락하는 경우에만 다시 시작될 수 있습니다.

시간 제한 고려 사항

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	범위다운로드됨
1709	16299	RecoverableWebErrorStatuses
1803	17134	MakeCurrentInTransferGroup
2004	19041	RemoveRequestHeader
2004	19041	SetRequestHeader

속성

CostPolicy	다운로드에 대한 비용 정책을 가져오고 설정합니다.
CurrentWebErrorStatus	DownloadOperation의 수명 동안 모니터링할 수 있는 전송의 WebErrorStatus입니다.
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()	연결된 다운로드의 진행률 및 완료를 모니터링하는 데 사용할 수 있는 비동기 작업을 반환합니다. 이 메서드를 호출하면 앱이 이전 앱 instance 시작된 다운로드 작업을 연결할 수 있습니다.
GetDownloadedRanges()	지금까지 다운로드한 파일 범위의 전체 목록을 반환합니다.
GetResponseInformation()	응답 정보를 가져옵니다.
GetResultRandomAccessStreamReference()	임의 액세스 스트림에 대한 참조를 가져오고 해당 스트림에서 읽습니다. GetResultRandomAccessStreamReference를 호출하기 전에 IsRandomAccessRequired 를 TRUE로 설정해야 합니다.
GetResultStreamAt(UInt64)	지정된 위치에서 부분적으로 다운로드한 응답을 가져옵니다.
MakeCurrentInTransferGroup()	다운로드 전송 작업(및 동일한 전송 그룹에서 수행되는 모든 전송)의 우선 순위를 지정합니다. 전송 그룹에 속하지 않는 전송 시 이 메서드를 호출해도 아무런 효과가 없습니다.
Pause()	다운로드 작업을 일시 중지합니다.
RemoveRequestHeader(String)	HTTP 요청 헤더를 제거하는 데 사용됩니다.
Resume()	일시 중지된 다운로드 작업을 다시 시작합니다.
SetRequestHeader(String, String)	HTTP 요청 헤더를 설정하는 데 사용됩니다.
StartAsync()	비동기 다운로드 작업을 시작합니다.

이벤트

RangesDownloaded

증분 다운로드 진행률에 대한 액세스를 제공합니다.

추가 정보

• 빠른 시작: 파일 다운로드
• 백그라운드 전송 샘플
• 백그라운드 전송 샘플(Windows 8.x)