HintergrundübertragungenBackground transfers

Verwenden Sie die Hintergrundübertragungs-API zum zuverlässigen Kopieren von Dateien im Netzwerk.Use the background transfer API to copy files reliably over the network. Die Hintergrundübertragungs-API bietet erweiterte Upload- und Downloadfeatures, die bei angehaltener App im Hintergrund ausgeführt werden und auch nach Beendigung der App aktiv bleiben.The background transfer API provides advanced upload and download features that run in the background during app suspension and persist beyond app termination. Die API überwacht den Netzwerkstatus und kann Übertragungen automatisch anhalten und fortsetzen, wenn die Verbindung unterbrochen wird. Übertragungen sind außerdem daten- und akkuabhängig – die Downloadaktivität wird also basierend auf dem aktuellen Verbindungs- und Geräteakkustatus angepasst.The API monitors network status and automatically suspends and resumes transfers when connectivity is lost, and transfers are also Data Sense-aware and Battery Sense-aware, meaning that download activity adjusts based on your current connectivity and device battery status. Die API ist ideal für das Hoch- und Herunterladen von großen Dateien über HTTP(S) geeignet.The API is ideal for uploading and downloading large files using HTTP(S). FTP wird auch unterstützt, allerdings nur für Downloads.FTP is also supported, but only for downloads.

Hintergrundübertragungen werden getrennt von der aufrufenden App ausgeführt und wurden hauptsächlich für lange Übertragungen von Ressourcen wie Videos, Musik und großen Bildern entwickelt.Background Transfer runs separately from the calling app and is primarily designed for long-term transfer operations for resources like video, music, and large images. Für diese Szenarien ist die Verwendung der Hintergrundübertragung unverzichtbar, da Downloads im Hintergrund fortgesetzt werden – selbst dann, wenn die App angehalten wurde.For these scenarios, using Background Transfer is essential because downloads continue to progress even when the app is suspended.

Wenn Sie kleine Ressourcen herunterladen, deren Download in der Regel schnell abgeschlossen ist, sollten Sie anstelle der Hintergrundübertragung HttpClient-APIs verwenden.If you are downloading small resources that are likely to complete quickly, you should use HttpClient APIs instead of Background Transfer.

Verwenden von Windows.Networking.BackgroundTransferUsing Windows.Networking.BackgroundTransfer

Wie funktioniert das Feature für die Hintergrundübertragung?How does the Background Transfer feature work?

Wenn eine App die Hintergrundübertragung verwendet, um eine Übertragung zu initiieren, wird die Anforderung mithilfe des Klassenobjekts BackgroundDownloader oder BackgroundUploader konfiguriert und initialisiert.When an app uses Background Transfer to initiate a transfer, the request is configured and initialized using BackgroundDownloader or BackgroundUploader class objects. Alle Übertragungsvorgänge werden vom System einzeln und getrennt von der aufrufenden App behandelt.Each transfer operation is handled individually by the system and separate from the calling app. Statusinformationen sind verfügbar, falls Sie den Benutzer in der Benutzeroberfläche Ihrer App über den Status informieren möchten. Zudem kann Ihre App während der Übertragung angehalten, fortgesetzt und abgebrochen werden oder sogar die Daten lesen.Progress information is available if you want to give status to the user in your app's UI, and your app can pause, resume, cancel, or even read from the data while the transfer is occurring. Die Behandlung von Übertragungen durch das System unterstützt den intelligenten Stromverbrauch und verhindert Probleme, die entstehen können, wenn bei einer verbundenen App Ereignisse wie das Anhalten der App, das Beenden der App oder plötzliche Änderungen des Netzwerkstatus auftreten.The way transfers are handled by the system promotes smart power usage and prevents problems that can arise when a connected app encounters events such as app suspension, termination, or sudden network status changes.

Hinweis

Aufgrund von Ressourcenbeschränkungen pro App sollte eine App nicht mehr als 200 Übertragungen (DownloadOperations + UploadOperations) zu einem bestimmten Zeitpunkt verfügen.Due to per-app resource constraints, an app should not have more than 200 transfers (DownloadOperations + UploadOperations) at any given time. Dieses Limit zu überschreiten kann die App-Übertragungswarteschlange in einen nicht wiederherstellbaren Zustand lassen.Exceeding that limit may leave the app’s transfer queue in an unrecoverable state.

Wenn eine Anwendung gestartet wird, muss sie AttachAsync für alle vorhandenen DownloadOperation- und UploadOperation-Objekte aufrufen.When an application is launched, it must call AttachAsync on all existing DownloadOperation and UploadOperation objects. Dies zu unterlassen führt dazu, dass bereits abgeschlossene Übertragungen verloren gehen, und sorgt dafür, dass Ihre Verwendung der Hintergrundübertragungsfunktion letztendlich nutzlos wird.Not doing this will cause the leak of already-completed transfers and will eventually render your use of the Background Transfer feature useless.

Durchführen authentifizierter Dateianforderungen mit HintergrundübertragungPerforming authenticated file requests with Background Transfer

Das Feature für die Hintergrundübertragung stellt Methoden bereit, die allgemeine Server- und Proxyanmeldeinformationen, Cookies sowie die Verwendung von benutzerdefinierten HTTP-Headern (mithilfe von SetRequestHeader) für einzelne Übertragungen unterstützen.Background Transfer provides methods that support basic server and proxy credentials, cookies, and the use of custom HTTP headers (via SetRequestHeader) for each transfer operation.

Wie reagiert dieses Feature bei Netzwerkstatusänderungen und unerwartetem Herunterfahren?How does this feature adapt to network status changes or unexpected shutdowns?

