Arka plan aktarımları

Dosyaları ağ üzerinden güvenilir bir şekilde kopyalamak için arka plan aktarım API'sini kullanın. Arka plan aktarımı API'si, uygulamanın askıya alınması sırasında arka planda çalışan ve uygulama sonlandırmanın ötesinde kalıcı olan gelişmiş karşıya yükleme ve indirme özellikleri sağlar. API, ağ durumunu izler ve bağlantı kaybolduğunda aktarımları otomatik olarak askıya alır ve bağlantı geri geldiğinde otomatik olarak sürdürür. Ayrıca, aktarımlar Veri Sensörüne ve Pil Sensörüne duyarlıdır; bu da indirme etkinliğinin mevcut bağlantınıza ve cihaz pil durumunuza göre ayarlandığı anlamına gelir. API, HTTP(S) kullanarak büyük dosyaları karşıya yüklemek ve indirmek için idealdir. FTP de desteklenir, ancak yalnızca indirmeler için desteklenir.

Note

API'lerWindows.Networking.BackgroundTransfer, WinUI 3 (Windows Uygulama SDK'sı) masaüstü uygulamalarında ve UWP uygulamalarında çalışan Windows Çalışma Zamanı (WinRT) API'lerdir. Arka plan aktarımları için paket kimliği gerekir; paketlenmemiş uygulamalar bu API'i kullanamaz.

Arka Plan Aktarımı, çağrı uygulamasından ayrı olarak çalışır ve öncelikle video, müzik ve büyük görüntüler gibi kaynaklar için uzun vadeli aktarım işlemleri için tasarlanmıştır. Bu senaryolarda, uygulama askıya alınsa bile indirmeler ilerlemeye devam ettiğinden Arka Plan Aktarımı'nın kullanılması önemlidir.

Hızlı bir şekilde tamamlanma olasılığı olan küçük kaynakları indiriyorsanız, Arka Plan Aktarımı yerine HttpClient API'lerini kullanmanız gerekir.

Windows.Networking.BackgroundTransfer kullanma

Arka Plan Aktarımı özelliği nasıl çalışır?

Bir uygulama aktarım başlatmak için Arka Plan Aktarımı'nı kullandığında, istek BackgroundDownloader veya BackgroundUploader sınıf nesneleri kullanılarak yapılandırılır ve başlatılır. Her aktarım işlemi sistem tarafından tek tek işlenir ve çağrı uygulamasından ayrı olarak gerçekleştirilir. Uygulamanızın kullanıcı arabiriminde kullanıcıya durum vermek istiyorsanız ilerleme durumu bilgileri sağlanır ve aktarım gerçekleşirken uygulamanız verileri duraklatabilir, sürdürebilir, iptal edebilir, hatta okuyabilir. Aktarımların sistem tarafından işlenme şekli akıllı güç kullanımını teşvik eder ve bağlı bir uygulama uygulama askıya alma, sonlandırma veya ani ağ durumu değişiklikleri gibi olaylarla karşılaştığında ortaya çıkabilecek sorunları önler.

Note

Uygulama başına kaynak kısıtlamaları nedeniyle, bir uygulamada herhangi bir zamanda 200'den fazla aktarım (DownloadOperations + UploadOperations) olmamalıdır. Bu sınırın aşılması, uygulamanın aktarım kuyruğunun kurtarılamaz durumda bırakılmasına neden olabilir.

Bir uygulama başlatıldığında, mevcut tüm DownloadOperation ve UploadOperation nesnelerinde AttachAsync'içağırması gerekir. Bunu yapmamak, zaten tamamlanmış aktarımların sızmasına neden olur ve sonunda Arka Plan Aktarımı özelliğini kullanımınızı gereksiz hale getirir.

Arka Plan Aktarımı ile kimliği doğrulanmış dosya istekleri gerçekleştirme

Arka Plan Aktarımı, her aktarım işlemi için temel sunucu ve proxy kimlik bilgilerini, tanımlama bilgilerini ve özel HTTP üst bilgilerinin kullanımını ( SetRequestHeader aracılığıyla) destekleyen yöntemler sağlar.

Bu özellik ağ durumu değişikliklerine veya beklenmeyen kapatmalara nasıl uyum sağlar?

