BackgroundDownloader 클래스

정의

네임스페이스:

Windows.Networking.BackgroundTransfer

CreateDownload를 사용하여 다운로드 작업을 실제로 만들기 전에 다운로드를 구성하는 데 사용됩니다. 백그라운드 전송 기능에 대한 개요는 백그라운드에서 데이터 전송을 참조하세요. 코드 예제에 대한 백그라운드 전송 샘플을 다운로드합니다.

참고

백그라운드 전송은 주로 비디오, 음악 및 대형 이미지와 같은 리소스에 대한 장기 전송 작업을 위해 설계되었습니다. 더 작은 리소스(예: 몇 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의 동시 다운로드를 지원하지 않습니다. 따라서 앱은 한 번 다운로드하거나 이전 다운로드 http://example.com/myfile.wmv 가 완료된 후 다시 다운로드할 수 있습니다. 이 경우 파일이 잘릴 수 있으므로 앱에서 동일한 Uri 의 두 다운로드를 동시에 시작해서는 안 됩니다.

백그라운드 전송 작업을 위해 라이브러리를 구현하고 다른 앱 또는 구성 요소에서 동일한 라이브러리를 사용하는 경우 다운로드를 만들 때 고유한그룹 이름 문자열(예: GUID)을 지정합니다. 그룹 이름 문자열이 있는 다운로드는 일치하는 문자열을 GetCurrentDownloadsAsync(String)에 제공해야만 열거할 수 있으며 GetCurrentDownloadsAsync 호출에는 표시되지 않습니다. 이렇게 하면 다운로드를 위해 동일한 라이브러리를 구현하는 다른 앱에서 다운로드가 표시되지 않습니다.

FTP를 통한 다운로드 작업이 지원됩니다. 그러나 FTP 작업의 경우 지정된 URI 내에서 인증 자격 증명을 제공해야 합니다. 예를 들어 ftp://user:password@server/file.txt.

다운로드 작업에 인증을 위해 사용자 이름과 암호가 필요한 경우 보안 문제가 발생할 수 있습니다. 사용할 인증 모델이 WinINet에서 지원되는 경우 ServerCredential 또는 ProxyCredential 속성을 사용합니다. 이러한 값은 WinVault에 안전하게 저장됩니다. 지원되는 인증 방법에 대한 자세한 내용은 인증 처리를 참조하세요.

인증 모델이 WinINet에서 지원되지 않는 경우 HttpClient를 사용하여 사용자 지정 인증을 구현하고 다운로드 관련 보안 토큰(쿠키)을 가져옵니다. 백그라운드 전송에 사용되는 보안 토큰 값을 갖도록 적절한 헤더를 설정합니다. 서비스는 보안 토큰의 유효성을 다운로드 중인 파일로만 제한해야 합니다.

참고

보안 토큰은 애플리케이션의 폴더 내에서 명확한 텍스트로 저장됩니다.

사용자 이름과 암호를 각 다운로드 파일에 대한 사용자 지정 헤더의 일반 텍스트로 설정해야 하는 업로드 서비스는 안전하지 않습니다. 백그라운드 전송은 앱의 폴더 내에서 작업 기간 동안 머리글을 명확한 텍스트로 캐시합니다.

알림 메시지

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를 사용하는 네 가지 시나리오로 인해 이 문제가 발생할 수 있습니다.

• 기존 프로젝트와 앱 이름은 같지만 다른 언어(예: C++에서 C#으로 변경)로 새 프로젝트를 만듭니다.
• 기존 프로젝트에서 대상 아키텍처를 변경합니다(예: x86에서 x64로 변경).
• 기존 프로젝트에서 문화권을 변경합니다(예: 중립에서 en-US로 변경).
• 기존 프로젝트의 패키지 매니페스트에서 접근 권한 값을 추가하거나 제거합니다(예: 엔터프라이즈 인증 추가). 접근 권한 값을 추가하거나 제거하는 매니페스트 업데이트를 비롯한 정기 앱 서비스는 앱의 최종 사용자 배포에서 이 문제를 트리거하지 않습니다.

이 문제를 해결하려면 앱의 모든 버전을 완전히 제거하고 새로운 언어, 아키텍처, 문화권 또는 접근 권한 값으로 다시 배포합니다. 이 작업은 시작 화면 또는 PowerShell 및 cmdlet을 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(그룹)는 Windows 8.1 후 릴리스에서 변경되거나 사용할 수 없습니다. 대신 GetCurrentDownloadsForTransferGroupAsync를 사용합니다. 특정 그룹에 대해 보류 중인 다운로드 컬렉션을 반환합니다.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	제공된 BackgroundTransferGroup과 연결된 모든 다운로드를 가져옵니다.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	참고 RequestUnconstrainedDownloadsAsync는 Windows 10 버전 1607 이후 릴리스에서 변경되거나 사용할 수 없습니다. 대신 CreateDownloadAsync를 사용합니다. 제한되지 않은 다운로드 작업을 요청하는 데 사용됩니다. 이 메서드를 호출하면 사용자에게 제약이 없는 작업에 대한 동의를 나타내는 데 사용할 수 있는 UI 프롬프트가 제공됩니다. 제한되지 않은 전송 작업은 디바이스가 배터리로 실행되는 동안 일반적으로 백그라운드 네트워크 작업과 관련된 리소스 제한 없이 실행됩니다.
SetRequestHeader(String, String)	HTTP 요청 헤더를 설정하는 데 사용됩니다.

추가 정보

• DownloadOperation
• 네트워크 앱에서 예외 처리
• 알림 메시지를 옵트인하는 방법
• 빠른 시작: 파일 다운로드
• 백그라운드 전송 샘플
• 백그라운드 전송 샘플(Windows 8.x)