افزونه مبدل

سندها را به ۴۵ قالب هدف تبدیل کنید

افزونه مبدل Doconut را به یک سرویس تبدیل سند تبدیل می‌کند. این موتور پشت نمایه عمومی DocumentConverter را فراهم می‌کند و — به صورت اختیاری — یک ویجت آماده توسط DocImage.axd ارائه می‌دهد، به طوری که می‌توانید اسناد را از C#، از ویجت، یا از یک رابط کاربری که خود می‌نویسید، تبدیل کنید.

SurfaceUse it when
DocumentConverter (C#)شما در سرور تبدیل می‌کنید، بدون درگیر شدن مرورگر
Drop-in widget (doconutConverter.js)شما یک صفحه بارگذاری، تبدیل و دانلود آماده در صفحه خود می‌خواهید
HTTP endpoints on DocImage.axd (?convert=open|run|download)شما رابط کاربری تبدیل خود را بر پایه قرارداد مستند سرور می‌سازید

نصب بسته

powershell
Install-Package Doconut.NETFramework.Converter

برای قفل کردن افزونه به نسخه‌ای که این مستندات توصیف می‌کند:

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

بسته مبدل را با همان نسخه‌ای که Doconut.NETFramework دارد، نگه دارید.

فایل مجوز افزونه، Doconut.Viewer.Converter.lic، در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد، قرار می‌گیرد؛ همراه با مجوز نمایشگر خوانده می‌شود.

ثبت افزونه

هر افزونه به همان روش ثبت می‌شود: AddPlugin<TPlugin>() در DoconutHost.Initialize، فراخوانی شده از Application_Start.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

این تمام آنچه نمایه C# نیاز دارد است. ویجت و نقاط انتهایی HTTP آن یک گزینه جداگانه هستند، AddConverterWidget() (به ویجت آماده مراجعه کنید).

افزونه به مجوزی نیاز دارد که قابلیت Converter را بدهد. بدون آن، DoconutHost.Initialize از 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.

در System.Web این به این معنی است که هر درخواست یک 500 خالی پاسخ می‌دهد و دلیل فقط در لاگ رویدادهای ویندوز (منبع ASP.NET) موجود است. این برای عدم وجود مجوز، یک فایل TRIAL قدیمی، مجوز بدون Converter، و یک مجوز پرداخت‌شده که خارج از بازه نسخه‌ای آن استفاده می‌شود، پرتاب می‌کند. مجوزهای موقت Demo/NFR پذیرفته می‌شوند. به راه‌اندازی مجوز مراجعه کنید.

مجوزدهی و واترمارک

License stateStartupConversion output
مجوز نمایشگر پرداخت‌شده که Converter را می‌دهد، در بازه نسخه‌ای خودشروع می‌شودتمیز — watermarked: false
مجوز موقت فعال (Demo/NFR)شروع می‌شودتبدیل می‌کند، با واترمارک ارزیابی — watermarked: true
مجوز موقت منقضی‌شده (Demo/NFR)شروع می‌شودتبدیل می‌کند، با واترمارک ارزیابی — watermarked: true
بدون مجوز، یک فایل TRIAL قدیمی، مجوز بدون Converter، یا یک مجوز پرداخت‌شده خارج از بازه نسخه‌ایApplication_Start پرتاب می‌کند؛ هر درخواست یک 500 خالی پاسخ می‌دهد—

نمایه DocumentConverter و هندلر ?convert=run ویجت همان قانون را اعمال می‌کنند. یک یکپارچه‌سازی می‌تواند بر روی یک مجوز ارزیابی قبل از خرید ساخته و به‌صورت انتها به انتها تست شود — فقط بایت‌های خروجی تغییر می‌کنند.

یک منبع DICOM (.dcm, .ima) نیز به قابلیت Dicom نیاز دارد. بدون آن، ConvertAsync یک LicenseException (Converting '.dcm' requires the Dicom capability license.) پرتاب می‌کند و open ویجت پاسخ می‌دهد 403.

استفاده از C#

هر تبدیل یک MemoryStream قابل جستجو که در موقعیت ۰ قرار دارد، برمی‌گرداند. DocumentConverter بدون وضعیت است: آن را از DoconutHost.Services در هر جایی که نیاز دارید دریافت کنید و آزادانه دوباره استفاده کنید.

csharp
// DocumentConverter را از DoconutHost.Services حل کنید؛ سازنده آن داخلی است، بنابراین هرگز `new` آن را استفاده نکنید.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension شامل نقطهٔ پیش‌رو است. password در صورتی که سند محافظت نشده باشد، null است.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: یک Stream که HTML را نگه می‌دارد تا به یک سند Word برگردانده شود، مانند نتیجهٔ WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

دو جزئیاتی که به راحتی می‌توان اشتباه کرد: sourceExtension در بارگذاری بیش از یک جریان باید نقطه پیشرو را شامل شود (".xlsx"، نه "xlsx")، در غیر این صورت حل نمی‌شود. و با وجود نامش، WordToHtmlAsync مقدار Task<Stream> را برمی‌گرداند، نه Task<string> — سند HTML (تصاویر به صورت Base64 تعبیه شده) به‌صورت یک جریان می‌آید، همانند هر نتیجه دیگر.

صدا کننده مالک MemoryStream ای است که یک تبدیل برمی‌گرداند و باید پس از کپی یا بازگرداندن آن، آن را آزاد کند (MVC's File(stream, …) برای شما آن را آزاد می‌کند). از ساخت یا آزاد کردن DocumentConverter به‌صورت خودتان خودداری کنید — سازنده آن داخلی است.

در یک کنترلر MVC 5

عمل را به صورت ناهمزمان کنید و تبدیل را await کنید:

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");
}

در Web Forms: هرگز تبدیل را مسدود نکنید

یک صفحه Web Forms در یک زمینه درخواست تک‌نخی اجرا می‌شود. ConvertAsync پس از تکمیل در همان زمینه ادامه می‌یابد، بنابراین صفحه‌ای که به‌صورت همزمان منتظر آن باشد — .Result، .Wait()، .GetAwaiter().GetResult() — همان رشته‌ای را که تبدیل برای اتمام به آن نیاز دارد، اشغال می‌کند. درخواست هرگز برنمی‌گردد. مرورگر می‌چرخد، IIS هیچ‌چیزی لاگ نمی‌کند، و بقیه سایت به کار خود ادامه می‌دهد، بنابراین به‌نظر می‌رسد که تبدیل کند است نه یک بن‌بست.

صفحه را Async="true" علامت‌گذاری کنید و تبدیل را به‌عنوان یک کار ناهمزمان صفحه اجرا کنید:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: دستور @Page نیاز به Async=\"true\" دارد، و تبدیل به عنوان یک کار ناهمزمان صفحه اجرا می‌شود.
// مسدود کردن آن به جای این (.Result, .Wait(), .GetAwaiter().GetResult()) باعث قفل شدن درخواست می‌شود:
// هرگز برنمی‌گردد و هیچ‌چیزی ثبت نمی‌شود.
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، نه HttpContext.Current: پس از await، دومی می‌تواند null باشد.
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

بدون Async="true" در دستور @Page، RegisterAsyncTask به‌صورت ساکت نادیده گرفته می‌شود. پس از یک await، از Context صفحه استفاده کنید؛ HttpContext.Current می‌تواند آنجا null باشد.

فرمت‌های هدف

ConversionTarget (فضای نام Doconut.Configs.Conversion) دارای ۴۵ عضو است:

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

هر منبع به همهٔ هدف‌ها تبدیل نمی‌شود: هر خانوادهٔ فرمت منبع (Word، Excel، PowerPoint، PDF، CAD، Image، Email، Diagram، Project، PSD، سند وب، DICOM) مجموعهٔ خاص خود را از هدف‌های مجاز دارد. تبدیل یک منبع DICOM (.dcm، .ima) همچنین به مجوزی نیاز دارد که قابلیت Dicom را بدهد؛ هدف‌های آن عبارتند از Pdf، Png، Jpeg، Bmp، Tiff و Gif. این enum را به‌عنوان فهرست هدف UI خود به‌صورت ثابت کدنویسی نکنید: ?convert=open برای فایل بارگذاری‌شده allowedTargets را برمی‌گرداند و این همان چیزی است که باید انتخاب‌کننده را هدایت کند.

ویجت Drop-in

فعال‌سازی نقطه‌های انتهایی

نقطه‌های انتهایی ?convert=open|run|download ویجت توسط DocImage.axd سرویس می‌شوند و به‌صورت پیش‌فرض غیرفعال هستند. آنها را در کنار ثبت‌نام افزونه فعال کنید:

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 تمام بارگذاری را قبل از اینکه Doconut آن را ببیند می‌خواند: maxRequestLength (KB) را نگه دارید و
// maxAllowedContentLength (bytes) را در Web.config بالاتر از MaxUploadMb ویجت تنظیم کنید.

AddConverterWidget() بدون آرگومان، ویجت را با مقادیر پیش‌فرض (MaxUploadMb = ۲۵) فعال می‌کند. این به‌تنهایی حق تبدیل را نمی‌دهد: به AddPlugin<ConverterPlugin>() نیاز دارد، یا DoconutHost.Initialize خطا می‌اندازد:

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.

دو مورد برای بررسی زمانی که ویجت رفتار نامناسب دارد:

  • basePath: '/DocImage.axd'. پیش‌فرض ویجت، /doconut، نقطهٔ انتهایی ASP.NET Core است. در این بسته، نقطه‌های انتهایی، هندلر DocImage.axd از Web.config هستند.
  • اسکریپت و نقطه‌های انتهایی مستقل هستند. ماژول منبع doconutConverter.js را سرویس می‌دهد چه ویجت فعال باشد چه نباشد. بدون AddConverterWidget()، ویجت بارگیری می‌شود، ناحیهٔ رهاسازی خود را می‌کشد و کاملاً صحیح به‌نظر می‌رسد — و اولین عمل آن به 404 پاسخ می‌دهد.

حدود بارگذاری

ASP.NET تمام بدنهٔ درخواست را پیش از اجرای DocImage.axd می‌خواند. یک بارگذاری بالاتر از MaxUploadMb اما زیر محدودیت‌های میزبان، JSON مخصوص ویجت را به صورت 413 دریافت می‌کند (File is too large.). یک بارگذاری بالاتر از محدودیت‌های میزبان ابتدا توسط IIS رد می‌شود، همراه با صفحهٔ خطایی که ویجت نمی‌تواند بخواند. هر دو محدودیت میزبان را در Web.config بالاتر از سقف ویجت نگه دارید:

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>

جاسازی آن

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) یک انتخابگر CSS یا یک عنصر را می‌گیرد، اگر نقطهٔ نصب یافت نشود استثنا می‌اندازد و یک دستگیره برمی‌گرداند. ویجت فایلی را بارگذاری می‌کند، پیش‌نمایشی از صفحهٔ ۱ نشان می‌دهد، به کاربر اجازه می‌دهد یکی از allowedTargets را انتخاب کند، تبدیل می‌کند، زمانی که امکان داشته باشد نتیجه را پیش‌نمایش می‌دهد و امکان دانلود را فراهم می‌کند.