Arka Plan Aktarımı özelliği, Bağlantı özelliği tarafından sağlanan bağlantı ve operatör veri planı durum bilgilerinden akıllı bir şekilde yararlanarak ağ durumu değişiklikleri gerçekleştiğinde her aktarım işlemi için tutarlı bir deneyim sağlar. Farklı ağ senaryolarında davranışı tanımlamak için, bir uygulama BackgroundTransferCostPolicy tarafından tanımlanan değerleri kullanarak her işlem için bir maliyet ilkesi ayarlar.

Örneğin, bir işlem için tanımlanan maliyet ilkesi, cihaz tarifeli ağ kullanırken işlemin otomatik olarak duraklatılması gerektiğini gösterebilir. "Kısıtlanmamış" bir ağa bağlantı kurulduğunda aktarım otomatik olarak sürdürülür (veya yeniden başlatılır). Ağların maliyete göre nasıl tanımlandığı hakkında daha fazla bilgi için bkz. NetworkCostType.

Arka Plan Aktarımı özelliğinin ağ durumu değişikliklerini işlemeye yönelik kendi mekanizmaları olsa da, ağa bağlı uygulamalar için diğer genel bağlantı konuları vardır. Bağlantı durumunu ve maliyet bilgilerini izlemek için Windows.Networking.Connectivity API’lerini kullanın.

Note

Mobil cihazlarda çalışan uygulamalar için, kullanıcının bağlantı türüne, dolaşım durumuna ve kullanıcının veri planına göre aktarılan veri miktarını izlemesine ve kısıtlamasına olanak sağlayan özellikler vardır. Bu nedenle BackgroundTransferCostPolicy aktarımın devam etmesi gerektiğini belirtse bile arka plan aktarımları telefonda duraklatılabilir.

Aşağıdaki tablo, telefonun geçerli durumu göz önünde bulundurulduğunda her BackgroundTransferCostPolicy değeri için telefonda arka plan aktarımlarına ne zaman izin verildiğini gösterir. Telefonun geçerli durumunu belirlemek için ConnectionCost sınıfını kullanabilirsiniz.

Cihaz Durumu	Yalnızca Kısıtlamasız	Varsayılan	Her zaman
WiFi'a bağlı	Allow	Allow	Allow
Ölçülü bağlantı, dolaşımda değil, veri sınırının altında, sınırın altında kalma yolunda	Deny	Allow	Allow
Ölçülü bağlantı, dolaşımda değil, veri sınırının altında, sınırı aşma yolunda	Deny	Deny	Allow
Tarifeli Bağlantı, dolaşım, veri sınırı altında	Deny	Deny	Allow
Ölçülü bağlantı, veri sınırı aşıldı. Bu durum yalnızca kullanıcı Data Sense kullanıcı arabiriminde "Arka plan verilerini kısıtla" seçeneğini etkinleştirdiğinde oluşur.	Deny	Deny	Deny

Dosya yükleme

Arka Plan Aktarımı kullanılırken, bir karşıya yükleme, işlemi yeniden başlatmak veya iptal etmek için kullanılan çeşitli denetim yöntemleri sunan bir UploadOperation olarak mevcut olur. Uygulama olayları (örneğin askıya alma veya sonlandırma) ve bağlantı değişiklikleri, her bir UploadOperation için sistem tarafından otomatik olarak işlenir; yüklemeler uygulama askıdayken devam eder veya duraklatılıp uygulama sonlandırıldıktan sonra da korunur. Ayrıca CostPolicy özelliğinin ayarlanması, İnternet bağlantısı için tarifeli ağ kullanılırken uygulamanızın karşıya yüklemeleri başlatıp başlatmayacağını gösterir.

Aşağıdaki örnekler, temel bir yüklemenin nasıl oluşturulup başlatılacağını ve önceki bir uygulama oturumundan kalan işlemlerin nasıl listelenip yeniden işleme alınacağını adım adım gösterir.

Tek bir dosya yükleme

Karşıya yükleme oluşturma işlemi BackgroundUploader ile başlar. Bu sınıf, uygulamanızın uploadOperation sonucunu oluşturmadan önce karşıya yüklemeyi yapılandırmasına olanak tanıyan yöntemleri sağlamak için kullanılır. Aşağıdaki örnek, gerekli Uri ve StorageFile nesneleriyle bunun nasıl yapılacağını gösterir.

