Doconut drop‑in dönüştürücü widget'ını .NET 8'de kaydedin ve etkinleştirin

Drop‑in widget, dosya yüklemek, bir dönüşüm çalıştırmak ve sonucu indirmek için Doconut’un hazır UI'sidir.
Varsayılan olarak widget'ın üç ?convert= uç noktası 404 döndürür; yalnızca Converter eklentisini kaydedip AddConverterWidget()'ı DoconutOptions üzerinde çağırdığınızda aktif hale gelir.

Aşağıda her iki gereksinimi de karşılayan, kopyala‑yapıştır hazır tam bir başlangıç yapılandırması bulunmaktadır.

---

1. Önkoşullar – lisans ve oturum desteği

• Lisans – Converter eklentisi, Converter yeteneğini sağlayan bir lisans gerektirir. Dosyayı (ör. Doconut.Viewer.lic) uygulamanın erişebileceği bir yere koyun ve DoconutOptions.LicensePath'ı ona yönlendirin.
• Oturum durumu – Doconut’un güvenlik modeli, belge‑oturum token'larını ASP.NET Core oturumunda saklar. Dağıtık bir önbellek ekleyin ve ara katman (middleware) bağlanmadan önce AddSession()'ı ekleyin.

builder.Services.AddDistributedMemoryCache();   // oturum için gerekli
builder.Services.AddSession();                  // IDistributedCache‑destekli oturumu etkinleştirir

---

2. Temel Doconut hizmetlerini kaydedin

AddDoconut(), görüntüleyiciyi, lisans hizmetini ve eklenti kaydını enjekte eden tek giriş noktasıdır.

builder.Services.AddDoconut(options =>
{
    // Doconut'a lisans dosyasının nerede bulunacağını söyleyin.
    options.LicensePath = "Doconut.Viewer.lic";

    // Converter eklentisini kaydedin – bu aynı zamanda lisans yeteneğini doğrular.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Lisans Converter yeteneğini içermiyorsa, yukarıdaki çağrı InvalidOperationException hatası verir ve uygulama başlatılamaz. Bu hızlı hata davranışı, hatalı lisanslı bir yapıyı dağıtmanızı önler.

---

3. Widget'ı AddConverterWidget ile etkinleştirin

Widget isteğe bağlıdır. AddConverterWidget()'ı çağırmak, üç dönüşüm uç noktasını (?convert=open, ?convert=run, ?convert=download) kaydeder ve istemci tarafı yapılandırmasının (maksimum yükleme boyutu, temel yollar vb.) küçük bir kısmını bağlar.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // Drop‑in UI'yi etkinleştirin ve istemci‑tarafı yükleme limitini ayarlayın.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // istemci ön‑kontrolü; sunucu kendi limitini uygular
    });
});

Yalnızca AddConverterWidget çağrısı uç noktaları oluşturur; statik JavaScript dosyası (doconutConverter.js) her zaman gömülü bir kaynak olarak sunulur, ancak uç noktalar eksikse sunucuya bağlanamaz.

---

4. Ara katmanı (middleware) doğru sırada bağlayın

Statik varlıkları sunan ara katman (UseDoconutResources), terminal görüntüleyici ara katmanı (UseDoconut) öncesinde çalışmalıdır. Oturum ara katmanı da daha erken yerleştirilmeli çünkü Doconut her istekte oturumu doğrular.

app.UseSession();           // UseDoconut()'dan önce gelmelidir
app.UseDoconutResources();  // JS, CSS ve görüntüleri sunar
app.UseDoconut();           // ?convert= ve belge sayfası isteklerini işler

Bu işlem hattı kurulduğunda, /doconut-res/doconutConverter.js'a yapılan istek başarılı olur ve widget /doconut?convert=open, /doconut?convert=run ve /doconut?convert=download'ı çağırabilir.

---

5. Widget'ın gerçekte yaptığı şey

Aşama	Sunucu uç noktası	Tipik yanıt
Aç	?convert=open	Bir JSON yükü döndürür; içinde bir token, sayfa sayısı, kaynak uzantısı ve izin verilen hedef formatların listesi bulunur.
Çalıştır	?convert=run	Dönüşümü başlatır ve bir downloadToken, sonuç sayfa sayısı, önerilen dosya adı ve çıktının filigranlı olup olmadığını gösteren bir işaret döndürür.
İndir	?convert=download	İstemci sağlanan indirme URL'sini izlediğinde dönüştürülmüş dosyayı akış olarak gönderir.

İstemci tarafında, widget widget.MaxUploadMb'a karşı bir ön‑yükleme boyut kontrolü yapar. Dosya bu sınırı aşarsa, widget yüklemeyi iptal eder ve onError geri çağrısını phase = "open" ve dostane bir mesajla tetikler. Sunucu kendi sınırını uygular ve istek istemci kontrolünü aşarsa 413 Payload Too Large yanıtını verir.

---

6. Widget olaylarına bağlanma (C#‑tarafı gerekmez)

Tüm geri çağrılar (onReady, onSourceLoaded, onConverted, onError, vb.) widget'ı barındıran sayfa tarafından sağlanan JavaScript fonksiyonlarıdır. Soru kayıt tarafına odaklandığı için bu geri çağrıları işlemek üzere ek C# kodu yazmanıza gerek yoktur—widget uç noktalar aktif olduğunda onları otomatik olarak çağırır.

---

7. Yaygın tuzaklar ve nasıl kaçınılır

Semptom	Muhtemel neden	Çözüm
404, /doconut?convert=open üzerinde	AddConverterWidget() atlanmıştı.	Bölüm 3'te gösterildiği gibi çağrıyı ekleyin.
Uygulama, eksik yetenek hakkında InvalidOperationException ile başlatılamıyor	Lisans dosyası Converter yetkisini vermiyor.	Converter yeteneğini içeren bir lisans edinin.
Oturum‑ile ilgili 500 hatası	UseSession(), UseDoconut()'dan sonra yerleştirildi veya önbellek kaydı eksik.	app.UseSession()'ın app.UseDoconut()'dan önce çalıştığından ve bir önbellek hizmetinin kaydedildiğinden emin olun.

---

8. Uygulamayı çalıştırın ve widget'ı eylemde görün

1. ASP.NET Core projesini derleyin ve çalıştırın.
2. <div id="doconut-convert"></div> öğesini içeren ve Doconut dönüştürücü betiğini (betik otomatik olarak /doconut-res/doconutConverter.js'dan sunulur) içeren bir sayfa açın.
3. Desteklenen bir dosyayı (PDF, DOCX, DWG, vb.) bırakma alanına sürükleyin.
4. Widget önce ?convert=open'ı, ardından ?convert=run'ı çağıracak ve sonunda ?convert=download'a işaret eden bir İndir bağlantısı gösterecektir.

Üç uç nokta 404 yerine JSON döndürürse, widget doğru şekilde kaydedilmiş ve üretim kullanımına hazır demektir.

Sonraki adım: Yukarıdaki kod parçacıklarını Program.cs (veya Startup.cs) dosyanıza ekleyin, lisans dosyasının mevcut olduğunu doğrulayın ve uygulamayı başlatın. Drop‑in dönüştürücü widget, başka bir sunucu‑tarafı değişiklik gerektirmeden canlı olacaktır.