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

Dönüştürücü eklentisi, Doconut'ı bir belge dönüştürme hizmetine dönüştürür. Genel DocumentConverter arabiriminin 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.NET8.Converter

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

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

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

Eklentiyi Kaydedin

AddConverter() yöntemi yoktur — Doconut'ın eklenti modeli tekdüzeldir. Her eklenti, Dönüştürücü dahil, aynı şekilde kaydedilir: AddDoconut() içinde AddPlugin<TPlugin>() çağırın. ConverterPlugin kendi NuGet paketinde, Doconut.NET8.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 bir istisna fırlatır — AddDoconut() içinde yükseltilen bir InvalidOperationException, uygulama istekleri hizmet vermeden ö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 olmaya devam eder. Sessiz bir ücretsiz katman yoktur. Lisansların nasıl yüklendiği için Lisans Kurulumu sayfasına bakın.

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

Her dönüşüm, 0 konumunda konumlandırılmış, hemen okunabilir veya kopyalanabilir bir seekable MemoryStream döndürür. DocumentConverter'ı ihtiyacınız olan her yerde DI'dan çözün — tasarım gereği durum bilgisi tutmaz, 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` etmeyin.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension baştaki noktayı içerir. password, document korunmadığı sürece 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: akış aşırı yüklemesindeki 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ızca uzantı çözülmez. Ve adının aksine, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belgesini (görseller Base64 olarak gömülmüş) 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'ını döndürür ve bu, seçim kutusunu yönlendirmelidir.

Yerleştirilebilir widget

Widget'ın ?convert=open|run|download uç noktaları isteğe bağlıdır ve kutudan çıktığında devre dışıdır — varsayılan olarak güvenlidir. Sunucu tarafında, eklenti kaydıyla birlikte bunları 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 — programlı olarak widget'ı kontrol etmek için saklayın:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // idle/drop ekrana geri dön; onReady tekrar 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 ucunuzu oluşturun

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()'ın monte edildiği 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 — resultToken ise saklamadan bağımsız olarak görüntüleyicinin oturum önbelleğine bağlı normal bir görüntüleyici oturum belirtecidir.

sourceExt, open yanıtında başında nokta yoktur (ör. "docx") — DocumentConverter.ConvertAsync üzerindeki sourceExtension parametresinin tersine, bu parametre bir nokta gerektirir.

Başarısızlık modları, rotaya göre gruplanmıştır:

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 durumsuzdur 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 bunun yerine viewer oturumu ömrünü takip eder. Bir viewer sonucunu kapatmak, hâlâ geçerli bir indirme saklamasını silmez ve tarayıcı widget'ını sıfırlamak da herhangi bir TTL'yi uzatmaz.

Sorun Giderme

Filigranlama

ConverterPlugin kayıtlı olduğunda, ana bilgisayarın lisansı üç durumdan birinde olur:

Her iki çağrı yolu da bayrağı aynı kuraldan hesaplar: DocumentConverter C# arayüzü, 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 bütünleşme, satın almadan önce bir değerlendirme lisansı üzerinde uçtan uca inşa edilebilir ve test edilebilir — yalnızca çıktı baytları değişir.