افزونه مبدل
سندها را به ۴۵ قالب هدف تبدیل کنید
افزونه مبدل Doconut را به یک سرویس تبدیل سند تبدیل میکند. این موتور پشت نمایه عمومی DocumentConverter را فراهم میکند و — به صورت اختیاری — یک ویجت آماده توسط DocImage.axd ارائه میدهد، به طوری که میتوانید اسناد را از C#، از ویجت، یا از یک رابط کاربری که خود مینویسید، تبدیل کنید.
| Surface | Use it when |
|---|---|
DocumentConverter (C#) | شما در سرور تبدیل میکنید، بدون درگیر شدن مرورگر |
Drop-in widget (doconutConverter.js) | شما یک صفحه بارگذاری، تبدیل و دانلود آماده در صفحه خود میخواهید |
HTTP endpoints on DocImage.axd (?convert=open|run|download) | شما رابط کاربری تبدیل خود را بر پایه قرارداد مستند سرور میسازید |
نصب بسته
Install-Package Doconut.NETFramework.Converterبرای قفل کردن افزونه به نسخهای که این مستندات توصیف میکند:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0بسته مبدل را با همان نسخهای که Doconut.NETFramework دارد، نگه دارید.
فایل مجوز افزونه، Doconut.Viewer.Converter.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد، قرار میگیرد؛ همراه با مجوز نمایشگر خوانده میشود.
ثبت افزونه
هر افزونه به همان روش ثبت میشود: AddPlugin<TPlugin>() در DoconutHost.Initialize، فراخوانی شده از Application_Start.
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 پرتاب میشود:
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 state | Startup | Conversion 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 در هر جایی که نیاز دارید دریافت کنید و آزادانه دوباره استفاده کنید.
// DocumentConverter را از DoconutHost.Services حل کنید؛ سازنده آن داخلی است، بنابراین هرگز `new` آن را استفاده نکنید.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension شامل نقطهٔ پیشرو است. password در صورتی که سند محافظت نشده باشد، null است.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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 کنید:
[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" علامتگذاری کنید و تبدیل را بهعنوان یک کار ناهمزمان صفحه اجرا کنید:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// 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) دارای ۴۵ عضو است:
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 سرویس میشوند و بهصورت پیشفرض غیرفعال هستند. آنها را در کنار ثبتنام افزونه فعال کنید:
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 خطا میاندازد:
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 بالاتر از سقف ویجت نگه دارید:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>جاسازی آن
<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 را انتخاب کند، تبدیل میکند، زمانی که امکان داشته باشد نتیجه را پیشنمایش میدهد و امکان دانلود را فراهم میکند.
گزینهها
| گزینه | نوع | پیشفرض | یادداشتها |
|---|---|---|---|
basePath | string | /doconut | آدرس URL نقطهٔ انتهایی. '/DocImage.axd' را روی این بسته تنظیم کنید |
resPath | string | /doconut-res | برای سازگاری با سایر ویجتهای Doconut پذیرفته شده است؛ ویجت مبدل هیچ URLی از آن نمیسازد |
maxUploadMb | number | 25 | فقط پیشبررسی سمت کلاینت؛ سرور سقف خود را اعمال میکند |
licenseUrl | string | null | null | اعلان واترمارک روی صفحهٔ نتیجه را به یک لینک تبدیل میکند |
labels | object | {} | هر زیرمجموعهای از رشتههای انگلیسی ویجت را بازنویسی میکند |
فراخوانیها
| فراخوانی | زمان فعال شدن | داده |
|---|---|---|
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() نمونهٔ ویجت را برمیگرداند:
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'.
| کلید | پیشفرض انگلیسی |
|---|---|
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. |
کلیدهای دیگر شامل 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 میخواند، بنابراین میتوانید بدون دستکاری داخلیها آن را تمگذاری کنید:
#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> | تبدیل منبع بارگذاریشده به target | 200 — { 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 دارد) | فقط وضعیت |
open | 400 | بارگذاری چندبخشی نیست | Expected a multipart file upload. |
open | 400 | فایلی وجود ندارد یا خالی است | No file uploaded. |
open | 400 | نوعی که قابل تبدیل نیست | This file type cannot be converted. |
open | 403 | نوع فایل به قابلیتی نیاز دارد که مجوز آن را نمیدهد (فایل DICOM بدون Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | بارگذاری از MaxUploadMb فراتر میرود (اما از محدودیتهای IIS نیست) | File is too large. |
run | 400 | توکن خراب (نه GUID) | Invalid token. |
run | 400 | یک target که به ConversionTarget تجزیه نمیشود | Unknown target format. |
run | 400 | هدف موجود در allowedTargets نیست | That target format is not available for this file. |
run | 404 | بارگذاری منقضی شده یا هرگز باز نشده است | Upload expired — please re-open the file. |
open, run | 500 | پردازش ناموفق بود | یک پیام پاکسازیشده |
download | 400 / 404 | توکن دانلود خراب، ناشناخته یا منقضی شده | فقط وضعیت |
یک مسیر کامل با fetch:
// 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 کنید.
در تولید
- نصب افزونه در کنار بستهٔ هسته، با همان نسخه:
Install-Package Doconut.NETFramework.Converter. - افزودن فایل مجوز. قرار دهید
Doconut.Viewer.Converter.licدر همان پوشهای کهDoconut.Viewer.licقرار دارد. - تنظیم محدودیتهای بارگذاری.
MaxUploadMbدرAddConverterWidgetمحدودیتی است که Doconut اعمال میکند؛ اطمینان حاصل کنید کهmaxRequestLengthوmaxAllowedContentLengthدرWeb.configبالاتر از آن باشند (به محدودیتهای بارگذاری مراجعه کنید)، و مقدارmaxUploadMbویجت برابر با آن باشد. - هرگز در تبدیل مسدود نشوید در فرمهای وب (به در فرمهای وب مراجعه کنید).
- نتایج تبدیل را آزاد کنید. جریان
ConvertAsyncکه برمیگرداند، در استخر قرار دارد؛ آزادسازی آن بافرهایش را به استخر برمیگرداند.
مزارع وب
ویجت هر بارگذاری و نتیجهٔ آن را در حافظهٔ سروری که open را سرویس داده است، نگه میدارد. پشت یک تعادلبار بدون نشستهای چسبان، یک درخواست بعدی run، download یا پیشنمایش میتواند به سرور دیگری برسد و بارگذاری را پیدا نکند. فروشگاه مشترک و رمزگذاریشدهٔ ویجت را از طریق آرگومان دوم 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"; // یک پوشه که هر سرور میتواند بخواند و بنویسد
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
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
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.
آیا این صفحه مفید بود؟