گزینه‌ها

گزینهنوعپیش‌فرضیادداشت‌ها
basePathstring/doconutآدرس URL نقطهٔ انتهایی. '/DocImage.axd' را روی این بسته تنظیم کنید
resPathstring/doconut-resبرای سازگاری با سایر ویجت‌های Doconut پذیرفته شده است؛ ویجت مبدل هیچ URLی از آن نمی‌سازد
maxUploadMbnumber25فقط پیش‌بررسی سمت کلاینت؛ سرور سقف خود را اعمال می‌کند
licenseUrlstring | nullnullاعلان واترمارک روی صفحهٔ نتیجه را به یک لینک تبدیل می‌کند
labelsobject{}هر زیرمجموعه‌ای از رشته‌های انگلیسی ویجت را بازنویسی می‌کند

فراخوانی‌ها

فراخوانیزمان فعال شدنداده
onReady()ویجت صفحهٔ دراپ خود را رندر کرده است—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })موفقیت ?convert=openتوکن منبع، تعداد صفحات، پسوند منبع (بدون نقطهٔ پیش‌رو)، هدف‌های مجاز
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })موفقیت ?convert=runپاسخ اجرا به علاوه target درخواست شده
onDownload({ downloadName, downloadToken })کاربر بر دانلود کلیک می‌کندبه‌همراه دانلود مرورگر نیز فعال می‌شود
onError({ phase, message })یک درخواست باز یا اجرا شکست می‌خوردphase برابر با 'open' یا 'run' است؛ message خطای سرور تصفیه‌شده است

