BackgroundUploader Klasse

Definition

public ref class BackgroundUploader sealed

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

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

[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

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.

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.

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.

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

Eigenschaften

Methoden

Gilt für:

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)