BackgroundUploader Klasse

Definition

Namespace:

Windows.Networking.BackgroundTransfer

Wird verwendet, um den Upload vor der eigentlichen Erstellung des Uploadvorgangs mithilfe von CreateUpload zu konfigurieren. 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

Die 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 mit Übertragungen kleinerer Ressourcen (d. h. ein paar KB) den Windows.Web.Http-Namespace .

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

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

Vererbung

Object Platform::Object IInspectable BackgroundUploader

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 Sie einen einfachen Uploadvorgang konfigurieren und beginnen.

using Windows.Foundation; 
using Windows.Networking.BackgroundTransfer;
using Windows.Storage.Pickers;
using Windows.Storage;

private async void StartUpload_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri uri = new Uri(serverAddressField.Text.Trim());
        FileOpenPicker picker = new FileOpenPicker();
        picker.FileTypeFilter.Add("*");
        StorageFile file = await picker.PickSingleFileAsync();

        BackgroundUploader uploader = new BackgroundUploader();
        uploader.SetRequestHeader("Filename", file.Name);

        UploadOperation upload = uploader.CreateUpload(uri, file);

        // Attach progress and completion handlers.
        HandleUploadAsync(upload, true);
    }
    catch (Exception ex)
    {
        LogException("Upload Error", ex);
    }
}

Hinweise

Nach dem Beenden der App sollte eine App alle vorhandenen UploadOperation-Instanzen beim nächsten Start mithilfe von GetCurrentUploadsAsync auflisten. Wenn eine UWP-App, die die Hintergrundübertragung verwendet, beendet wird, bleiben unvollständige Uploads 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. Nach dem Aufzählen werden PUT-Uploadvorgänge automatisch neu gestartet, und POST-Uploadvorgänge werden beendet.

Hinweis

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

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 Uploads eine eindeutigeGruppennamenzeichenfolge (z. B. eine GUID) an. Ein Upload mit einer Gruppennamenzeichenfolge kann nur durch Angabe der übereinstimmenden Zeichenfolge für GetCurrentDownloadsAsync(String) aufgezählt werden und wird nicht in GetCurrentDownloadsAsync-Aufrufen ohne angezeigt. Dadurch wird sichergestellt, dass andere Apps, die dieselbe Bibliothek für Uploads implementieren, Ihre Uploads nicht sehen.

Uploadvorgänge über FTP werden nicht unterstützt.

Sicherheitsbedenken können bestehen, wenn Uploadvorgä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 uploadspezifisches 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 hochgeladen 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 Uploaddatei 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 BackgroundUploader-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 Uploadvorgangs 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 behandelt 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.

Einige HRESULT-Werte können nicht in einen WebErrorStatus-Enumerationswert konvertiert werden. Wenn ein POST-Hintergrundvorgang abgebrochen wird, wird eine Ausnahme ausgelöst. Der Vorgang wird nicht neu gestartet. Weitere Informationen finden Sie unter UploadOperation.StartAsync.

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

Anleitung zum Debuggen

Das Beenden einer Debugsitzung in Microsoft Visual Studio ist mit dem Schließen der App vergleichbar; PUT-Uploads werden angehalten und POST-Uploads werden beendet. Auch beim Debuggen sollte die App alle beibehaltenen Uploads auflisten und dann neu starten oder abbrechen. Sie können beispielsweise aufgelistete beibehaltene Uploadvorgänge beim App-Start durch die App abbrechen lassen, wenn kein Interesse an vorherigen Operationen für diese Debugsitzung besteht.

Während Downloads/Uploads beim App-Start in einer Debugsitzung aufgelistet werden, können Sie diese durch Ihre App abbrechen lassen, wenn kein Interesse an vorherigen Operationen für diese Debugsitzung besteht. Beachten Sie, dass GetCurrentUploadsAsync keine Vorgänge auflisten kann, die mit der vorherigen App-Bereitstellung erstellt wurden, wenn Microsoft Visual Studio-Projektupdates wie Änderungen am App-Manifest vorhanden sind und die App deinstalliert und erneut bereitgestellt wird.

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

BackgroundUploader()	Instanziiert ein neues BackgroundUploader-Objekt .
BackgroundUploader(BackgroundTransferCompletionGroup)	Instanziiert ein neues BackgroundUploader-Objekt als Mitglied einer Abschlussgruppe.

