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ı olarak — kendi HTTP sözleşmesi olan 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çirin:

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 Doconut.NET8.Converter; .26.7.0 yalnızca indirilen .nupkg dosya adında görünür.

Eklentiyi Kaydedin

AddConverter() yöntemi 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.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, filigranlı çı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ü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 durumsuzdur, bu yüzden tek bir örnek istekler arasında güvenle yeniden kullanılabilir.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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ğuyla eşleştirir ve yalnızca uzantı çözülmez. Ve adı ne olursa olsun, WordToHtmlAsync Task<string> yerine Task<Stream> döndürür — HTML belgesini (Base64 olarak gömülü görüntülerle) 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 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.

Drop-in widget

Widget'ın ?convert=open|run|download uç noktaları isteğe bağlıdır ve varsayılan olarak 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ü bir statik kaynaktır; yalnızca iletişim kurduğu uç noktalar kısıtlanmıştır). AddConverterWidget() hâlâ Converter eklentisinin kaydedilmiş olmasını ve Converter yetkisi veren bir lisansı gerektirir — kendi başına dönüşüm hakları vermez.

Widget'ı Özelleştirme

Doconut.convert(seçici, seçenekler)'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();         // 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 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 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 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 penceresine sahip olur — resultToken ise görüntüleyicinin oturum önbelleğinin süresini izleyen normal bir oturum tokenıdır, saklamadan bağımsız.

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

Hata Modları, Rota Bazında Gruplanmış

Kaynak Sahipliği

Dönüştürücü, sıfır konumunda konumlandırılmış bir MemoryStream döndürür. Çağıran bu akışın sahibidir ve içeriği kopyaladıktan veya döndürdükten sonra serbest bırakmalıdır. DocumentConverter hizmeti 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 görüntüleyici resultToken ise görüntüleyici oturum süresini 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 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ı kurala göre hesaplar: DocumentConverter C# arayüzü, lisansın IsViewerLicensed ve IsTemporary durumundan dahili olarak türetir ve widget'ın ?convert=run işleyicisi aynı kontrolü (IsViewerLicensed && !IsTrial && !IsTemporary) yaparak döndürdüğü watermarked alanını doldurur. Bir entegrasyon, satın almadan önce değerlendirme lisansı ile uçtan uca oluşturulup test edilebilir — yalnızca çıktı baytları değişir.