پلاگین مبدل
سندها را به 45 قالب هدف تبدیل کنید
پلاگین مبدل Doconut را به یک سرویس تبدیل سند تبدیل میکند. این پلاگین موتور پشت رابط عمومی DocumentConverter را فراهم میکند و — بهصورت opt‑in — یک ویجت درونریز با قرارداد HTTP خود دارد، بنابراین میتوانید اسناد را از C#، از ویجت یا از یک فرانتاند که خودتان مینویسید، تبدیل کنید.
| سطح | چه زمانی استفاده کنید |
|---|---|
DocumentConverter (C#) | شما در سرور تبدیل میکنید، بدون مرورگر |
ویجت درونریز (doconutConverter.js) | میخواهید یک صفحه بارگذاری، تبدیل و دانلود آماده در صفحهٔ خود داشته باشید |
نقاط انتهایی HTTP (?convert=open|run|download) | شما رابط کاربری تبدیل خود را بر پایه قرارداد مستند سرور میسازید |
نصب بسته
پلاگین مبدل پایدار آخرین نسخه را نصب کنید:
dotnet add package Doconut.NET8.Converterبرای قفل کردن پلاگین به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
dotnet add package Doconut.NET8.Converter --version 26.10.0پکیج مبدل را با همان نسخهٔ Doconut.NET8 نگه دارید. شناسهٔ بسته Doconut.NET8.Converter است؛ .<version> فقط در نام فایل دانلود شدهٔ .nupkg ظاهر میشود.
فایل مجوز پلاگین، Doconut.Viewer.Converter.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد، قرار میگیرد؛ همراه با مجوز نمایشگر خوانده میشود.
پلتفرمها. پلاگین در هر جایی که Doconut.NET8 اجرا میشود، کار میکند: ویندوز و لینوکس مبتنی بر glibc بر روی x64 (نه Alpine و نه توزیعهای مبتنی بر musl). در لینوکس، قبل از باز شدن اولین سند، کتابخانهٔ پیکربندی فونت را نصب کنید:
apt-get update && apt-get install -y libfontconfig1در RHEL، فدورا و توزیعهای مشابه بسته fontconfig است. بدون آن، باز کردن سند با The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. شکست میخورد.
ثبت پلاگین
هیچ روش AddConverter() وجود ندارد — مدل پلاگین Doconut یکنواخت است. هر پلاگین، از جمله مبدل، به همان روش ثبت میشود: داخل AddDoconut()، AddPlugin<TPlugin>() را فراخوانی کنید. ConverterPlugin در بستهٔ NuGet خود، Doconut.NET8.Converter، همراه با بستهٔ پایهٔ نمایشگر نصب میشود.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});این تمام آنچه که رابط C# نیاز دارد، است. ویجت و نقاط انتهایی HTTP آن یک گزینهٔ جداگانهٔ opt‑in هستند، AddConverterWidget() (به ویجت درونریز مراجعه کنید).
پلاگین به مجوزی نیاز دارد که قابلیت Converter را بدهد. بدون آن، AddDoconut() در هنگام راهاندازی یک InvalidOperationException پرتاب میکند، پیش از اینکه برنامه درخواست را سرو کند:
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.این خطا برای عدم وجود مجوز، فایل قدیمی TRIAL، مجوز بدون Converter، و مجوز پرداختی که خارج از بازهٔ نسخهٔ آن استفاده میشود، رخ میدهد. مجوزهای موقت Demo/NFR پذیرفته میشوند. هیچ لایهٔ رایگان ساکتی وجود ندارد. برای نحوهٔ بارگذاری مجوزها، به راهاندازی مجوز مراجعه کنید.
مجوزدهی و واترمارک
| وضعیت مجوز | راهاندازی | خروجی تبدیل |
|---|---|---|
مجوز نمایشگر پرداختی که Converter را اعطا میکند، در بازهٔ نسخهٔ خود | شروع میشود | تمیز — watermarked: false |
| مجوز موقت فعال (Demo/NFR) | شروع میشود | تبدیل میکند، با واترمارک ارزیابی — watermarked: true |
| مجوز موقت منقضیشده (Demo/NFR) | شروع میشود | تبدیل میکند، با واترمارک ارزیابی — watermarked: true |
بدون مجوز، فایل قدیمی TRIAL، مجوز بدون Converter، یا مجوز پرداختی خارج از بازهٔ نسخه | AddDoconut() throws | — |
هر دو مسیر فراخوانی پرچم را بر اساس همان قانون محاسبه میکنند: رابط C# DocumentConverter آن را بهصورت داخلی از وضعیت IsViewerLicensed و IsTemporary مجوز استخراج میکند، و هندلر ?convert=run ویجت بررسی معادل (IsViewerLicensed && !IsTrial && !IsTemporary) را انجام میدهد تا فیلد watermarked را که برمیگرداند، پر کند. یک ادغام میتواند قبل از خرید بر روی یک مجوز ارزیابی بهصورت انتها به انتها ساخته و تست شود — فقط بایتهای خروجی تغییر میکنند.
یک منبع DICOM (.dcm، .ima) نیز به قابلیت Dicom نیاز دارد. بدون آن، ConvertAsync یک LicenseException (Converting '.dcm' requires the Dicom capability license.) پرتاب میکند و پاسخ open ویجت 403 است.
استفاده از C#
هر تبدیل یک MemoryStream قابل جستجو که در موقعیت 0 قرار دارد، برمیگرداند، آماده برای خواندن یا کپی کردن بلافاصله. DocumentConverter را از DI در هر جایی که نیاز دارید حل کنید — بهصورت بیحالت طراحی شده است، بنابراین یک نمونهٔ واحد برای استفاده مجدد در درخواستها ایمن است.
// DocumentConverter را تزریق کنید؛ سازندهٔ آن داخلی است، بنابراین هرگز `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 در overload استریم باید نقطهٔ پیشرو را شامل شود (".xlsx"، نه "xlsx") — مبدل آن را در مقابل فهرست فرمتها مقایسه میکند و یک پسوند ساده حل نمیشود. و با وجود نامش، WordToHtmlAsync مقدار Task<Stream> را برمیگرداند، نه Task<string> — شما سند HTML (تصاویر بهصورت Base64 جاسازی شده) را بهعنوان یک استریم دریافت میکنید، همانند هر نتیجهٔ تبدیل دیگر.
صاحب استریم بازگرداندهشده، فراخواننده است و باید پس از کپی یا بازگرداندن محتوا آن را آزاد کند. سرویس DocumentConverter خود از تزریق وابستگی حل میشود؛ آن را بهصورت دستی ساخت یا آزاد نکنید.
فرمتهای هدف
ConversionTarget (فضاینامی Doconut.Configs.Conversion) 45 عضو دارد:
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/Task، PSD، سند وب، DICOM) را به مجموعهٔ ثابت هدفهای مجاز خود نگاشت میکند. تبدیل یک منبع DICOM (.dcm، .ima) همچنین به مجوزی نیاز دارد که قابلیت Dicom را بدهد؛ هدفهای آن عبارتند از Pdf، Png، Jpeg، Bmp، Tiff و Gif. این enum را بهعنوان فهرست هدف UI خود بهصورت ثابت کدنویسی نکنید: ?convert=open مقدار واقعی allowedTargets را برای هر فایلی که تازه بارگذاری شده برمیگرداند و این باید منبع انتخابکننده باشد.
ویجت یکپارچه
فعالسازی نقطههای انتهایی
نقطههای انتهایی ?convert=open|run|download ویجت بهصورت اختیاری هستند و بهطور پیشفرض غیرفعالاند — بهصورت پیشفرض ایمن. آنها را در سمت سرور فعال کنید، همراه با ثبت افزونه:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});AddConverterWidget() بدون آرگومان، ویجت را با مقادیر پیشفرض (MaxUploadMb = 25) فعال میکند. این بهتنهایی حق تبدیل را نمیدهد: به AddPlugin<ConverterPlugin>() نیاز دارد، یا AddDoconut() خطا میاندازد:
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.بدون AddConverterWidget()، سه نقطهٔ انتهایی ?convert= پاسخ 404 میدهند — اما فایل JS خود همچنان سرو میشود (این یک منبع ثابت جاسازیشده ساده است؛ فقط نقطههای انتهایی که به آنها مراجعه میکند محدود شدهاند).
جاسازی آن
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>Doconut.convert(selectorOrElement, options) یک سلکتور CSS یا یک عنصر را میگیرد، اگر محل نصب یافت نشود خطا میاندازد و یک هندل برمیگرداند. ویجت فایلی را آپلود میکند، پیشنمایش صفحهٔ 1 را نشان میدهد، به کاربر اجازه میدهد یکی از allowedTargets را انتخاب کند، تبدیل میکند، نتیجه را زمانی که امکانپذیر باشد پیشنمایش میدهد و دانلود را ارائه میکند.
گزینهها
| گزینه | نوع | پیشفرض | یادداشتها |
|---|---|---|---|
basePath | string | /doconut | مسیر پایه برای نقطههای انتهایی ?convert=؛ باید با شاخه ASP.NET که در آن UseDoconut() واقعاً نصب شده است مطابقت داشته باشد (معمولاً از طریق MiddlewarePath هماهنگ میشود) |
resPath | string | /doconut-res | برای سازگاری پیکربندی با سایر ویجتهای Doconut پذیرفته میشود؛ ویجت مبدل در حال حاضر هیچ URLی از آن نمیسازد |
maxUploadMb | number | 25 | فقط بررسی پیشقابلی سمت کلاینت — فایل بزرگتری را قبل از بارگذاری رد میکند. سرور بهصورت مستقل محدودیت خود را اعمال میکند و اگر تجاوز شود، 413 را پاسخ میدهد |
licenseUrl | string | null | null | هنگامی که تنظیم شود، اعلان واترمارک در صفحه نتیجه را به پیوندی به این URL تبدیل میکند |
labels | object | {} | هر زیرمجموعهای از رشتههای پیشفرض انگلیسی ویجت (متن کشیدن، دکمهها، اعلانهای aria‑live، پیامهای خطا) را بازنویسی میکند |
بازخوانیها
| بازخوانی | زمانی که رخ میدهد | داده |
|---|---|---|
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: '/doconut' });
const file = document.querySelector('#picker').files[0]; // یک File از خودتان <input type="file" id="picker">
conv.reset(); // بازگشت به صفحه idle/drop؛ دوباره onReady فراخوانی نمیشود
conv.loadFile(file); // جریان را با یک شیء File آغاز میکند؛ در غیر این صورت (اگر در حالت idle نباشد) هیچ کاری انجام نمیدهد
conv.destroy(); // listeners را حذف میکند، mount را خالی میکند؛ پس از این نمونه غیرقابل استفاده استبرچسبها
هر رشته دارای پیشفرض انگلیسی است؛ 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 است — برای تجربه کاربری متفاوت، رابط کاربری خود را مستقیماً در برابر آن بسازید. هر سه مسیر زیر شاخه ASP.NET قرار دارند که در آن UseDoconut() سوار شده است (بهطور معمول /doconut)، و تا زمانی که AddConverterWidget() فراخوانی شود، به 404 پاسخ میدهند. خطاها بدنه JSON دارند، { "error": "..." }، بهجز مواردی که جدول میگوید «فقط وضعیت». یک مقدار ناشناخته ?convert= به 400 پاسخ میدهد.
| مسیر | هدف | پاسخ موفق |
|---|---|---|
POST ?convert=open (multipart, one file) | بارگذاری و باز کردن یک سند منبع برای پیشنمایش | 200 — { token, pages, sourceExt, allowedTargets } |
POST ?token=<token>&convert=run&target=<ext> | تبدیل منبع ذخیرهشده به target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET ?convert=download&token=<downloadToken> | پخش فایل تبدیلشده | 200 — file bytes, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt در پاسخ open نقطهٔ پیشرو ندارد (مثلاً "docx") — بر خلاف قرارداد پارامتر sourceExtension در DocumentConverter.ConvertAsync که یک نقطه میطلبد. allowedTargets فهرست نامهای هدف با حروف کوچک را نشان میدهد ("pdf"، "html"، …)؛ یکی از آنها را به عنوان target عبور دهید، که بهصورت بدون حساسیت به حروف بزرگ/کوچک مقایسه میشود. open از اولین فایل در بدنهٔ multipart استفاده میکند.
resultToken null است، و resultPages 0 است، زمانی که نتیجه قابل پیشنمایش نیست. downloadName نام فایل منبع به همراه پسوند هدف است.
تصاویر پیشنمایش از مسیر تصویر استاندارد ویور، {basePath}?token={token}&page=1&thumb=1&width={px}، استفاده میکنند، همراه با token از open یا resultToken از run. ویجت درخواست width=240 را میکند.
بایتهای منبع بارگذاریشده در سمت سرور ذخیره میشوند و به مدت ۳۰ دقیقه پس از آخرین خواندن نگه داشته میشوند؛ پس از پایان این بازه، run به 404 پاسخ میدهد و باید فایل دوباره باز شود. نتیجهٔ تبدیلشده در همان مخزن زندگی میکند — وقتی تبدیل تکمیل میشود، downloadToken بازهٔ تازهٔ ۳۰ دقیقهای خود را دریافت میکند — در حالی که resultToken یک توکن جلسهٔ معمولی ویور برای پیشنمایش نتیجه است. وقتی نتیجه قابل پیشنمایش باشد، downloadToken و resultToken مقدار یکسانی دارند. بستن نتیجهٔ ویور مخزن دانلود هنوز معتبر را حذف نمیکند، و تنظیم مجدد ویجت مرورگر هیچیک از بازهها را تمدید نمیکند.
حالتهای شکست، گروهبندی شده بر حسب مسیر:
| مسیر | وضعیت | زمان | بدنه |
|---|---|---|---|
| any | 404 | ویجت فعال نیست (AddConverterWidget() هرگز فراخوانی نشده است) — قبل از هر یک از سه مسیر بررسی میشود | فقط وضعیت |
| any | 405 | متد HTTP نادرست (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 است، در برابر Content-Length بررسی میشود و در حین خواندن بارگذاری | File is too large. |
run | 400 | توکن خراب (GUID نیست) | Invalid token. |
run | 400 | target که به ConversionTarget تجزیه نمیشود | Unknown target format. |
run | 400 | target در allowedTargets منبع وجود ندارد | That target format is not available for this file. |
run | 404 | بارگذاری ذخیرهشده منقضی شده یا توکن هرگز باز نشده است | Upload expired — please re-open the file. |
open, run | 500 | پردازش بهصورت داخلی شکست خورد | پیام پاکسازیشده — به همان شیوهای که برای هر مسیر خطای Doconut دیگر انجام میشود؛ هرگز جزئیات داخلی را فاش نمیکند |
download | 400 | توکن خراب (GUID نیست) | فقط وضعیت |
download | 404 | توکن دانلود ناشناخته یا منقضی شده | فقط وضعیت |
یک مسیر کامل با fetch:
// فایل: فایل برای تبدیل، برای مثال از یک <input type="file">.
async function convertFile(file) {
const base = '/doconut';
// 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 ندارد. UI و اسکریپت ویجت را از همان منشأ Doconut سرو کنید، یا هر دو مسیر /doconut (مسیر میدلویر و مسیر منابع) را بهصورت reverse‑proxy تحت منشأ UI خود قرار دهید.
در تولید
- نصب افزونه در کنار بستهٔ هسته، با همان نسخه:
dotnet add package Doconut.NET8.Converter. - افزودن فایل مجوز. فایل
Doconut.Viewer.Converter.licرا در همان پوشهٔDoconut.Viewer.licقرار دهید. - تنظیم حداکثر سرور.
MaxUploadMbدرAddConverterWidgetمحدودیتی است که سرور اعمال میکند؛maxUploadMbویجت فقط یک بررسی سمت‑کلاینت است. دو مقدار را برابر نگه دارید. - سرو کردن رابط کاربری از همان مبدأ همانند نقطههای انتهایی Doconut، یا با معکوس‑پروکسی کردن آنها (نگاه کنید به ساخت رابط کاربری خودتان).
- از بین بردن نتایج تبدیل. جریانی که
ConvertAsyncبرمیگرداند در استخر نگهداری میشود؛ از بین بردن آن بافرهایش را به استخر برمیگرداند.
مزارع وب
ویجت هر بارگذاری و نتیجهٔ آن را در حافظهٔ گرهای که open را سرو کرده نگه میدارد. پشت یک تعادلبار بدون نشستهای چسبنده، یک درخواست بعدی run، download یا پیشنمایش میتواند به گرهٔ دیگری برسد و بارگذاری را پیدا نکند. فروشگاه مشترک و رمزنگاریشدهٔ ویجت را یکبار، پس از AddDoconut() ثبت کنید:
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // یک پوشه که هر گره میتواند بخواند و بنویسد
store.FarmKey = farmKey; // حداقل 32 بایت، یکسان در هر گره
// 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);
}از تزریق وابستگی حل میشود؛ سازنده داخلی است. 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 را برمیگرداند تا فراخوانیها بتوانند زنجیره شوند.
عیبیابی
| علامت | علت | راهحل |
|---|---|---|
AddDoconut() پرتاب میکند The Converter plugin is registered via AddPlugin but no active license grants Converter. | بدون مجوز، فایل TRIAL، مجوز بدون Converter، یا مجوز پرداختشده خارج از بازهٔ نسخهٔ آن | یک مجوز که Converter را اعطا میکند نصب کنید، یا AddPlugin<ConverterPlugin>() را حذف کنید |
AddDoconut() پرتاب میکند 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>() داخل AddDoconut() |
| تبدیل جریان میگوید قالب پشتیبانی نمیشود | sourceExtension نقطهٔ پیشرو ندارد | از ".xlsx" استفاده کنید، نه "xlsx" |
ConvertAsync پرتاب میکند Converting '.dcm' requires the Dicom capability license. | منبع DICOM، و مجوز Dicom را اعطا نمیکند | از مجوزی که Dicom را اعطا میکند استفاده کنید |
| خروجی دارای واترمارک است | مجوز موقت است (Demo/NFR) | از مجوز پرداختشدهای که Converter را اعطا میکند استفاده کنید |
ویجت بارگذاری میشود اما درخواستهای آن پاسخ میدهند 404 | AddConverterWidget() فراخوانی نشده است، یا basePath با شاخهای که UseDoconut() سوار شده مطابقت ندارد | فراخوانی کنید AddConverterWidget()؛ اصلاح کنید basePath |
open پاسخ میدهد 403 Converting this file type requires the Dicom capability license. | بارگذاری DICOM، و مجوز Dicom را اعطا نمیکند | از مجوزی که Dicom را اعطا میکند استفاده کنید |
open پاسخ میدهد 413 File is too large. | بارگذاری از MaxUploadMb فراتر میرود | بالا ببرید MaxUploadMb در AddConverterWidget؛ maxUploadMb ویجت فقط یک بررسی سمت‑کلاینت است |
run پاسخ میدهد 400 That target format is not available for this file. | هدف یکی از allowedTargets منبع نیست | فقط allowedTargets را از open ارائه دهید |
run یا download پاسخ میدهد 404 (Upload expired — please re-open the file. از run) | پنجرهٔ ۳۰‑دقیقهای تمام شده است، یا گرهٔ مزارع وب بارگذاری را ندارد | فایل را دوباره باز کنید؛ در یک مزارع، AddDoconutDistributedWidgets را ثبت کنید |
| ویجت هنگامیکه رابط کاربری در مبدأ دیگری باشد شکست میخورد | نقطههای انتهایی پشتیبانی CORS ندارند | رابط کاربری را از همان مبدأ سرو کنید، یا مسیرهای Doconut را معکوس‑پروکسی کنید |
| تم اعمال نمیشود | متغیرها بر روی یک والد یا عنصر داخل ماونت تنظیم شدهاند؛ قانون .dcw خود ویجت آنها را بر روی ماونت تنظیم میکند | مستقیم به ماونت هدف بگیرید: #doconut-convert.dcw یا #doconut-convert |
آیا این صفحه مفید بود؟