BackgroundDownloader Kelas

Definisi

Ruang nama:

Windows.Networking.BackgroundTransfer

Digunakan untuk mengonfigurasi unduhan sebelum pembuatan aktual operasi pengunduhan menggunakan CreateDownload. Untuk gambaran umum kemampuan Transfer Latar Belakang, lihat Mentransfer data di latar belakang. Unduh sampel transfer Latar Belakang untuk contoh kode.

Catatan

Transfer Latar Belakang terutama dirancang untuk operasi transfer jangka panjang untuk sumber daya seperti video, musik, dan gambar besar. Untuk operasi jangka pendek yang melibatkan transfer sumber daya yang lebih kecil (yaitu beberapa KB), gunakan namespace 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

Warisan

Object Platform::Object IInspectable BackgroundDownloader

Atribut

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Penerapan

IBackgroundTransferBase

Persyaratan Windows

Rangkaian perangkat	Windows 10 (diperkenalkan dalam 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (diperkenalkan dalam v1.0)
Kemampuan aplikasi	internetClient internetClientServer privateNetworkClientServer

Contoh

Contoh berikut menunjukkan cara mengonfigurasi dan memulai operasi pengunduhan dasar.

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);
     }
 }

Keterangan

Setelah penghentian aplikasi, aplikasi harus menghitung semua instans DownloadOperation yang ada pada start-up berikutnya menggunakan GetCurrentDownloadsAsync. Ketika aplikasi UWP yang menggunakan Transfer Latar Belakang dihentikan, unduhan yang tidak lengkap akan bertahan di latar belakang. Jika aplikasi dimulai ulang setelah penghentian dan operasi dari sesi sebelumnya tidak dijumlahkan dan dilampirkan kembali ke sesi saat ini, mereka akan tetap tidak lengkap dan terus menempati sumber daya.

Catatan

Saat aplikasi dihapus instalan operasi Transfer Latar Belakang saat ini atau yang bertahan yang terkait dengannya akan dibersihkan.

Transfer latar belakang tidak mendukung unduhan bersamaan dari Uri yang sama. Jadi aplikasi dapat mengunduh http://example.com/myfile.wmv sekali, atau mengunduhnya lagi setelah unduhan sebelumnya selesai. Aplikasi tidak boleh memulai dua unduhan Uri yang sama secara bersamaan, karena ini dapat mengakibatkan file yang terpotok.

Saat menerapkan pustaka untuk operasi Transfer Latar Belakang, dan pustaka yang sama ini digunakan oleh aplikasi atau komponen lain, tentukan string namagrup unik (misalnya, GUID) saat membuat unduhan. Unduhan dengan string nama grup hanya dapat dijumlahkan dengan menyediakan string yang cocok ke GetCurrentDownloadsAsync(String), dan tidak akan muncul dalam panggilan GetCurrentDownloadsAsync tanpa. Ini akan memastikan bahwa aplikasi lain yang menerapkan pustaka yang sama untuk unduhan tidak akan melihat unduhan Anda.

Operasi pengunduhan melalui FTP didukung. Namun, untuk operasi FTP, kredensial autentikasi harus disediakan dalam URI yang ditentukan. Misalnya, ftp://user:password@server/file.txt.

Masalah keamanan dapat terjadi saat operasi pengunduhan memerlukan nama pengguna dan kata sandi untuk autentikasi. Jika model autentikasi yang akan digunakan didukung oleh WinINet, gunakan properti ServerCredential atau ProxyCredential . Nilai-nilai ini akan disimpan dengan aman di WinVault. Untuk informasi tentang metode autentikasi yang didukung, lihat Menangani Autentikasi.

Jika model autentikasi tidak didukung oleh WinINet, gunakan HttpClient untuk menerapkan autentikasi kustom dan mendapatkan token aman (cookie) khusus unduhan. Atur header yang sesuai agar memiliki nilai token aman yang digunakan untuk transfer latar belakang. Layanan harus membatasi validitas token aman hanya ke file yang sedang diunduh.

Catatan

Token aman akan disimpan dalam teks yang jelas dalam folder aplikasi.

Mengunggah layanan yang mengharuskan nama pengguna dan kata sandi diatur dalam teks yang jelas di header kustom untuk setiap file unduhan tidak aman. Transfer latar belakang akan menyimpan header dalam teks yang jelas selama durasi operasi dalam folder aplikasi.

Pemberitahuan toast

Kelas BackgroundDownloader di Windows 8.1 dan Windows Server 2012 R2 mendukung opsi bagi pengguna untuk menerima petak peta dan pemberitahuan toast ketika transfer berhasil diselesaikan atau gagal diselesaikan.

Aplikasi yang menggunakan Windows.Networking.BackgroundTransfer untuk berkomunikasi melalui pemberitahuan toast harus menyatakan bahwa toast mampu dalam file manifes aplikasi. Pengaturan berkemampuan Toast terletak di bawah bagian Pemberitahuan pada tab Aplikasi . Atur opsi kemampuan Toast ke "Ya" sehingga aplikasi dapat menerima pemberitahuan toast.

