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.

PermukaanKapan 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

powershell
Install-Package Doconut.NETFramework.Converter

Untuk mengunci plugin ke rilis yang dijelaskan dalam dokumentasi ini:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

Pastikan 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.

csharp
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:

text
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 lisensiMulaiOutput konversi
Lisensi penampil berbayar yang memberikan Converter, dalam jendela versinyaMulaiBersih — watermarked: false
Lisensi Sementara Aktif (Demo/NFR)MulaiMengonversi, dengan watermark evaluasi — watermarked: true
Lisensi Sementara Kedaluwarsa (Demo/NFR)MulaiMengonversi, dengan watermark evaluasi — watermarked: true
Tidak ada lisensi, file TRIAL warisan, lisensi tanpa Converter, atau lisensi berbayar di luar jendela versinyaApplication_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.

csharp
// Resolusi DocumentConverter dari DoconutHost.Services; konstruktornya internal, jadi jangan pernah `new`-kan itu.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension mencakup titik di depannya. password bernilai null kecuali dokumen dilindungi.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// 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:

csharp
[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:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// 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:

text
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

Tidak 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:

csharp
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:

text
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 handler DocImage.axd dari Web.config.
  • Skrip dan endpoint bersifat independen. Modul sumber daya menyajikan doconutConverter.js terlepas dari apakah widget diaktifkan atau tidak. Tanpa AddConverterWidget(), widget dimuat, menggambar zona drop-nya, dan tampak sepenuhnya benar — dan aksi pertamanya menjawab 404.

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:

xml
<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

html
<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

OpsiTipeBawaanCatatan
basePathstring/doconutURL endpoint. Atur '/DocImage.axd' pada paket ini
resPathstring/doconut-resDiterima untuk konsistensi dengan widget Doconut lainnya; widget konverter tidak membangun URL apa pun darinya
maxUploadMbnumber25Hanya pemeriksaan pra-sisi klien; server menegakkan batasnya sendiri
licenseUrlstring | nullnullMengubah pemberitahuan watermark pada layar hasil menjadi tautan
labelsobject{}Menimpa setiap subset string bahasa Inggris widget

Callback

CallbackTerjadi ketikaMuatan
onReady()Widget telah merender layar drop-nya—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open berhasilToken sumber, jumlah halaman, ekstensi sumber (tanpa titik di depan), target yang diizinkan
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run berhasilRespons run ditambah target yang diminta
onDownload({ downloadName, downloadToken })Pengguna mengklik UnduhTerjadi bersamaan dengan unduhan bawaan browser
onError({ phase, message })Permintaan open atau run gagalphase 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:

javascript
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 ini

Label

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'.

KunciDefault bahasa Inggris
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould 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:

css
#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.

RuteTujuanRespons sukses
POST /DocImage.axd?convert=open (multipart, satu berkas)Unggah dan buka dokumen sumber200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Konversi sumber yang diunggah ke target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Alirkan berkas yang telah dikonversi200 — 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.

RuteStatusKapanBadan
apa saja404Widget tidak diaktifkan (AddConverterWidget() tidak pernah dipanggil)hanya status
apa saja405Verba salah (open/run memerlukan POST, download memerlukan GET)hanya status
open400Bukan unggahan multipartExpected a multipart file upload.
open400Tidak ada berkas, atau berkas kosongNo file uploaded.
open400Tipe yang tidak dapat dikonversiThis file type cannot be converted.
open403Tipe berkas memerlukan kemampuan yang tidak diberikan lisensi (berkas DICOM tanpa Dicom)Converting this file type requires the Dicom capability license.
open413Unggahan melebihi MaxUploadMb (tetapi tidak melebihi batas IIS)File is too large.
run400Token yang tidak terbentuk dengan benar (bukan GUID)Invalid token.
run400Sebuah target yang tidak dapat diurai menjadi ConversionTargetUnknown target format.
run400Target yang tidak ada dalam allowedTargetsThat target format is not available for this file.
run404Unggahan kedaluwarsa atau tidak pernah dibukaUpload expired — please re-open the file.
open, run500Pemrosesan gagalPesan yang disanitasi
download400 / 404Token unduhan yang tidak terbentuk dengan benar, tidak dikenal, atau kedaluwarsahanya status

Siklus lengkap dengan fetch:

javascript
// 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

  1. Pasang plugin di samping paket inti, dengan versi yang sama: Install-Package Doconut.NETFramework.Converter.
  2. Tambahkan file lisensi. Letakkan Doconut.Viewer.Converter.lic di folder yang sama dengan Doconut.Viewer.lic.
  3. Atur batas unggahan. MaxUploadMb di AddConverterWidget adalah batas yang ditegakkan oleh Doconut; pertahankan maxRequestLength dan maxAllowedContentLength di Web.config di atasnya (lihat Batas unggahan), dan maxUploadMb widget sama dengan itu.
  4. Jangan pernah memblokir konversi di Web Forms (lihat Di Web Forms).
  5. Buang hasil konversi. Stream yang dikembalikan oleh ConvertAsync dipool; 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:

csharp
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 Ttl setelah ditulis; membacanya tidak memperpanjang jendela tersebut.
  • FarmKey harus setidaknya 32 byte dan sama pada setiap server. Muat dari penyimpanan rahasia; jangan pernah menuliskannya secara keras. Registrasi melemparkan ArgumentException ketika RootPath tidak ada atau FarmKey lebih pendek dari 32 byte.
  • Arahkan RootPath ke 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

csharp
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

csharp
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

GejalaPenyebabSolusi
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 versinyaPasang 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-nyaTambahkan 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 terdaftarTambahkan AddPlugin<ConverterPlugin>() di DoconutHost.Initialize
Konversi Web Forms tidak pernah mengembalikan hasilHalaman terblokir pada ConvertAsyncGunakan Async="true" dan RegisterAsyncTask
Konversi aliran mengatakan format tidak didukungsourceExtension tidak memiliki titik di depanBerikan ".xlsx", bukan "xlsx"
ConvertAsync menghasilkan Converting '.dcm' requires the Dicom capability license.Sumber DICOM, dan lisensi tidak memberikan DicomGunakan lisensi yang memberikan Dicom
Output berwatermarkLisensi bersifat sementara (Demo/NFR)Gunakan lisensi berbayar yang memberikan Converter
Widget dimuat tetapi permintaannya mengembalikan 404AddConverterWidget() tidak dipanggil, atau basePath tidak '/DocImage.axd'Panggil AddConverterWidget(); atur basePath: '/DocImage.axd'
Unggahan besar menampilkan halaman error IIS alih-alih pesan widgetmaxRequestLength / maxAllowedContentLength berada di bawah MaxUploadMbTingkatkan batas Web.config di atas MaxUploadMb
open menjawab 403 Converting this file type requires the Dicom capability license.Unggahan DICOM, dan lisensi tidak memberikan DicomGunakan lisensi yang memberikan Dicom
run menjawab 400 That target format is not available for this file.Target bukan salah satu allowedTargets sumberTawarkan 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 tersebutBuka kembali file tersebut; dalam farm, daftarkan AddDoconutDistributedWidgets
Widget gagal ketika UI berada pada origin lainEndpoint tidak mendukung CORSLayani UI dari origin yang sama, atau gunakan reverse-proxy pada jalur Doconut
Tema tidak diterapkanVariabel diatur pada induk atau pada elemen di dalam mount; aturan .dcw milik widget mengaturnya pada mountTargetkan 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, melalui DoconutHost.Initialize, bukan di builder.Services.AddDoconut. Layanan seperti AddDoconutDistributedWidgets dimasukkan pada argumen keduanya.
  • Endpoint dilayani oleh DocImage.axd dan skrip oleh DoconutResourceModule, keduanya terdaftar di Web.config, bukan di UseDoconut() dan UseDoconutResources(). Widget membutuhkan basePath: '/DocImage.axd'.
  • Kegagalan startup muncul sebagai 500 kosong 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?