Dönüştürücü Eklentisi

Dönüştürücü eklentisi, Doconut'u bir belge-dönüştürme hizmetine dönüştürür. Kamu DocumentConverter arayüzünün arkasındaki motoru sağlar ve — isteğe bağlı — kendi HTTP sözleşmesine sahip bir drop-in widget sunar, böylece belgeleri C#'tan, widget'tan veya kendinizin yazdığı bir ön uçtan dönüştürebilirsiniz.

Paketi Yükleyin

En son kararlı Dönüştürücü eklentisini yükleyin:

dotnet add package Doconut.NET6.Converter

Eklentiyi mevcut 26.7.0 sürümüne sabitlemek için, sürümü ayrı olarak geçirin:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Dönüştürücü paketini Doconut.NET6 ile aynı sürümde tutun. Paket kimliği Doconut.NET6.Converter; .26.7.0 yalnızca indirilen .nupkg dosya adında görünür.

Eklentiyi Kaydedin

AddConverter() adlı bir yöntem yoktur — Doconut'un eklenti modeli tekdüzedir. Her eklenti, Dönüştürücü dahil, aynı şekilde kaydedilir: AddDoconut() içinde AddPlugin<TPlugin>() çağırın. ConverterPlugin kendi NuGet paketinde, Doconut.NET6.Converter, temel görüntüleyici paketiyle birlikte kurulur.

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

Bu çağrı, eksik bir lisans, eski bir TRIAL dosyası veya Converter yeteneğini vermeyen geçici olmayan bir lisans nedeniyle başlangıçta hata verir — bir InvalidOperationException, AddDoconut() içinde yükseltilen, uygulama istekleri işlemeye başlamadan önce. Geçici Demo/NFR kayıtları kabul edilir; takvim süresi dolduktan sonra, dönüşüm su işareti eklenmiş çıktı ile kullanılabilir kalır. Sessiz bir ücretsiz katman yoktur. Lisansların nasıl yüklendiği için Lisans Kurulumu bölümüne bakın.

C#'tan Dönüştür

Her dönüşüm, 0 konumunda konumlandırılmış, hemen okunmaya veya kopyalanmaya hazır bir seekable MemoryStream döndürür. Gerektiği yerde DI'den DocumentConverter çözün — tasarım gereği durumsuzdur, bu yüzden tek bir örnek istekler arasında güvenle yeniden kullanılabilir.

// DocumentConverter'ı enjekte edin; yapıcı içsel olduğu için, asla `new` etme.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension baştaki noktayı içerir. password, belge korunmuyorsa null olur.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Yanlış yapılması kolay iki detay: stream overload'unda sourceExtension, baştaki noktayı (".xlsx", "xlsx" değil) içermelidir — dönüştürücü bunu format kataloğuna karşı eşleştirir ve yalnız bir uzantı çözülemez. Ve adının aksine, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belgesini (Base64 olarak gömülü görüntüler) bir akış olarak alırsınız, diğer tüm dönüşüm sonuçları gibi.

Hedef formatlar

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Her kaynak her hedefe dönüştürülmez — eklenti, her kaynağın format ailesini (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) kendi sabit izin verilen hedef kümesine eşler. Bu enum'ı UI'nizin hedef listesi olarak sabitlemeyin: ?convert=open, yeni yüklenen dosyanın gerçek allowedTargets değerini döndürür ve bu, seçim aracını yönlendirmelidir.

Yerleştirilebilir widget

Widget'ın ?convert=open|run|download uç noktaları isteğe bağlıdır ve kutudan çıktığı anda devre dışıdır — varsayılan olarak güvenlidir. Sunucu tarafında, eklenti kaydıyla birlikte etkinleştirin:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

AddConverterWidget() olmadan, üç ?convert= uç nokta 404 yanıt verir — ancak JS dosyası yine de sunulur (bu, gömülü basit bir statik kaynaktır; yalnızca iletişim kurduğu uç noktalar kısıtlanmıştır). AddConverterWidget() hâlâ Converter eklentisinin kaydedilmesini ve Converter sağlayan bir lisansı gerektirir — tek başına dönüşüm hakları vermez.

Widget'ı özelleştir

Doconut.convert(selector, options)'a iletilen başlangıç seçenekleri:

Geri Çağrılar:

Doconut.convert() widget örneğini döndürür — programatik olarak widget'ı kontrol etmek için saklayın:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // idle/drop ekranına geri dön; onReady yeniden tetiklenmez
conv.loadFile(file);  // akışı bir File nesnesiyle başlatır; şu anda idle değilse no-op
conv.destroy();       // dinleyicileri kaldırır, mount'ı boşaltır; bu işlemden sonra instance kullanılamaz

Kendi ön ucunu oluştur

Widget, bu HTTP sözleşmesi için yalnızca bir istemcidir — farklı bir kullanıcı deneyimi için doğrudan ona karşı kendi ön ucunuzu oluşturun. Üç rota da UseDoconut()'in bağlandığı ASP.NET dalının altında bulunur (genellikle /doconut).

Yüklenen kaynak baytları sunucu tarafında 30 dakikalık TTL ile saklanır; bu süre dolduğunda, run 404 yanıtını verir ve dosya yeniden açılmalıdır. Dönüştürülmüş sonuç aynı saklamada bulunur — dönüşüm tamamlandığında downloadToken kendi yeni 30 dakikalık penceresini alır — ancak resultToken, saklamadan bağımsız olarak görüntüleyicinin oturum önbelleğine bağlı bir normal görüntüleyici oturum belirtecidir.

sourceExt, open yanıtında başta nokta içermez (ör. "docx") — bu, bir nokta gerektiren DocumentConverter.ConvertAsync üzerindeki sourceExtension parametresinin ters konvansiyonudur.

Hata modları, rotaya göre gruplanmış:

Kaynak sahipliği

Dönüştürücü, sıfır konumunda konumlandırılmış bir seekable MemoryStream döndürür. Çağıran bu akışı sahiplenir ve içeriği kopyaladıktan veya döndürdükten sonra serbest bırakmalıdır. DocumentConverter hizmeti kendisi durum bilgisizdir ve bağımlılık enjeksiyonundan çözülür; hizmeti manuel olarak oluşturmayın veya serbest bırakmayın.

Web widget'ı için, yükleme ve indirme saklamaları bağımsız 30 dakikalık TTL'lere sahiptir. Bir viewer resultToken, viewer oturumu ömrünü izler. Bir viewer sonucunu kapatmak, hâlâ geçerli bir indirme saklamasını silmez ve tarayıcı widget'ını sıfırlamak da TTL'yi uzatmaz.

Sorun Giderme

Filigranlama

ConverterPlugin kaydedildiğinde, ana bilgisayarın lisansı üç durumdan birinde olur:

Her iki çağrı yolu da aynı kurala dayanarak bayrağı hesaplar: DocumentConverter C# fasadı, lisansın IsViewerLicensed ve IsTemporary durumundan dahili olarak türetir ve widget'ın ?convert=run işleyicisi eşdeğer kontrolü (IsViewerLicensed && !IsTrial && !IsTemporary) yaparak döndürdüğü watermarked alanını doldurur. Bir entegrasyon, satın almadan önce bir değerlendirme lisansı üzerinde uçtan uca oluşturulup test edilebilir — yalnızca çıktı baytları değişir.