Jika toast mampu tidak diaktifkan dalam manifes aplikasi, maka pengaturan toast apa pun di namespace Windows.Networking.BackgroundTransfer akan diabaikan secara diam-diam dan tidak ada pemberitahuan toast yang akan diterima oleh aplikasi.

Catatan

Pengguna dapat menonaktifkan atau mengaktifkan pemberitahuan toast secara manual untuk aplikasi Anda kapan saja.

Untuk informasi selengkapnya tentang pemberitahuan toast, lihat Mengirim pemberitahuan toast dan Cara memilih notifikasi toast.

Menangani pengecualian

Sejumlah kesalahan dapat menyebabkan pengecualian terjadi selama operasi pengunduhan. Anda harus menulis kode untuk menangani pengecualian ketika Anda memanggil metode di kelas ini. Pengecualian dapat diakibatkan oleh kesalahan validasi parameter, kegagalan resolusi nama, dan kesalahan jaringan. Pengecualian dari kesalahan jaringan (hilangnya konektivitas, kegagalan koneksi, dan kesalahan HTTP lainnya, misalnya) dapat terjadi kapan saja. Kesalahan ini mengakibatkan pengecualian dilemparkan. Jika tidak ditangani oleh aplikasi Anda, pengecualian dapat menyebabkan seluruh aplikasi Anda dihentikan oleh runtime.

Aplikasi dapat menggunakan HRESULT dari pengecualian untuk menentukan kesalahan yang menyebabkan pengecualian. Aplikasi kemudian dapat memutuskan cara menangani pengecualian berdasarkan kode kesalahan. Metode BackgroundTransferError.GetStatus dapat mengonversi sebagian besar nilai HRESULT yang dikembalikan ke nilai enumerasi WebErrorStatus . Sebagian besar nilai enumerasi WebErrorStatus sesuai dengan kesalahan yang dikembalikan oleh operasi klien HTTP atau FTP asli. Aplikasi dapat memfilter nilai enumerasi WebErrorStatus tertentu untuk memodifikasi perilaku aplikasi tergantung pada penyebab pengecualian.

Untuk informasi tentang pengecualian jaringan, lihat Menangani pengecualian di aplikasi jaringan.

Panduan Penelusuran Kesalahan

Menghentikan sesi penelusuran kesalahan di Microsoft Visual Studio sebanding dengan menutup aplikasi Anda. Bahkan saat penelusuran kesalahan, aplikasi Anda harus menghitung lalu, melanjutkan, memulai ulang, atau membatalkan unduhan apa pun yang bertahan dari sesi sebelumnya. Misalnya, Anda dapat meminta aplikasi membatalkan operasi pengunduhan tetap yang dijumlahkan pada startup aplikasi jika tidak ada minat pada operasi sebelumnya untuk sesi debug saat ini.

Jika ada pembaruan proyek Microsoft Visual Studio, seperti perubahan pada manifes aplikasi, dan aplikasi dihapus instalannya dan disebarkan ulang, GetCurrentUploadsAsync tidak dapat menghitung operasi yang dibuat menggunakan penyebaran aplikasi sebelumnya.

Lihat Men-debug dan menguji aplikasi UWP untuk informasi selengkapnya.

Saat menggunakan Transfer Latar Belakang selama pengembangan, Anda mungkin masuk ke situasi di mana cache internal operasi transfer yang aktif dan selesai dapat tidak sinkron. Hal ini dapat mengakibatkan ketidakmampuan untuk memulai operasi transfer baru atau berinteraksi dengan operasi yang ada dan objek BackgroundTransferGroup . Dalam beberapa kasus, mencoba berinteraksi dengan operasi yang ada dapat memicu crash. Hasil ini dapat terjadi jika properti TransferBehavior diatur ke Paralel. Masalah ini hanya terjadi dalam skenario tertentu selama pengembangan dan tidak berlaku untuk pengguna akhir aplikasi Anda.

Empat skenario menggunakan Microsoft Visual Studio dapat menyebabkan masalah ini.

