BackgroundDownloader Class

Wird verwendet, um Downloads vor der Erstellung des Downloadvorgangs mit CreateDownload zu konfigurieren. Eine Übersicht über Hintergrundübertragungsfunktionen finden Sie unter Übertragen von Daten im Hintergrund. Beispiele mit JavaScript, C# und C++ finden Sie im Beispiel für Hintergrundübertragung.

Hinweis  Hintergrundübertragung ist hauptsächlich für langfristige Übertragungsvorgänge für Ressourcen wie Videos, Musik und große Bilder vorgesehen. Für Kurzzeitvorgänge, die Übertragungen kleinerer Ressourcen beinhalten (d. h ein paar KB), verwenden Sie den Windows.Web.Http-Namespace.

Syntax


var backgroundDownloader = new Windows.Networking.BackgroundTransfer.BackgroundDownloader();

Attribute

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]

Member

BackgroundDownloaderKlasse hat diese Membertypen:

Konstruktoren

BackgroundDownloaderKlasse hat diese Konstruktoren.

KonstruktorBeschreibung
BackgroundDownloader Instantiates a new BackgroundDownloader object.

 

Methoden

The BackgroundDownloader Klasse hat diese Methoden. Mit C#, Visual Basic und C++ erbt es auch Methoden aus Object Klasse.

MethodeBeschreibung
CreateDownload(Uri, IStorageFile) Initializes a DownloadOperation object that contains the specified Uri and the file that the response is written to.
CreateDownload(Uri, IStorageFile, IStorageFile) Initializes a DownloadOperation object with the resource Uri, the file that the response is written to, and the request entity body.
CreateDownloadAsync Creates an asynchronous download operation that includes a URI, the file that the response will be written to, and the IInputStream object from which the file contents are read.
GetCurrentDownloadsAsync() Returns a collection of pending downloads that are not associated with a group.
GetCurrentDownloadsAsync(String) Returns a collection of pending downloads for a specific Group.
GetCurrentDownloadsForTransferGroupAsync Gets all downloads associated with the provided BackgroundTransferGroup
RequestUnconstrainedDownloadsAsync Used to request an unconstrained download operation. When this method is called the user is provided with a UI prompt that they can use to indicate their consent for an unconstrained operation.
SetRequestHeader Used to set an HTTP request header.

 

Eigenschaften

Der BackgroundDownloaderKlasse hat diese Eigenschaften.

EigenschaftZugriffstypBeschreibung

CostPolicy

Lese-/SchreibzugriffGets or sets the cost policy for the background download operation.

FailureTileNotification

Lese-/SchreibzugriffGets or sets the TileNotification used to define the visuals, identification tag, and expiration time of a tile notification used to update the app tile when indicating failure of a download to the user.

FailureToastNotification

Lese-/SchreibzugriffGets or sets the ToastNotification that defines the content, associated metadata, and events used in a toast notification to indicate failure of a download to the user.

Group

Lese-/SchreibzugriffGets or sets a string value (e.g. a GUID) indicating the group the transfer will belong to. A download operation with a group ID will only appear in operation enumerations using GetCurrentDownloadsAsync(String)

Method

Lese-/SchreibzugriffGets or sets the HTTP method used for the background download

ProxyCredential

Lese-/SchreibzugriffGets or sets the proxy credentials for the background transfer.

ServerCredential

Lese-/SchreibzugriffGets or sets the credentials to use to authenticate with the origin server.

SuccessTileNotification

Lese-/SchreibzugriffGets or sets the TileNotification used to define the visuals, identification tag, and expiration time of a tile notification used to update the app tile when indicating success of a download to the user.

SuccessToastNotification

Lese-/SchreibzugriffGets or sets the ToastNotification that defines the content, associated metadata, and events used in a toast notification to indicate success of a download to the user.

TransferGroup

Lese-/SchreibzugriffGets or sets the group that a download operation will belong to.

 

Hinweise

