BackgroundUploader Kelas

Definisi

Ruang nama:

Windows.Networking.BackgroundTransfer

Digunakan untuk mengonfigurasi pengunggahan sebelum pembuatan aktual operasi pengunggahan menggunakan CreateUpload. 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 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

Warisan

Object Platform::Object IInspectable BackgroundUploader

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 unggahan dasar.

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

Keterangan

Setelah penghentian aplikasi, aplikasi harus menghitung semua instans UploadOperation yang ada pada start-up berikutnya menggunakan GetCurrentUploadsAsync. Saat aplikasi UWP yang menggunakan Transfer Latar Belakang dihentikan, unggahan 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. Setelah dijumlahkan, operasi unggahan PUT secara otomatis dimulai ulang, dan operasi unggahan POST dihentikan.

Catatan

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

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 unggahan. Unggahan dengan string nama grup hanya dapat dijumlahkan dengan menyediakan string yang cocok ke GetCurrentDownloadsAsync(String), dan tidak akan muncul dalam panggilan GetCurrentDownloadsAsync tanpanya. Ini akan memastikan bahwa aplikasi lain yang menerapkan pustaka yang sama untuk unggahan tidak akan melihat unggahan Anda

Operasi unggah melalui FTP tidak didukung.

Masalah keamanan dapat terjadi saat operasi unggahan 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 khusus unggahan (cookie). 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 diunggah.

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 unggahan tidak aman. Transfer latar belakang akan menyimpan header dalam teks yang jelas selama durasi operasi dalam folder aplikasi.

Pemberitahuan toast

Kelas BackgroundUploader di Windows 8.1 dan Windows Server 2012 R2 mendukung opsi bagi pengguna untuk menerima pemberitahuan petak peta dan 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 Toast yang mampu ke "Ya" sehingga aplikasi dapat menerima pemberitahuan toast.

Jika Toast mampu tidak diaktifkan dalam manifes aplikasi, maka pengaturan toast apa pun di namespace Layanan 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 ikut serta dalam pemberitahuan toast.

Menangani Pengecualian

Sejumlah kesalahan dapat menyebabkan pengecualian terjadi selama operasi pengunggahan. Anda harus menulis kode untuk menangani pengecualian saat 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.

Beberapa nilai HRESULT tidak dapat dikonversi ke nilai enumerasi WebErrorStatus . Ketika operasi POST latar belakang dibatalkan, pengecualian akan dilemparkan. Operasi tidak dimulai ulang. Untuk informasi selengkapnya, lihat UploadOperation.StartAsync

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; Unggahan PUT dijeda dan unggahan POST dihentikan. Bahkan saat penelusuran kesalahan, aplikasi Anda harus menghitung lalu menghidupkan ulang atau membatalkan unggahan yang bertahan. Misalnya, Anda dapat meminta aplikasi membatalkan operasi pengunggahan yang diperhitungkan saat memulai aplikasi jika tidak ada minat pada operasi sebelumnya untuk sesi debug tersebut.

Saat menghitung unduhan/unggahan pada startup aplikasi selama sesi debug, Anda dapat meminta aplikasi membatalkannya jika tidak ada minat pada operasi sebelumnya untuk sesi debug tersebut. Perhatikan bahwa jika ada pembaruan proyek Microsoft Visual Studio, seperti perubahan pada manifes aplikasi, dan aplikasi dihapus instalasinya dan disebarkan kembali, 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

BackgroundUploader()	Membuat instans objek BackgroundUploader baru.
BackgroundUploader(BackgroundTransferCompletionGroup)	Membuat instans objek BackgroundUploader baru sebagai anggota grup penyelesaian.

Properti

CompletionGroup	Mendapatkan BackgroundTransferCompletionGroup yang terkait dengan BackgroundUploader.
CostPolicy	Mendapatkan atau menetapkan kebijakan biaya untuk operasi pengunggah latar belakang.
FailureTileNotification	Mendapatkan dan 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 unggahan kepada pengguna.
FailureToastNotification	Mendapatkan atau mengatur ToastNotification yang menentukan konten, metadata terkait, dan peristiwa yang digunakan dalam pemberitahuan toast untuk menunjukkan kegagalan unggahan 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 unggahan akan berada. Operasi pengunggahan 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 unggahan. Metode default yang digunakan untuk operasi unggahan adalah POST.
ProxyCredential	Mendapatkan atau mengatur kredensial proksi untuk unggahan.
ServerCredential	Mendapatkan atau mengatur kredensial yang akan digunakan untuk mengautentikasi dengan server asal.
SuccessTileNotification	Mendapatkan dan 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 unggahan kepada pengguna.
SuccessToastNotification	Mendapatkan atau mengatur ToastNotification yang menentukan konten, metadata terkait, dan peristiwa yang digunakan dalam pemberitahuan toast untuk menunjukkan keberhasilan unggahan kepada pengguna.
TransferGroup	Mendapatkan atau mengatur grup tempat operasi unggahan akan berada.

Metode

CreateUpload(Uri, IStorageFile)	Menginisialisasi UploadOperation yang menunjukkan lokasi dan file untuk diunggah.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Mengembalikan operasi asinkron yang, setelah selesai, mengembalikan UploadOperation dengan URI yang ditentukan dan satu atau beberapa objek BackgroundTransferContentPart .
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Mengembalikan operasi asinkron yang, setelah selesai, mengembalikan UploadOperation dengan URI yang ditentukan, satu atau beberapa objek BackgroundTransferContentPart , dan subjenis multibanyak.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Mengembalikan operasi asinkron yang, setelah selesai, mengembalikan UploadOperation dengan URI yang ditentukan, subjenis multibalik, satu atau beberapa objek BackgroundTransferContentPart , dan nilai batas pemisah yang digunakan untuk memisahkan setiap bagian.
CreateUploadFromStreamAsync(Uri, IInputStream)	Mengembalikan operasi asinkron yang, setelah selesai, mengembalikan UploadOperation dengan URI yang ditentukan dan aliran sumber.
GetCurrentUploadsAsync()	Mengembalikan kumpulan unggahan tertunda yang tidak terkait dengan grup.
GetCurrentUploadsAsync(String)	Catatan GetCurrentUploadsAsync(group) dapat diubah atau tidak tersedia untuk rilis setelah Windows 8.1. Sebagai gantinya, gunakan GetCurrentUploadsForTransferGroupAsync. Mengembalikan kumpulan unggahan yang tertunda untuk Grup tertentu.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Mendapatkan semua unggahan yang terkait dengan BackgroundTransferGroup yang disediakan.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Catatan RequestUnconstrainedUploadsAsync dapat diubah atau tidak tersedia untuk rilis setelah Windows 10, versi 1607. Sebagai gantinya, gunakan CreateUploadAsync. Digunakan untuk meminta operasi unggahan 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

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