Karşıya yükleme için dosyayı ve hedefi belirleme

UploadOperation oluşturmaya başlamadan önce karşıya yüklenecek konumun URI'sini ve karşıya yüklenecek dosyayı tanımlamamız gerekir. Aşağıdaki örnekte, uriString değeri kullanıcı arabirimi girişinden alınan bir dize kullanılarak, file değeri ise PickSingleFileAsync işlemi tarafından döndürülen StorageFile nesnesi kullanılarak doldurulur.

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);
    });
}

Karşıya yükleme işlemini oluşturma ve başlatma

Önceki adımda uriString ve dosya değerleri, yeni karşıya yükleme işlemini yapılandırmak ve başlatmak için kullanılan bir sonraki örneğimiz olan UploadOp örneğine geçirilir. İlk olarak, gerekli Uri nesnesini oluşturmak için uriString ayrıştırılır.

Ardından, sağlanan StorageFile (dosya) özellikleri BackgroundUploader tarafından istek üst bilgisini doldurmak ve SourceFile özelliğini StorageFile nesnesiyle ayarlamak için kullanılır. SetRequestHeader yöntemi daha sonra dize olarak sağlanan dosya adını ve StorageFile.Name özelliğini eklemek için çağrılır.

Son olarak BackgroundUploader, UploadOperation'ı (yükleme) oluşturur.

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);
        }
    };
}

JavaScript promises kullanılarak tanımlanan zaman uyumsuz yöntem çağrılarına dikkat edin. Son örnekten bir satıra bakıyoruz:

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

Zaman uyumsuz yöntem çağrısının ardından then , zaman uyumsuz yöntem çağrısından bir sonuç döndürülürken çağrılan, uygulama tarafından tanımlanan yöntemleri gösteren bir deyim bulunur. Bu programlama düzeni hakkında daha fazla bilgi için bkz. Promises kullanarak JavaScript'te zaman uyumsuz programlama.

Birden çok dosyayı karşıya yükleme

Karşıya yükleme için dosyaları ve hedefi belirleme

Tek bir UploadOperation ile aktarılan birden çok dosya içeren bir senaryoda, işlem genellikle gerekli hedef URI'yi ve yerel dosya bilgilerini sağlayarak başlar. Önceki bölümdeki örneğe benzer şekilde, URI son kullanıcı tarafından bir dize olarak sağlanır ve FileOpenPicker , kullanıcı arabirimi aracılığıyla dosyaları gösterme olanağı sağlamak için de kullanılabilir. Ancak bu senaryoda uygulamanın kullanıcı arabirimi aracılığıyla birden çok dosya seçimini etkinleştirmek için PickMultipleFilesAsync yöntemini çağırması gerekir.

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);
       });
    }

Sağlanan parametreler için nesneler oluşturma

Sonraki iki örnekte, son adımın sonunda çağrılan startMultipart adlı tek bir örnek yönteminde yer alan kod kullanılır. Açıklama amacıyla, bir BackgroundTransferContentPart nesneleri dizisi oluşturan yöntemdeki kod, sonuçta elde edilen UploadOperation nesnesini oluşturan koddan ayrılmıştır.

İlk olarak, kullanıcı tarafından sağlanan URI dizesi Uri olarak başlatılır. Ardından, bu yönteme geçirilen IStorageFile nesneleri (dosyalar) dizisi yinelenir, her nesne contentParts dizisine yerleştirilen yeni bir BackgroundTransferContentPart nesnesi oluşturmak için kullanılır.

    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);
            });

Çok parçalı karşıya yükleme işlemini oluşturun ve başlatın

Yükleme için her bir IStorageFile öğesini temsil eden tüm BackgroundTransferContentPart nesneleriyle contentParts dizimiz doldurulduğunda, isteğin nereye gönderileceğini belirtmek için Uri kullanarak CreateUploadAsync çağrısını yapmaya hazırız.

        // 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);
         }
     };

Kesintiye uğrayan yükleme işlemlerini yeniden başlatma