Nach Beendigung der App sollte eine App alle vorhandenen DownloadOperation-Instanzen beim folgenden Start mithilfe von GetCurrentDownloadsAsync auflisten. Wenn eine Windows Store-App beendet wird, die die Hintergrundübertragung verwendet, bestehen unvollständige Herunterladevorgänge im Hintergrund weiter. Wenn die App nach Beendigung neu gestartet wird und Vorgänge von der vorherigen Sitzung nicht aufgelistet und wieder zur aktuellen Sitzung hinzugefügt werden, bleiben diese unvollständig und beanspruchen weiterhin Ressourcen.

Hinweis  Wenn eine Anwendung deinstalliert wird, werden alle zugeordneten aktuellen oder persistenten Hintergrundübertragungsvorgänge bereinigt.

Die Hintergrundübertragung unterstützt keine gleichzeitigen Downloads von derselben Uri. Daher kann eine App http://example.com/myfile.wmv einmal oder erneut nach einem zuvor abgeschlossenen Download herunterladen. Eine App sollte nicht gleichzeitig zwei Downloads von derselben Uri beginnen, da dies möglicherweise zu abgeschnittenen Dateien führt.

Wenn Sie eine Bibliothek für Hintergrundübertragungsvorgänge implementieren und die gleiche Bibliothek von anderen Apps oder Komponenten verwendet wird, geben Sie eine eindeutige group-Namenszeichenfolge (beispielsweise eine GUID) beim Erstellen von Downloads an. Ein Download mit einer Gruppennamenszeichenfolge kann nur aufgezählt werden, indem GetCurrentDownloadsAsync(String) die übereinstimmende Zeichenfolge erhält. Ohne wird der Download nicht in GetCurrentDownloadsAsync-Aufrufen angezeigt. Damit wird sichergestellt, dass andere Apps, die die gleiche Bibliothek für Downloads implementieren, Ihre Downloads nicht wahrnehmen.

Downloadvorgänge über FTP werden unterstützt. Es müssen jedoch Authentifizierungsinformationen innerhalb des angegebenen URI für FTP-Vorgänge bereitgestellt werden. Beispiel: ftp://user:password@server/file.txt.

Sicherheitsrisiken können bestehen, wenn für Downloadvorgänge ein Benutzername und ein Kennwort zur Authentifizierung benötigt werden. Wenn das zu verwendende Authentifizierungsmodell von WinINet unterstützt wird, verwenden Sie die ServerCredential- oder ProxyCredential-Eigenschaften. Diese Werte werden in WinVault sicher gespeichert. Weitere Informationen zu unterstützten Authentifizierungsmethoden finden Sie unter Behandlungs-Authentifizierung.

Wenn das Authentifizierungsmodell nicht von WinINet unterstützt wird, verwenden Sie HttpClient, um eine benutzerdefinierte Authentifizierung zu implementieren und ein downloadspezifisches sicheres Token (Cookie) zu erhalten. Legen Sie für den entsprechenden Header den Wert des sicheren Tokens fest, der für die Hintergrundübertragung verwendet wird. Der Dienst muss dafür sorgen, dass der sichere Token nur für die Datei gültig ist, die heruntergeladen wird.

Hinweis  Das sichere Token wird als Klartext im Ordner der Anwendung gespeichert.

Dienste zum Hochladen, bei denen der Benutzername und das Kennwort im Klartext in einem benutzerdefinierten Header für jede herunterzuladende Datei festgelegt werden müssen, sind nicht sicher. Die Hintergrundübertragung bewirkt eine Zwischenspeicherung der Kopfzeilen im Klartext für die Dauer des Vorgangs im App-Ordner.

Handling Exceptions

