افزونه مبدل
سندها را به 45 فرمت هدف تبدیل کنید
افزونه مبدل Doconut را به یک سرویس تبدیل سند تبدیل میکند. این موتور پشت رابط عمومی DocumentConverter را فراهم میکند و — به صورت اختیاری — یک ویجت آماده با قرارداد HTTP خود دارد، به طوری که میتوانید اسناد را از C#، از ویجت، یا از یک فرانتاند که خودتان مینویسید، تبدیل کنید.
| سطح | زمان استفاده |
|---|---|
DocumentConverter (C#) | شما روی سرور تبدیل میکنید، بدون درگیر شدن مرورگر |
Drop-in widget (doconutConverter.js) | میخواهید یک صفحه آماده بارگذاری، تبدیل و دانلود در صفحه خود داشته باشید |
HTTP endpoints (?convert=open|run|download) | شما رابط کاربری تبدیل خود را بر پایه قرارداد مستند سرور میسازید |
نصب بسته
آخرین نسخه پایدار افزونه مبدل را نصب کنید:
dotnet add package Doconut.NET6.Converterبرای قفل کردن افزونه به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
dotnet add package Doconut.NET6.Converter --version 26.10.0بسته مبدل را با همان نسخهای که Doconut.NET6 دارد نگه دارید. شناسه بسته
Doconut.NET6.Converter است؛ .<version> فقط در نام فایل دانلود شده .nupkg ظاهر میشود.
فایل مجوز افزونه، Doconut.Viewer.Converter.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد قرار میگیرد؛ همراه با مجوز ویور خوانده میشود.
پلتفرمها. افزونه در هر جایی که Doconut.NET6 اجرا میشود کار میکند: ویندوز و لینوکس مبتنی بر glibc بر روی x64 (نه Alpine یا توزیعهای دیگر مبتنی بر musl). در لینوکس، قبل از باز شدن اولین سند کتابخانه پیکربندی فونت را نصب کنید:
apt-get update && apt-get install -y libfontconfig1در توزیعهای RHEL، Fedora و مشابه، بسته 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.NET6.Converter، همراه با بسته پایه ویور نصب میشود.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});این تمام آنچه رابط C# نیاز دارد است. ویجت و نقاط انتهایی HTTP آن یک گزینه جداگانه، 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 پذیرفته میشوند. هیچ لایه رایگان ساکتی وجود ندارد. برای نحوه بارگذاری مجوزها به تنظیمات مجوز مراجعه کنید.
مجوزدهی و واترمارک
| وضعیت مجوز | راهاندازی | خروجی تبدیل |
|---|---|---|
Paid viewer license granting Converter, within its version window | Starts | Clean — watermarked: false |
| Active Temporary (Demo/NFR) license | Starts | Converts, with the evaluation watermark — watermarked: true |
| Expired Temporary (Demo/NFR) license | Starts | Converts, with the evaluation watermark — watermarked: true |
No license, a legacy TRIAL file, a license without Converter, or a paid license outside its version window | 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) ۴۵ عضو دارد:
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 را برای هر فایلی که تازه بارگذاری شده برمیگرداند و این باید منبع انتخابکننده باشد.
ویجت Drop‑in
فعالسازی نقطههای انتهایی
نقطههای انتهایی ?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 = ۲۵). این بهتنهایی حق تبدیل را نمیدهد: به 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 یا یک عنصر میگیرد، اگر محل نصب پیدا نشود استثنا میاندازد و یک هندل برمیگرداند. ویجت فایلی را بارگذاری میکند، پیشنمایشی از صفحهٔ ۱ نشان میدهد، به کاربر اجازه میدهد یکی از 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 شروع میکند؛ no-op مگر اینکه در حال حاضر idle باشد
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 است — برای تجربه کاربری متفاوت، مستقیماً یک رابط کاربری سفارشی در برابر آن بسازید. هر سه مسیر زیر شاخه ASP.NET قرار دارند که در آن UseDoconut() سوار شده است (به طور معمول /doconut)، و تا زمانی که AddConverterWidget() فراخوانی شود، به 404 پاسخ میدهند. خطاها یک بدنه JSON دارند، { "error": "..." }، بهجز مواردی که جدول میگوید «فقط وضعیت». یک مقدار ناشناخته ?convert= به 400 پاسخ میدهد.
| مسیر | هدف | پاسخ موفقیت |
|---|---|---|
POST ?convert=open (چندبخشی، یک فایل) | بارگذاری و باز کردن یک سند منبع برای پیشنمایش | 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 — بایتهای فایل، Content-Disposition: attachment، Cache-Control: no-store |
sourceExt در پاسخ open نقطهٔ پیشرو ندارد (مثلاً "docx") — بر خلاف قرارداد پارامتر sourceExtension در DocumentConverter.ConvertAsync که یک نقطه میخواهد. allowedTargets فهرست نامهای هدف با حروف کوچک را نشان میدهد ("pdf"، "html"، …)؛ یکی از آنها را به عنوان target عبور دهید، که بهصورت بدون حساسیت به حروف بزرگ/کوچک مقایسه میشود. open از اولین فایل در بدنهٔ چندبخشی استفاده میکند.
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 مقدار یکسانی دارند. بستن نتیجهٔ ویور، مخزن دانلود هنوز معتبر را حذف نمیکند، و بازنشانی ویجت مرورگر هیچیک از این بازهها را تمدید نمیکند.
حالتهای شکست، گروهبندی شده بر حسب مسیر:
| مسیر | وضعیت | زمان | بدنه |
|---|---|---|---|
| هر | 404 | ویجت فعال نیست (AddConverterWidget() هرگز فراخوانی نشده است) — قبل از پردازش هر یک از سه مسیر بررسی میشود | فقط وضعیت |
| هر | 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 ندارد. رابط کاربری و اسکریپت ویجت را از همان منبعی که Doconut قرار دارد سرو کنید، یا هر دو مسیر /doconut (مسیر میانی و مسیر منابع) را بهصورت معکوس‑پروکسی زیر منبع UI خود قرار دهید.
در محیط تولید
- نصب افزونه در کنار بستهٔ هسته، با همان نسخه:
dotnet add package Doconut.NET6.Converter. - فایل مجوز را اضافه کنید.
Doconut.Viewer.Converter.licرا در همان پوشهای کهDoconut.Viewer.licقرار دارد بگذارید. - حد سرور را تنظیم کنید.
MaxUploadMbدرAddConverterWidgetمحدودیتی است که سرور اعمال میکند؛maxUploadMbویجت فقط یک بررسی سمت مشتری است. دو مقدار را برابر نگه دارید. - UI را از همان منبع که نقاط انتهایی Doconut هستند سرو کنید، یا از طریق reverse‑proxy (به ساخت رابط کاربری خودتان مراجعه کنید).
- نتایج تبدیل را آزاد کنید. جریانی که
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 ثبت نشده است | در داخل AddDoconut()، AddPlugin<ConverterPlugin>() را اضافه کنید |
| تبدیل جریان میگوید قالب پشتیبانی نمیشود | 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 فراتر میرود | در AddConverterWidget، MaxUploadMb را برانگیزید؛ 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 را ثبت کنید |
| ویجت هنگامیکه UI در منبع دیگری باشد شکست میخورد | نقاط انتهایی پشتیبانی CORS ندارند | UI را از همان منبع سرو کنید، یا مسیرهای Doconut را reverse‑proxy کنید |
| تم اعمال نمیشود | متغیرها بر روی یک والد یا عنصر داخل mount تنظیم شدهاند؛ قانون .dcw خود ویجت آنها را بر روی mount تنظیم میکند | مستقیم به mount هدف بگیرید: #doconut-convert.dcw یا #doconut-convert |
آیا این صفحه مفید بود؟