UploadOperation tamamlandıktan veya iptal edildikten sonra ilişkili tüm sistem kaynakları serbest bırakılır. Ancak, uygulamanız bu işlemlerden biri gerçekleşmeden önce sonlandırılırsa tüm etkin işlemler duraklatılır ve her biriyle ilişkili kaynaklar dolu kalır. Bu işlemler numaralandırılmaz ve sonraki uygulama oturumuna yeniden tanıtılmazsa tamamlanmaz ve cihaz kaynaklarını işgal etmeye devam eder.

Kalıcı işlemleri numaralandıran işlevi tanımlamadan önce, döndüreceği UploadOperation nesnelerini içerecek bir dizi oluşturmamız gerekir:
```
var uploadOperations = [];
```
Ardından kalıcı işlemleri numaralandıran ve bunları dizimizde depolayan işlevi tanımlayacağız. UploadOperation'a geri çağırmaları yeniden atamak için çağrılan yükleme yönteminin, uygulama sonlandırması yoluyla kalıcı olması durumunda, bu bölümün devamında tanımladığımız UploadOp sınıfında olduğunu unutmayın.
```
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);
        }
    }
};
```

Dosyaları indirme

Arka Plan Aktarımı kullanılırken, her indirme işlemi duraklatmak, sürdürmek, yeniden başlatmak ve iptal etmek için kullanılan bir dizi denetim yöntemini kullanıma sunan bir DownloadOperation olarak bulunur. Uygulama olayları (örneğin, askıya alma veya sonlandırma) ve bağlantı değişiklikleri DownloadOperation başına sistem tarafından otomatik olarak işlenir; indirme işlemleri, uygulama askıya alma dönemlerinde devam eder veya uygulama sonlandırmanın ötesinde duraklatılır ve kalıcı hale getirir. Mobil ağ senaryolarında CostPolicy özelliğinin ayarlanması, İnternet bağlantısı için tarifeli ağ kullanılırken uygulamanızın indirmelerin başlatılıp başlamayacağını veya devam edip etmeyeceğini gösterir.

Hızlı bir şekilde tamamlanma olasılığı olan küçük kaynakları indiriyorsanız, Arka Plan Aktarımı yerine HttpClient API'lerini kullanmanız gerekir.

Aşağıdaki örneklerde, temel bir indirmenin oluşturulması ve başlatılması ve önceki bir uygulama oturumunda kalıcı olan işlemlerin nasıl numaralandırılacağı ve yeniden başlatılacağı anlatılacaktır.

Arka Plan Aktarımı dosyası indirmeyi yapılandırma ve başlatma

Aşağıdaki örnekte, URI'yi ve dosya adını temsil eden dizelerin, istenen dosyayı içerecek bir Uri nesnesi ve StorageFile oluşturmak için nasıl kullanılabileceğini gösterir. Bu örnekte, yeni dosya otomatik olarak önceden tanımlanmış bir konuma yerleştirilir. Alternatif olarak, FileSavePicker kullanıcıların dosyanın cihaza kaydedileceği yeri belirtmesine izin vermek için kullanılabilir. Uygulama sonlandırıldıktan sonra da sürmesi durumunda geri çağrıları DownloadOperation öğesine yeniden atamak için çağrılan load yönteminin, bu bölümün ilerleyen kısımlarında tanımlanan DownloadOp sınıfında bulunduğunu unutmayın.

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);
        }
    };
}

JavaScript promises kullanılarak tanımlanan zaman uyumsuz yöntem çağrılarına dikkat edin. Önceki kod örneğinden 17. satıra bakıyoruz:

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

Asenkron yöntem çağrısını, asenkron yöntem çağrısından bir sonuç döndürüldüğünde uygulama tarafından tanımlanan hangi yöntemlerin çağrılacağını belirten bir then ifadesi izler. Bu programlama düzeni hakkında daha fazla bilgi için bkz. Promises kullanarak JavaScript'te zaman uyumsuz programlama.

Ek işlem denetimi yöntemleri ekleme

Ek DownloadOperation yöntemleri uygulanarak denetim düzeyi artırılabilir. Örneğin, yukarıdaki örne aşağıdaki kodu eklemek indirmeyi iptal etme özelliğini tanıtır.

// 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);
    }
};

