SmartUpload 1.0.7, .NET MAUI'ye çöklemeye dayanıklı parçalı yüklemeler getiriyor

Plugin.Maui.SmartUpload'ın 1.0.7 sürümü nuget.org üzerinde yayımlandı. dev.to'daki bir tanıtım yazısına göre bu kütüphane, .NET MAUI için parçalı yükleme (chunked upload) istemcisi olup ayırt edici özelliği dayanıklılık: sunucunun onayladığı her ofset diske yazılıyor, böylece bir sonraki deneme — bir çökme, bilinçli bir duraklatma veya yeniden deneme sonrasında — sıfırdan başlamak yerine o bayttan devam ediyor.

Kütüphanenin hedef aldığı sorun, mobil uygulama geliştiren herkese tanıdık gelir. Tek bir POST isteği ortasında kesilen bir fotoğraf yüklemesi sıfıncı bayttan yeniden başlamak zorundadır ve uygulamanın yeni başlatılan bir kopyası, sunucunun zaten aldığı veriler hakkında hiçbir hatıraya sahip değildir. SmartUpload bu hatırayı uygulama adına saklar.

Sürümde neler var

SmartUpload MIT lisanslıdır ve Android, iOS, Mac Catalyst ile Windows üzerinde çalışır. net10.0'ı ve platform türevlerini hedefler: net10.0-android (API 21+), net10.0-ios ve net10.0-maccatalyst (15+) ile net10.0-windows (10.0.17763+). dev.to yazısında belirtildiği üzere 1.0.7, paylaşılan uygulamaya özellikle Mac Catalyst ve Windows hedef çerçevelerini (target framework) ekliyor.

Yazarın açıkça belirttiği bir sınır şudur: işlem sona erdiğinde işletim sistemi bayt göndermeyi durdurur. Arayüz kapalıyken devam etmesi gereken bir aktarım, Android'de bir foreground service veya iOS'ta NSURLSession background yapılandırması sağlamak için yine ev sahibi uygulamaya ihtiyaç duyar. SmartUpload, o platform ev sahiplerinin geri çağıracağı devam noktasıdır.

Kurulum ve yapılandırma

Paket yüklendikten sonra uygulamalar, MauiApp builder kurulumu sırasında UseSmartUpload ile istemciyi kaydeder; EnableLogging, DefaultChunkSize, MaxConcurrentUploads, ResumeInterruptedOnStart, RequireHttps ve bir DefaultRetry politikası gibi seçenekler geçirilir. İstemci daha sonra dependency injection üzerinden çözümlenir veya SmartUpload.Current ile erişilir.

Bilinmesi gereken varsayılanlar: parça boyutu 1 MB'a düşer ve 64 KB ile 32 MB arasında sınırlandırılır; istek başına parça boyutları pozitif olmalı ve en fazla 32 MB olabilir. MaxConcurrentUploads varsayılanı 2'dir; fazladan oturumlar bir yuva boşalana kadar Queued durumunda bekler. Her parçaya 100 saniyelik bir HTTP zaman aşımı uygulanır. ResumeInterruptedOnStart varsayılan olarak false'dur; bu nedenle geliştiriciler ya bunu etkinleştirir ya da işlem ölürken ortada kalan oturumları ve AutoStart ile işaretlenmiş kuyruktaki işleri canlandırmak için başlatma sonrasında ResumeInterruptedAsync() metodunu kendileri çağırır.

Oturumlar, durumlar ve kontrol

Dosyalar, mutlak bir FilePath, zorunlu bir Endpoint, Authorization gibi header'lar ve isteğe bağlı metadata içeren bir UploadRequest ile EnqueueAsync üzerinden kuyruğa alınır. AutoStart varsayılan olarak true'dur; devre dışı bırakmak oturumu sonraki bir StartAsync için kalıcı hale getirir. Çağıranın sağladığı bir SessionId yalnızca harf, rakam, tire ve alt çizgi içerebilir ve en fazla 128 karakter olabilir; aksi halde bir GUID üretilir.