• Anda membuat proyek baru dengan nama aplikasi yang sama dengan proyek yang ada, tetapi bahasa yang berbeda (dari C++ ke C#, misalnya).
• Anda mengubah arsitektur target (dari x86 ke x64, misalnya) dalam proyek yang ada.
• Anda mengubah budaya (dari netral ke en-US, misalnya) dalam proyek yang ada.
• Anda menambahkan atau menghapus kemampuan dalam manifes paket (menambahkan Autentikasi Perusahaan, misalnya) dalam proyek yang ada. Layanan aplikasi reguler, termasuk pembaruan manifes yang menambahkan atau menghapus kemampuan, tidak memicu masalah ini pada penyebaran pengguna akhir aplikasi Anda.

Untuk mengatasi masalah ini, hapus semua versi aplikasi sepenuhnya dan sebarkan ulang dengan bahasa, arsitektur, budaya, atau kemampuan baru. Ini dapat dilakukan melalui layar Mulai atau menggunakan PowerShell dan Remove-AppxPackage cmdlet .

Konstruktor

BackgroundDownloader()	Membuat objek BackgroundDownloader baru.
BackgroundDownloader(BackgroundTransferCompletionGroup)	Membuat objek BackgroundDownloader baru dengan BackgroundTransferCompletionGroup.

Properti

CompletionGroup	Mendapatkan BackgroundTransferCompletionGroup yang terkait dengan BackgroundDownloader.
CostPolicy	Mendapatkan atau menetapkan kebijakan biaya untuk operasi pengunduhan latar belakang.
FailureTileNotification	Mendapatkan atau mengatur TileNotification yang digunakan untuk menentukan visual, tag identifikasi, dan waktu kedaluwarsa pemberitahuan petak peta yang digunakan untuk memperbarui petak peta aplikasi saat menunjukkan kegagalan pengunduhan kepada pengguna.
FailureToastNotification	Mendapatkan atau mengatur ToastNotification yang menentukan konten, metadata terkait, dan peristiwa yang digunakan dalam pemberitahuan toast untuk menunjukkan kegagalan pengunduhan kepada pengguna.
Group	Catatan Grup dapat diubah atau tidak tersedia untuk rilis setelah Windows 8.1. Sebagai gantinya, gunakan TransferGroup. Mendapatkan atau menetapkan nilai string (misalnya, GUID) yang menunjukkan grup tempat transfer akan berada. Operasi pengunduhan dengan ID grup hanya akan muncul dalam enumerasi operasi menggunakan GetCurrentDownloadsAsync(String) dengan nilai string grup tertentu.
Method	Mendapatkan atau mengatur metode HTTP yang digunakan untuk pengunduhan latar belakang. Metode default yang digunakan untuk operasi pengunduhan adalah GET.
ProxyCredential	Mendapatkan atau mengatur kredensial proksi untuk transfer latar belakang.
ServerCredential	Mendapatkan atau mengatur kredensial yang akan digunakan untuk mengautentikasi dengan server asal. Catatan Untuk unduhan melalui FTP, kredensial autentikasi harus disediakan dalam URI yang ditentukan. Misalnya, ftp://user:password@server/file.txt.
SuccessTileNotification	Mendapatkan atau mengatur TileNotification yang digunakan untuk menentukan visual, tag identifikasi, dan waktu kedaluwarsa pemberitahuan petak peta yang digunakan untuk memperbarui petak peta aplikasi saat menunjukkan keberhasilan pengunduhan kepada pengguna.
SuccessToastNotification	Mendapatkan atau mengatur ToastNotification yang menentukan konten, metadata terkait, dan peristiwa yang digunakan dalam pemberitahuan toast untuk menunjukkan keberhasilan unduhan kepada pengguna.
TransferGroup	Mendapatkan atau mengatur grup tempat operasi pengunduhan akan berada.

Metode

CreateDownload(Uri, IStorageFile)	Menginisialisasi objek DownloadOperation yang berisi Uri yang ditentukan dan file tempat respons ditulis.
CreateDownload(Uri, IStorageFile, IStorageFile)	Menginisialisasi objek DownloadOperation dengan Uri sumber daya, file tempat respons ditulis, dan isi entitas permintaan.
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	Membuat operasi pengunduhan asinkron yang menyertakan URI, file tempat respons akan ditulis, dan objek IInputStream tempat konten file dibaca.
GetCurrentDownloadsAsync()	Mengembalikan kumpulan unduhan tertunda yang tidak terkait dengan BackgroundTransferGroup.
GetCurrentDownloadsAsync(String)	Catatan GetCurrentDownloadsAsync(group) mungkin diubah atau tidak tersedia untuk rilis setelah Windows 8.1. Sebagai gantinya, gunakan GetCurrentDownloadsForTransferGroupAsync. Mengembalikan kumpulan unduhan yang tertunda untuk Grup tertentu.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	Mendapatkan semua unduhan yang terkait dengan BackgroundTransferGroup yang disediakan.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	Catatan RequestUnconstrainedDownloadsAsync dapat diubah atau tidak tersedia untuk rilis setelah Windows 10, versi 1607. Sebagai gantinya, gunakan CreateDownloadAsync. Digunakan untuk meminta operasi pengunduhan yang tidak dibatasi. Ketika metode ini disebut pengguna diberikan perintah UI yang dapat mereka gunakan untuk menunjukkan persetujuan mereka untuk operasi yang tidak dibatasi. Operasi transfer yang tidak dibatasi akan berjalan tanpa pembatasan sumber daya yang biasanya terkait dengan operasi jaringan latar belakang saat perangkat berjalan pada baterai.
SetRequestHeader(String, String)	Digunakan untuk mengatur header permintaan HTTP.

Lihat juga

• DownloadOperation
• Menangani pengecualian di aplikasi jaringan
• Cara ikut serta dalam pemberitahuan toast
• Mulai cepat: Mengunduh file
• Sampel transfer latar belakang
• Sampel transfer latar belakang (Windows 8.x)