Başlatma sırasında kalıcı işlemleri numaralandırma

DownloadOperation tamamlandığında veya iptal edildiyse, ilişkili tüm sistem kaynakları serbest bırakılır. Ancak, uygulamanız bu olaylardan biri gerçekleşmeden önce sonlandırılırsa indirmeler duraklatılır ve arka planda kalır. Aşağıdaki örneklerde kalıcı indirmelerin yeni bir uygulama oturumunda nasıl yeniden tanıtılması gösterilmektedir.

Kalıcı işlemleri numaralandıran işlevi tanımlamadan önce, döndüreceği DownloadOperation nesnelerini içerecek bir dizi oluşturmamız gerekir:
```
var downloadOps = [];
```

Ardından kalıcı işlemleri numaralandıran ve bunları dizimizde depolayan işlevi tanımlayacağız. Kalıcı bir DownloadOperation için geri çağırmaları yeniden atamak için çağrılan yükleme yönteminin, bu bölümün devamında tanımladığımız DownloadOp örneğinde olduğunu unutmayın.

// 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);
    }
});

Artık bekleyen işlemleri yeniden başlatmak için doldurulmuş listeyi kullanabilirsiniz.

İşlem sonrası

Windows 10'daki yeni bir özellik, uygulama çalışmadığında bile arka plan aktarımı tamamlandığında uygulama kodunu çalıştırabilme özelliğidir. Örneğin uygulamanız, bir film indirildikten sonra uygulamanızın her başlatıldığında yeni film taraması yapmak yerine kullanılabilir filmlerin listesini güncelleştirmek isteyebilir. Veya uygulamanız farklı bir sunucu veya bağlantı noktası kullanarak yeniden deneyerek başarısız bir dosya aktarımını işlemek isteyebilir. İşlem sonrası hem başarılı hem de başarısız aktarımlar için çağrılır, böylece özel hata işleme ve yeniden deneme mantığını uygulamak için kullanabilirsiniz.

Postprocessing, mevcut arka plan görev altyapısını kullanır. Aktarımları başlatmadan önce bir arka plan görevi oluşturur ve bunu aktarımlarınızla ilişkilendirirsiniz. Aktarımlar daha sonra arka planda yürütülür ve tamamlandıklarında, son işlemeyi gerçekleştirmek üzere arka plan göreviniz çağrılır.

İşlem sonrası, BackgroundTransferCompletionGroup adlı yeni bir sınıf kullanır. Bu sınıf, arka plan aktarımlarını birlikte gruplandırmanıza olanak tanıdığı için mevcut BackgroundTransferGroup'a benzer, ancak BackgroundTransferCompletionGroup , aktarım tamamlandığında çalıştırılacak bir arka plan görevi atama yeteneği ekler.

İşlem sonrası ile aşağıdaki gibi bir arka plan aktarımı başlatırsınız.

BackgroundTransferCompletionGroup nesnesi oluşturun. Ardından bir BackgroundTaskBuilder nesnesi oluşturun. Oluşturucu nesnesinin Trigger özelliğini tamamlama grubu nesnesine, oluşturucunun TaskEntryPoint özelliğini de aktarım tamamlandığında yürütülmesi gereken arka plan görevinin giriş noktasına ayarlayın. Son olarak, arka plan görevinizi kaydetmek için BackgroundTaskBuilder.Register yöntemini çağırın. Birçok tamamlama grubunun bir arka plan görev giriş noktasını paylaşabileceğini, ancak arka plan görev kaydı başına yalnızca bir tamamlama grubunuz olabileceğini unutmayın.

var completionGroup = new BackgroundTransferCompletionGroup();
BackgroundTaskBuilder builder = new BackgroundTaskBuilder();

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

BackgroundTaskRegistration downloadProcessingTask = builder.Register();

Ardından arka plan aktarımlarını tamamlama grubuyla ilişkilendirirsiniz. Tüm aktarımlar oluşturulduktan sonra tamamlama grubunu etkinleştirin.

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.CompletionGroup.Enable();

Arka plan görevindeki kod, tetikleyici ayrıntılarından işlem listesini ayıklar ve kodunuz her işlemin ayrıntılarını inceleyebilir ve her işlem için uygun son işlemeyi gerçekleştirebilir.

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
    }
}