Das Feature für die Hintergrundübertragung bewahrt die Einheitlichkeit der einzelnen Übertragungen, wenn sich der Netzwerkstatus ändert. Hierzu werden die vom Feature für die Konnektivität bereitgestellten Statusinformationen zur Konnektivität und zum Status des Datentarifs des Netzbetreibers intelligent genutzt.The Background Transfer feature maintains a consistent experience for each transfer operation when network status changes occur, by intelligently leveraging connectivity and carrier data-plan status information provided by the Connectivity feature. Um das Verhalten für unterschiedliche Netzwerkszenarien zu definieren, legt eine App mithilfe der von BackgroundTransferCostPolicy definierten Werte eine Kostenrichtlinie für die einzelnen Übertragungen fest.To define behavior for different network scenarios, an app sets a cost policy for each operation using values defined by BackgroundTransferCostPolicy.

Beispielsweise kann die für einen Vorgang definierte Kostenrichtlinie vorsehen, dass der Vorgang automatisch angehalten wird, wenn das Gerät in einem getakteten Netzwerk verwendet wird.For example, the cost policy defined for an operation can indicate that the operation should be paused automatically when the device is using a metered network. Die Übertragung wird automatisch fortgesetzt (oder erneut gestartet), wenn eine Verbindung mit einem „uneingeschränkten“ Netzwerk hergestellt wird.The transfer is then automatically resumed (or restarted) when a connection to an "unrestricted" network has been established. Weitere Informationen zur Definition von Netzwerken durch Kosten finden Sie unter NetworkCostType.For more information on how networks are defined by cost, see NetworkCostType.

Obwohl das Feature für die Hintergrundübertragung über eigene Mechanismen zur Behandlung von Netzwerkstatusänderungen verfügt, müssen bei mit einem Netzwerk verbundenen Apps einige allgemeine Punkte im Zusammenhang mit der Konnektivität beachtet werden.While the Background Transfer feature has its own mechanisms for handling network status changes, there are other general connectivity considerations for network-connected apps. Weitere Informationen finden Sie unter Zugreifen auf den Netzwerkverbindungsstatus und Verwalten von Netzwerkkosten (HTML).Read Leveraging available network connection information for additional info.

Hinweis  Mithilfe von Features für auf Mobilgeräten ausgeführte Apps kann der Benutzer die übertragene Datenmenge basierend auf dem Verbindungstyp, Roamingstatus und Datentarif überwachen und einschränken.Note  For apps running on mobile devices, there are features that allow the user to monitor and restrict the amount of data that is transferred based on the type of connection, roaming status, and the user's data plan. Aus diesem Grund können Hintergrundübertragungen auf dem Telefon auch dann angehalten werden, wenn die Übertragung gemäß dem BackgroundTransferCostPolicy-Wert fortgesetzt werden sollte.Because of this, background transfers may be paused on the phone even when the BackgroundTransferCostPolicy indicates that the transfer should proceed.

Die folgende Tabelle zeigt für jeden BackgroundTransferCostPolicy-Wert, wann Hintergrundübertragungen basierend auf dem aktuellen Status des Telefons zulässig sind.The following table indicates when background transfers are allowed on the phone for each BackgroundTransferCostPolicy value, given the current state of the phone. Sie können den aktuellen Status des Telefons auch mithilfe der ConnectionCost-Klasse ermitteln.You can use the ConnectionCost class to determine the phone's current state.

GerätestatusDevice State UnrestrictedOnlyUnrestrictedOnly StandardwertDefault ImmerAlways
Mit WLAN verbundenConnected to WiFi AllowAllow AllowAllow AllowAllow
Getaktete Verbindung, kein Roaming, unter dem Datenlimit, Überschreitung des Limits nicht zu erwartenMetered Connection, not roaming, under data limit, on track to stay under limit DenyDeny AllowAllow AllowAllow
Getaktete Verbindung, kein Roaming, unter dem Datenlimit, Überschreitung des Limits zu erwartenMetered Connection, not roaming, under data limit, on track to exceed limit DenyDeny DenyDeny AllowAllow
Getaktete Verbindung, Roaming, unter dem DatenlimitMetered Connection, roaming, under data limit DenyDeny DenyDeny AllowAllow
Getaktete Verbindung, Roaming, über dem Datenlimit.Metered Connection, over data limit. Dieser Status tritt nur auf, wenn der Benutzer in der Data Sense-Benutzeroberfläche die Option „Datennutzung im Hintergrund einschränken“ aktiviert.This state only occurs when the user enables "Restrict background data in the Data Sense UI. DenyDeny DenyDeny DenyDeny

Hochladen von DateienUploading files

Bei der Hintergrundübertragung erfolgt der Upload als UploadOperation. Dabei wird eine Reihe von Steuerungsmethoden zum Neustarten oder Abbrechen des Vorgangs verfügbar gemacht.When using Background Transfer an upload exists as an UploadOperation that exposes a number of control methods that are used to restart or cancel the operation. App-Ereignisse (z. B. Anhalten oder Beenden) und Konnektivitätsänderungen werden vom System automatisch durch UploadOperation behandelt. Uploads werden bei Anhalten oder Unterbrechen einer App und auch nach dem Beenden der App fortgesetzt.App events (for example, suspension or termination) and connectivity changes are handled automatically by the system per UploadOperation; uploads will continue during app suspension periods or pause and persist beyond app termination. Außerdem wird durch Festlegen der CostPolicy-Eigenschaft angegeben, ob die App Uploads startet, wenn für die Internetkonnektivität ein getaktetes Netzwerk verwendet wird.Additionally, setting the CostPolicy property will indicate whether or not your app will start uploads while a metered network is being used for Internet connectivity.

In den folgenden Beispielen werden die Erstellung und Initialisierung eines einfachen Uploads sowie das Aufzählen und Fortsetzen von in einer vorherigen App-Sitzung gespeicherten Vorgängen erläutert.The following examples will walk you through the creation and initialization of a basic upload and how to enumerate and reintroduce operations persisted from a previous app session.

