BackgroundDownloader Klasse

Definition

Namespace:

Windows.Networking.BackgroundTransfer

Dient zum Konfigurieren von Downloads vor der eigentlichen Erstellung des Downloadvorgangs mithilfe von CreateDownload. Eine Übersicht über die Funktionen der Hintergrundübertragung finden Sie unter Übertragen von Daten im Hintergrund. Laden Sie das Beispiel für die Hintergrundübertragung für ein Codebeispiel herunter.

Hinweis

Hintergrundübertragung ist in erster Linie für langfristige Übertragungsvorgänge für Ressourcen wie Video, Musik und große Bilder konzipiert. Verwenden Sie für kurzfristige Vorgänge, die die Übertragung kleinerer Ressourcen (d. h. ein paar KB) umfassen, den Windows.Web.Http-Namespace .

public ref class BackgroundDownloader sealed

/// [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.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

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

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.

Hinweis

Wenn eine App deinstalliert wird, werden alle aktuellen oder dauerhaften Hintergrundübertragungsvorgänge, die damit verknüpft sind, bereinigt.

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.

Hinweis

Das sichere Token wird in Klartext im Ordner der Anwendung gespeichert.

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.

Hinweis

Ein Benutzer kann Popupbenachrichtigungen für Ihre App jederzeit manuell deaktivieren oder aktivieren.

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

BackgroundDownloader()	Erstellt ein neues BackgroundDownloader-Objekt .
BackgroundDownloader(BackgroundTransferCompletionGroup)	Erstellt ein neues BackgroundDownloader-Objekt mit einer BackgroundTransferCompletionGroup.

Eigenschaften

CompletionGroup	Ruft die BackgroundTransferCompletionGroup ab, die dem BackgroundDownloader zugeordnet ist.
CostPolicy	Ruft die Kostenrichtlinie für den Hintergrunddownloadvorgang ab oder legt diese fest.
FailureTileNotification	Ruft die TileNotification ab, die verwendet wird, um die Visuals, das Identifikationstag und die Ablaufzeit einer Kachelbenachrichtigung zu definieren, die zum Aktualisieren der App-Kachel verwendet wird, wenn ein Download für den Benutzer fehlgeschlagen ist, oder legt diese fest.
FailureToastNotification	Ruft die ToastNotification ab, die den Inhalt, die zugeordneten Metadaten und Ereignisse definiert, die in einer Popupbenachrichtigung verwendet werden, um auf einen Fehler eines Downloads für den Benutzer hinzuweisen, oder legt diesen fest.
Group	Hinweis Die Gruppe kann nach Windows 8.1 geändert oder nicht mehr für Releases verfügbar sein. Verwenden Sie stattdessen TransferGroup. Ruft einen Zeichenfolgenwert (z. B. eine GUID) ab, der die Gruppe angibt, zu der die Übertragung gehört, oder legt diesen fest. Ein Downloadvorgang mit einer Gruppen-ID wird nur in Vorgangsaufzählungen mit GetCurrentDownloadsAsync(String) mit dem spezifischen Gruppenzeichenfolgenwert angezeigt.
Method	Ruft die http-Methode ab, die für den Hintergrunddownload verwendet wird, oder legt sie fest. Die Standardmethode für Downloadvorgänge ist GET.
ProxyCredential	Ruft die Proxyanmeldeinformationen für die Hintergrundübertragung ab oder legt diese fest.
ServerCredential	Ruft die Anmeldeinformationen ab, die für die Authentifizierung beim Ursprungsserver verwendet werden sollen, oder legt diese fest. Hinweis Für Downloads über FTP müssen die Anmeldeinformationen für die Authentifizierung innerhalb des angegebenen URI angegeben werden. Beispiel: ftp://user:password@server/file.txt.
SuccessTileNotification	Ruft die TileNotification ab, die zum Definieren der Visuals, des Identifikationstags und der Ablaufzeit einer Kachelbenachrichtigung verwendet wird, die zum Aktualisieren der App-Kachel verwendet wird, wenn der Benutzer einen erfolgreichen Download angibt, oder legt diese fest.
SuccessToastNotification	Ruft die ToastNotification ab, die den Inhalt, die zugeordneten Metadaten und Ereignisse definiert, die in einer Popupbenachrichtigung verwendet werden, um den Erfolg eines Downloads für den Benutzer anzuzeigen, oder legt diesen fest.
TransferGroup	Ruft die Gruppe ab, zu der ein Downloadvorgang gehört, oder legt sie fest.

Methoden

CreateDownload(Uri, IStorageFile)	Initialisiert ein DownloadOperation-Objekt , das den angegebenen URI und die Datei enthält, in die die Antwort geschrieben wird.
CreateDownload(Uri, IStorageFile, IStorageFile)	Initialisiert ein DownloadOperation-Objekt mit dem Ressourcen-URI, der Datei, in die die Antwort geschrieben wird, und dem Anforderungsentitätstext.
CreateDownloadAsync(Uri, IStorageFile, IInputStream)	Erstellt einen asynchronen Downloadvorgang, der einen URI, die Datei, in die die Antwort geschrieben wird, und das IInputStream-Objekt enthält, aus dem die Dateiinhalte gelesen werden.
GetCurrentDownloadsAsync()	Gibt eine Auflistung ausstehender Downloads zurück, die keiner BackgroundTransferGroup zugeordnet sind.
GetCurrentDownloadsAsync(String)	Hinweis GetCurrentDownloadsAsync(group) ist für Releases nach Windows 8.1 möglicherweise geändert oder nicht verfügbar. Verwenden Sie stattdessen GetCurrentDownloadsForTransferGroupAsync. Gibt eine Auflistung ausstehender Downloads für eine bestimmte Gruppe zurück.
GetCurrentDownloadsForTransferGroupAsync(BackgroundTransferGroup)	Ruft alle Downloads ab, die der bereitgestellten BackgroundTransferGroup zugeordnet sind.
RequestUnconstrainedDownloadsAsync(IIterable<DownloadOperation>)	Hinweis RequestUnconstrainedDownloadsAsync ist für Releases nach Windows 10 Version 1607 möglicherweise geändert oder nicht verfügbar. Verwenden Sie stattdessen CreateDownloadAsync. Wird verwendet, um einen uneingeschränkten Downloadvorgang anzufordern. Wenn diese Methode aufgerufen wird, wird dem Benutzer eine Benutzeroberflächenaufforderung bereitgestellt, die er verwenden kann, um seine Zustimmung für einen uneingeschränkten Vorgang anzugeben. Ein nicht eingeschränkter Übertragungsvorgang wird ohne die Ressourceneinschränkungen ausgeführt, die normalerweise mit Hintergrundnetzwerkvorgängen verbunden sind, während ein Gerät mit Akku ausgeführt wird.
SetRequestHeader(String, String)	Wird verwendet, um einen HTTP-Anforderungsheader festzulegen.

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)