BackgroundUploader Класс

Определение

Пространство имен:

Windows.Networking.BackgroundTransfer

Используется для настройки отправки до фактического создания операции отправки с помощью createUpload. Общие сведения о возможностях фоновой передачи см. в разделе Передача данных в фоновом режиме. Скачайте пример фоновой передачи для примера кода.

Примечание

Фоновая передача в основном предназначена для долгосрочных операций передачи ресурсов, таких как видео, музыка и большие изображения. Для краткосрочных операций, связанных с передачей небольших ресурсов (т. е. пару КБ), используйте пространство имен 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);
    }
}

Комментарии

После завершения работы приложения приложение должно перечислить все существующие экземпляры UploadOperation при следующем запуске с помощью GetCurrentUploadsAsync. Когда приложение UWP, использующее фоновую передачу, завершается, неполные отправки сохраняются в фоновом режиме. Если приложение перезапущено после завершения, а операции из предыдущего сеанса не перечисляются и не подключены к текущему сеансу, они останутся неполными и продолжат занимать ресурсы. После перечисления операции отправки PUT автоматически перезапускаются, а операции отправки POST завершаются.

Примечание

При удалении приложения удаляются все текущие или сохраненные операции фоновой передачи, связанные с ним.

При реализации библиотеки для операций фоновой передачи, а эта же библиотека используется другими приложениями или компонентами, укажите уникальную строку именигруппы (например, GUID) при создании отправки. Отправка со строкой имени группы может быть перечислена только путем предоставления соответствующей строки getCurrentDownloadsAsync(String) и не будет отображаться в вызовах GetCurrentDownloadsAsync без. Это гарантирует, что другие приложения, реализующие ту же библиотеку для отправки, не будут видеть ваши отправки.

Операции отправки через FTP не поддерживаются.

Проблемы безопасности могут возникать, если операции отправки требуют имени пользователя и пароля для проверки подлинности. Если используемая модель проверки подлинности поддерживается WinINet, используйте свойства ServerCredential или ProxyCredential . Эти значения будут безопасно сохранены в WinVault. Сведения о поддерживаемых методах проверки подлинности см. в разделе Обработка проверки подлинности.

Если модель проверки подлинности не поддерживается WinINet, используйте HttpClient для реализации пользовательской проверки подлинности и получения маркера безопасности (cookie) для отправки. Задайте соответствующий заголовок, чтобы значение маркера безопасности использовалось для фоновой передачи. Служба должна ограничить допустимость безопасного маркера только тем файлом, который передается.

Примечание

Безопасный маркер будет храниться в виде чистого текста в папке приложения.

Службы отправки, для которых требуется задать имя пользователя и пароль в виде простого текста в пользовательском заголовке для каждого файла отправки, небезопасны. Фоновая передача будет кэшировать заголовки в виде ясного текста на время операции в папке приложения.

Всплывающие уведомления

Класс BackgroundUploader в Windows 8.1 и Windows Server 2012 R2 поддерживает возможность получения пользователем плиток и всплывающих уведомлений при успешном завершении передачи или сбое.

Приложение, использующее Windows.Networking.BackgroundTransfer для обмена данными через всплывающее уведомление, должно объявить, что оно поддерживает всплывающие уведомления в файле манифеста приложения. Параметр с поддержкой всплывающих уведомлений находится в разделе Уведомления на вкладке Приложение . Задайте для параметра Toast capable значение "Да", чтобы приложение получите всплывающие уведомления.

Если поддержка всплывающих уведомлений не включена в манифесте приложения, все параметры всплывающего уведомления в пространстве имен Windows.Networking.BackgroundTransfer будут игнорироваться без уведомления, и приложение не будет получать всплывающие уведомления.

Примечание

Пользователь может вручную отключить или включить всплывающие уведомления для вашего приложения в любое время.

Дополнительные сведения о всплывающих уведомлениях см. в разделах Отправка всплывающих уведомлений и Согласие на всплывающие уведомления.

Обработка исключений