Hochladen einer DateiUploading a single file

Die Erstellung eines Uploads beginnt mit BackgroundUploader.The creation of an upload begins with BackgroundUploader. Mit dieser Klasse werden die Methoden bereitgestellt, womit die App den Upload konfigurieren kann, bevor die resultierende UploadOperation-Instanz erstellt wird.This class is used to provide the methods that enable your app to configure the upload before creating the resultant UploadOperation. Im folgenden Beispiel wird gezeigt, wie dies mit den erforderlichen Uri und StorageFile-Objekten gemacht wird.The following example shows how to do this with the required Uri and StorageFile objects.

Identifizieren der Datei und des Ziels für den UploadIdentify the file and destination for the upload

Vor dem Erstellen einer UploadOperation müssen wir den URI des Speicherorts für den Upload und die hochzuladende Datei bestimmen.Before we can begin with the creation of an UploadOperation, we first need to identify the URI of the location to upload to, and the file that will be uploaded. Im folgenden Beispiel wird der uriString-Wert mit einer Zeichenfolge aus der Benutzeroberflächeneingabe und der file-Wert mit dem StorageFile-Objekt gefüllt, das von einem PickSingleFileAsync-Vorgang zurückgegeben wird.In the following example, the uriString value is populated using a string from UI input, and the file value using the StorageFile object returned by a PickSingleFileAsync operation.

function uploadFile() {
    var filePicker = new Windows.Storage.Pickers.FileOpenPicker();
    filePicker.fileTypeFilter.replaceAll(["*"]);

    filePicker.pickSingleFileAsync().then(function (file) {
        if (!file) {
            printLog("No file selected");
            return;
        }

        var upload = new UploadOp();
        var uriString = document.getElementById("serverAddressField").value;
        upload.start(uriString, file);

        // Store the upload operation in the uploadOps array.
        uploadOperations.push(upload);
    });
}

Erstellen und Initialisieren des UploadvorgangsCreate and initialize the upload operation

Im vorherigen Schritt wurden die Werte uriString und file an eine Instanz von „UploadOp“ aus dem nächsten Beispiel übergeben. Dort werden sie zum Konfigurieren und Starten des neuen Uploadvorgangs verwendet.In the previous step the uriString and file values are passed to an instance of our next example, UploadOp, where they are used to configure and start the new upload operation. Zunächst wird uriString analysiert, um das erforderliche Uri-Objekt zu erstellen.First, uriString is parsed to create the required Uri object.

Dann verwendet BackgroundUploader die Eigenschaften der bereitgestellten StorageFile-Klasse (file) zum Füllen des Anforderungsheaders und Festlegen der SourceFile-Eigenschaft mit dem StorageFile-Objekt.Next, the properties of the provided StorageFile (file) are used by BackgroundUploader to populate the request header and set the SourceFile property with the StorageFile object. Anschließend wird die SetRequestHeader-Methode aufgerufen, um den als Zeichenfolge bereitgestellten Dateinamen und die StorageFile.Name-Eigenschaft einzufügen.The SetRequestHeader method is then called to insert the file name, provided as a string, and the StorageFile.Name property.

Schließlich erstellt BackgroundUploader die UploadOperation-Klasse (upload).Finally, BackgroundUploader creates the UploadOperation (upload).

function UploadOp() {
    var upload = null;
    var promise = null;

    this.start = function (uriString, file) {
        try {
        
            var uri = new Windows.Foundation.Uri(uriString);
            var uploader = new Windows.Networking.BackgroundTransfer.BackgroundUploader();

            // Set a header, so the server can save the file (this is specific to the sample server).
            uploader.setRequestHeader("Filename", file.name);

            // Create a new upload operation.
            upload = uploader.createUpload(uri, file);

            // Start the upload and persist the promise to be able to cancel the upload.
            promise = upload.startAsync().then(complete, error, progress);
        } catch (err) {
            displayError(err);
        }
    };
    // On application activation, reassign callbacks for a upload
    // operation persisted from previous application state.
    this.load = function (loadedUpload) {
        try {
            upload = loadedUpload;
            promise = upload.attachAsync().then(complete, error, progress);
        } catch (err) {
            displayError(err);
        }
    };
}

Beachten Sie die asynchronen Methodenaufrufe, die mit JavaScript-Zusagen definiert sind.Note the asynchronous method calls defined using JavaScript promises. Sehen Sie sich die folgende Zeile aus dem letzten Beispiel an:Looking at a line from the last example:

promise = upload.startAsync().then(complete, error, progress);

Nach dem Async-Methodenaufruf folgt eine then-Anweisung, die von der App definierte Methoden angibt, die aufgerufen werden, wenn ein Ergebnis aus dem Async-Methodenaufruf zurückgegeben wird.The async method call is followed by a then statement which indicates methods, defined by the app, that are called when a result from the async method call is returned. Weitere Informationen zu diesem Programmierungsmuster finden Sie unter Asynchrone Programmierung in JavaScript mit Zusagen.For more information on this programming pattern, see Asynchronous programming in JavaScript using promises.

Hochladen mehrerer DateienUploading multiple files

Identifizieren der Dateien und des Ziels für den UploadIdentify the files and destination for the upload

In einem Szenario, in dem mehrere Dateien mit einer einzelnen UploadOperation übertragen werden, beginnt der Vorgang wie üblich mit der Angabe des erforderlichen Ziel-URI und der lokalen Dateiinformationen.In a scenario involving multiple files transferred with a single UploadOperation, the process begins as it usually does by first providing the required destination URI and local file information. Ähnlich wie in dem Beispiel im vorherigen Abschnitt wird der URI als Zeichenfolge vom Endbenutzer angegeben, und mit FileOpenPicker kann auch das Auswählen von Dateien über die Benutzeroberfläche ermöglicht werden.Similar to the example in the previous section, the URI is provided as a string by the end-user and FileOpenPicker can be used to provide the ability to indicate files through the user interface as well. In diesem Szenario muss die App allerdings stattdessen die PickMultipleFilesAsync-Methode aufrufen, um die Auswahl mehrerer Dateien über die Benutzeroberfläche zu ermöglichen.However, in this scenario the app should instead call the PickMultipleFilesAsync method to enable the selection of multiple files through the UI.