یک فراخوانی که استثنا می‌اندازد، گرفته و ثبت می‌شود؛ هرگز جریان ویجت را قطع نمی‌کند.

دستگیره امری

Doconut.convert() نمونهٔ ویجت را برمی‌گرداند:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // یک File از خودتان <input type="file" id="picker">
conv.reset();         // بازگشت به صفحهٔ رها کردن؛ دوباره onReady اجرا نمی‌شود
conv.loadFile(file);  // جریان را با یک File شروع می‌کند؛ no-op مگر اینکه widget در صفحهٔ رها کردن باشد
conv.destroy();       // listenerها را حذف می‌کند، mount را خالی می‌کند؛ این instance پس از این قابل استفاده نیست

برچسب‌ها

هر رشته‌ای مقدار پیش‌فرض انگلیسی دارد؛ labels هر زیرمجموعه‌ای را بازنویسی می‌کند و بقیه به انگلیسی می‌مانند. بخش‌هایی که در زمان اجرا تغییر می‌کنند از {placeholders} استفاده می‌کنند، مانند uploading: 'Uploading {name}…' و pages: '{n} pages'.

کلیدپیش‌فرض انگلیسی
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.

کلیدهای دیگر شامل aria-label ناحیهٔ دراپ (dropAriaLabel)، متن‌های پیش‌نمایش alt (previewAlt، resultAlt)، فرم پیوندی اعلان واترمارک استفاده‌شده با licenseUrl (watermarkNoticePrefix، watermarkNoticeLink، watermarkNoticeSuffix)، یک پاسخ غیرقابل خواندن (badResponse) و اعلان‌های aria-live (annReady، annUploading، annLoaded، annLoadedNoTargets، annConverting، annDone، annError) می‌باشد.