Ряд ошибок может привести к возникновению исключений во время операции отправки. Необходимо написать код для обработки исключений при вызове методов в этом классе. Исключения могут возникать из-за ошибок проверки параметров, ошибок разрешения имен и сетевых ошибок. Исключения из сетевых ошибок (например, потеря подключения, сбои подключения и другие ошибки HTTP) могут произойти в любое время. В результате таких ошибок создаются исключения. Если приложение не обрабатывается, исключение может привести к завершению всего приложения средой выполнения.

Приложение может использовать HRESULT из исключения для определения ошибки, вызвавшей исключение. Затем приложение может решить, как обрабатывать исключение на основе кода ошибки. Метод BackgroundTransferError.GetStatus может преобразовать большинство возвращаемых значений HRESULT в значение перечисления WebErrorStatus . Большинство значений перечисления WebErrorStatus соответствуют ошибке, возвращаемой стандартной операцией клиента HTTP или FTP. Приложение может фильтровать полученные данные по определенному значению перечисления WebErrorStatus, чтобы по-разному действовать в зависимости от причины исключения.

Некоторые значения HRESULT нельзя преобразовать в значение перечисления WebErrorStatus . При отмене фоновой операции POST возникает исключение. Операция не перезапускается. Дополнительные сведения см. в разделе UploadOperation.StartAsync.

Сведения об исключениях сети см. в разделе Обработка исключений в сетевых приложениях.

Руководство по отладке

Остановка сеанса отладки в Microsoft Visual Studio сопоставима с закрытием приложения: отправки PUT при этом приостанавливаются, а отправки POST завершаются. Даже в процессе отладки ваше приложение должно перечислить, а затем перезапустить или отменить любые оставшиеся отправки. Например, можно сделать так, чтобы приложение отменяло перечисленные сохранившиеся операции отправки при запуске приложения, если предыдущие операции не имеют значения для данного сеанса отладки.

Можно сделать, чтобы при перечислении скачиваний и отправок во время запуска приложения в процессе сеанса отладки приложение отменяло их, если для данного сеанса отладки предыдущие операции не важны. Обратите внимание, что при наличии обновлений проекта Microsoft Visual Studio, например изменений в манифесте приложения, а также при удалении и повторном развертывании приложения GetCurrentUploadsAsync не сможет перечислить операции, созданные с помощью предыдущего развертывания приложения.

Дополнительные сведения см. в статье Отладка и тестирование приложений UWP .

При использовании фоновой передачи данных во время разработки возможны ситуации, когда внутренние кэши активных и завершенных операций передачи могут выйти из синхронизации. Это может привести к невозможности запуска новой операции передачи или взаимодействия с существующими операциями и объектами BackgroundTransferGroup. В ряде случаев попытка взаимодействия с существующими операциями способна вызвать сбой. Это может произойти, если свойству TransferBehavior задано значение Parallel. Такая проблема присуща определенным сценариям во время разработки и не затрагивает конечных пользователей приложения.

Эта проблема может быть вызвана четырьмя сценариями использования Microsoft Visual Studio.