function uploadFiles() {
       var filePicker = new Windows.Storage.Pickers.FileOpenPicker();
       filePicker.fileTypeFilter.replaceAll(["*"]);

       filePicker.pickMultipleFilesAsync().then(function (files) {
          if (files === 0) {
             printLog("No file selected");
                return;
          }

          var upload = new UploadOperation();
          var uriString = document.getElementById("serverAddressField").value;
          upload.startMultipart(uriString, files);

          // Persist the upload operation in the global array.
          uploadOperations.push(upload);
       });
    }

Erstellen von Objekten für die verfügbaren ParameterCreate objects for the provided parameters

In den nächsten beiden Beispielen wird Code in einer Beispielmethode namens startMultipart verwendet, die am Ende des letzten Schritts aufgerufen wurde.The next two examples use code contained in a single example method, startMultipart, which was called at the end of the last step. Für diese Anleitung wurde der Code in der Methode, der ein Array mit BackgroundTransferContentPart-Objekten erstellt, von dem Code getrennt, der die resultierende UploadOperation erstellt.For the purpose of instruction the code in the method that creates an array of BackgroundTransferContentPart objects has been split from the code that creates the resultant UploadOperation.

Zuerst wird die vom Benutzer angegebene URI-Zeichenfolge als Uri initialisiert.First, the URI string provided by the user is initialized as a Uri. Danach wird das Array mit IStorageFile-Objekten (files) durchlaufen, die an diese Methode übergeben wurden, und auf der Grundlage der einzelnen Objekte wird jeweils ein neues BackgroundTransferContentPart-Objekt erstellt und anschließend im contentParts-Array platziert.Next, the array of IStorageFile objects (files) passed to this method is iterated through, each object is used to create a new BackgroundTransferContentPart object which is then placed in the contentParts array.

    upload.startMultipart = function (uriString, files) {
        try {
            var uri = new Windows.Foundation.Uri(uriString);
            var uploader = new Windows.Networking.BackgroundTransfer.BackgroundUploader();

            var contentParts = [];
            files.forEach(function (file, index) {
                var part = new Windows.Networking.BackgroundTransfer.BackgroundTransferContentPart("File" + index, file.name);
                part.setFile(file);
                contentParts.push(part);
            });

Erstellen und Initialisieren des mehrteiligen UploadvorgangsCreate and initialize the multi-part upload operation

Nachdem das contentParts-Array mit allen BackgroundTransferContentPart-Objekten aufgefüllt wurde, die jeweils eine IStorageFile zum Hochladen darstellen, kann CreateUploadAsync mit dem Uri aufgerufen werden, um das Ziel für die Anforderung anzugeben.With our contentParts array populated with all of the BackgroundTransferContentPart objects representing each IStorageFile for upload, we are ready to call CreateUploadAsync using the Uri to indicate where the request will be sent.

        // Create a new upload operation.
            uploader.createUploadAsync(uri, contentParts).then(function (uploadOperation) {

               // Start the upload and persist the promise to be able to cancel the upload.
               upload = uploadOperation;
               promise = uploadOperation.startAsync().then(complete, error, progress);
            });

         } catch (err) {
             displayError(err);
         }
     };

Neustarten von unterbrochenen UploadvorgängenRestarting interrupted upload operations

