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

Converter 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ükleyin

En son kararlı Converter 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çirin:

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

Converter 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 Kaydedin

AddConverter() yöntemi yoktur — Doconut'ın eklenti modeli tekdüzedir. Converter dahil her eklenti 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 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 MemoryStream döndürür. DocumentConverter'ı ihtiyacınız olan her yerde DI'dan alın — tasarım gereği durum içermez, 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çtedir, bu yüzden asla `new` ile oluşturmayı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(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ı içermelidir (".xlsx" , "xlsx" değil) — 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<string> yerine Task<Stream> döndürür — HTML belgesini (gömülü Base64 resimler) bir akış olarak alırsınız, diğer tüm dönüşüm sonuçları gibi.

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 tek enum, her kaynak ailesini kapsar. Önceki kütüphane, aile başına bir *ConfigConverter türüne sahipti — WordConfigConverter, ExcelConfigConverter vb. — her biri kendi iç içe EnTargetFormat enum'ına ve giriş için bir SourceFormatConverter enum'ına sahipti. Hepsi kaldırıldı; göç rehberine 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 belgesi) kendi sabit izin verilen hedef kümesine eşler. Bu enum'ı UI'nızın hedef listesi olarak sabit kodlamayın: ?convert=open yeni yüklenen dosya için gerçek allowedTargets değerini döndürür ve bu değer bir 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 çı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ç noktası 404 yanıtı verir — ancak JS dosyası yine de servis edilir (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 izni veren bir lisansı gerektirir — tek başına dönüşüm hakları vermez.

Widget'ı özelleştir

Doconut.convert(seçici, seçenekler)'a geçirilen başlangıç seçenekleri:

Geri aramalar:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

Kendi ön yüzünüzü 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 yüzünüzü oluşturun. Üç rota da UseDoconut()'ın 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 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 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.

open yanıtındaki sourceExt başında nokta içermez (ö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ış, aranabilir bir MemoryStream döndürür. Çağıran, bu akışı sahiplenir ve içeriğini kopyaladıktan veya 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 görüntüleyici resultToken bunun yerine görüntüleyici oturumu ömrünü izler. Bir görüntüleyici sonucunu kapatmak, hâlâ geçerli bir indirme saklamasını silmez ve tarayıcı widget'ını sıfırlamak da hiçbir TTL'yi uzatmaz.

Sorun Giderme

Filigranlama

ConverterPlugin kaydedildiğinde, 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 durumlarından 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 — sadece çıktı baytları değişir.