خطای JSON از سرور همان‌گونه که سرور نوشته است نشان داده می‌شود؛ serverError فقط زمانی استفاده می‌شود که پاسخ ناموفق هیچ خطای JSONی نداشته باشد، مانند 404 یک ویجت غیرفعال.

تم‌گذاری

ویجت کلاس dcw را به عنصر نصب خود اضافه می‌کند و رنگ‌ها، شعاع و قلم آن را از ویژگی‌های سفارشی CSS می‌خواند، بنابراین می‌توانید بدون دست‌کاری داخلی‌ها آن را تم‌گذاری کنید:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

پیش‌فرض‌ها: --dcw-accent: #2b6cb0، --dcw-bg: #ffffff، --dcw-fg: #1a202c، --dcw-muted: #718096، --dcw-border: #cbd5e0، --dcw-radius: 8px، و یک قلم UI سیستمی برای --dcw-font.

ساخت رابط کاربری خود

ویجت یک کلاینت برای این قرارداد HTTP بر روی DocImage.axd است. مسیرها تا زمانی که AddConverterWidget() فراخوانی شود، به 404 پاسخ می‌دهند. خطاها یک بدنه JSON، { "error": "..." }، حمل می‌کنند، به‌جز مواردی که جدول می‌گوید «فقط وضعیت». یک مقدار ناشناخته ?convert= به 400 پاسخ می‌دهد.

مسیرهدفپاسخ موفق
POST /DocImage.axd?convert=open (چندبخشی، یک فایل)بارگذاری و باز کردن یک سند منبع200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>تبدیل منبع بارگذاری‌شده به target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>پخش فایل تبدیل‌شده200 — فایل، Content-Disposition: attachment، Cache-Control: no-store

