DownloadOperation Clase

Definición

Espacio de nombres:

Windows.Networking.BackgroundTransfer

Realiza una operación de descarga asincrónica. En el ejemplo de transferencia en segundo plano se muestra esta funcionalidad. Para obtener información general sobre las funcionalidades de transferencia en segundo plano, consulte Transferencia de datos en segundo plano.

public ref class DownloadOperation sealed : IBackgroundTransferOperationPriority

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class DownloadOperation final : IBackgroundTransferOperationPriority

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class DownloadOperation : IBackgroundTransferOperationPriority

Public NotInheritable Class DownloadOperation
Implements IBackgroundTransferOperationPriority

Herencia

Object Platform::Object IInspectable DownloadOperation

Atributos

ContractVersionAttribute MarshalingBehaviorAttribute

Implementaciones

IBackgroundTransferOperation IBackgroundTransferOperationPriority

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

Las aplicaciones de ejemplo que usan esta clase incluyen el ejemplo de transferencia en segundo plano.

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

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

Comentarios

Al siguiente inicio después de la finalización de la aplicación, la aplicación debe enumerar todas las instancias de DownloadOperation existentes mediante GetCurrentDownloadsAsync. Cuando finaliza una aplicación para UWP mediante transferencia en segundo plano, las descargas incompletas se conservan en segundo plano. Si la aplicación se reinicia después de la finalización y estas operaciones incompletas no se enumeran y se vuelven a introducir en la sesión actual, pasarán a estar obsoletas y seguirán ocupando los recursos del dispositivo.

La transferencia en segundo plano no admite descargas simultáneas del mismo URI. Por lo tanto, una aplicación puede descargarla http://example.com/myfile.wmv una vez o volver a descargarla después de que se haya completado una descarga anterior. Una aplicación no debe iniciar dos descargas del mismo URI simultáneamente, ya que esto puede dar lugar a archivos truncados.

Nota:

Las operaciones de descarga pausadas o incompletas solo se pueden reanudar si el servidor acepta solicitudes de intervalo.

Consideraciones sobre el tiempo de espera

1. Al establecer una nueva conexión para una descarga a través de TCP/SSL, el intento de conexión se anula si no se establece en un plazo de cinco minutos.
2. Una vez establecida la conexión, se anula un mensaje de solicitud HTTP que no ha recibido una respuesta en dos minutos. Suponiendo que hay conectividad a Internet, la transferencia en segundo plano reintentará una descarga hasta tres veces. En caso de que no se detecte la conectividad a Internet, no se realizarán intentos adicionales hasta que sea así.

Guía de depuración

Detener una sesión de depuración en Microsoft Visual Studio es comparable a cerrar la aplicación; las descargas se pausan y se finalizan las cargas POST. Incluso durante la depuración, la aplicación debe enumerar y, a continuación, pausar, reanudar, reiniciar o cancelar las descargas persistentes.

Sin embargo, si el proyecto de Microsoft Visual Studio se actualiza, como los cambios en el manifiesto de la aplicación, requiere que la aplicación se desinstale y se vuelva a implementar para la depuración, GetCurrentDownloadsAsync no puede enumerar las operaciones persistentes creadas con la implementación de la aplicación anterior.

Historial de versiones

Versión de Windows	Versión del SDK	Valor agregado
1709	16299	CurrentWebErrorStatus
1709	16299	GetDownloadedRanges
1709	16299	GetResultRandomAccessStreamReference
1709	16299	IsRandomAccessRequired
1709	16299	RangesDownloaded
1709	16299	RecoverableWebErrorStatuses
1803	17134	MakeCurrentInTransferGroup
2004	19041	RemoveRequestHeader
2004	19041	SetRequestHeader

Propiedades

CostPolicy	Obtiene y establece la directiva de costo de la descarga.
CurrentWebErrorStatus	WebErrorStatus de una transferencia, que se puede supervisar durante la vigencia de DownloadOperation.
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 un valor de cadena que indica al grupo al que pertenece la transferencia.
Guid	Se trata de un identificador único para una operación de descarga específica. Un GUID asociado a una operación de descarga no cambiará durante la descarga.
IsRandomAccessRequired	Propiedad booleana para habilitar el acceso aleatorio. La propiedad debe establecerse en TRUE antes de llamar a StartAsync() en un objeto DownloadOperation para usar la característica de acceso aleatorio. Después de llamar a StartAsync(), llame a GetResultRandomAccessStreamReference para obtener una referencia a la secuencia de acceso aleatorio y leerla.
Method	Obtiene el método que se va a usar para la descarga.
Priority	Obtiene o establece la prioridad de transferencia de esta operación de descarga cuando se encuentra dentro de backgroundTransferGroup. Los valores posibles se definen mediante BackgroundTransferPriority.
Progress	Obtiene el progreso actual de la operación.
RecoverableWebErrorStatuses	Un conjunto de valores de WebErrorStatus que las aplicaciones prevén que se alcanzará la descarga y que las aplicaciones sepan cómo controlar.
RequestedUri	Obtiene el URI del que se va a descargar el archivo.
ResultFile	Devuelve el objeto IStorageFile proporcionado por el autor de la llamada al crear el objeto DownloadOperation mediante CreateDownload.
TransferGroup	Obtiene el grupo al que pertenece esta operación de descarga.

Métodos

AttachAsync()	Devuelve una operación asincrónica que se puede usar para supervisar el progreso y la finalización de la descarga adjunta. Llamar a este método permite a una aplicación adjuntar operaciones de descarga iniciadas en una instancia de aplicación anterior.
GetDownloadedRanges()	Devuelve la lista completa de intervalos de archivos que se han descargado hasta ahora.
GetResponseInformation()	Obtiene la información de respuesta.
GetResultRandomAccessStreamReference()	Obtiene una referencia a la secuencia de acceso aleatorio y lee desde ella. Es necesario establecer IsRandomAccessRequired en TRUE antes de llamar a GetResultRandomAccessStreamReference.
GetResultStreamAt(UInt64)	Obtiene la respuesta descargada parcialmente en la posición especificada.
MakeCurrentInTransferGroup()	Prioriza la operación de transferencia de descarga (y las transferencias que lo siguen en el mismo grupo de transferencia). Llamar a este método en una transferencia que no pertenece a un grupo de transferencia no tiene ningún efecto.
Pause()	Pausa una operación de descarga.
RemoveRequestHeader(String)	Se usa para quitar un encabezado de solicitud HTTP.
Resume()	Reanuda una operación de descarga en pausa.
SetRequestHeader(String, String)	Se usa para establecer un encabezado de solicitud HTTP.
StartAsync()	Inicia una operación de descarga asincrónica.

Eventos

RangesDownloaded

Proporciona acceso al progreso de descarga incremental.

Consulte también

• Inicio rápido: Descarga de un archivo
• Ejemplo de transferencia en segundo plano
• Ejemplo de transferencia en segundo plano (Windows 8.x)