DownloadOperation Klasse

  • Referenz

Definition

Namespace:
Windows.Networking.BackgroundTransfer
Bearbeiten

Führt einen asynchronen Downloadvorgang aus. Das Beispiel für die Hintergrundübertragung veranschaulicht diese Funktionalität. Eine Übersicht über die Funktionen der Hintergrundübertragung finden Sie unter Übertragen von Daten im Hintergrund.

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
Vererbung
Object Platform::Object IInspectable DownloadOperation
Attribute
ContractVersionAttribute MarshalingBehaviorAttribute
Implementiert
IBackgroundTransferOperation IBackgroundTransferOperationPriority

Windows-Anforderungen

Gerätefamilie
Windows 10 (eingeführt in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (eingeführt in v1.0)
App-Funktionen
internetClient internetClientServer privateNetworkClientServer

Beispiele

Beispielanwendungen, die diese Klasse verwenden, sind das Beispiel für die Hintergrundübertragung.

Im folgenden Beispiel wird veranschaulicht, wie Ein einfacher Downloadvorgang konfiguriert und gestartet wird.

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

Hinweise

Beim nächsten Start nach der Anwendungsbeendigung sollte Ihre Anwendung alle vorhandenen DownloadOperation-Instanzen mithilfe von GetCurrentDownloadsAsync auflisten. Wenn eine UWP-Anwendung, die die Hintergrundübertragung verwendet, beendet wird, bleiben unvollständige Downloads im Hintergrund erhalten. Wenn Ihre Anwendung nach der Beendigung neu gestartet wird und diese unvollständigen Vorgänge nicht aufgelistet und erneut in die aktuelle Sitzung eingeführt werden, werden sie veraltet und belegen weiterhin Geräteressourcen.

Die Hintergrundübertragung unterstützt keine gleichzeitigen Downloads desselben URI. Eine App kann also einmal heruntergeladen http://example.com/myfile.wmv oder erneut heruntergeladen werden, nachdem ein vorheriger Download abgeschlossen ist. Eine App sollte nicht zwei Downloads desselben URI gleichzeitig starten, da dies zu abgeschnittenen Dateien führen kann.

Hinweis

Angehaltene oder unvollständige Downloadvorgänge können nur fortgesetzt werden, wenn der Server Bereichsanforderungen akzeptiert.

Überlegungen zu Timeout

  1. Beim Herstellen einer neuen Verbindung für einen Download über TCP/SSL wird der Verbindungsversuch abgebrochen, wenn er nicht innerhalb von fünf Minuten hergestellt wird.
  2. Nachdem die Verbindung hergestellt wurde, wird eine HTTP-Anforderungsnachricht abgebrochen, die innerhalb von zwei Minuten keine Antwort erhalten hat. Unter der Voraussetzung, dass eine Internetverbindung vorhanden ist, versucht die Hintergrundübertragung einen Download bis zu dreimal. Wenn die Internetkonnektivität nicht erkannt wird, werden weitere Versuche erst durchgeführt, wenn dies der Fall ist.

Anleitung zum Debuggen

Das Beenden einer Debugsitzung in Microsoft Visual Studio ist mit dem Schließen Ihrer App vergleichbar. Downloads werden angehalten, und POST-Uploads werden beendet. Auch beim Debuggen sollte Ihre App alle dauerhaften Downloads auflisten und dann anhalten, fortsetzen, neu starten oder abbrechen.

Wenn Jedoch Microsoft Visual Studio-Projektupdates, z. B. Änderungen am App-Manifest, erfordern, dass die App deinstalliert und zum Debuggen erneut bereitgestellt wird, kann GetCurrentDownloadsAsync keine dauerhaften Vorgänge auflisten, die mit der vorherigen App-Bereitstellung erstellt wurden.

Versionsverlauf

Windows-Version SDK-Version Wertschöpfung
1709 16299 CurrentWebErrorStatus
1709 16299 GetDownloadedRanges
1709 16299 GetResultRandomAccessStreamReference
1709 16299 IsRandomAccessRequired
1709 16299 BereicheHerunterladen
1709 16299 RecoverableWebErrorStatuses
1803 17134 MakeCurrentInTransferGroup
2004 19041 RemoveRequestHeader
2004 19041 SetRequestHeader

Eigenschaften

CostPolicy

Ruft die Kostenrichtlinie für den Download ab und legt sie fest.
CurrentWebErrorStatus

WebErrorStatus einer Übertragung, der während der Lebensdauer der DownloadOperation überwacht werden kann.
Group

Hinweis

Die Gruppe kann für Releases nach Windows 8.1 geändert oder nicht mehr verfügbar sein. Verwenden Sie stattdessen TransferGroup.

Ruft einen Zeichenfolgenwert ab, der die Gruppe angibt, zu der die Übertragung gehört.
Guid

Dies ist ein eindeutiger Bezeichner für einen bestimmten Downloadvorgang. Eine GUID , die einem Downloadvorgang zugeordnet ist, ändert sich für die Dauer des Downloads nicht.
IsRandomAccessRequired

Eine boolesche Eigenschaft zum Aktivieren des zufälligen Zugriffs. Die -Eigenschaft muss vor dem Aufrufen von StartAsync() für ein DownloadOperation-Objekt auf TRUE festgelegt werden, um das Feature für den zufallsfreien Zugriff zu verwenden. Nachdem Sie StartAsync() aufgerufen haben, rufen Sie GetResultRandomAccessStreamReference auf, um einen Verweis auf den Datenstrom zu erhalten und daraus zu lesen.
Method

Ruft die Methode ab, die für den Download verwendet werden soll.
Priority

Ruft die Übertragungspriorität dieses Downloadvorgangs in einer BackgroundTransferGroup ab oder legt diese fest. Mögliche Werte werden von BackgroundTransferPriority definiert.
Progress

Ruft den aktuellen Fortschritt des Vorgangs ab.
RecoverableWebErrorStatuses

Eine Reihe von WebErrorStatus-Werten , von denen Anwendungen erwarten, dass der Download erreicht wird, und die die Anwendungen wissen, wie sie zu behandeln sind.
RequestedUri

Ruft den URI ab, von dem die Datei heruntergeladen werden soll.
ResultFile

Gibt das IStorageFile-Objekt zurück, das vom Aufrufer beim Erstellen des DownloadOperation-Objekts mithilfe von CreateDownload bereitgestellt wird.
TransferGroup

Ruft die Gruppe ab, zu der dieser Downloadvorgang gehört.

Methoden

AttachAsync()

Gibt einen asynchronen Vorgang zurück, der verwendet werden kann, um den Fortschritt und abschluss des angefügten Downloads zu überwachen. Durch Aufrufen dieser Methode kann eine App Downloadvorgänge anfügen, die in einer vorherigen App instance gestartet wurden.
GetDownloadedRanges()

Gibt die vollständige Liste der Dateibereiche zurück, die bisher heruntergeladen wurden.
GetResponseInformation()

Ruft die Antwortinformationen ab.
GetResultRandomAccessStreamReference()

Ruft einen Verweis auf den Datenstrom mit zufälligem Zugriff ab und liest daraus. Es ist erforderlich, IsRandomAccessRequired auf TRUE festzulegen, bevor GetResultRandomAccessStreamReference aufgerufen wird.
GetResultStreamAt(UInt64)

Ruft die teilweise heruntergeladene Antwort an der angegebenen Position ab.
MakeCurrentInTransferGroup()

Priorisiert den Downloadübertragungsvorgang (und alle Übertragungen, die in derselben Übertragungsgruppe folgen). Das Aufrufen dieser Methode für eine Übertragung, die nicht zu einer Übertragungsgruppe gehört, hat keine Auswirkung.
Pause()

Hält einen Downloadvorgang an.
RemoveRequestHeader(String)

Wird verwendet, um einen HTTP-Anforderungsheader zu entfernen.
Resume()

Setzt einen angehaltenen Downloadvorgang fort.
SetRequestHeader(String, String)

Wird verwendet, um einen HTTP-Anforderungsheader festzulegen.
StartAsync()

Startet einen asynchronen Downloadvorgang.

Ereignisse

RangesDownloaded

Ermöglicht den Zugriff auf den Fortschritt des inkrementellen Downloads.

Gilt für:

Weitere Informationen