BackgroundDownloader Klasse

Definition

public ref class BackgroundDownloader sealed

/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class BackgroundDownloader final

/// [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(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundDownloader final

[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[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)]
public sealed class BackgroundDownloader

[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(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundDownloaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundDownloader

function BackgroundDownloader(completionGroup)

Public NotInheritable Class BackgroundDownloader

Vererbung

Object Platform::Object IInspectable BackgroundDownloader

Attribute

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementiert

IBackgroundTransferBase

Windows-Anforderungen

Beispiele

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

Nach dem Beenden der App sollte eine App alle vorhandenen DownloadOperation-Instanzen beim nächsten Start mithilfe von GetCurrentDownloadsAsync auflisten. Wenn eine UWP-App, die die Hintergrundübertragung verwendet, beendet wird, bleiben unvollständige Downloads im Hintergrund erhalten. Wenn die App nach dem Beenden neu gestartet wird und Vorgänge aus der vorherigen Sitzung nicht aufgelistet und erneut an die aktuelle Sitzung angefügt werden, bleiben sie unvollständig und belegen weiterhin Ressourcen.

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.

Wenn Sie eine Bibliothek für Hintergrundübertragungsvorgänge implementieren und dieselbe Bibliothek von anderen Apps oder Komponenten verwendet wird, geben Sie beim Erstellen von Downloads eine eindeutigeGruppennamenzeichenfolge (z. B. eine GUID) an. Ein Download mit einer Gruppennamenzeichenfolge kann nur aufgelistet werden, indem die übereinstimmende Zeichenfolge für GetCurrentDownloadsAsync(String) bereitgestellt wird, und wird in GetCurrentDownloadsAsync-Aufrufen ohne nicht angezeigt. Dadurch wird sichergestellt, dass ihre Downloads von anderen Apps, die dieselbe Bibliothek für Downloads implementieren, nicht angezeigt werden.

Downloadvorgänge über FTP werden unterstützt. Für FTP-Vorgänge müssen jedoch anmeldeinformationen für die Authentifizierung innerhalb des angegebenen URI angegeben werden. Beispiel: ftp://user:password@server/file.txt.

Sicherheitsbedenken können vorliegen, wenn Downloadvorgänge einen Benutzernamen und ein Kennwort für die Authentifizierung erfordern. Wenn das zu verwendende Authentifizierungsmodell von WinINet unterstützt wird, verwenden Sie die Eigenschaften ServerCredential oder ProxyCredential . Diese Werte werden sicher in WinVault gespeichert. Informationen zu unterstützten Authentifizierungsmethoden finden Sie unter Behandeln der Authentifizierung.

Wenn das Authentifizierungsmodell von WinINet nicht unterstützt wird, verwenden Sie HttpClient , um die benutzerdefinierte Authentifizierung zu implementieren und ein downloadspezifisches sicheres Token (Cookie) abzurufen. Legen Sie den entsprechenden Header so fest, dass der Wert des sicheren Tokens für die Hintergrundübertragung verwendet wird. Der Dienst sollte die Gültigkeit des sicheren Tokens nur auf die Datei beschränken, die heruntergeladen wird.

Uploaddienste, bei denen der Benutzername und das Kennwort in einem benutzerdefinierten Header für jede Downloaddatei als Klartext festgelegt werden müssen, sind unsicher. Bei der Hintergrundübertragung werden die Header im Klartext für die Dauer des Vorgangs im Ordner der App zwischengespeichert.

Popupbenachrichtigungen

Die BackgroundDownloader-Klasse in Windows 8.1 und Windows Server 2012 R2 unterstützt Optionen für den Benutzer, um Kachel- und Popupbenachrichtigungen zu empfangen, wenn eine Übertragung erfolgreich abgeschlossen wurde oder nicht abgeschlossen werden kann.

Eine App, die Windows.Networking.BackgroundTransfer für die Kommunikation über eine Popupbenachrichtigung verwendet, muss in der App-Manifestdatei deklarieren, dass sie toastfähig ist. Die Einstellung Toastfähig befindet sich im Abschnitt Benachrichtigungen der Registerkarte Anwendung . Legen Sie die Option Popupfähig auf "Ja" fest, damit die App Popupbenachrichtigungen empfangen kann.

Wenn popupfähig im App-Manifest nicht aktiviert ist, werden alle Popupeinstellungen im Windows.Networking.BackgroundTransfer-Namespace im Hintergrund ignoriert, und die App empfängt keine Popupbenachrichtigungen.

Weitere Informationen zu Popupbenachrichtigungen finden Sie unter Senden von Popupbenachrichtigungen und Aktivieren von Popupbenachrichtigungen.

Behandeln von Ausnahmen

Eine Reihe von Fehlern kann dazu führen, dass während eines Downloadvorgangs Ausnahmen auftreten. Sie sollten Code schreiben, um Ausnahmen zu behandeln, wenn Sie Methoden für diese Klasse aufrufen. Ausnahmen können sich aus Parametervalidierungsfehlern, Namenauflösungsfehlern und Netzwerkfehlern ergeben. Ausnahmen von Netzwerkfehlern (z. B. Verbindungsverlust, Verbindungsfehler und andere HTTP-Fehler) können jederzeit auftreten. Diese Fehler haben zur Folge, dass Ausnahmen ausgelöst werden. Wenn sie nicht von Ihrer App verarbeitet wird, kann eine Ausnahme dazu führen, dass Ihre gesamte App von der Runtime beendet wird.

Eine App kann das HRESULT aus der Ausnahme verwenden, um den Fehler zu ermitteln, der die Ausnahme verursacht hat. Eine App kann dann basierend auf dem Fehlercode entscheiden, wie die Ausnahme behandelt werden soll. Die BackgroundTransferError.GetStatus-Methode kann die meisten zurückgegebenen HRESULT-Werte in einen WebErrorStatus-Enumerationswert konvertieren. Die meisten WebErrorStatus-Enumerationswerte entsprechen einem vom systemeigenen HTTP- oder FTP-Clientvorgang zurückgegebenen Fehler. Eine App kann nach bestimmten WebErrorStatus-Enumerationswerten filtern, um das App-Verhalten je nach Ausnahmeursache zu ändern.

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

Anleitung zum Debuggen

Das Beenden einer Debugsitzung in Microsoft Visual Studio ist vergleichbar mit dem Schließen Ihrer App. Auch beim Debuggen sollte Ihre App alle Downloads aus der vorherigen Sitzung auflisten und dann fortsetzen, neu starten oder abbrechen. Beispielsweise können Sie ihre App beim Starten der App auflistende persistente Downloadvorgänge abbrechen lassen, wenn kein Interesse an vorherigen Vorgängen für die aktuelle Debugsitzung besteht.

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

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

Bei der Verwendung von Hintergrundübertragungen während der Entwicklung kann es vorkommen, dass die internen Caches aktiver und abgeschlossener Übertragungsvorgänge nicht mehr synchron sind. Dies kann zur Folge haben, dass keine neuen Übertragungsvorgänge gestartet werden können, oder dass keine Interaktion mit vorhandenen Vorgängen und BackgroundTransferGroup-Objekten mehr möglich ist. In einigen Fällen wird durch den Versuch einer Interaktion mit vorhandenen Vorgängen ein Absturz ausgelöst. Dies kann vorkommen, wenn die TransferBehavior-Eigenschaft auf Parallel festgelegt ist. Dieses Problem tritt nur bei bestimmten Szenarien während der Entwicklung auf und betrifft nicht die Endbenutzer Ihrer App.

Vier Szenarien mit Microsoft Visual Studio können dieses Problem verursachen.

• Sie erstellen ein neues Projekt mit demselben App-Namen wie ein vorhandenes Projekt, jedoch einer anderen Sprache (z. B. C# statt C++).
• Sie ändern die Zielarchitektur (z. B. von x86 zu x64) in einem vorhandenen Projekt.
• Sie ändern die Kultur (z. B. von neutral zu en-US) in einem vorhandenen Projekt.
• Sie fügen in einem vorhandenen Projekt eine Funktion im Paketmanifest (z. B. Unternehmensauthentifizierung) hinzu oder entfernen eine. Normale App-Wartungen wie z. B. Manifestaktualisierungen, bei denen Funktionen hinzugefügt oder entfernt werden, lösen dieses Problem in den Bereitstellungen Ihrer App für Endbenutzer nicht aus.

Umgehen Sie dieses Problem, indem Sie alle Versionen der App vollständig deinstallieren und sie mit der neuen Sprache, Architektur, Kultur oder Funktion erneut bereitstellen. Dies kann über den Startbildschirm oder mithilfe von PowerShell und dem Remove-AppxPackage Cmdlet erfolgen.

Konstruktoren

Eigenschaften

Methoden

Gilt für:

Weitere Informationen

• DownloadOperation
• Behandeln von Ausnahmen in Netzwerk-Apps
• Aktivieren von Popupbenachrichtigungen
• Schnellstart: Herunterladen einer Datei
• Beispiel für die Hintergrundübertragung
• Beispiel für die Hintergrundübertragung (Windows 8.x)