Bei Abschluss oder Abbruch von UploadOperation werden alle zugeordneten Systemressourcen freigegeben.On completion or cancellation of an UploadOperation, any associated system resources are released. Wenn die App allerdings vor Auftreten eines dieser Ereignisse beendet wird, werden aktive Vorgänge angehalten, und die ihnen zugeordneten Ressourcen bleiben belegt.However, if your app is terminated before either of these things can occur, any active operations are paused and the resources associated with each remain occupied. Wenn diese Vorgänge nicht in der nächsten App-Sitzung aufgezählt und fortgesetzt werden, werden sie nicht abgeschlossen und belegen weiterhin Geräteressourcen.If these operations are not enumerated and re-introduced to the next app session, they will not be completed and will continue to occupy device resources.

  1. Bevor Sie die Funktion zum Aufzählen beibehaltener Vorgänge definieren, müssen wir ein Array erstellen, das die zurückzugebenden UploadOperation-Objekte enthält:Before defining the function that enumerates persisted operations, we need to create an array that will contain the UploadOperation objects that it will return:

    var uploadOperations = [];
    
  2. Im nächsten Schritt definieren Sie die Funktion, die alle beibehaltenen Vorgänge aufzählt und im Array speichert.Next we define the function that enumerates persisted operations and stores them in our array. Die load-Methode, die zum Neuzuweisen der Rückrufe von UploadOperation aufgerufen wird, wenn der Download nach Beendigung der App fortgesetzt wird, befindet sich in der UploadOp-Klasse, die Sie weiter unten in diesem Abschnitt definieren.Note that the load method called to re-assign callbacks to the UploadOperation, should it persist through app termination, is in the UploadOp class we define later in this section.

    function Windows.Networking.BackgroundTransfer.BackgroundUploader.getCurrentUploadsAsync() {
        .then(function (uploads) {
            for (var i = 0; i < uploads.size; i++) {
                var upload = new UploadOp();
                upload.load(uploads[i]);
                uploadOperations.push(upload);
            }
        }
    };
    

Herunterladen von DateienDownloading files

Bei der Hintergrundübertragung erfolgt jeder Download als DownloadOperation. Dabei werden eine Reihe von Steuerungsmethoden zum Anhalten, Fortsetzen, Neustarten und Abbrechen des Vorgangs verfügbar gemacht.When using Background Transfer, each download exists as a DownloadOperation that exposes a number of control methods used to pause, resume, restart, and cancel the operation. App-Ereignisse (z. B. Anhalten oder Beenden) und Konnektivitätsänderungen werden vom System automatisch durch DownloadOperation behandelt. Downloads werden bei Anhalten oder Unterbrechen einer App und auch nach dem Beenden der App fortgesetzt.App events (for example, suspension or termination) and connectivity changes are handled automatically by the system per DownloadOperation; downloads will continue during app suspension periods or pause and persist beyond app termination. In Szenarien für mobile Netzwerke wird außerdem durch Festlegen der CostPolicy-Eigenschaft angegeben, ob die App Downloads startet oder fortsetzt, wenn für die Internetkonnektivität ein getaktetes Netzwerk verwendet wird.For mobile network scenarios, setting the CostPolicy property will indicate whether or not your app will begin or continue downloads while a metered network is being used for Internet connectivity.

Wenn Sie kleine Ressourcen herunterladen, deren Download in der Regel schnell abgeschlossen ist, sollten Sie anstelle der Hintergrundübertragung HttpClient-APIs verwenden.If you are downloading small resources that are likely to complete quickly, you should use HttpClient APIs instead of Background Transfer.

In den folgenden Beispielen werden die Erstellung und Initialisierung eines einfachen Downloads sowie das Aufzählen und Fortsetzen von in einer vorherigen App-Sitzung gespeicherten Vorgängen erläutert.The following examples will walk you through the creation and initialization of a basic download, and how to enumerate and reintroduce operations persisted from a previous app session.

Konfigurieren und Starten eines Dateidownloads mit HintergrundübertragungConfigure and start a Background Transfer file download

Das folgende Beispiel veranschaulicht, wie mit Zeichenfolgen, die einen URI und einen Dateinamen darstellen, ein Uri-Objekt und die StorageFile erstellt werden können, die die angeforderte Datei enthalten.The following example demonstrates how strings representing a URI and a file name can be used to create a Uri object and the StorageFile that will contain the requested file. Im Beispiel wird die neue Datei automatisch an einem vordefinierten Speicherort abgelegt.In this example, the new file is automatically placed in a pre-defined location. Alternativ kann Benutzern mithilfe von FileSavePicker ermöglicht werden, den Speicherort der Datei auf dem Gerät anzugeben.Alternatively, FileSavePicker can be used allow users to indicate where to save the file on the device. Die load-Methode, die zum Neuzuweisen der Rückrufe von DownloadOperation aufgerufen wird, wenn der Download nach Beendigung der App fortgesetzt wird, befindet sich in der „DownloadOp“-Klasse, die Sie weiter unten in diesem Abschnitt definieren.Note that the load method called to re-assign callbacks to the DownloadOperation, should it persist through app termination, is in the DownloadOp class defined later in this section.

function DownloadOp() {
    var download = null;
    var promise = null;
    var imageStream = null;

    this.start = function (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);
        }
    };
    // On application activation, reassign callbacks for a download
    // operation persisted from previous application state.
    this.load = function (loadedDownload) {
        try {
            download = loadedDownload;
            printLog("Found download: " + download.guid + " from previous application run.<br\>");
            promise = download.attachAsync().then(complete, error, progress);
        } catch (err) {
            displayException(err);
        }
    };
}

Beachten Sie die asynchronen Methodenaufrufe, die mit JavaScript-Zusagen definiert sind.Note the asynchronous method calls defined using JavaScript promises. Aus Zeile 17 des vorherigen Codebeispiels geht Folgendes hervor:Looking at line 17 from the previous code example:

promise = download.startAsync().then(complete, error, progress);

Nach dem Async-Methodenaufruf folgt eine then-Anweisung, die von der App definierte Methoden angibt, die aufgerufen werden, wenn ein Ergebnis aus dem Async-Methodenaufruf zurückgegeben wird.The async method call is followed by a then statement which indicates methods, defined by the app, that are called when a result from the async method call is returned. Weitere Informationen zu diesem Programmierungsmuster finden Sie unter Asynchrone Programmierung in JavaScript mit Zusagen.For more information on this programming pattern, see Asynchronous programming in JavaScript using promises.

Hinzufügen weiterer Methoden zur VorgangssteuerungAdding additional operation control methods

Der Grad der Steuerung lässt sich durch Implementieren zusätzlicher DownloadOperation-Methoden erhöhen.The level of control can be increased by implementing additional DownloadOperation methods. Wenn Sie beispielsweise dem obigen Beispiel den folgenden Code hinzufügen, wird das Abbrechen des Downloads ermöglicht.For example, adding the following code to the example above will introduce the ability to cancel the download.

// Cancel download.
this.cancel = function () {
    try {
        if (promise) {
            promise.cancel();
            promise = null;
            printLog("Canceling download: " + download.guid + "<br\>");
            if (imageStream) {
                imageStream.close();
            }
        }
        else {
            printLog("Download " + download.guid + " already canceled.<br\>");
        }
    } catch (err) {
        displayException(err);
    }
};

Aufzählen beibehaltener Vorgänge beim StartEnumerating persisted operations at start-up

