پلاگین مبدل

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

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

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

نصب بسته

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

bash
dotnet add package Doconut.NETStandard.Converter

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

bash
dotnet add package Doconut.NETStandard.Converter --version 26.10.0

پکیج Converter را در همان نسخه‌ای که Doconut.NETStandard دارد نگه دارید. شناسه پکیج Doconut.NETStandard.Converter است؛ .<version> فقط در نام فایل دانلود شده .nupkg ظاهر می‌شود.

فایل مجوز پلاگین، Doconut.Viewer.Converter.lic، در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد قرار می‌گیرد؛ به همراه مجوز ویور خوانده می‌شود.

ثبت پلاگین

هیچ روش AddConverter() وجود ندارد — مدل پلاگین Doconut یکسان است. هر پلاگین، از جمله Converter، به همان روش ثبت می‌شود: داخل AddDoconut()، AddPlugin<TPlugin>() را فراخوانی کنید. ConverterPlugin در بسته NuGet خود، Doconut.NETStandard.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 پذیرفته می‌شوند. هیچ لایه رایگان ساکتی وجود ندارد. برای نحوه بارگذاری مجوزها به تنظیمات مجوز مراجعه کنید.

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

وضعیت مجوزراه‌اندازیخروجی تبدیل
مجوز پرداخت‌شده ویور که Converter را می‌دهد، در بازه نسخه‌ای خودشروع می‌شودتمیز — watermarked: false
مجوز موقت فعال (Demo/NFR)شروع می‌شودتبدیل می‌کند، با واترمارک ارزیابی — watermarked: true
مجوز موقت منقضی‌شده (Demo/NFR)شروع می‌شودتبدیل می‌کند، با واترمارک ارزیابی — watermarked: true
بدون مجوز، فایل قدیمی TRIAL، مجوز بدون Converter، یا مجوز پرداخت‌شده خارج از بازه نسخه‌ایخطای AddDoconut() پرتاب می‌شود—

هر دو مسیر فراخوانی پرچم را بر پایه همان قانون محاسبه می‌کنند: رابط 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 یا یک عنصر می‌گیرد، اگر mount پیدا نشود خطا می‌اندازد و یک handle برمی‌گرداند. ویجت فایلی را بارگذاری می‌کند، پیش‌نمایشی از صفحه ۱ نشان می‌دهد، به کاربر اجازه می‌دهد یکی از 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]; // یک فایل از خودتان <input type="file" id="picker">
conv.reset();         // بازگشت به صفحه بیکاری/رهاسازی؛ دوباره onReady اجرا نمی‌شود
conv.loadFile(file);  // جریان را با یک شی File شروع می‌کند؛ هیچ کاری انجام نمی‌دهد مگر اینکه در حال حاضر بیکار باشد
conv.destroy();       // گوش‌دهنده‌ها را حذف می‌کند، 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 (چندبخشی، یک فایل)بارگذاری و باز کردن یک سند منبع برای پیش‌نمایش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

در پاسخ open، sourceExt نقطهٔ پیش‌رو ندارد (مثلاً "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 مقدار یکسانی دارند. بستن نتیجهٔ مشاهده‌گر مخزن دانلود هنوز معتبر را حذف نمی‌کند، و بازنشانی ویجت مرورگر هیچ‌یک از این بازه‌ها را تمدید نمی‌کند.

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

مسیروضعیتزمانبدنه
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.
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
// file: فایل برای تبدیل، برای مثال از یک <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.NETStandard.Converter.
  2. فایل مجوز را اضافه کنید. Doconut.Viewer.Converter.lic را در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد بگذارید.
  3. حداکثر سرور را تنظیم کنید. MaxUploadMb در AddConverterWidget محدودیتی است که سرور اعمال می‌کند؛ maxUploadMb ویجت فقط یک بررسی سمت‌کلاینت است. دو مقدار را برابر نگه دارید.
  4. رابط کاربری را از همان مبدا که نقاط انتهایی 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;                   // حداقل ۳۲ بایت، یکسان در هر گره
    // 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 استدر 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

یادداشت‌های چارچوب

  • viewer.Converter.GetConverter() اینجا وجود ندارد. تبدیل دیگر از طریق نمونهٔ viewer انجام نمی‌شود: به جای آن Doconut.DocumentConverter را تزریق کنید.
  • این ConversionTarget enum تمام خانواده‌های منبع را پوشش می‌دهد. کتابخانهٔ قبلی یک نوع *ConfigConverter برای هر خانواده داشت — WordConfigConverter، ExcelConfigConverter، و غیره — که هر کدام enum تو در توی EnTargetFormat خود را داشتند، به‌علاوه یک enum SourceFormatConverter برای ورودی. همهٔ آن‌ها حذف شده‌اند؛ راهنمای راهنمای مهاجرت را ببینید.
  • فقط ویندوز، مانند بقیهٔ بستهٔ .NET Standard.

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