İşlem sonrası görevi normal bir arka plan görevidir. Tüm arka plan görevleri havuzunun bir parçasıdır ve tüm arka plan görevleriyle aynı kaynak yönetimi ilkesine tabidir.

Ayrıca, son işlemenin ön plan tamamlama işleyicilerinin yerini almadığını unutmayın. Uygulamanız bir ön plan tamamlama işleyicisi tanımlıyorsa ve dosya aktarımı tamamlandığında uygulamanız çalışıyorsa hem ön plan tamamlama işleyiciniz hem de arka plan tamamlama işleyiciniz çağrılır. Ön plan ve arka plan görevlerinin çağrılma sırası garanti edilemez. Her ikisini de tanımlarsanız, iki görevi düzgün çalıştığından ve eşzamanlı olarak çalışıyorsa birbiriyle karışmadığından emin olmanız gerekir.

İstek zaman aşımları

Dikkate alınması gereken iki birincil bağlantı zaman aşımı senaryosu vardır:

Aktarım için yeni bir bağlantı oluşturulurken, bağlantı isteği beş dakika içinde kurulmazsa iptal edilir.
Bağlantı kurulduktan sonra, iki dakika içinde yanıt almamış bir HTTP isteği iletisi durduruldu.

Not her iki senaryoda da İnternet bağlantısı olduğunu varsayarsak Arka Plan Aktarımı bir isteği otomatik olarak en fazla üç kez yeniden dener. İnternet bağlantısı algılanmazsa, ek istekler bağlantı algılanana kadar bekletilir.

Hata ayıklama kılavuzu

Microsoft Visual Studio'de hata ayıklama oturumlarını durdurmak uygulamanızı kapatmayla karşılaştırılabilir; PUT karşıya yüklemeleri duraklatılır ve POST yüklemeleri sonlandırılır. Hata ayıklama sırasında bile uygulamanız, kaydedilmiş yükleme işlemlerini listelemeli ve ardından bunları yeniden başlatmalı veya iptal etmelidir. Örneğin, bu hata ayıklama oturumunda önceki işlemlerle artık ilgilenilmiyorsa, uygulamanız başlatılırken listelenen kalıcı yükleme işlemlerini iptal etmesini sağlayabilirsiniz.

Hata ayıklama oturumu sırasında, uygulama başlatılırken indirme/yükleme işlemleri listelenirken, bu hata ayıklama oturumundaki önceki işlemlerle artık ilgilenmiyorsanız uygulamanızın bunları iptal etmesini sağlayabilirsiniz. Uygulama bildirimindeki değişiklikler gibi Visual Studio proje güncelleştirmeleri varsa ve uygulama kaldırılır ve yeniden dağıtılırsa GetCurrentUploadsAsync, önceki uygulama dağıtımı kullanılarak oluşturulan işlemleri numaralandıramaz.

Geliştirme sırasında Arka Plan Aktarımı'nı kullanırken etkin ve tamamlanmış aktarım işlemlerinin iç önbelleklerinin eşitlenmemiş duruma gelebileceği bir duruma gelebilirsiniz. Bu, yeni aktarım işlemlerini başlatamama veya mevcut işlemler ve BackgroundTransferGroup nesneleriyle etkileşime geçememeyle sonuçlanabilir. Bazı durumlarda, mevcut işlemlerle etkileşime geçmeye çalışmak çökmeye neden olabilir. TransferBehavior özelliği Paralel olarak ayarlandıysa bu sonuç oluşabilir. Bu sorun yalnızca geliştirme sırasında belirli senaryolarda oluşur ve uygulamanızın son kullanıcıları için geçerli değildir.

Visual Studio kullanan dört senaryo bu soruna neden olabilir.

Mevcut bir projeyle aynı uygulama adıyla yeni bir proje oluşturursunuz, ancak farklı bir dil oluşturursunuz (örneğin, C++'tan C#'a).
Var olan bir projede hedef mimariyi (örneğin x86'dan x64'e) değiştirirsiniz.
Var olan bir projede kültürü (örneğin, nötrden en-US) değiştirirsiniz.
Var olan bir projede paket bildirimine (örneğin Kurumsal Kimlik Doğrulaması ekleme) bir özellik ekler veya kaldırırsınız.