Bei Abschluss oder Abbruch von DownloadOperation werden alle zugeordneten Systemressourcen freigegeben.On completion or cancellation of a DownloadOperation, any associated system resources are released. Wenn die App allerdings vor Auftreten eines dieser Ereignisse beendet wird, werden die Downloads angehalten und im Hintergrund beibehalten.However, if your app is terminated before either of these events occur, downloads will pause and persist in the background. In den folgenden Beispielen wird gezeigt, wie Sie beibehaltene Downloads in einer neuen App-Sitzung fortsetzen.The following examples demonstrate how to re-introduce persisted downloads into a new app session.

  1. Bevor Sie die Funktion zum Aufzählen beibehaltener Vorgänge definieren, müssen wir ein Array erstellen, das die zurückzugebenden DownloadOperation-Objekte enthält:Before defining the function that enumerates persisted operations, we need to create an array that will contain the DownloadOperation objects that it will return:

    var downloadOps = [];
    
  2. Im nächsten Schritt definieren Sie die Funktion, die alle beibehaltenen Vorgänge aufzählt und im Array speichert.Next we define the function that enumerates persisted operations and stores them in our array. Die load-Methode, die zum Neuzuweisen von Rückrufen für eine beibehaltene DownloadOperation aufgerufen wird, befindet sich im Beispiel für die DownloadOp-Klasse, die weiter unten in diesem Abschnitt definiert wird.Note that the load method called to re-assign callbacks for a persisted DownloadOperation is in the DownloadOp example we define later in this section.

    // Enumerate outstanding downloads.
    Windows.Networking.BackgroundTransfer.BackgroundDownloader.getCurrentDownloadsAsync().done(function (downloads) {
    
        for (var i = 0; i < downloads.size; i++) {
            var download = new DownloadOp();
            download.load(downloads[i]);
            downloadOps.push(download);
        }
    });
    
  3. Die mit Daten aufgefüllte Liste kann nun zum Neustarten ausstehender Vorgänge verwendet werden.You can now use the populated list to restart pending operations.

NachverarbeitungPost-processing

Ein neues Feature in Windows 10 ermöglicht es nach Abschluss einer Hintergrundübertragung, den Anwendungscode auszuführen, selbst wenn die App nicht ausgeführt wird.A new feature in Windows 10 is the ability to run application code at the completion of a background transfer even when the app is not running. Ihre App möchte z. B. eine Liste der verfügbaren Filme aktualisieren, nachdem ein Film heruntergeladen wurde, statt bei jedem Start nach neuen Filmen zu suchen.For example, your app might want to update a list of available movies after a movie has finished downloading, rather than have your app scan for new movies every time it starts. Ihre App möchte ggf. eine fehlerhafte Dateiübertragung behandeln, indem diese unter Verwendung eines anderes Servers oder Ports wiederholt wird.Or your app might want to handle a failed file transfer by trying again using a different server or port. Nachbearbeitung wird für erfolgreiche und nicht erfolgreiche Übertragungen aufgerufen, damit Sie sie zum Implementieren benutzerdefinierter Fehlerbehandlung und Wiederholungslogik verwenden können.Post-processing is invoked for both successful and failed transfers, so you can use it to implement custom error-handling and retry logic.

Nachbearbeitung verwendet die vorhandene Hintergrundaufgaben-Infrastruktur.Postprocessing uses the existing background task infrastructure. Erstellen Sie eine Hintergrundaufgabe, und ordnen Sie sie Ihren Übertragungen zu, bevor Sie die Übertragung starten.You create a background task and associate it with your transfers before you start the transfers. Die Übertragungen werden dann im Hintergrund ausgeführt, und wenn sie abgeschlossen sind, wird die Hintergrundaufgabe aufgerufen, um die Nachbearbeitung auszuführen.The transfers are then executed in the background, and when they are complete, your background task is called to perform post-processing.

Für die Nachbearbeitung wird als neue Klasse BackgroundTransferCompletionGroup verwendet.Post-processing uses a new class, BackgroundTransferCompletionGroup. Diese Klasse ist mit der vorhandenen BackgroundTransferGroup-Klasse vergleichbar, mit der Sie Hintergrundübertragungen gruppieren können. Die BackgroundTransferCompletionGroup-Klasse ermöglicht es jedoch zudem, eine Hintergrundaufgabe anzugeben, die nach Abschluss der Übertragung ausgeführt werden soll.This class is similar to the existing BackgroundTransferGroup in that it allows you to group background transfers together, but BackgroundTransferCompletionGroup adds the ability to designate a background task to be run when the transfer is complete.

Initiieren Sie wie folgt eine Hintergrundübertragung mit Nachbearbeitung.You initiate a background transfer with post-processing as follows.

  1. Erstellen Sie ein BackgroundTransferCompletionGroup-Objekt.Create a BackgroundTransferCompletionGroup object. Erstellen Sie dann ein BackgroundTaskBuilder-Objekt.Then, create a BackgroundTaskBuilder object. Legen Sie die Trigger-Eigenschaft des Generator-Objekts auf das Abschlussgruppenobjekt und die TaskEntryPoint-Eigenschaft des Generators auf den Einstiegspunkt der Hintergrundaufgabe fest, die nach Abschluss der Übertragung ausgeführt werden soll.Set the Trigger property of the builder object to the completion group object, and the TaskEntryPoint property of the builder to the entry point of the background task that should execute on transfer completion. Rufen Sie schließlich die BackgroundTaskBuilder.Register-Methode auf, um die Hintergrundaufgabe zu registrieren.Finally, call the BackgroundTaskBuilder.Register method to register your background task. Beachten Sie, dass viele Abschlussgruppen einen Einstiegspunkt für die Hintergrundaufgabe gemeinsam verwenden können, Sie jedoch nur über eine Abschlussgruppe pro Registrierung einer Hintergrundaufgabe verfügen dürfen.Note that many completion groups can share one background task entry point, but you can have only one completion group per background task registration.
var completionGroup = new BackgroundTransferCompletionGroup();
BackgroundTaskBuilder builder = new BackgroundTaskBuilder();

builder.Name = "MyDownloadProcessingTask";
builder.SetTrigger(completionGroup.Trigger);
builder.TaskEntryPoint = "Tasks.BackgroundDownloadProcessingTask";

