BackgroundDownloader Класс

Определение

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

Windows.Networking.BackgroundTransfer

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

Примечание

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

Комментарии

После завершения работы приложения приложение должно перечислить все существующие экземпляры DownloadOperation при следующем запуске с помощью GetCurrentDownloadsAsync. Когда приложение 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 для реализации пользовательской проверки подлинности и получите маркер безопасности для скачивания (файл cookie). Задайте соответствующий заголовок, чтобы значение маркера безопасности использовалось для фоновой передачи. Служба должна ограничивать действительность маркера безопасности только скачиваемого файла.

Примечание

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

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

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

Класс BackgroundDownloader в 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, чтобы по-разному действовать в зависимости от причины исключения.

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

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

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

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

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

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

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

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

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

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

BackgroundDownloader()	Создает новый объект BackgroundDownloader .
BackgroundDownloader(BackgroundTransferCompletionGroup)	Создает новый объект BackgroundDownloader с backgroundTransferCompletionGroup.

Свойства

CompletionGroup	Возвращает объект BackgroundTransferCompletionGroup , связанный с BackgroundDownloader.
CostPolicy	Возвращает или задает политику затрат для фоновой операции скачивания.
FailureTileNotification	Возвращает или задает элемент TileNotification , используемый для определения визуальных элементов, тега идентификации и времени истечения срока действия уведомления плитки, используемого для обновления плитки приложения при сбое скачивания для пользователя.
FailureToastNotification	Возвращает или задает toastNotification , определяющее содержимое, связанные метаданные и события, используемые во всплывающем уведомлении для указания на сбой загрузки для пользователя.
Group	Примечание Группа может быть изменена или недоступна для выпусков после Windows 8.1. Вместо этого используйте TransferGroup. Возвращает или задает строковое значение (например, GUID), указывающее группу, к которой будет принадлежать передача. Операция скачивания с идентификатором группы будет отображаться только в перечислениях операций с использованием GetCurrentDownloadsAsync(String) с определенным значением строки группы.
Method	Возвращает или задает метод HTTP, используемый для фонового скачивания. По умолчанию для операций скачивания используется метод GET.
ProxyCredential	Возвращает или задает учетные данные прокси-сервера для фоновой передачи.
ServerCredential	Возвращает или задает учетные данные, используемые для проверки подлинности на сервере-источнике. Примечание Для скачивания через FTP учетные данные проверки подлинности должны быть указаны в указанном универсальном коде ресурса (URI). Например, ftp://user:password@server/file.txt.
SuccessTileNotification	Возвращает или задает элемент TileNotification , используемый для определения визуальных элементов, тега идентификации и времени истечения срока действия уведомления плитки, используемого для обновления плитки приложения при успешном скачивании для пользователя.
SuccessToastNotification	Возвращает или задает toastNotification , определяющее содержимое, связанные метаданные и события, используемые во всплывающем уведомлении для указания пользователю успешного скачивания.
TransferGroup	Возвращает или задает группу, к которой будет принадлежать операция скачивания.

Методы

CreateDownload(Uri, IStorageFile)	Инициализирует объект DownloadOperation , содержащий указанный универсальный код ресурса (URI ) и файл, в который записывается ответ.
CreateDownload(Uri, IStorageFile, IStorageFile)	Инициализирует объект DownloadOperation с помощью URI ресурса, файла, в который записывается ответ, и тела сущности запроса.
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	Создает асинхронную операцию скачивания, которая включает универсальный код ресурса (URI), файл, в который будет записан ответ, и объект IInputStream , из которого считывается содержимое файла.
GetCurrentDownloadsAsync()	Возвращает коллекцию ожидающих скачиваний, которые не связаны с BackgroundTransferGroup.
GetCurrentDownloadsAsync(String)	Примечание GetCurrentDownloadsAsync(group) может быть изменен или недоступен для выпусков после Windows 8.1. Вместо этого используйте GetCurrentDownloadsForTransferGroupAsync. Возвращает коллекцию ожидающих скачиваний для определенной группы.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	Получает все загрузки, связанные с предоставленной backgroundTransferGroup.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	Примечание RequestUnconstrainedDownloadsAsync может быть изменен или недоступен для выпусков после Windows 10 версии 1607. Вместо этого используйте CreateDownloadAsync. Используется для запроса неограниченной операции скачивания. При вызове этого метода пользователю предоставляется запрос пользовательского интерфейса, который можно использовать для указания согласия на выполнение неограниченной операции. Операция неограниченной передачи будет выполняться без ограничений ресурсов, обычно связанных с фоновыми сетевыми операциями, пока устройство работает от батареи.
SetRequestHeader(String, String)	Используется для задания заголовка HTTP-запроса.

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

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