BackgroundUploader 클래스

정의

네임스페이스:

Windows.Networking.BackgroundTransfer

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

참고

백그라운드 전송은 주로 비디오, 음악 및 대형 이미지와 같은 리소스에 대한 장기 전송 작업을 위해 설계되었습니다. 더 작은 리소스(예: 몇 KB)의 전송과 관련된 단기 작업의 경우 Windows.Web.Http 네임스페이스를 사용합니다.

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

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

상속

Object Platform::Object IInspectable BackgroundUploader

특성

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.Pickers;
using Windows.Storage;

private async void StartUpload_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri uri = new Uri(serverAddressField.Text.Trim());
        FileOpenPicker picker = new FileOpenPicker();
        picker.FileTypeFilter.Add("*");
        StorageFile file = await picker.PickSingleFileAsync();

        BackgroundUploader uploader = new BackgroundUploader();
        uploader.SetRequestHeader("Filename", file.Name);

        UploadOperation upload = uploader.CreateUpload(uri, file);

        // Attach progress and completion handlers.
        HandleUploadAsync(upload, true);
    }
    catch (Exception ex)
    {
        LogException("Upload Error", ex);
    }
}

설명

앱 종료 후 앱은 GetCurrentUploadsAsync를 사용하여 다음 시작 시 모든 기존 UploadOperation 인스턴스를 열거해야 합니다. 백그라운드 전송을 사용하는 UWP 앱이 종료되면 불완전한 업로드가 백그라운드에서 유지됩니다. 종료 후 앱이 다시 시작되고 이전 세션의 작업이 열거되고 현재 세션에 다시 연결되지 않은 경우 불완전한 상태로 유지되고 리소스를 계속 차지합니다. 열거되면 PUT 업로드 작업이 자동으로 다시 시작되고 POST 업로드 작업이 종료됩니다.

참고

앱이 제거되면 앱과 연결된 현재 또는 지속형 백그라운드 전송 작업이 정리됩니다.

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

FTP를 통한 업로드 작업은 지원되지 않습니다.

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

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

참고

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

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

알림 메시지

Windows 8.1 및 Windows Server 2012 R2의 BackgroundUploader 클래스는 전송이 성공적으로 완료되거나 완료되지 않을 때 사용자가 타일 및 알림 메시지를 받을 수 있는 옵션을 지원합니다.

Windows.Networking.BackgroundTransfer를 사용하여 알림 메시지를 통해 통신하는 앱은 앱 매니페스트 파일에서 알림 메시지를 사용할 수 있음을 선언해야 합니다. 알림 가능 설정은 애플리케이션 탭의 알림 섹션 아래에 있습니다. 앱이 알림 메시지를 받을 수 있도록 알림 가능 옵션을 "예"로 설정합니다.

앱 매니페스트에서 알림 기능을 사용하도록 설정하지 않으면 Windows.Networking.BackgroundTransfer 네임스페이스의 알림 설정이 자동으로 무시되고 앱에서 알림 메시지를 받지 않습니다.

참고

사용자는 언제든지 앱에 대한 알림 메시지를 수동으로 사용하지 않도록 설정하거나 사용하도록 설정할 수 있습니다.

알림 메시지에 대한 자세한 내용은 알림 메시지 보내기 및 알림 메시지를 옵트인하는 방법을 참조하세요.

예외 처리

많은 오류로 인해 업로드 작업 중에 예외가 발생할 수 있습니다. 이 클래스에서 메서드를 호출할 때 예외를 처리하는 코드를 작성해야 합니다. 예외는 매개 변수 유효성 검사 오류, 이름 확인 오류 및 네트워크 오류로 인해 발생할 수 있습니다. 네트워크 오류(예: 연결 손실, 연결 오류 및 기타 HTTP 오류)의 예외는 언제든지 발생할 수 있습니다. 이러한 오류로 인해 예외가 발생합니다. 앱에서 처리하지 않으면 예외로 인해 전체 앱이 런타임에 의해 종료될 수 있습니다.