BackgroundTaskRegistration downloadProcessingTask = builder.Register();
  1. Ordnen Sie als Nächstes die Hintergrundübertragungen mit der Abschlussgruppe zu.Next you associate background transfers with the completion group. Aktivieren Sie nach Erstellen aller Übertragungen die Abschlussgruppe.Once all transfers are created, enable the completion group.
BackgroundDownloader downloader = new BackgroundDownloader(completionGroup);
DownloadOperation download = downloader.CreateDownload(uri, file);
Task<DownloadOperation> startTask = download.StartAsync().AsTask();

// App still sees the normal completion path
startTask.ContinueWith(ForegroundCompletionHandler);

// Do not enable the CompletionGroup until after all downloads are created.
downloader.CompletinGroup.Enable();
  1. Der Code in der Hintergrundaufgabe extrahiert die Liste der Vorgänge anhand der Triggerdetails und kann dann die Details für jeden Vorgang überprüfen und die entsprechende Nachbearbeitung für jeden Vorgang ausführen.The code in the background task extracts the list of operations from the trigger details, and your code can then inspect the details for each operation and perform appropriate post-processing for each operation.
public class BackgroundDownloadProcessingTask : IBackgroundTask
{
    public async void Run(IBackgroundTaskInstance taskInstance)
    {
    var details = (BackgroundTransferCompletionGroupTriggerDetails)taskInstance.TriggerDetails;
    IReadOnlyList<DownloadOperation> downloads = details.Downloads;

    // Do post-processing on each finished operation in the list of downloads
    }
}

Die Nachbearbeitungsaufgabe stellt eine reguläre Hintergrundaufgabe dar.The post-processing task is a regular background task. Sie ist Teil des Pools aller Hintergrundaufgaben und unterliegt auch derselben Ressourcenverwaltungsrichtlinie wie alle anderen Hintergrundaufgaben.It is part of the pool of all background tasks, and it is subject to the same resource management policy as all background tasks.

Beachten Sie, dass die Nachbearbeitung nicht die Vordergrund-Abschlusshandler ersetzt.Also, note that post-processing does not replace foreground completion handlers. Wenn Ihre App einen Vordergrund-Abschlusshandler definiert und nach Abschluss der Dateiübertragung App ausgeführt wird, werden der Vordergrund- und Hintergrund-Abschlusshandler aufgerufen.If your app defines a foreground completion handler, and your app is running when the file transfer completes, then both your foreground completion handler and your background completion handler will be called. Die Reihenfolge, in der die Vordergrund- und Hintergrundaufgaben aufgerufen werden, kann nicht garantiert werden.The order in which foreground and background tasks are called is not guaranteed. Wenn Sie beide Handler definieren, sollten Sie sicherstellen, dass die zwei Aufgaben ordnungsgemäß ausgeführt werden und keine Konflikte aufweisen, wenn sie gleichzeitig ausgeführt werden.If you define both, you should ensure that the two tasks will work properly and not interfere with each other if they are running concurrently.

Zeitüberschreitungen bei AnforderungenRequest timeouts

Es müssen zwei primäre Szenarien zu Verbindungszeitüberschreitungen berücksichtigt werden:There are two primary connection timeout scenarios to take into consideration:

  • Beim Herstellen einer neuen Verbindung für die Übertragung wird die Verbindungsanforderung abgebrochen, wenn die Verbindung nicht innerhalb von fünf Minuten hergestellt wird.When establishing a new connection for a transfer, the connection request is aborted if it is not established within five minutes.

  • Nach dem Herstellen einer Verbindung wird eine HTTP-Anforderungsnachricht abgebrochen, auf die nicht innerhalb von zwei Minuten reagiert wurde.After a connection has been established, an HTTP request message that has not received a response within two minutes is aborted.

Hinweis  Vorausgesetzt, dass eine Internetverbindung besteht, wiederholt die Hintergrundübertragung in beiden Szenarien eine Anforderung automatisch bis zu drei Mal.Note  In either scenario, assuming there is Internet connectivity, Background Transfer will retry a request up to three times automatically. Wenn keine Internetkonnektivität erkannt wird, warten zusätzliche Anforderungen, bis Konnektivität vorhanden ist.In the event Internet connectivity is not detected, additional requests will wait until it is.

Debugging-LeitfadenDebugging guidance

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.Stopping a debugging session in Microsoft Visual Studio is comparable to closing your app; PUT uploads are paused and POST uploads are terminated. Auch beim Debuggen sollte die App alle beibehaltenen Uploads auflisten und dann neu starten oder abbrechen.Even while debugging, your app should enumerate and then restart or cancel any persisted uploads. 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.For example, you can have your app cancel enumerated persisted upload operations at app startup if there is no interest in previous operations for that debug session.

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.While enumerating downloads/uploads on app startup during a debug session, you can have your app cancel them if there is no interest in previous operations for that debug session. Beachten Sie, dass GetCurrentUploadsAsync Vorgänge nicht auflisten kann, die mithilfe der vorherigen App-Bereitstellung erstellt werden, wenn Visual Studio-Projektupdates, beispielsweise Änderungen am App-Manifest, vorhanden sind und die App deinstalliert und erneut bereitgestellt wird.Note that if there are Visual Studio project updates, like changes to the app manifest, and the app is uninstalled and re-deployed, GetCurrentUploadsAsync cannot enumerate operations created using the previous app deployment.

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.When using Background Transfer during development, you may get into a situation where the internal caches of active and completed transfer operations can get out of sync. This may result in the inability to start new transfer operations or interact with existing operations and BackgroundTransferGroup objects. In einigen Fällen wird durch den Versuch einer Interaktion mit vorhandenen Vorgängen ein Absturz ausgelöst.In some cases, attempting to interact with existing operations may trigger a crash. Dies kann vorkommen, wenn die TransferBehavior-Eigenschaft auf Parallel festgelegt ist.This result can occur if the TransferBehavior property is set to Parallel. Dieses Problem tritt nur bei bestimmten Szenarien während der Entwicklung auf und betrifft nicht die Endbenutzer Ihrer App.This issue occurs only in certain scenarios during development and is not applicable to end users of your app.