Eigenschaften

CompletionGroup	Ruft die BackgroundTransferCompletionGroup ab, die dem BackgroundUploader zugeordnet ist.
CostPolicy	Ruft die Kostenrichtlinie für den Uploadvorgang im Hintergrund ab oder legt sie 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 Upload für den Benutzer fehlgeschlagen ist, und 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 beim Hochladen an den Benutzer hinzuweisen, oder legt diese 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 der Upload gehört, oder legt diesen fest. Ein Uploadvorgang mit einer Gruppen-ID wird nur in Vorgangsenumeration angezeigt, indem GetCurrentDownloadsAsync(String) mit dem spezifischen Gruppenzeichenfolgenwert verwendet wird.
Method	Ruft die http-Methode ab, die für den Upload verwendet wird, oder legt diese fest. Die Standardmethode für Uploadvorgänge ist POST.
ProxyCredential	Ruft die Proxyanmeldeinformationen für den Upload ab oder legt diese fest.
ServerCredential	Ruft die Anmeldeinformationen ab, die für die Authentifizierung beim Ursprungsserver verwendet werden sollen, oder legt diese fest.
SuccessTileNotification	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 Upload für den Benutzer erfolgreich war.
SuccessToastNotification	Ruft die ToastNotification ab, die den Inhalt, die zugeordneten Metadaten und Ereignisse definiert, die in einer Popupbenachrichtigung verwendet werden, um den Erfolg eines Uploads an den Benutzer anzuzeigen, oder legt diesen fest.
TransferGroup	Ruft die Gruppe ab, zu der ein Uploadvorgang gehört, oder legt sie fest.

Methoden

CreateUpload(Uri, IStorageFile)	Initialisiert eine UploadOperation , die den Speicherort für und die Datei für den Upload angibt.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>)	Gibt einen asynchronen Vorgang zurück, der bei Abschluss eine UploadOperation mit dem angegebenen URI und mindestens einem BackgroundTransferContentPart-Objekt zurückgibt.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String)	Gibt einen asynchronen Vorgang zurück, der bei Abschluss eine UploadOperation mit dem angegebenen URI, mindestens einem BackgroundTransferContentPart-Objekt und dem mehrteiligen Untertyp zurückgibt.
CreateUploadAsync(Uri, IIterable<BackgroundTransferContentPart>, String, String)	Gibt einen asynchronen Vorgang zurück, der bei Abschluss eine UploadOperation mit dem angegebenen URI, dem angegebenen mehrteiligen Untertyp, mindestens einem BackgroundTransferContentPart-Objekt und dem Trennzeichengrenzwert zurückgibt, der zum Trennen der einzelnen Teile verwendet wird.
CreateUploadFromStreamAsync(Uri, IInputStream)	Gibt einen asynchronen Vorgang zurück, der nach Abschluss eine UploadOperation mit dem angegebenen URI und dem Quelldatenstrom zurückgibt.
GetCurrentUploadsAsync()	Gibt eine Auflistung von ausstehenden Uploads zurück, die keiner Gruppe zugeordnet sind.
GetCurrentUploadsAsync(String)	Hinweis GetCurrentUploadsAsync(group) ist für Releases nach Windows 8.1 möglicherweise geändert oder nicht verfügbar. Verwenden Sie stattdessen GetCurrentUploadsForTransferGroupAsync. Gibt eine Auflistung von ausstehenden Uploads für eine bestimmte Gruppe zurück.
GetCurrentUploadsForTransferGroupAsync(BackgroundTransferGroup)	Ruft alle Uploads ab, die der bereitgestellten BackgroundTransferGroup zugeordnet sind.
RequestUnconstrainedUploadsAsync(IIterable<UploadOperation>)	Hinweis RequestUnconstrainedUploadsAsync ist für Releases nach Windows 10 Version 1607 möglicherweise geändert oder nicht verfügbar. Verwenden Sie stattdessen CreateUploadAsync. Wird verwendet, um einen uneingeschränkten Uploadvorgang 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

• UploadOperation
• Behandeln von Ausnahmen in Netzwerk-Apps
• So melden Sie sich für Popupbenachrichtigungen an
• Schnellstart: Hochladen einer Datei
• Beispiel für die Hintergrundübertragung
• Beispiel für die Hintergrundübertragung (Windows 8.x)