BackgroundUploader Clase

Definición

Espacio de nombres:

Windows.Networking.BackgroundTransfer

Se usa para configurar la carga antes de la creación real de la operación de carga mediante CreateUpload. Para obtener información general sobre las funcionalidades de transferencia en segundo plano, consulte Transferencia de datos en segundo plano. Descargue el ejemplo de transferencia en segundo plano para obtener un ejemplo de código.

Nota:

La transferencia de fondo está diseñada principalmente para operaciones de transferencia a largo plazo para recursos como vídeo, música y imágenes grandes. Para las operaciones a corto plazo que implican transferencias de recursos más pequeños (es decir, un par de KB), use el espacio de nombres 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

Herencia

Object Platform::Object IInspectable BackgroundUploader

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementaciones

IBackgroundTransferBase

Requisitos de Windows

Familia de dispositivos	Windows 10 (se introdujo en la versión 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (se introdujo en la versión v1.0)
Características de aplicaciones	internetClient internetClientServer privateNetworkClientServer

Ejemplos

En el ejemplo siguiente se muestra cómo configurar e iniciar una operación de carga básica.

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

Comentarios

Después de la finalización de la aplicación, una aplicación debe enumerar todas las instancias de UploadOperation existentes en el siguiente inicio mediante GetCurrentUploadsAsync. Cuando se finaliza una aplicación para UWP mediante transferencia en segundo plano, las cargas incompletas se conservarán en segundo plano. Si la aplicación se reinicia después de la finalización y las operaciones de la sesión anterior no se enumeran y se vuelven a adjuntar a la sesión actual, permanecerán incompletas y seguirán ocupando recursos. Una vez enumeradas, las operaciones de carga PUT se reinician automáticamente y se finalizan las operaciones de carga POST.

Nota:

Cuando se desinstala una aplicación, se limpian las operaciones de transferencia en segundo plano actuales o persistentes asociadas a ella.

Al implementar una biblioteca para las operaciones de transferencia en segundo plano y otras aplicaciones o componentes usan esta misma biblioteca, especifique una cadena de nombre degrupo única (por ejemplo, un GUID) al crear cargas. Una carga con una cadena de nombre de grupo solo se puede enumerar proporcionando la cadena coincidente a GetCurrentDownloadsAsync(String) y no aparecerá en las llamadas GetCurrentDownloadsAsync sin. Esto garantizará que otras aplicaciones que implementan esa misma biblioteca para las cargas no verán las cargas.

No se admiten las operaciones de carga a través de FTP.

Los problemas de seguridad pueden existir cuando las operaciones de carga requieren un nombre de usuario y una contraseña para la autenticación. Si WinINet admite el modelo de autenticación que se va a usar, use las propiedades ServerCredential o ProxyCredential . Estos valores se guardarán de forma segura en WinVault. Para obtener información sobre los métodos de autenticación admitidos, consulte Control de la autenticación.

Si WinINet no admite el modelo de autenticación, use HttpClient para implementar la autenticación personalizada y obtener un token seguro (cookie) específico de la carga. Establezca el encabezado adecuado para que tenga el valor de token seguro usado para la transferencia en segundo plano. El servicio debe limitar la validez del token seguro solo al archivo que se está cargando.

Nota:

El token seguro se almacenará en texto no cifrado dentro de la carpeta de la aplicación.

Los servicios de carga que requieren que el nombre de usuario y la contraseña se establezcan en texto no cifrado en un encabezado personalizado para cada archivo de carga no son seguros. La transferencia en segundo plano almacenará en caché los encabezados en texto no cifrado durante la operación dentro de la carpeta de la aplicación.

Notificaciones del sistema

La clase BackgroundUploader de Windows 8.1 y Windows Server 2012 R2 admite opciones para que el usuario reciba notificaciones del icono y del sistema cuando se complete correctamente una transferencia o no se complete.

Una aplicación que usa Windows.Networking.BackgroundTransfer para comunicarse a través de una notificación del sistema debe declarar que es compatible con la notificación del sistema en el archivo de manifiesto de la aplicación. La configuración compatible con la notificación del sistema se encuentra en la sección Notificaciones de la pestaña Aplicación . Establezca la opción compatible con la notificación del sistema en "Sí" para que la aplicación pueda recibir notificaciones del sistema.

Si la compatibilidad con notificaciones del sistema no está habilitada en el manifiesto de la aplicación, cualquier configuración del sistema en el espacio de nombres Windows.Networking.BackgroundTransfer se omitirá silenciosamente y la aplicación no recibirá notificaciones del sistema.

Nota:

Un usuario puede deshabilitar o habilitar manualmente las notificaciones del sistema para la aplicación en cualquier momento.

Para obtener más información sobre las notificaciones del sistema, consulte Envío de notificaciones del sistema y Cómo participar en las notificaciones del sistema.

Control de excepciones

Varios errores pueden hacer que se produzcan excepciones durante una operación de carga. Debe escribir código para controlar las excepciones al llamar a métodos en esta clase. Las excepciones pueden deberse a errores de validación de parámetros, errores de resolución de nombres y errores de red. Las excepciones de los errores de red (pérdida de conectividad, errores de conexión y otros errores HTTP, por ejemplo) pueden producirse en cualquier momento. Estos errores hacen que se arrojen excepciones. Si la aplicación no la controla, una excepción puede hacer que el tiempo de ejecución finalice toda la aplicación.

Una aplicación puede usar HRESULT de la excepción para determinar el error que provocó la excepción. Después, una aplicación puede decidir cómo controlar la excepción en función del código de error. El método BackgroundTransferError.GetStatus puede convertir la mayoría de los valores HRESULT devueltos a un valor de enumeración WebErrorStatus . La mayoría de los valores de enumeración WebErrorStatus corresponden a un error devuelto por la operación de cliente HTTP o FTP nativa. Una aplicación puede filtrar según valores WebErrorStatus concretos para modificar el comportamiento de la aplicación en función del motivo de la excepción.

Algunos valores HRESULT no se pueden convertir en un valor de enumeración WebErrorStatus . Cuando se cancela una operación POST en segundo plano, se produce una excepción. La operación no se reinicia. Para obtener más información, consulte UploadOperation.StartAsync.

Para obtener información sobre las excepciones de red, consulte Control de excepciones en aplicaciones de red.

Guía de depuración

Detener una sesión de depuración en Microsoft Visual Studio se puede comparar a cerrar una aplicación. Las cargas PUT se pausan y las cargas POST se finalizan. Incluso durante la depuración, tu aplicación debe enumerar y reiniciar o cancelar todas las cargas que persisten. Por ejemplo, tu aplicación puede cancelar operaciones de carga persistentes al iniciar la aplicación, si no hay ningún interés por operaciones anteriores para la sesión de depuración.

Mientras se enumeran las cargas y descargas al iniciarse una aplicación durante una sesión de depuración, puedes hacer que tu aplicación las cancele si, en esa sesión de depuración, no se tiene ningún interés por las operaciones anteriores. Tenga en cuenta que si hay actualizaciones de proyecto de Microsoft Visual Studio, como cambios en el manifiesto de la aplicación, y la aplicación se desinstala y se vuelve a implementar, GetCurrentUploadsAsync no puede enumerar las operaciones creadas con la implementación de la aplicación anterior.

Consulta Depuración y prueba de aplicaciones para UWP para obtener más información.

Cuando uses la transferencia en segundo plano durante el desarrollo, es posible que las memorias caché internas de las operaciones de transferencia activas y finalizadas dejen de estar sincronizadas. Esto puede provocar que no puedas iniciar nuevas operaciones de transferencia ni interactuar con operaciones existentes y objetos de BackgroundTransferGroup. En algunos casos, intentar interactuar con operaciones ya existentes puede producir un bloqueo. Este resultado puede producirse si la propiedad TransferBehavior se establece en Parallel. Este problema se produce únicamente en determinados escenarios, durante el desarrollo, y no se aplica a los usuarios finales de tu aplicación.

Cuatro escenarios con Microsoft Visual Studio pueden provocar este problema.

• Creas un proyecto nuevo con el mismo nombre de aplicación que un proyecto ya existente, pero otro lenguaje (de C++ a C#, por ejemplo).
• Cambias la arquitectura de destino (de x86 a x64, por ejemplo) de un proyecto ya existente.
• Cambias la cultura (de neutral a en-US, por ejemplo) en un proyecto ya existente.
• Agregas o quitas una capacidad en el manifiesto del paquete (agregando, por ejemplo, Autenticación de empresa) en un proyecto ya existente. El mantenimiento regular de tu aplicación, incluidas las actualizaciones de manifiesto que agregan o quitan capacidades, no causa este problema en las implementaciones de usuario final de tu aplicación.

Para evitar este problema, desinstala completamente todas las versiones de la aplicación y vuelve a implementarlas con el lenguaje, la arquitectura, la cultura o la capacidad nuevos. Esto se puede hacer a través de la pantalla Inicio o mediante PowerShell y el Remove-AppxPackage cmdlet .

Constructores

BackgroundUploader()	Crea una instancia de un nuevo objeto BackgroundUploader .
BackgroundUploader(BackgroundTransferCompletionGroup)	Crea una instancia de un nuevo objeto BackgroundUploader como miembro de un grupo de finalización.

Propiedades

CompletionGroup	Obtiene el backgroundTransferCompletionGroup asociado al objeto BackgroundUploader.
CostPolicy	Obtiene o establece la directiva de costo para la operación de carga en segundo plano.
FailureTileNotification	Obtiene y establece el icono TileNotification usado para definir los objetos visuales, la etiqueta de identificación y la hora de expiración de una notificación de icono usada para actualizar el icono de la aplicación al indicar un error de carga al usuario.
FailureToastNotification	Obtiene o establece la notificación del sistema que define el contenido, los metadatos asociados y los eventos usados en una notificación del sistema para indicar un error de carga al usuario.
Group	Nota: El grupo puede modificarse o no estar disponible para las versiones después de Windows 8.1. En su lugar, use TransferGroup. Obtiene o establece un valor de cadena (por ejemplo, un GUID) que indica al grupo al que pertenecerá la carga. Una operación de carga con un identificador de grupo solo aparecerá en las enumeraciones de operaciones mediante GetCurrentDownloadsAsync(String) con el valor de cadena de grupo específico.
Method	Obtiene o establece el método HTTP usado para la carga. El método predeterminado que se usa para las operaciones de carga es POST.
ProxyCredential	Obtiene o establece las credenciales de proxy para la carga.
ServerCredential	Obtiene o establece las credenciales que se van a usar para autenticarse con el servidor de origen.
SuccessTileNotification	Obtiene y establece el icono TileNotification usado para definir los objetos visuales, la etiqueta de identificación y la hora de expiración de una notificación de icono usada para actualizar el icono de la aplicación al indicar que se ha realizado correctamente una carga al usuario.
SuccessToastNotification	Obtiene o establece la notificación del sistema que define el contenido, los metadatos asociados y los eventos usados en una notificación del sistema para indicar que la carga se ha realizado correctamente en el usuario.
TransferGroup	Obtiene o establece el grupo al que pertenecerá una operación de carga.

Métodos

CreateUpload(Uri, IStorageFile)	Inicializa una uploadOperation que indica la ubicación de y el archivo para la carga.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Devuelve una operación asincrónica que, al finalizar, devuelve uploadOperation con el URI especificado y uno o varios objetos BackgroundTransferContentPart .
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Devuelve una operación asincrónica que, al finalizar, devuelve uploadOperation con el URI especificado, uno o varios objetos BackgroundTransferContentPart y el subtipo de varias partes.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Devuelve una operación asincrónica que, al finalizar, devuelve uploadOperation con el URI especificado, subtipo de varias partes, uno o varios objetos BackgroundTransferContentPart y el valor de límite delimitador usado para separar cada parte.
CreateUploadFromStreamAsync(Uri, IInputStream)	Devuelve una operación asincrónica que, al finalizar, devuelve uploadOperation con el URI especificado y la secuencia de origen.
GetCurrentUploadsAsync()	Devuelve una colección de cargas pendientes que no están asociadas a un grupo.
GetCurrentUploadsAsync(String)	Nota: GetCurrentUploadsAsync(group) puede modificarse o no estar disponible para las versiones después de Windows 8.1. En su lugar, use GetCurrentUploadsForTransferGroupAsync. Devuelve una colección de cargas pendientes para un grupo específico.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Obtiene todas las cargas asociadas al backgroundTransferGroup proporcionado.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Nota: RequestUnconstrainedUploadsAsync puede modificarse o no estar disponible para las versiones posteriores a Windows 10, versión 1607. En su lugar, use CreateUploadAsync. Se usa para solicitar una operación de carga sin restricciones. Cuando se llama a este método, se proporciona al usuario una solicitud de interfaz de usuario que puede usar para indicar su consentimiento para una operación sin restricciones. Una operación de transferencia sin restricciones se ejecutará sin las restricciones de recursos normalmente asociadas a las operaciones de red en segundo plano mientras un dispositivo se ejecuta con batería.
SetRequestHeader(String, String)	Se usa para establecer un encabezado de solicitud HTTP.

Consulte también

• UploadOperation
• Control de excepciones en aplicaciones de red
• Cómo participar en las notificaciones del sistema
• Inicio rápido: Carga de un archivo
• Ejemplo de transferencia en segundo plano
• Ejemplo de transferencia en segundo plano (Windows 8.x)