Eine Reihe von Fehlern können Ausnahmen auslösen, die während des Herunterladens auftreten. Wenn Sie Methoden dieser Klasse aufrufen, sollten Sie Code zur Behandlung von Ausnahmen schreiben. Ausnahmen können durch Parametervalidierungsfehler, Namensauflösungsfehler und Netzwerkfehler ausgelöst werden. Ausnahmen durch Netzwerkfehler (beispielsweise Verlust der Konnektivität, Verbindungsfehler und andere HTTP-Fehler) können jederzeit vorkommen. Durch diese Fehler werden Ausnahmen ausgelöst. Wenn sie nicht von der Anwendung verarbeitet wird, kann eine Ausnahme bewirken, dass die gesamte App von der Laufzeit beendet wird.

Eine App kann das HRESULT aus der Ausnahme verwenden, um den Fehler zu bestimmen, der die Ausnahme ausgelöst hat. Eine App kann dann entscheiden, wie die Ausnahme aufgrund des Fehlercodes behandelt wird. Die BackgroundTransferError.GetStatus-Methode kann die meisten zurückgegebenen HRESULT-Werte in einen WebErrorStatus-Enumerationswert konvertieren. Die meisten der WebErrorStatus-Enumerationswerte entsprechen einem Fehler, der von der systemeigenen HTTP- oder FTP-Client-Operation zurückgegeben wird. Eine App kann bestimmte WebErrorStatus-Enumerationswerte filtern, um das App-Verhalten abhängig von der Ursache der Ausnahme zu ändern.

Weitere Informationen zu Netzwerkausnahmen finden Sie unter Behandeln von Ausnahmen in den Netzwerk-Apps.

Debugging Guidance

Eine Debugsitzung in Microsoft Visual Studio zu beenden ist mit dem Schließen der App vergleichbar. Auch beim Debuggen sollte die App alle aus der vorherigen Sitzung beibehaltenen Downloads auflisten und dann fortsetzen, neu starten oder abbrechen. Sie können beispielsweise aufgelistete beibehaltene Downloadvorgänge beim App-Start durch die App abbrechen lassen, wenn kein Interesse an vorherigen Operationen für diese Debugsitzung besteht.

Wenn Visual Studio-Projektupdates, wie Änderungen am App-Manifest, vorhanden sind und die App deinstalliert und erneut bereitgestellt wird, kann GetCurrentUploadsAsync Vorgänge nicht auflisten, die mithilfe der vorherigen App-Bereitstellung erstellt werden.

Weitere Informationen finden Sie unter Debuggen und Testen von Windows Store-Apps.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie Sie einen einfachen Downloadvorgang konfigurieren und starten. Das Beispiel basiert auf dem Beispiel für eine Hintergrundübertragung, das im Windows-Beispielkatalog bereitgestellt wird.


        var download = null;
        var promise = null;

        function DownloadFile (uriString, fileName) {
            try {
                // Asynchronously create the file in the pictures folder.
                Windows.Storage.KnownFolders.picturesLibrary.createFileAsync(fileName, Windows.Storage.CreationCollisionOption.generateUniqueName).done(function (newFile) {
                    var uri = Windows.Foundation.Uri(uriString);
                    var downloader = new Windows.Networking.BackgroundTransfer.BackgroundDownloader();

                    // Create a new download operation.
                    download = downloader.createDownload(uri, newFile);

                    // Start the download and persist the promise to be able to cancel the download.
                    promise = download.startAsync().then(complete, error, progress);
                }, error);
            } catch (err) {
                displayException(err);
            }
        };

Anforderungen

Mindestens unterstützter Client

Windows 8 [Nur Windows Store-Apps]

Mindestens unterstützter Server

Windows Server 2012 [Nur Windows Store-Apps]

Namespace

Windows.Networking.BackgroundTransfer
Windows::Networking::BackgroundTransfer [C++]

Metadaten

Windows.winmd

Capabilities

internetClient
internetClientServer
privateNetworkClientServer

Siehe auch

Schnellstart: Herunterladen einer Datei
Beispiel für Hintergrundübertragung
Behandeln von Ausnahmen in Netzwerk-Apps

 

 

Anzeigen:
© 2014 Microsoft