• если вы создаете новый проект с таким же именем приложения, как в существующем проекте, но на другом языке (например, не C++, а C#);
• если вы изменяете архитектуру конечного объекта (например, с x86 на x64) в существующем проекте;
• если вы изменяете культуру (например, с нейтральной на en-US) в существующем проекте;
• если вы добавляете или удаляете возможность в манифесте пакета (например, добавляете корпоративную аутентификацию) в существующем проекте. Обычное обслуживание приложения, включая обновления манифеста, добавляющие или удаляющие возможности, не вызывает данную проблему при развертывании приложения у конечных пользователей.

Чтобы обойти проблему, полностью удалите все версии приложения и повторите развертывание с новым языком, архитектурой, культурой или возможностью. Это можно сделать на начальном экране или с помощью PowerShell и командлета Remove-AppxPackage .

Конструкторы

BackgroundUploader()	Создает экземпляр нового объекта BackgroundUploader .
BackgroundUploader(BackgroundTransferCompletionGroup)	Создает экземпляр нового объекта BackgroundUploader в качестве члена группы завершения.

Свойства

CompletionGroup	Возвращает объект BackgroundTransferCompletionGroup , связанный с BackgroundUploader.
CostPolicy	Возвращает или задает политику затрат для фоновой операции отправки.
FailureTileNotification	Получает и задает элемент TileNotification , используемый для определения визуальных элементов, тега идентификации и времени истечения срока действия уведомления плитки, используемого для обновления плитки приложения при сбое отправки пользователю.
FailureToastNotification	Возвращает или задает toastNotification , определяющее содержимое, связанные метаданные и события, используемые во всплывающем уведомлении для указания на сбой отправки пользователю.
Group	Примечание Группа может быть изменена или недоступна для выпусков после Windows 8.1. Вместо этого используйте TransferGroup. Возвращает или задает строковое значение (например, GUID), указывающее группу, к которой будет принадлежать отправка. Операция отправки с идентификатором группы будет отображаться только в перечислениях операций с помощью GetCurrentDownloadsAsync(String) с определенным значением строки группы.
Method	Возвращает или задает метод HTTP, используемый для отправки. По умолчанию для операций отправки используется метод POST.
ProxyCredential	Возвращает или задает учетные данные прокси-сервера для отправки.
ServerCredential	Возвращает или задает учетные данные, используемые для проверки подлинности на сервере-источнике.
SuccessTileNotification	Возвращает и задает элемент TileNotification , используемый для определения визуальных элементов, тега идентификации и времени истечения срока действия уведомления плитки, используемого для обновления плитки приложения при успешной отправке пользователю.
SuccessToastNotification	Возвращает или задает toastNotification , определяющее содержимое, связанные метаданные и события, используемые во всплывающем уведомлении для указания успешной отправки пользователю.
TransferGroup	Возвращает или задает группу, к которой будет принадлежать операция отправки.

Методы

CreateUpload(Uri, IStorageFile)	Инициализирует UploadOperation , который указывает расположение и файл для отправки.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Возвращает асинхронную операцию, которая после завершения возвращает UploadOperation с указанным URI и одним или несколькими объектами BackgroundTransferContentPart .
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Возвращает асинхронную операцию, которая после завершения возвращает UploadOperation с указанным URI, одним или несколькими объектами BackgroundTransferContentPart и многокомпонентным подтипом.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Возвращает асинхронную операцию, которая после завершения возвращает UploadOperation с указанным URI, составным подтипом, одним или несколькими объектами BackgroundTransferContentPart и значением границы разделителя, используемым для разделения каждой части.
CreateUploadFromStreamAsync(Uri, IInputStream)	Возвращает асинхронную операцию, которая после завершения возвращает UploadOperation с указанным URI и исходным потоком.
GetCurrentUploadsAsync()	Возвращает коллекцию ожидающих отправки, не связанных с группой.
GetCurrentUploadsAsync(String)	Примечание GetCurrentUploadsAsync(group) может быть изменен или недоступен для выпусков после Windows 8.1. Вместо этого используйте GetCurrentUploadsForTransferGroupAsync. Возвращает коллекцию ожидающих отправки для определенной группы.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Получает все отправки, связанные с предоставленной backgroundTransferGroup.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Примечание Параметр RequestUnconstrainedUploadsAsync может быть изменен или недоступен для выпусков после Windows 10 версии 1607. Вместо этого используйте CreateUploadAsync. Используется для запроса неограниченной операции отправки. При вызове этого метода пользователю предоставляется запрос пользовательского интерфейса, который можно использовать для указания согласия на выполнение неограниченной операции. Операция неограниченной передачи будет выполняться без ограничений ресурсов, обычно связанных с фоновыми сетевыми операциями, пока устройство работает от батареи.
SetRequestHeader(String, String)	Используется для задания заголовка HTTP-запроса.

См. также раздел

• UploadOperation
• Обработка исключений в сетевых приложениях
• Как согласиться на всплывающие уведомления
• Краткое руководство. Отправка файла
• Пример фоновой передачи
• Пример фоновой передачи данных (Windows 8.x)