İstemci PauseAsync, ResumeAsync, RetryAsync, CancelAsync ve RemoveAsync metodlarını sunar. Duraklatma, mevcut parça iptal edildikten sonra durur ancak ofseti korur; yeniden deneme, başarısız veya iptal edilmiş bir oturumu aynı onaylanmış bayttan yeniden başlatır. Oturumlar Queued, Uploading, Paused, Completed, Failed ve Cancelled durumlarından geçer; bu durumlar ProgressChanged, SessionCompleted, SessionFailed ve SessionStateChanged olaylarıyla ortaya çıkar ve ilerleme, yüklenen baytların sınırlandırılmış bir oranı olarak bildirilir.

Protokoller ve genişletme noktası

İki protokol yerleşik olarak gelir. ContentRange varsayılanlandır: her dilim bir Content-Range başlığıyla birlikte X-Upload-Id, X-Chunk-Index ve X-Chunk-Count gönderilir; Range veya X-Last-Byte döndüren isteğe bağlı bir HEAD isteği istemcinin kaldığı yere yetişmesini sağlar. Tus, tus 1.0 akışını uygular — oluşturma için POST, Upload-Offset için HEAD, application/offset+octet-stream içerik türüyle PATCH ve metadata'nın Upload-Metadata içinde taşınması. Bunların dışındaki her şey, başlatma, ilerleme sorguları, parça yükleme, tamamlama ve iptal için kancalar sunan özel bir IUploadProtocol uygulamasından geçer; başlatma işlemi idempotent olmalıdır. İptal durumunda, DeleteRemoteOnCancel bayrağı sunucu termination uzantısını duyurduğunda bir tus DELETE tetikleyebilir.

Depolama ve güvenlik uyarıları

Oturum durumu, FileSystem.AppDataDirectory/Plugin.Maui.SmartUpload/ altında JSON dosyaları olarak yaşar; her biri dosya yolunu, boyutu, son yazma zaman damgasını, endpoint'i, header'ları, protokol durumunu (tus Location dahil) ve onaylanmış ofseti kaydeder. Klasör taşınabilir ve deponun tamamı özel bir IUploadStore ile değiştirilebilir. Devam etme kontrolleri sıkıdır: eksik bir dosya UploadError.FileNotFound ile başarısız olur; değişen uzunluk veya yazma zamanı UploadError.FileChanged ile başarısız olur, böylece istemci artık orijinal olmayan bir dosyaya karşı devam etmez.

İki uyarı öne çıkıyor. Authorization token'ları dahil header'lar o JSON içinde kalıcı hale getirilir — saklanan bir bearer token, bir sonraki isteğin göndereceği şeyin ta kendisidir; bu yüzden uygulama kapalıyken süresi dolabilecek token'lar devam etmeden önce yenilenmelidir. Ayrıca RequireHttps varsayılan olarak true'dur; bu, 1.0.6'dan taşınan bir sağlamlaştırmadır. http endpoint'leri bayrak devre dışı bırakılmadıkça exception fırlatır; yazar bunu yalnızca yerel geliştirme için öneriyor.

Neden önemli

Mobil süreçler sürekli ölür — işletim sisteminin uygulamayı kapatması, kullanıcının uygulamayı kaydırarak kapatması, tükenen batarya, dengesiz bir bağlantı. Büyük yüklemeleri sıfırdan başlatmak bant genişliğini ve bataryayı israf eder ve yüklemenin hiçbir zaman tamamlanmamasına yol açabilir. Ofset kalıcılığı web tarafında yerleşik çözümdür ve SmartUpload, benzer bir mekanizmayı .NET MAUI'ye pratik varsayılanlar, iki gerçek protokol, yeniden deneme yönetimi ve değiştirilebilir bir depolama katmanıyla getirir. Arka plan yürütmenin hâlâ bir platform ev sahibi gerektirdiği yönündeki açık söylemi, değerlendirilebilir bir kütüphane ile bir demo arasındaki farkı yaratan türden bir netliktir.