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ı olarak — kendi HTTP sözleşmesine sahip bir drop‑in widget sunar; böylece belgeleri C#'tan, widget'tan ya da kendinizin yazdığı bir ön uçtan dönüştürebilirsiniz.

Paketi Yükleyin

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

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

Converter paketini Doconut.NET6 ile aynı sürümde tutun. Paket kimliği Doconut.NET6.Converter'dır; .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, Converter dahil, aynı şekilde kaydedilir: AddDoconut() içinde AddPlugin<TPlugin>() çağrılır. ConverterPlugin kendi NuGet paketi Doconut.NET6.Converter içinde gelir ve 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 yetkisi vermeyen geçici olmayan bir lisans nedeniyle başlangıçta bir istisna fırlatır — AddDoconut() içinde yükseltilen bir InvalidOperationException ile, uygulama istekleri işlemeye başlamadan önce. Geçici Demo/NFR kayıtları kabul edilir; süresi dolduktan sonra dönüşüm, filigranlı çıktı ile kullanılabilir. Sessiz bir ücretsiz katman yoktur. Lisansların nasıl yüklendiğini görmek için Lisans Kurulumu sayfasına bakın.

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

Her dönüşüm, 0 konumunda konumlandırılmış, hemen okunabilir veya kopyalanabilir bir MemoryStream döndürür. DocumentConverter'ı ihtiyacınız olduğu yerde DI'dan alın — tasarım gereği durum bilgisizdir, 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 nokta vardır: akış aşırı yüklemesindeki sourceExtension ön ek nokta içermelidir (".xlsx" gibi, "xlsx" değil) — dönüştürücü bunu format kataloğuna karşı eşleştirir ve noktasız bir uzantı çözülemez. Ayrıca adı ne olursa olsun, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belgesini (Base64 gömülü resimlerle) 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ülemez — 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ümesiyle eşleştirir. Bu enum'ı UI'nizin hedef listesi olarak sabitlemeyin: ?convert=open yeni yüklenen dosya için gerçek allowedTargets değerlerini döndürür ve bu değerler bir seçim kutusunu beslemelidir.

Drop-in 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. Bu uç noktaları 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() kullanılmadığında üç ?convert= uç noktası 404 yanıtı verir — ancak JavaScript dosyası yine de sunulur (bu, sadece iletişim kurduğu uç noktaların kısıtlandığı düz bir gömülü statik kaynaktır). AddConverterWidget() hâlâ Converter eklentisinin kaydedilmiş olmasını ve Converter yetkisi veren bir lisansın bulunmasını gerektirir; kendi başına dönüşüm hakkı vermez.

Widget'ı Özelleştirin

Doconut.convert(seçici, seçenekler) fonksiyonuna 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 bu örneği saklayın:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // boş/bırakma ekranına geri döner; onReady tekrar tetiklenmez
conv.loadFile(file);  // bir File nesnesiyle akışı başlatır; şu anda boş değilse hiçbir şey yapmaz
conv.destroy();       // dinleyicileri kaldırır, bağlamayı boşaltır; örnek bundan sonra kullanılamaz

Kendi Ön Ucunuzun Oluşturun

Widget sadece bu HTTP sözleşmesi için bir istemcidir — farklı bir UX için doğrudan ona karşı kendi ön ucunuzu oluşturun. Üç rota da UseDoconut()'un bağlandığı 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 kalır — dönüşüm tamamlandığında downloadToken kendi 30 dakikalık süresini alır — resultToken ise görüntüleyicinin oturum önbelleğinin süresini izleyen normal bir görüntüleyici oturum token'ıdır, saklamadan bağımsızdır.

open yanıtındaki sourceExt ön ek nokta içermez (ör. "docx"); bu, DocumentConverter.ConvertAsync üzerindeki sourceExtension parametresinin bir nokta gerektiren ters konvansiyonudur.

Hata Modları, Rota Bazında Gruplanmıştır:

Kaynak Sahipliği

Dönüştürücü, sıfır konumunda konumlandırılmış, arama yapılabilir bir MemoryStream döndürür. Bu akışı çağıran taraf sahip olur ve içeriği kopyaladıktan veya döndürdükten sonra serbest bırakmalıdır. DocumentConverter servisi durum bilgisizdir ve bağımlılık enjeksiyonundan çözülür; hizmeti elle oluşturmayın veya elle 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 oturumunun ömrünü izler. Bir görüntüleyici sonucu kapatmak hâlâ geçerli bir indirme saklamasını silmez ve tarayıcı widget'ını sıfırlamak da TTL'leri uzatmaz.

Sorun Giderme

Filigranlama

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

Her iki çağrı yolu da aynı kuralı kullanarak bayrağı hesaplar: DocumentConverter C# arayüzü, lisansın IsViewerLicensed ve IsTemporary durumlarından içsel olarak türetir; 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ı ile uçtan uca kurulup test edilebilir — yalnızca çıktı baytları değişir.