DownloadOperation Klasse

Referenz

Definition

Namespace:: Windows.Networking.BackgroundTransfer

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

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

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.
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:

Freigeben über