Vier Szenarien mit Visual Studio können dieses Problem auslösen.Four scenarios using Visual Studio can cause this issue.

  • Sie erstellen ein neues Projekt mit demselben App-Namen wie ein vorhandenes Projekt, jedoch einer anderen Sprache (z. B. C# statt C++).You create a new project with the same app name as an existing project, but a different language (from C++ to C#, for example).
  • Sie ändern die Zielarchitektur (z. B. von x86 zu x64) in einem vorhandenen Projekt.You change the target architecture (from x86 to x64, for example) in an existing project.
  • Sie ändern die Kultur (z. B. von neutral zu en-US) in einem vorhandenen Projekt.You change the culture (from neutral to en-US, for example) in an existing project.
  • Sie fügen in einem vorhandenen Projekt eine Funktion im Paketmanifest (z. B. Unternehmensauthentifizierung) hinzu oder entfernen eine.You add or remove a capability in the package manifest (adding Enterprise Authentication, for example) in an existing project.

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.Regular app servicing, including manifest updates which add or remove capabilities, do not trigger this issue on end user deployments of your app. 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.To work around this issue, completely uninstall all versions of the app and re-deploy with the new language, architecture, culture, or capability. Dies ist auf der Startseite oder mithilfe von PowerShell und dem Remove-AppxPackage-Cmdlet möglich.This can be done via the Start screen or using PowerShell and the Remove-AppxPackage cmdlet.

Ausnahmen in Windows.Networking.BackgroundTransferExceptions in Windows.Networking.BackgroundTransfer

Eine Ausnahme wird ausgelöst, wenn eine ungültige Zeichenfolge für einen Uniform Resource Identifier (URI) an den Konstruktor für das Windows.Foundation.Uri-Objekt übergeben wird.An exception is thrown when an invalid string for a the Uniform Resource Identifier (URI) is passed to the constructor for the Windows.Foundation.Uri object.

.NET: Der Windows.Foundation.Uri-Typ wird in C# und VB als System.Uri angezeigt..NET: The Windows.Foundation.Uri type appears as System.Uri in C# and VB.

In C# und Visual Basic kann dieser Fehler vermieden werden, indem die System.Uri-Klasse in .NET 4.5 und eine der System.Uri.TryCreate-Methoden zum Testen der vom App-Benutzer erhaltenen Zeichenfolge verwendet wird, bevor der URI erstellt wird.In C# and Visual Basic, this error can be avoided by using the System.Uri class in the .NET 4.5 and one of the System.Uri.TryCreate methods to test the string received from the app user before the URI is constructed.

In C++ gibt es keine Methode zum Analysieren einer Zeichenfolge für einen URI.In C++, there is no method to try and parse a string to a URI. Wenn eine App vom Benutzer eine Eingabe für das Windows.Foundation.Uri-Element erhält, sollte sich der Konstruktor innerhalb eines try/catch-Blocks befinden.If an app gets input from the user for the Windows.Foundation.Uri, the constructor should be in a try/catch block. Wenn eine Ausnahme ausgelöst wird, kann die App den Benutzer benachrichtigen und einen neuen Hostnamen anfordern.If an exception is thrown, the app can notify the user and request a new hostname.

Der Windows.Networking.backgroundTransfer-Namespace enthält praktische Hilfsmethoden und verwendet im Windows.Networking.Sockets-Namespace Enumerationen zum Behandeln von Fehlern.The Windows.Networking.backgroundTransfer namespace has convenient helper methods and uses enumerations in the Windows.Networking.Sockets namespace for handling errors. Mit ihnen lassen sich spezifische Netzwerkausnahmen in der App unterschiedlich behandeln.This can be useful for handling specific network exceptions differently in your app.

Ein Fehler in einer asynchronen Methode im Windows.Networking.backgroundTransfer-Namespace wird als ein HRESULT-Wert zurückgegeben.An error encountered on an asynchronous method in the Windows.Networking.backgroundTransfer namespace is returned as an HRESULT value. Mit der BackgroundTransferError.GetStatus-Methode wird ein Netzwerkfehler aus einem Hintergrundübertragungsvorgang in einen WebErrorStatus-Enumerationswert konvertiert.The BackgroundTransferError.GetStatus method is used to convert a network error from a background transfer operation to a WebErrorStatus enumeration value. Die meisten WebErrorStatus-Enumerationswerte entsprechen einem vom systemeigenen HTTP- oder FTP-Clientvorgang zurückgegebenen Fehler.Most of the WebErrorStatus enumeration values correspond to an error returned by the native HTTP or FTP client operation. Eine App kann nach bestimmten WebErrorStatus-Enumerationswerten filtern, um das App-Verhalten je nach Ausnahmeursache zu ändern.An app can filter on specific WebErrorStatus enumeration values to modify app behavior depending on the cause of the exception.

Bei Parameterprüfungsfehlern kann eine App den HRESULT-Wert aus der Ausnahme auch verwenden, um ausführlichere Informationen zum zugehörigen Fehler zu erhalten.For parameter validation errors, an app can also use the HRESULT from the exception to learn more detailed information on the error that caused the exception. Mögliche HRESULT-Werte sind in der Headerdatei Winerror.h aufgeführt.Possible HRESULT values are listed in the Winerror.h header file. Für die meisten Parameterüberprüfungsfehler wird der HRESULT-Wert E_INVALIDARG zurückgegeben.For most parameter validation errors, the HRESULT returned is E_INVALIDARG.

Wichtige APIsImportant APIs