앱은 예외의 HRESULT 를 사용하여 예외를 발생시킨 오류를 확인할 수 있습니다. 그러면 앱에서 오류 코드에 따라 예외를 처리하는 방법을 결정할 수 있습니다. BackgroundTransferError.GetStatus 메서드는 반환된 대부분의 HRESULT 값을 WebErrorStatus 열거형 값으로 변환할 수 있습니다. 대부분의 WebErrorStatus 열거형 값은 기본 HTTP 또는 FTP 클라이언트 작업에서 반환한 오류에 해당합니다. 앱은 특정 WebErrorStatus 열거형 값을 필터링하여 예외의 원인에 따라 앱 동작을 수정할 수 있습니다.

일부 HRESULT 값은 WebErrorStatus 열거형 값으로 변환할 수 없습니다. 백그라운드 POST 작업이 취소되면 예외가 throw됩니다. 작업이 다시 시작되지 않습니다. 자세한 내용은 UploadOperation.StartAsync를 참조하세요.

네트워크 예외에 대한 자세한 내용은 네트워크 앱에서 예외 처리를 참조하세요.

디버깅 지침

Microsoft Visual Studio에서 디버깅 세션을 중지하는 것은 앱을 닫는 것과 같습니다. PUT 업로드가 일시 중지되고 POST 업로드가 종료됩니다. 디버깅 중에도 앱이 지속형 업로드를 열거한 다음 다시 시작하거나 취소해야 합니다. 예를 들어 해당 디버그 세션의 이전 작업에 관심이 없는 경우 앱을 시작할 때 앱에서 열거된 지속형 업로드 작업을 취소하도록 할 수 있습니다.

디버그 세션의 이전 작업에 관심이 없는 경우 디버그 세션 중 앱을 시작할 때 다운로드/업로드를 열거하는 동안 앱에서 취소하도록 할 수 있습니다. 앱 매니페스트 변경과 같은 Microsoft Visual Studio 프로젝트 업데이트가 있고 앱이 제거되고 다시 배포되는 경우 GetCurrentUploadsAsync 는 이전 앱 배포를 사용하여 만든 작업을 열거할 수 없습니다.

자세한 내용은 UWP 앱 디버깅 및 테스트를 참조하세요.

개발 중 백그라운드 전송을 사용하는 경우 활성 및 완료된 전송 작업의 내부 캐시가 동기화되지 않는 상황이 발생할 수 있습니다. 이 경우 새 전송 작업을 시작하거나 기존 작업 및 BackgroundTransferGroup 개체를 조작하지 못할 수 있습니다. 기존 작업을 조작할 때 크래시가 트리거되는 경우도 있습니다. TransferBehavior 속성이 Parallel로 설정된 경우 이러한 결과가 발생할 수 있습니다. 이 문제는 개발 중 특정 시나리오에서만 발생하며 앱의 최종 사용자에게는 해당하지 않습니다.

Microsoft Visual Studio를 사용하는 4가지 시나리오로 인해 이 문제가 발생할 수 있습니다.

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

이 문제를 해결하려면 앱의 모든 버전을 완전히 제거하고 새로운 언어, 아키텍처, 문화권 또는 접근 권한 값으로 다시 배포합니다. 이 작업은 시작 화면 또는 PowerShell 및 cmdlet을 Remove-AppxPackage 통해 수행할 수 있습니다.

생성자

BackgroundUploader()	새 BackgroundUploader 개체를 인스턴스화합니다.
BackgroundUploader(BackgroundTransferCompletionGroup)	새 BackgroundUploader 개체를 완료 그룹의 구성원으로 인스턴스화합니다.

속성