Özellikleri ekleyen veya kaldıran bildirim güncelleştirmeleri de dahil olmak üzere normal uygulama hizmetleri, uygulamanızın son kullanıcı dağıtımlarında bu sorunu tetiklemez. Bu sorunu geçici olarak çözmek için uygulamanın tüm sürümlerini tamamen kaldırın ve yeni dil, mimari, kültür veya yetenekle yeniden dağıtın. Bu işlem Başlangıç ekranı veya PowerShell ve Remove-AppxPackage cmdlet'i kullanılarak yapılabilir.

Windows.Networking.BackgroundTransfer İçindeki Özel Durumlar

Windows.Foundation.Uri nesnesinin oluşturucusuna Tek Biçimli Kaynak Tanımlayıcısı (URI) için geçersiz bir dize geçirildiğinde bir özel durum oluşturulur.

.NET:Windows. Foundation.Uri türü C# ve VB'de System.Uri olarak görünür.

C# ve Visual Basic'da, URI oluşturmadan önce uygulama kullanıcısından alınan dizeyi test etmek için .NET 4.5'teki System.Uri sınıfı ve System.Uri.TryCreate yöntemlerinden biri kullanılarak bu hata önlenebilir.

C++'ta, bir dizeyi URI'ye ayrıştırmaya çalışmak için bir yöntem yoktur. Bir uygulama, Windows.Foundation.Uri için kullanıcıdan girdi alıyorsa, oluşturucu try/catch bloğu içinde yer almalıdır. Bir özel durum oluşursa, uygulama kullanıcıyı bilgilendirebilir ve yeni bir konak adı isteyebilir.

Windows.Networking.backgroundTransfer ad alanı kullanışlı yardımcı yöntemlere sahiptir ve hataları işlemek için Windows.Networking.Sockets ad alanındaki numaralandırmaları kullanır. Bu, uygulamanızda belirli ağ özel durumlarını farklı şekilde işlemek için yararlı olabilir.

Windows.Networking.backgroundTransfer ad alanındaki zaman uyumsuz bir yöntemde karşılaşılan hata, HRESULT değeri olarak döndürülür. BackgroundTransferError.GetStatus yöntemi, bir ağ hatasını arka plan aktarım işleminden WebErrorStatus numaralandırma değerine dönüştürmek için kullanılır. WebErrorStatus numaralandırma değerlerinin çoğu yerel HTTP veya FTP istemci işlemi tarafından döndürülen bir hataya karşılık gelir. Bir uygulama, özel durumun nedenine bağlı olarak uygulama davranışını değiştirmek için belirli WebErrorStatus numaralandırma değerlerini filtreleyebilir.

Parametre doğrulama hataları için, bir uygulama özel duruma neden olan hata hakkında daha ayrıntılı bilgi edinmek için özel durumdan HRESULT'yi de kullanabilir. Olası HRESULT değerleri Winerror.h üst bilgi dosyasında listelenir. Çoğu parametre doğrulama hatasında, döndürülen HRESULT değeri E_INVALIDARG olur.

Önemli API'ler

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-01

Arka plan aktarımları

Windows.Networking.BackgroundTransfer kullanma

Arka Plan Aktarımı özelliği nasıl çalışır?

Arka Plan Aktarımı ile kimliği doğrulanmış dosya istekleri gerçekleştirme

Bu özellik ağ durumu değişikliklerine veya beklenmeyen kapatmalara nasıl uyum sağlar?

Dosya yükleme

Tek bir dosya yükleme

Birden çok dosyayı karşıya yükleme

Kesintiye uğrayan yükleme işlemlerini yeniden başlatma

Dosyaları indirme

Arka Plan Aktarımı dosyası indirmeyi yapılandırma ve başlatma

Ek işlem denetimi yöntemleri ekleme

Başlatma sırasında kalıcı işlemleri numaralandırma

İşlem sonrası

İstek zaman aşımları

Hata ayıklama kılavuzu

Windows.Networking.BackgroundTransfer İçindeki Özel Durumlar

Önemli API'ler

İlgili konular

Geri Bildirim

Ek kaynaklar