پلاگین مبدل

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

پلاگین مبدل Doconut را به یک سرویس تبدیل سند تبدیل می‌کند. این پلاگین موتور پشت رابط عمومی DocumentConverter را فراهم می‌کند و — به‌صورت opt‑in — یک ویجت درون‌ریز با قرارداد HTTP خود دارد، بنابراین می‌توانید اسناد را از C#، از ویجت یا از یک فرانت‌اند که خودتان می‌نویسید، تبدیل کنید.

سطحچه زمانی استفاده کنید
DocumentConverter (C#)شما در سرور تبدیل می‌کنید، بدون مرورگر
ویجت درون‌ریز (doconutConverter.js)می‌خواهید یک صفحه بارگذاری، تبدیل و دانلود آماده در صفحهٔ خود داشته باشید
نقاط انتهایی HTTP (?convert=open|run|download)شما رابط کاربری تبدیل خود را بر پایه قرارداد مستند سرور می‌سازید

نصب بسته

پلاگین مبدل پایدار آخرین نسخه را نصب کنید:

bash
dotnet add package Doconut.NET8.Converter

برای قفل کردن پلاگین به نسخه‌ای که این مستندات توصیف می‌کند، نسخه را به‌صورت جداگانه پاس دهید:

bash
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). در لینوکس، قبل از باز شدن اولین سند، کتابخانهٔ پیکربندی فونت را نصب کنید:

bash
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، همراه با بستهٔ پایهٔ نمایشگر نصب می‌شود.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

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

پلاگین به مجوزی نیاز دارد که قابلیت Converter را بدهد. بدون آن، AddDoconut() در هنگام راه‌اندازی یک InvalidOperationException پرتاب می‌کند، پیش از اینکه برنامه درخواست را سرو کند:

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.

این خطا برای عدم وجود مجوز، فایل قدیمی 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 در هر جایی که نیاز دارید حل کنید — به‌صورت بی‌حالت طراحی شده است، بنابراین یک نمونهٔ واحد برای استفاده مجدد در درخواست‌ها ایمن است.

csharp
// DocumentConverter را تزریق کنید؛ سازندهٔ آن داخلی است، بنابراین هرگز `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 در overload استریم باید نقطهٔ پیش‌رو را شامل شود (".xlsx"، نه "xlsx") — مبدل آن را در مقابل فهرست فرمت‌ها مقایسه می‌کند و یک پسوند ساده حل نمی‌شود. و با وجود نامش، WordToHtmlAsync مقدار Task<Stream> را برمی‌گرداند، نه Task<string> — شما سند HTML (تصاویر به‌صورت Base64 جاسازی شده) را به‌عنوان یک استریم دریافت می‌کنید، همانند هر نتیجهٔ تبدیل دیگر.

صاحب استریم بازگردانده‌شده، فراخواننده است و باید پس از کپی یا بازگرداندن محتوا آن را آزاد کند. سرویس DocumentConverter خود از تزریق وابستگی حل می‌شود؛ آن را به‌صورت دستی ساخت یا آزاد نکنید.

فرمت‌های هدف

ConversionTarget (فضای‌نامی Doconut.Configs.Conversion) 45 عضو دارد:

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/Task، PSD، سند وب، DICOM) را به مجموعهٔ ثابت هدف‌های مجاز خود نگاشت می‌کند. تبدیل یک منبع DICOM (.dcm، .ima) همچنین به مجوزی نیاز دارد که قابلیت Dicom را بدهد؛ هدف‌های آن عبارتند از Pdf، Png، Jpeg، Bmp، Tiff و Gif. این enum را به‌عنوان فهرست هدف UI خود به‌صورت ثابت کدنویسی نکنید: ?convert=open مقدار واقعی allowedTargets را برای هر فایلی که تازه بارگذاری شده برمی‌گرداند و این باید منبع انتخاب‌کننده باشد.

ویجت یکپارچه

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

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

csharp
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() خطا می‌اندازد:

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.

بدون AddConverterWidget()، سه نقطهٔ انتهایی ?convert= پاسخ 404 می‌دهند — اما فایل JS خود همچنان سرو می‌شود (این یک منبع ثابت جاسازی‌شده ساده است؛ فقط نقطه‌های انتهایی که به آن‌ها مراجعه می‌کند محدود شده‌اند).

جاسازی آن

html
<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 را انتخاب کند، تبدیل می‌کند، نتیجه را زمانی که امکان‌پذیر باشد پیش‌نمایش می‌دهد و دانلود را ارائه می‌کند.

گزینه‌ها

