다음을 통해 공유


DownloadOperation 클래스

정의

비동기 다운로드 작업을 수행합니다. 백그라운드 전송 샘플에서는 이 기능을 보여 줍니다. 백그라운드 전송 기능에 대한 개요는 백그라운드에서 데이터 전송을 참조하세요.

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
특성
구현

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

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

적용 대상

추가 정보