sourceExt در پاسخ open نقطهٔ پیش‌رو ندارد ("docx") — برعکس پارامتر sourceExtension از ConvertAsync. allowedTargets فهرست نام‌های هدف با حروف کوچک را نشان می‌دهد ("pdf"، "html"، …)؛ یکی از آن‌ها را به عنوان target بدهید، که به‌صورت بدون حساسیت به حروف بزرگ/کوچک مقایسه می‌شود. open از اولین فایل در بدنهٔ چندبخشی استفاده می‌کند.

resultToken برابر با null است، و resultPages برابر با 0 است، وقتی نتیجه قابل پیش‌نمایش نیست. downloadName نام فایل منبع با پسوند هدف است.

تصاویر پیش‌نمایش از مسیر تصویر استاندارد ویور، /DocImage.axd?token={token}&page=1&thumb=1&width={px}، استفاده می‌کنند، با token از open یا resultToken از run. ویجت درخواست width=240 را می‌کند.

سندهای بارگذاری‌شده به مدت ۳۰ دقیقه پس از آخرین خوانده شدن نگهداری می‌شوند؛ پس از آن، run به 404 پاسخ می‌دهد و فایل باید دوباره باز شود. downloadToken پنجرهٔ ۳۰‑دقیقهٔ خود را پس از تکمیل تبدیل دریافت می‌کند. resultToken یک توکن ویور معمولی برای پیش‌نمایش نتیجه است؛ وقتی نتیجه قابل پیش‌نمایش باشد، همان مقدار downloadToken است.

مسیروضعیتزمانبدنه
هر404ویجت فعال نیست (AddConverterWidget() هرگز فراخوانی نشده است)فقط وضعیت
هر405فعل نادرست (open/run نیاز به POST دارند، download نیاز به GET دارد)فقط وضعیت
open400بارگذاری چندبخشی نیستExpected a multipart file upload.
open400فایلی وجود ندارد یا خالی استNo file uploaded.
open400نوعی که قابل تبدیل نیستThis file type cannot be converted.
open403نوع فایل به قابلیتی نیاز دارد که مجوز آن را نمی‌دهد (فایل DICOM بدون Dicom)Converting this file type requires the Dicom capability license.
open413بارگذاری از MaxUploadMb فراتر می‌رود (اما از محدودیت‌های IIS نیست)File is too large.
run400توکن خراب (نه GUID)Invalid token.
run400یک target که به ConversionTarget تجزیه نمی‌شودUnknown target format.
run400هدف موجود در allowedTargets نیستThat target format is not available for this file.
run404بارگذاری منقضی شده یا هرگز باز نشده استUpload expired — please re-open the file.
open, run500پردازش ناموفق بودیک پیام پاک‌سازی‌شده
download400 / 404توکن دانلود خراب، ناشناخته یا منقضی شدهفقط وضعیت

یک مسیر کامل با fetch:

