افزونه مبدل

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

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

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

نصب بسته

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

bash
dotnet add package Doconut.NET6.Converter

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

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

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

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

این تمام آنچه رابط C# نیاز دارد است. ویجت و نقاط انتهایی HTTP آن یک گزینه جداگانه، 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 پذیرفته می‌شوند. هیچ لایه رایگان ساکتی وجود ندارد. برای نحوه بارگذاری مجوزها به تنظیمات مجوز مراجعه کنید.

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

وضعیت مجوزراه‌اندازیخروجی تبدیل
Paid viewer license granting Converter, within its version windowStartsClean — watermarked: false
Active Temporary (Demo/NFR) licenseStartsConverts, with the evaluation watermark — watermarked: true
Expired Temporary (Demo/NFR) licenseStartsConverts, with the evaluation watermark — watermarked: true
No license, a legacy TRIAL file, a license without Converter, or a paid license outside its version windowAddDoconut() 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) ۴۵ عضو دارد:

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 را برای هر فایلی که تازه بارگذاری شده برمی‌گرداند و این باید منبع انتخاب‌کننده باشد.

ویجت Drop‑in

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

نقطه‌های انتهایی ?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 = ۲۵). این به‌تنهایی حق تبدیل را نمی‌دهد: به 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 یا یک عنصر می‌گیرد، اگر محل نصب پیدا نشود استثنا می‌اندازد و یک هندل برمی‌گرداند. ویجت فایلی را بارگذاری می‌کند، پیش‌نمایشی از صفحهٔ ۱ نشان می‌دهد، به کاربر اجازه می‌دهد یکی از 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 شروع می‌کند؛ no-op مگر اینکه در حال حاضر idle باشد
conv.destroy();       // listenerها را حذف می‌کند، mount را خالی می‌کند؛ instance پس از این غیرقابل استفاده است

برچسب‌ها

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

کلیدپیش‌فرض انگلیسی
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

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

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

قالب‌بندی

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

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

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

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

ویجت فقط یک کلاینت برای این قرارداد HTTP است — برای تجربه کاربری متفاوت، مستقیماً یک رابط کاربری سفارشی در برابر آن بسازید. هر سه مسیر زیر شاخه 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>تبدیل منبع ذخیره‌شده به target200 — { 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 نیاز دارد)فقط وضعیت
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.
run400target در 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 ندارد. رابط کاربری و اسکریپت ویجت را از همان منبعی که Doconut قرار دارد سرو کنید، یا هر دو مسیر /doconut (مسیر میانی و مسیر منابع) را به‌صورت معکوس‑پروکسی زیر منبع UI خود قرار دهید.

در محیط تولید

  1. نصب افزونه در کنار بستهٔ هسته، با همان نسخه: dotnet add package Doconut.NET6.Converter.
  2. فایل مجوز را اضافه کنید. Doconut.Viewer.Converter.lic را در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد بگذارید.
  3. حد سرور را تنظیم کنید. MaxUploadMb در AddConverterWidget محدودیتی است که سرور اعمال می‌کند؛ maxUploadMb ویجت فقط یک بررسی سمت مشتری است. دو مقدار را برابر نگه دارید.
  4. UI را از همان منبع که نقاط انتهایی Doconut هستند سرو کنید، یا از طریق reverse‑proxy (به ساخت رابط کاربری خودتان مراجعه کنید).
  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 ثبت نشده استدر داخل AddDoconut()، AddPlugin<ConverterPlugin>() را اضافه کنید
تبدیل جریان می‌گوید قالب پشتیبانی نمی‌شود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 فراتر می‌روددر 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

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