گزینهنوعپیش‌فرضیادداشت‌ها
basePathstring/doconutمسیر پایه برای نقطه‌های انتهایی ?convert=؛ باید با شاخه ASP.NET که در آن UseDoconut() واقعاً نصب شده است مطابقت داشته باشد (معمولاً از طریق MiddlewarePath هماهنگ می‌شود)
resPathstring/doconut-resبرای سازگاری پیکربندی با سایر ویجت‌های Doconut پذیرفته می‌شود؛ ویجت مبدل در حال حاضر هیچ URLی از آن نمی‌سازد
maxUploadMbnumber25فقط بررسی پیش‌قابلی سمت کلاینت — فایل بزرگ‌تری را قبل از بارگذاری رد می‌کند. سرور به‌صورت مستقل محدودیت خود را اعمال می‌کند و اگر تجاوز شود، 413 را پاسخ می‌دهد
licenseUrlstring | nullnullهنگامی که تنظیم شود، اعلان واترمارک در صفحه نتیجه را به پیوندی به این URL تبدیل می‌کند
labelsobject{}هر زیرمجموعه‌ای از رشته‌های پیش‌فرض انگلیسی ویجت (متن کشیدن، دکمه‌ها، اعلان‌های 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() نمونهٔ ویجت را به‌صورت خود باز می‌گرداند — آن را نگه دارید تا ویجت را به‌صورت برنامه‌نویسی کنترل کنید:

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

کلیدپیش‌فرض انگلیسی
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 است — برای تجربه کاربری متفاوت، رابط کاربری خود را مستقیماً در برابر آن بسازید. هر سه مسیر زیر شاخه 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>تبدیل منبع ذخیره‌شده به target200 — { 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 مقدار یکسانی دارند. بستن نتیجهٔ ویور مخزن دانلود هنوز معتبر را حذف نمی‌کند، و تنظیم مجدد ویجت مرورگر هیچ‌یک از بازه‌ها را تمدید نمی‌کند.

حالت‌های شکست، گروه‌بندی شده بر حسب مسیر:

مسیروضعیتزمانبدنه
any404ویجت فعال نیست (‏AddConverterWidget()‏ هرگز فراخوانی نشده است) — قبل از هر یک از سه مسیر بررسی می‌شودفقط وضعیت
any405متد HTTP نادرست (‏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 است، در برابر Content-Length بررسی می‌شود و در حین خواندن بارگذاریFile is too large.
run400توکن خراب (GUID نیست)Invalid token.
run400‎target‎ که به ‎ConversionTarget‎ تجزیه نمی‌شودUnknown target format.
run400‎target‎ در ‎allowedTargets‎ منبع وجود نداردThat target format is not available for this file.
run404بارگذاری ذخیره‌شده منقضی شده یا توکن هرگز باز نشده استUpload expired — please re-open the file.
open, run500پردازش به‌صورت داخلی شکست خوردپیام پاک‌سازی‌شده — به همان شیوه‌ای که برای هر مسیر خطای Doconut دیگر انجام می‌شود؛ هرگز جزئیات داخلی را فاش نمی‌کند
download400توکن خراب (GUID نیست)فقط وضعیت
download404توکن دانلود ناشناخته یا منقضی شدهفقط وضعیت

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

javascript
// فایل: فایل برای تبدیل، برای مثال از یک <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 خود قرار دهید.

در تولید

  1. نصب افزونه در کنار بستهٔ هسته، با همان نسخه: dotnet add package Doconut.NET8.Converter.
  2. افزودن فایل مجوز. فایل Doconut.Viewer.Converter.lic را در همان پوشهٔ Doconut.Viewer.lic قرار دهید.
  3. تنظیم حداکثر سرور. MaxUploadMb در AddConverterWidget محدودیتی است که سرور اعمال می‌کند؛ maxUploadMb ویجت فقط یک بررسی سمت‑کلاینت است. دو مقدار را برابر نگه دارید.
  4. سرو کردن رابط کاربری از همان مبدأ همانند نقطه‌های انتهایی Doconut، یا با معکوس‑پروکسی کردن آن‌ها (نگاه کنید به ساخت رابط کاربری خودتان).
  5. از بین بردن نتایج تبدیل. جریانی که ConvertAsync برمی‌گرداند در استخر نگهداری می‌شود؛ از بین بردن آن بافرهایش را به استخر برمی‌گرداند.

مزارع وب

ویجت هر بارگذاری و نتیجهٔ آن را در حافظهٔ گره‌ای که open را سرو کرده نگه می‌دارد. پشت یک تعادل‌بار بدون نشست‌های چسبنده، یک درخواست بعدی run، download یا پیش‌نمایش می‌تواند به گرهٔ دیگری برسد و بارگذاری را پیدا نکند. فروشگاه مشترک و رمزنگاری‌شدهٔ ویجت را یک‌بار، پس از AddDoconut() ثبت کنید:

csharp
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

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

از تزریق وابستگی حل می‌شود؛ سازنده داخلی است. 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 را برمی‌گرداند تا فراخوانی‌ها بتوانند زنجیره شوند.

عیب‌یابی

علامتعلتراه‌حل
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 را اعطا می‌کند استفاده کنید
ویجت بارگذاری می‌شود اما درخواست‌های آن پاسخ می‌دهند 404AddConverterWidget() فراخوانی نشده است، یا 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

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