javascript
// file: فایلی که باید تبدیل شود، برای مثال از یک <input type="file">.
async function convertFile(file) {
  const base = '/DocImage.axd';

  // 1. open: فایل را بارگذاری کنید
  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: به PDF تبدیل کنید وقتی مجاز است، در غیر این صورت به اولین هدف مجاز
  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 ساده که مرورگر می‌تواند دنبال کند
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

نقطه‌های انتهایی هم‌مبدا هستند: این نسخه پشتیبانی CORS ندارد. رابط کاربری و اسکریپت ویجت را از همان مبدا که Doconut قرار دارد سرو کنید، یا هندلر و مسیرهای منبع را تحت مبدا UI خود به‌صورت reverse‑proxy کنید.

در تولید

  1. نصب افزونه در کنار بستهٔ هسته، با همان نسخه: Install-Package Doconut.NETFramework.Converter.
  2. افزودن فایل مجوز. قرار دهید Doconut.Viewer.Converter.lic در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد.
  3. تنظیم محدودیت‌های بارگذاری. MaxUploadMb در AddConverterWidget محدودیتی است که Doconut اعمال می‌کند؛ اطمینان حاصل کنید که maxRequestLength و maxAllowedContentLength در Web.config بالاتر از آن باشند (به محدودیت‌های بارگذاری مراجعه کنید)، و مقدار maxUploadMb ویجت برابر با آن باشد.
  4. هرگز در تبدیل مسدود نشوید در فرم‌های وب (به در فرم‌های وب مراجعه کنید).
  5. نتایج تبدیل را آزاد کنید. جریان ConvertAsync که برمی‌گرداند، در استخر قرار دارد؛ آزادسازی آن بافرهایش را به استخر برمی‌گرداند.

مزارع وب

ویجت هر بارگذاری و نتیجهٔ آن را در حافظهٔ سروری که open را سرویس داده است، نگه می‌دارد. پشت یک تعادل‌بار بدون نشست‌های چسبان، یک درخواست بعدی run، download یا پیش‌نمایش می‌تواند به سرور دیگری برسد و بارگذاری را پیدا نکند. فروشگاه مشترک و رمزگذاری‌شدهٔ ویجت را از طریق آرگومان دوم 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";   // یک پوشه که هر سرور می‌تواند بخواند و بنویسد
        store.FarmKey = farmKey;                   // حداقل ۳۲ بایت، در هر سرور یکسان
        // store.Ttl = TimeSpan.FromMinutes(30);   // مدت زمانی که یک بارگذاری نگه داشته می‌شود (پیش‌فرض)
    }));
  • یک سرور تک‌نقشه به هیچ چیز نیاز ندارد: بدون این فراخوانی، فروشگاه در‑حافظه استفاده می‌شود.
  • بارگذاری‌ها و نتایج در حالت استراحت بر روی اشتراک رمزگذاری می‌شوند (AES-256، encrypt-then-MAC)، و هر فایل به توکن خود متصل است، به‌طوری‌که یک توکن هرگز نمی‌تواند فایل دیگری را بخواند.
  • در اشتراک، یک بارگذاری یا نتیجه به مدت Ttl پس از نوشتن نگه داشته می‌شود؛ خواندن آن این بازه زمانی را تمدید نمی‌کند.
  • FarmKey باید حداقل ۳۲ بایت باشد و در همه سرورها یکسان باشد. آن را از یک مخزن محرمانه بارگذاری کنید؛ هرگز به‌صورت ثابت کد نکنید. ثبت‌نام یک ArgumentException را زمانی که RootPath موجود نیست یا FarmKey کوتاه‌تر از ۳۲ بایت است، پرتاب می‌کند.
  • RootPath را به همان مکان مشترکی که نمایشگر توزیع‌شده استفاده می‌کند، اشاره کنید.

مرجع API

فاساد و گزینه‌های ویجت در فضای نام Doconut قرار دارند؛ ConversionTarget در Doconut.Configs.Conversion است. ConverterPlugin در 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);
}

از DoconutHost.Services حل می‌شود؛ سازنده داخلی است. sourceExtension شامل نقطهٔ پیشرو است. HtmlToWordAsync یک فایل .doc می‌نویسد وقتی outputFormat برابر با ConversionTarget.Doc باشد، و یک فایل .docx برای هر مقدار دیگر.

ConversionTarget

۴۵ قالب خروجی فهرست‌شده در قالب‌های هدف هستند.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

از طریق DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) تنظیم می‌شود، که DoconutOptions را برمی‌گرداند تا فراخوانی‌ها بتوانند زنجیره شوند.

عیب‌یابی

