Plugin Konverter
Konversi dokumen ke 45 format target
Plugin Converter mengubah Doconut menjadi layanan konversi dokumen. Ia menyediakan mesin di balik antarmuka publik DocumentConverter dan — opt-in — widget drop-in yang disajikan oleh DocImage.axd, sehingga Anda dapat mengonversi dokumen dari C#, dari widget, atau dari frontend yang Anda tulis sendiri.
| Permukaan | Kapan digunakan |
|---|---|
DocumentConverter (C#) | Anda mengonversi di server, tanpa melibatkan browser |
Drop-in widget (doconutConverter.js) | Anda menginginkan layar unggah, konversi, dan unduh siap pakai di halaman Anda |
HTTP endpoints on DocImage.axd (?convert=open|run|download) | Anda membangun UI konversi Anda sendiri berdasarkan kontrak server yang terdokumentasi |
Pasang paket
Install-Package Doconut.NETFramework.ConverterUntuk mengunci plugin ke rilis yang dijelaskan dalam dokumentasi ini:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Pastikan paket Converter berada pada versi yang sama dengan Doconut.NETFramework.
File lisensi plugin, Doconut.Viewer.Converter.lic, diletakkan di folder yang sama dengan Doconut.Viewer.lic; ia dibaca bersama lisensi penampil.
Daftarkan plugin
Setiap plugin didaftarkan dengan cara yang sama: AddPlugin<TPlugin>() di DoconutHost.Initialize, dipanggil dari Application_Start.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});Itu semua yang dibutuhkan antarmuka C#. Widget dan endpoint HTTP-nya adalah opt-in terpisah, AddConverterWidget() (lihat Widget Drop-in).
Plugin membutuhkan lisensi yang memberikan kemampuan Converter. Tanpa lisensi, DoconutHost.Initialize melempar dari Application_Start:
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.Di System.Web itu berarti setiap permintaan menjawab 500 kosong, dan alasannya hanya ada di log peristiwa Windows (sumber ASP.NET). Ia melempar karena tidak ada lisensi, file TRIAL warisan, lisensi tanpa Converter, dan lisensi berbayar yang digunakan di luar jendela versinya. Lisensi Demo/NFR sementara diterima. Lihat Pengaturan Lisensi.
Lisensi & watermark
| Status lisensi | Mulai | Output konversi |
|---|---|---|
Lisensi penampil berbayar yang memberikan Converter, dalam jendela versinya | Mulai | Bersih — watermarked: false |
| Lisensi Sementara Aktif (Demo/NFR) | Mulai | Mengonversi, dengan watermark evaluasi — watermarked: true |
| Lisensi Sementara Kedaluwarsa (Demo/NFR) | Mulai | Mengonversi, dengan watermark evaluasi — watermarked: true |
Tidak ada lisensi, file TRIAL warisan, lisensi tanpa Converter, atau lisensi berbayar di luar jendela versinya | Application_Start melempar; setiap permintaan menjawab 500 kosong | — |
Antarmuka DocumentConverter dan penangan ?convert=run widget menerapkan aturan yang sama. Integrasi dapat dibangun dan diuji end to end dengan lisensi evaluasi sebelum pembelian — hanya byte output yang berubah.
Sumber DICOM (.dcm, .ima) juga membutuhkan kemampuan Dicom. Tanpa itu, ConvertAsync melempar LicenseException (Converting '.dcm' requires the Dicom capability license.) dan open widget menjawab 403.
Gunakan dari C#
Setiap konversi mengembalikan MemoryStream yang dapat dicari dengan posisi 0. DocumentConverter bersifat stateless: dapatkan dari DoconutHost.Services di mana pun Anda membutuhkannya dan gunakan kembali secara bebas.
// Resolusi DocumentConverter dari DoconutHost.Services; konstruktornya internal, jadi jangan pernah `new`-kan itu.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension mencakup titik di depannya. password bernilai null kecuali dokumen dilindungi.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html: sebuah Stream yang memegang HTML untuk diubah kembali menjadi dokumen Word, seperti hasil dari WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);Dua detail yang mudah keliru: sourceExtension pada overload stream harus menyertakan titik depan (".xlsx", bukan "xlsx"), atau tidak akan terpecahkan. Dan meskipun namanya, WordToHtmlAsync mengembalikan Task<Stream>, bukan Task<string> — dokumen HTML (gambar tersemat sebagai Base64) datang sebagai stream, seperti setiap hasil lainnya.
Pemanggil memiliki MemoryStream yang dikembalikan oleh konversi dan harus membuangnya setelah menyalin atau mengembalikannya (MVC's File(stream, …) membuangnya untuk Anda). Jangan membuat atau membuang DocumentConverter sendiri — konstruktornya bersifat internal.
Dalam pengontrol MVC 5
Buat aksi menjadi asynchronous dan await konversi:
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
Stream pdf = await converter.ConvertAsync(
file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
password: null, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}Di Web Forms: jangan pernah memblokir konversi
Sebuah halaman Web Forms berjalan pada konteks permintaan single-threaded. ConvertAsync melanjutkan pada konteks itu ketika selesai, sehingga halaman yang menunggunya secara sinkron — .Result, .Wait(), .GetAwaiter().GetResult() — menahan thread yang dibutuhkan konversi untuk selesai. Permintaan tidak pernah kembali. Browser terus berputar, log IIS tidak mencatat apa pun, dan bagian lain situs tetap berfungsi, sehingga terlihat seperti konversi yang lambat bukan deadlock.
Tandai halaman Async="true" dan jalankan konversi sebagai tugas async halaman:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: direktif @Page membutuhkan Async=\"true\", dan konversi berjalan sebagai tugas async halaman.
// Memblokirnya dengan cara itu (.Result, .Wait(), .GetAwaiter().GetResult()) menyebabkan deadlock pada permintaan:
// itu tidak pernah kembali, dan tidak ada yang tercatat.
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack) return;
RegisterAsyncTask(new PageAsyncTask(async ct =>
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
using (var pdf = await converter.ConvertAsync(
Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
using (var ms = new MemoryStream())
{
if (pdf.CanSeek) pdf.Position = 0;
await pdf.CopyToAsync(ms);
Response.ContentType = "application/pdf";
Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
Response.BinaryWrite(ms.ToArray());
// Context, bukan HttpContext.Current: setelah await yang terakhir dapat menjadi null.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Tanpa Async="true" dalam arahan @Page, RegisterAsyncTask diabaikan secara diam-diam. Setelah sebuah await, gunakan Context halaman; HttpContext.Current dapat menjadi null di sana.
Format target
ConversionTarget (namespace Doconut.Configs.Conversion) memiliki 45 anggota:
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, IcoTidak setiap sumber dapat dikonversi ke setiap target: setiap keluarga format sumber (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, dokumen web, DICOM) memiliki set target yang diizinkan masing‑masing. Mengonversi sumber DICOM (.dcm, .ima) juga memerlukan lisensi yang memberikan kemampuan Dicom; targetnya adalah Pdf, Png, Jpeg, Bmp, Tiff, dan Gif. Jangan menghardcode enum ini sebagai daftar target UI Anda: ?convert=open mengembalikan allowedTargets untuk file yang diunggah, dan itulah yang seharusnya mengendalikan pemilih.
Widget drop-in
Aktifkan endpoint
Endpoint ?convert=open|run|download widget dilayani oleh DocImage.axd dan nonaktif secara default. Aktifkan mereka di sebelah pendaftaran plugin:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});
// System.Web membaca seluruh unggahan sebelum Doconut melihatnya: pertahankan maxRequestLength (KB) dan
// maxAllowedContentLength (bytes) di Web.config di atas MaxUploadMb widget’s.AddConverterWidget() tanpa argumen mengaktifkan widget dengan nilai default (MaxUploadMb = 25). Itu tidak memberikan hak konversi secara otomatis: ia memerlukan AddPlugin<ConverterPlugin>(), atau DoconutHost.Initialize melempar:
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.Dua hal yang harus diperiksa ketika widget tidak berfungsi dengan benar:
basePath: '/DocImage.axd'. Default widget,/doconut, adalah endpoint ASP.NET Core. Pada paket ini, endpointnya adalah handlerDocImage.axddariWeb.config.- Skrip dan endpoint bersifat independen. Modul sumber daya menyajikan
doconutConverter.jsterlepas dari apakah widget diaktifkan atau tidak. TanpaAddConverterWidget(), widget dimuat, menggambar zona drop-nya, dan tampak sepenuhnya benar — dan aksi pertamanya menjawab404.
Batas unggahan
ASP.NET membaca seluruh isi permintaan sebelum DocImage.axd dijalankan. Unggahan di atas MaxUploadMb tetapi di bawah batas host menghasilkan JSON 413 milik widget (File is too large.). Unggahan di atas batas host ditolak oleh IIS terlebih dahulu, dengan halaman error yang tidak dapat dibaca widget. Pertahankan kedua batas host dalam Web.config di atas batas maksimum widget:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Sematkan itu
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd', maxUploadMb: 25 });
</script>Doconut.convert(selectorOrElement, options) menerima selector CSS atau elemen, melempar error jika mount tidak ditemukan, dan mengembalikan sebuah handle. Widget mengunggah sebuah file, menampilkan pratinjau halaman 1, memungkinkan pengguna memilih satu dari allowedTargets, mengonversi, menampilkan pratinjau hasil bila memungkinkan, dan menawarkan unduhan.
Opsi
| Opsi | Tipe | Bawaan | Catatan |
|---|---|---|---|
basePath | string | /doconut | URL endpoint. Atur '/DocImage.axd' pada paket ini |
resPath | string | /doconut-res | Diterima untuk konsistensi dengan widget Doconut lainnya; widget konverter tidak membangun URL apa pun darinya |
maxUploadMb | number | 25 | Hanya pemeriksaan pra-sisi klien; server menegakkan batasnya sendiri |
licenseUrl | string | null | null | Mengubah pemberitahuan watermark pada layar hasil menjadi tautan |
labels | object | {} | Menimpa setiap subset string bahasa Inggris widget |
Callback
| Callback | Terjadi ketika | Muatan |
|---|---|---|
onReady() | Widget telah merender layar drop-nya | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open berhasil | Token sumber, jumlah halaman, ekstensi sumber (tanpa titik di depan), target yang diizinkan |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run berhasil | Respons run ditambah target yang diminta |
onDownload({ downloadName, downloadToken }) | Pengguna mengklik Unduh | Terjadi bersamaan dengan unduhan bawaan browser |
onError({ phase, message }) | Permintaan open atau run gagal | phase adalah 'open' atau 'run'; message adalah error server yang disanitasi |
Callback yang melempar error ditangkap dan dicatat; itu tidak pernah menghentikan alur widget.
Handle imperatif
Doconut.convert() mengembalikan instance widget:
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // File dari milik Anda sendiri <input type="file" id="picker">
conv.reset(); // kembali ke layar drop; tidak memicu ulang onReady
conv.loadFile(file); // memulai alur dengan File; tidak melakukan apa-apa kecuali widget berada di layar dropnya
conv.destroy(); // menghapus pendengar, mengosongkan mount; instance tidak dapat digunakan setelah iniLabel
Setiap string memiliki default bahasa Inggris; labels menimpa setiap subset dan sisanya tetap bahasa Inggris. Fragmen yang berubah pada waktu berjalan menggunakan {placeholders}, seperti uploading: 'Uploading {name}…' dan pages: '{n} pages'.
| Kunci | Default bahasa Inggris |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could not reach the server. Please check your connection and try again. |
Kunci tambahan mencakup aria-label zona drop (dropAriaLabel), teks alt pratinjau (previewAlt, resultAlt), bentuk tautan dari pemberitahuan watermark yang digunakan dengan licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), respons yang tidak dapat dibaca (badResponse) dan pengumuman aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
Error JSON dari server ditampilkan sebagaimana ditulis server; serverError hanya digunakan ketika respons gagal tidak membawa error JSON, seperti 404 pada widget yang dinonaktifkan.
Tema
Widget menambahkan kelas dcw ke elemen mount-nya dan membaca warna, radius, serta font dari properti khusus CSS, sehingga Anda dapat menata temanya tanpa menyentuh bagian internalnya:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}Bawaan: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, dan font UI sistem untuk --dcw-font.
Bangun frontend Anda sendiri
Widget merupakan klien untuk kontrak HTTP ini pada DocImage.axd. Rute-rute menjawab 404 sampai AddConverterWidget() dipanggil. Kesalahan menyertakan badan JSON, { "error": "..." }, kecuali pada tabel yang menyatakan "hanya status". Nilai ?convert= yang tidak dikenal menjawab 400.
| Rute | Tujuan | Respons sukses |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, satu berkas) | Unggah dan buka dokumen sumber | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Konversi sumber yang diunggah ke target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Alirkan berkas yang telah dikonversi | 200 — berkas, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt dalam respons open tidak memiliki titik di depan ("docx") — berlawanan dengan parameter sourceExtension dari ConvertAsync. allowedTargets mencantumkan nama target huruf kecil ("pdf", "html", …); berikan salah satunya sebagai target, yang dicocokkan tanpa memperhatikan huruf besar/kecil. open menggunakan berkas pertama dalam badan multipart.
resultToken adalah null, dan resultPages adalah 0, ketika hasil tidak dapat dipratinjau. downloadName adalah nama berkas sumber dengan ekstensi target.
Gambar pratinjau menggunakan rute gambar penampil standar, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, dengan token dari open atau resultToken dari run. Widget meminta width=240.
Sumber yang diunggah disimpan selama 30 menit setelah terakhir dibaca; setelah itu, run menjawab 404 dan berkas harus dibuka kembali. downloadToken mendapatkan jendela 30 menitnya sendiri ketika konversi selesai. resultToken adalah token penampil biasa untuk mempratinjau hasil; ketika hasil dapat dipratinjau, nilainya sama dengan downloadToken.
| Rute | Status | Kapan | Badan |
|---|---|---|---|
| apa saja | 404 | Widget tidak diaktifkan (AddConverterWidget() tidak pernah dipanggil) | hanya status |
| apa saja | 405 | Verba salah (open/run memerlukan POST, download memerlukan GET) | hanya status |
open | 400 | Bukan unggahan multipart | Expected a multipart file upload. |
open | 400 | Tidak ada berkas, atau berkas kosong | No file uploaded. |
open | 400 | Tipe yang tidak dapat dikonversi | This file type cannot be converted. |
open | 403 | Tipe berkas memerlukan kemampuan yang tidak diberikan lisensi (berkas DICOM tanpa Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Unggahan melebihi MaxUploadMb (tetapi tidak melebihi batas IIS) | File is too large. |
run | 400 | Token yang tidak terbentuk dengan benar (bukan GUID) | Invalid token. |
run | 400 | Sebuah target yang tidak dapat diurai menjadi ConversionTarget | Unknown target format. |
run | 400 | Target yang tidak ada dalam allowedTargets | That target format is not available for this file. |
run | 404 | Unggahan kedaluwarsa atau tidak pernah dibuka | Upload expired — please re-open the file. |
open, run | 500 | Pemrosesan gagal | Pesan yang disanitasi |
download | 400 / 404 | Token unduhan yang tidak terbentuk dengan benar, tidak dikenal, atau kedaluwarsa | hanya status |
Siklus lengkap dengan fetch:
// file: File yang akan dikonversi, misalnya dari <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: unggah file
const form = new FormData();
form.append('file', file, file.name);
const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
if (!openResp.ok) throw new Error((await openResp.json()).error);
const opened = await openResp.json();
// 2. run: konversi ke PDF ketika diizinkan, jika tidak ke target pertama yang diizinkan
const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
'&convert=run&target=' + target, { method: 'POST' });
if (!runResp.ok) throw new Error((await runResp.json()).error);
const converted = await runResp.json();
// 3. download: GET sederhana yang dapat diikuti browser
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}Endpoint bersifat same-origin: versi ini tidak mendukung CORS. Layani UI Anda dan skrip widget dari origin yang sama dengan Doconut, atau gunakan reverse-proxy pada handler dan jalur sumber daya di bawah origin UI Anda.
Dalam produksi
- Pasang plugin di samping paket inti, dengan versi yang sama:
Install-Package Doconut.NETFramework.Converter. - Tambahkan file lisensi. Letakkan
Doconut.Viewer.Converter.licdi folder yang sama denganDoconut.Viewer.lic. - Atur batas unggahan.
MaxUploadMbdiAddConverterWidgetadalah batas yang ditegakkan oleh Doconut; pertahankanmaxRequestLengthdanmaxAllowedContentLengthdiWeb.configdi atasnya (lihat Batas unggahan), danmaxUploadMbwidget sama dengan itu. - Jangan pernah memblokir konversi di Web Forms (lihat Di Web Forms).
- Buang hasil konversi. Stream yang dikembalikan oleh
ConvertAsyncdipool; membuangnya mengembalikan buffer ke pool.
Farm web
Widget menyimpan setiap unggahan dan hasilnya di memori pada server yang melayani open. Di belakang load balancer tanpa sesi lengket, permintaan run, download, atau pratinjau berikutnya dapat mencapai server lain dan tidak menemukan unggahan. Daftarkan penyimpanan widget bersama yang terenkripsi melalui argumen kedua dari DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // sebuah folder yang dapat dibaca dan ditulis oleh setiap server
store.FarmKey = farmKey; // setidaknya 32 byte, identik pada setiap server
// store.Ttl = TimeSpan.FromMinutes(30); // berapa lama unggahan disimpan (default)
}));- Sebuah server tunggal tidak memerlukan apa pun: tanpa pemanggilan ini penyimpanan dalam memori akan digunakan.
- Unggahan dan hasil dienkripsi saat disimpan pada share (AES-256, encrypt-then-MAC), dan setiap file terikat pada tokennya, sehingga satu token tidak pernah dapat membaca file token lain.
- Pada share, sebuah unggahan atau hasil disimpan selama
Ttlsetelah ditulis; membacanya tidak memperpanjang jendela tersebut. FarmKeyharus setidaknya 32 byte dan sama pada setiap server. Muat dari penyimpanan rahasia; jangan pernah menuliskannya secara keras. Registrasi melemparkanArgumentExceptionketikaRootPathtidak ada atauFarmKeylebih pendek dari 32 byte.- Arahkan
RootPathke lokasi bersama yang sama yang digunakan oleh penampil terdistribusi.
Referensi API
Facade dan opsi widget berada di namespace Doconut; ConversionTarget berada di Doconut.Configs.Conversion. ConverterPlugin berada di Doconut.Plugins.Converter.
DocumentConverter
public sealed class DocumentConverter
{
public Task<Stream> ConvertAsync(
string filePath, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> ConvertAsync(
Stream source, string sourceExtension, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);
public Task<Stream> HtmlToWordAsync(
Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
CancellationToken ct = default);
}Di-resolve dari DoconutHost.Services; konstruktor bersifat internal. sourceExtension menyertakan titik di depan. HtmlToWordAsync menulis file .doc ketika outputFormat adalah ConversionTarget.Doc, dan file .docx untuk nilai lain apa pun.
ConversionTarget
45 format output yang tercantum dalam Format target.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Diatur melalui DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), yang mengembalikan DoconutOptions sehingga pemanggilan dapat dirantai.
Pemecahan Masalah
| Gejala | Penyebab | Solusi |
|---|---|---|
Setiap permintaan menjawab 500 yang kosong setelah menambahkan plugin; log peristiwa Windows (sumber ASP.NET) menunjukkan The Converter plugin is registered via AddPlugin but no active license grants Converter. | Tidak ada lisensi, file TRIAL, lisensi tanpa Converter, atau lisensi berbayar di luar jendela versinya | Pasang lisensi yang memberikan Converter, atau hapus AddPlugin<ConverterPlugin>() |
Setiap permintaan menjawab 500 yang kosong; log peristiwa menunjukkan AddConverterWidget() was called but the Converter plugin is not registered. | Widget diaktifkan tanpa plugin-nya | Tambahkan options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
Menyelesaikan DocumentConverter menghasilkan No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin tidak terdaftar | Tambahkan AddPlugin<ConverterPlugin>() di DoconutHost.Initialize |
| Konversi Web Forms tidak pernah mengembalikan hasil | Halaman terblokir pada ConvertAsync | Gunakan Async="true" dan RegisterAsyncTask |
| Konversi aliran mengatakan format tidak didukung | sourceExtension tidak memiliki titik di depan | Berikan ".xlsx", bukan "xlsx" |
ConvertAsync menghasilkan Converting '.dcm' requires the Dicom capability license. | Sumber DICOM, dan lisensi tidak memberikan Dicom | Gunakan lisensi yang memberikan Dicom |
| Output berwatermark | Lisensi bersifat sementara (Demo/NFR) | Gunakan lisensi berbayar yang memberikan Converter |
Widget dimuat tetapi permintaannya mengembalikan 404 | AddConverterWidget() tidak dipanggil, atau basePath tidak '/DocImage.axd' | Panggil AddConverterWidget(); atur basePath: '/DocImage.axd' |
| Unggahan besar menampilkan halaman error IIS alih-alih pesan widget | maxRequestLength / maxAllowedContentLength berada di bawah MaxUploadMb | Tingkatkan batas Web.config di atas MaxUploadMb |
open menjawab 403 Converting this file type requires the Dicom capability license. | Unggahan DICOM, dan lisensi tidak memberikan Dicom | Gunakan lisensi yang memberikan Dicom |
run menjawab 400 That target format is not available for this file. | Target bukan salah satu allowedTargets sumber | Tawarkan hanya allowedTargets dari convert=open |
run atau download menjawab 404 (Upload expired — please re-open the file. dari run) | Jendela 30 menit telah berakhir, atau server lain dalam farm tidak memiliki unggahan tersebut | Buka kembali file tersebut; dalam farm, daftarkan AddDoconutDistributedWidgets |
| Widget gagal ketika UI berada pada origin lain | Endpoint tidak mendukung CORS | Layani UI dari origin yang sama, atau gunakan reverse-proxy pada jalur Doconut |
| Tema tidak diterapkan | Variabel diatur pada induk atau pada elemen di dalam mount; aturan .dcw milik widget mengaturnya pada mount | Targetkan mount itu sendiri: #doconut-convert.dcw atau #doconut-convert |
Catatan Kerangka
Dibandingkan dengan paket ASP.NET Core, paket ini hanya berbeda dalam hal hosting; API, kontrak endpoint, skrip widget, dan aturan lisensi tetap sama.
- Registrasi berada di
Application_Start, melaluiDoconutHost.Initialize, bukan dibuilder.Services.AddDoconut. Layanan sepertiAddDoconutDistributedWidgetsdimasukkan pada argumen keduanya. - Endpoint dilayani oleh
DocImage.axddan skrip olehDoconutResourceModule, keduanya terdaftar diWeb.config, bukan diUseDoconut()danUseDoconutResources(). Widget membutuhkanbasePath: '/DocImage.axd'. - Kegagalan startup muncul sebagai
500kosong pada setiap permintaan, dengan alasannya di log peristiwa Windows. - Unggahan dibaca secara penuh oleh ASP.NET sebelum Doconut melihatnya, sehingga batas IIS harus di atas
MaxUploadMb. - Halaman Web Forms tidak boleh terblokir pada konversi; lihat Di Web Forms.
- Hanya Windows, seperti paket .NET Framework lainnya.
Apakah halaman ini membantu?