CompletionGroup	BackgroundUploader와 연결된 BackgroundTransferCompletionGroup을 가져옵니다.
CostPolicy	백그라운드 업로드 작업에 대한 비용 정책을 가져오거나 설정합니다.
FailureTileNotification	사용자에게 업로드 실패를 나타낼 때 앱 타일을 업데이트하는 데 사용되는 타일 알림의 시각적 개체, 식별 태그 및 만료 시간을 정의하는 데 사용되는 TileNotification 을 가져오고 설정합니다.
FailureToastNotification	사용자에게 업로드 실패를 나타내기 위해 알림 메시지에 사용된 콘텐츠, 연결된 메타데이터 및 이벤트를 정의하는 ToastNotification 을 가져오거나 설정합니다.
Group	참고 그룹은 Windows 8.1 후 릴리스에 대해 변경되거나 사용할 수 없을 수 있습니다. 대신 TransferGroup을 사용합니다. 업로드가 속할 그룹을 나타내는 문자열 값(예: GUID)을 가져오거나 설정합니다. 그룹 ID가 있는 업로드 작업은 특정 그룹 문자열 값이 있는 GetCurrentDownloadsAsync(String) 를 사용하여 작업 열거형에만 표시됩니다.
Method	업로드에 사용되는 HTTP 메서드를 가져오거나 설정합니다. 업로드 작업에 사용되는 기본 방법은 POST입니다.
ProxyCredential	업로드에 대한 프록시 자격 증명을 가져오거나 설정합니다.
ServerCredential	원본 서버에서 인증하는 데 사용할 자격 증명을 가져오거나 설정합니다.
SuccessTileNotification	사용자에게 업로드의 성공을 나타내는 경우 앱 타일을 업데이트하는 데 사용되는 타일 알림의 시각적 개체, 식별 태그 및 만료 시간을 정의하는 데 사용되는 TileNotification 을 가져오고 설정합니다.
SuccessToastNotification	사용자에게 업로드의 성공을 나타내기 위해 알림 메시지에 사용되는 콘텐츠, 연결된 메타데이터 및 이벤트를 정의하는 ToastNotification 을 가져오거나 설정합니다.
TransferGroup	업로드 작업이 속할 그룹을 가져오거나 설정합니다.

메서드

CreateUpload(Uri, IStorageFile)	업로드할 및 파일의 위치를 나타내는 UploadOperation 을 초기화합니다.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	완료 시 지정된 URI 및 하나 이상의 BackgroundTransferContentPart 개체가 있는 UploadOperation을 반환하는 비동기 작업을 반환합니다.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	완료 시 지정된 URI, 하나 이상의 BackgroundTransferContentPart 개체 및 다중 파트 하위 형식을 사용하여 UploadOperation을 반환하는 비동기 작업을 반환합니다.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	완료 시 지정된 URI, 다중 파트 하위 형식, 하나 이상의 BackgroundTransferContentPart 개체 및 각 파트를 구분하는 데 사용되는 구분 기호 경계 값을 사용하여 UploadOperation을 반환하는 비동기 작업을 반환합니다.
CreateUploadFromStreamAsync(Uri, IInputStream)	완료 시 지정된 URI 및 원본 스트림을 사용하여 UploadOperation 을 반환하는 비동기 작업을 반환합니다.
GetCurrentUploadsAsync()	그룹과 연결되지 않은 보류 중인 업로드 컬렉션을 반환합니다.
GetCurrentUploadsAsync(String)	참고 GetCurrentUploadsAsync(그룹)는 Windows 8.1 후 릴리스에서 변경되거나 사용할 수 없습니다. 대신 GetCurrentUploadsForTransferGroupAsync를 사용합니다. 특정 그룹에 대해 보류 중인 업로드 컬렉션을 반환합니다.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	제공된 BackgroundTransferGroup과 연결된 모든 업로드를 가져옵니다.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	참고 RequestUnconstrainedUploadsAsync는 Windows 10 버전 1607 이후 릴리스에서 변경되거나 사용할 수 없습니다. 대신 CreateUploadAsync를 사용합니다. 제한되지 않은 업로드 작업을 요청하는 데 사용됩니다. 이 메서드를 호출하면 사용자에게 제약이 없는 작업에 대한 동의를 나타내는 데 사용할 수 있는 UI 프롬프트가 제공됩니다. 제한되지 않은 전송 작업은 디바이스가 배터리로 실행되는 동안 일반적으로 백그라운드 네트워크 작업과 관련된 리소스 제한 없이 실행됩니다.
SetRequestHeader(String, String)	HTTP 요청 헤더를 설정하는 데 사용됩니다.

추가 정보

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