علامتدلیلرفع
هر درخواست یک 500 خالی برمی‌گرداند پس از افزودن افزونه؛ لاگ رویداد ویندوز (منبع ASP.NET) نشان می‌دهد The Converter plugin is registered via AddPlugin but no active license grants Converter.بدون لایسنس، یک فایل TRIAL، لایسنس بدون Converter، یا لایسنس پرداخت‌شده خارج از بازه نسخهٔ آنیک لایسنس که Converter را اعطا می‌کند نصب کنید، یا AddPlugin<ConverterPlugin>() را حذف کنید
هر درخواست یک 500 خالی برمی‌گرداند؛ لاگ رویداد نشان می‌دهد AddConverterWidget() was called but the Converter plugin is not registered.ویجت بدون افزونهٔ خود فعال شده استoptions.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() را اضافه کنید
حل کردن DocumentConverter خطای No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). می‌اندازدConverterPlugin ثبت نشده استAddPlugin<ConverterPlugin>() را در DoconutHost.Initialize اضافه کنید
یک تبدیل Web Forms هرگز باز نمی‌گرددصفحه بر روی ConvertAsync مسدود می‌شوداز Async="true" و RegisterAsyncTask استفاده کنید
تبدیل جریان می‌گوید قالب پشتیبانی نمی‌شودsourceExtension نقطهٔ پیش‌رو ندارد".xlsx" را پاس کنید، نه "xlsx"
ConvertAsync خطای Converting '.dcm' requires the Dicom capability license. می‌اندازدیک منبع DICOM، و لایسنس Dicom را اعطا نمی‌کنداز لایسنس که Dicom را اعطا می‌کند استفاده کنید
خروجی دارای واترمارک استلایسنس موقت است (دمو/NFR)از لایسنس پرداخت‌شده‌ای که Converter را اعطا می‌کند استفاده کنید
ویجت بارگذاری می‌شود اما درخواست‌های آن 404 برمی‌گردانندAddConverterWidget() فراخوانی نشده بود، یا basePath '/DocImage.axd' نیستAddConverterWidget() را فراخوانی کنید؛ basePath: '/DocImage.axd' را تنظیم کنید
یک بارگذاری بزرگ صفحهٔ خطای IIS را نشان می‌دهد به جای پیام ویجتmaxRequestLength / maxAllowedContentLength زیر MaxUploadMb هستندمحدودیت‌های Web.config را بالاتر از MaxUploadMb افزایش دهید
open پاسخ می‌دهد 403 Converting this file type requires the Dicom capability license.یک بارگذاری DICOM، و لایسنس Dicom را اعطا نمی‌کنداز لایسنس که Dicom را اعطا می‌کند استفاده کنید
run پاسخ می‌دهد 400 That target format is not available for this file.هدف یکی از allowedTargets منبع نیستفقط allowedTargets را از convert=open ارائه دهید
run یا download پاسخ می‌دهد 404 (Upload expired — please re-open the file. از run)پنجرهٔ ۳۰ دقیقه‌ای تمام شده است، یا سرور دیگری در فارم بارگذاری را نداردفایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید
ویجت هنگامیکه UI در منبع دیگری باشد شکست می‌خوردنقطه‌های انتهایی پشتیبانی CORS ندارندUI را از همان منبع سرو کنید، یا مسیرهای Doconut را به‌صورت reverse‑proxy کنید
تم اعمال نمی‌شودمتغیرها بر روی یک والد یا عنصر داخل mount تنظیم شده‌اند؛ قانون .dcw خود ویجت آن‌ها را بر روی mount تنظیم می‌کندمستقیم به خود mount هدف بگیرید: #doconut-convert.dcw یا #doconut-convert

نکات چارچوب

در مقایسه با بسته‌های ASP.NET Core، این بسته فقط در میزبانی متفاوت است؛ API، قرارداد نقطهٔ انتهایی، اسکریپت ویجت و قوانین لایسنس یکسان هستند.

  • ثبت‌نام در Application_Start قرار دارد، از طریق DoconutHost.Initialize، به جای builder.Services.AddDoconut. سرویس‌هایی مانند AddDoconutDistributedWidgets در آرگومان دوم آن قرار می‌گیرند.
  • نقطه‌های انتهایی توسط DocImage.axd سرو می‌شوند و اسکریپت توسط DoconutResourceModule، هر دو در Web.config ثبت شده‌اند، به جای UseDoconut() و UseDoconutResources(). ویجت به basePath: '/DocImage.axd' نیاز دارد.
  • خطاهای راه‌اندازی به‌صورت یک 500 خالی در هر درخواست ظاهر می‌شوند، با دلیل در لاگ رویداد ویندوز.
  • بارگذاری‌ها به‌صورت کامل توسط ASP.NET خوانده می‌شوند قبل از اینکه Doconut آن‌ها را ببیند، بنابراین محدودیت‌های IIS باید بالاتر از MaxUploadMb باشند.
  • وب فرم‌ها صفحات نباید بر روی یک تبدیل مسدود شوند؛ ببینید در وب فرم‌ها.
  • فقط ویندوز، مانند بقیه بستهٔ .NET Framework.

آیا این صفحه مفید بود؟