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 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ükle

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

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

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

Eklentiyi Kaydet

AddConverter() adlı bir yöntem yoktur — Doconut'ın 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.NETStandard.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 damgası eklenmiş çıktı ile kullanılabilir olmaya devam eder. 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 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 durumsuzdur, bu yüzden tek bir örnek istekler arasında güvenle yeniden kullanılabilir.

viewer.Converter.GetConverter() burada mevcut değildir. Dönüşüm artık görüntüleyici örneği üzerinden erişilmez: bunun yerine Doconut.DocumentConverter enjekte edin.

// DocumentConverter'ı enjekte edin; yapıcı içsel olduğu için, asla `new` yapmayın.
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(stream, ".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ız bir uzantı çözülemez. Ve adının aksine, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belgesini (görseller Base64 olarak gömülü) bir akış olarak alırsınız, diğer tüm dönüşüm sonuçlarıyla aynı.

Hedef formatlar

ConversionTarget (namespace Doconut.Configs.Conversion) 45 üyeye sahiptir:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Bu enum, her kaynak ailesini kapsar. Önceki kütüphane, aile başına bir *ConfigConverter türü — WordConfigConverter, ExcelConfigConverter vb. — her biri kendi iç içe EnTargetFormat enum'ına sahipti, ayrıca giriş için bir SourceFormatConverter enum'ı vardı. Hepsi kaldırıldı; geçiş rehberi bölümüne bakın.

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 sabit kodlamayın: ?convert=open, yeni yüklenen dosya için gerçek allowedTargets'ı döndürür ve bu, seçim aracını yönlendirmelidir.

Yerleştirilebilir widget

Widget'in ?convert=open|run|download uç noktaları isteğe bağlıdır ve kutudan çıkar çıkmaz 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, basit bir gömülü 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'i özelleştir

Doconut.convert(selector, options)'a geçirilen 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);  // File nesnesiyle akışı başlat; currently idle olmadıkça 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 monte edildiği ASP.NET dalı altında bulunur (genellikle /doconut).

Yüklenen kaynak baytları sunucu tarafında 30 dakikalık bir TTL ile saklanır; bu süre dolduğunda, run 404 yanıt verir ve dosyanın yeniden açılması gerekir. Dönüştürülmüş sonuç aynı saklamada bulunur — dönüşüm tamamlandığında downloadToken kendi yeni 30 dakikalık süresini 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 token'ıdır.

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

Hata 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 ya da döndürdükten sonra serbest bırakmalıdır. DocumentConverter hizmeti kendisi durumssızdır 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 entegrasyon, satın almadan önce bir değerlendirme lisansı üzerinde uçtan uca oluşturulup test edilebilir — yalnızca çıktı baytları değişir.