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

نصب بسته

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

bash

dotnet add package Doconut.NET6.Converter

برای قفل کردن افزونه به نسخهٔ جاری ۲۶.۷.۰، نسخه را به‌صورت جداگانه پاس دهید:

bash

dotnet add package Doconut.NET6.Converter --version 26.7.0

بستهٔ مبدل را با همان نسخهٔ Doconut.NET6 نگه دارید. شناسهٔ بسته Doconut.NET6.Converter است؛ .26.7.0 فقط در نام فایل دانلود شدهٔ .nupkg ظاهر می‌شود.

ثبت افزونه

هیچ روش 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>();
});

این فراخوانی در زمان راه‌اندازی به‌دلیل عدم وجود لایسنس، فایل قدیمی TRIAL، یا لایسنس غیر موقت که قابلیت Converter را اعطا نمی‌کند، خطا می‌اندازد — یک InvalidOperationException که از داخل AddDoconut() ایجاد می‌شود، پیش از این‌که برنامه درخواست‌ها را سرویس دهد. ثبت‌نام‌های موقت Demo/NFR پذیرفته می‌شوند؛ پس از انقضای تقویمی آن‌ها، تبدیل همچنان با خروجی دارای واترمارک در دسترس است. هیچ لایهٔ رایگان ساکتی وجود ندارد. برای نحوه بارگذاری لایسنس‌ها، به راه‌اندازی مجوز مراجعه کنید.

تبدیل از C#

هر تبدیل یک MemoryStream قابل جستجو که در موقعیت ۰ قرار دارد، برمی‌گرداند، آماده برای خواندن یا کپی فوری. 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(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

csharp

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

csharp

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

دو نکته‌ای که به‌راحتی می‌توان اشتباه کرد: sourceExtension در بارگذاری استریم باید نقطهٔ پیش‌رو را شامل شود (".xlsx"، نه "xlsx") — مبدل آن را در مقابل فهرست فرمت‌ها مقایسه می‌کند و پسوند بدون نقطه حل نمی‌شود. و با وجود نامش، WordToHtmlAsync ‎Task<Stream> را برمی‌گرداند، نه Task<string> — شما سند HTML (تصاویر به صورت Base64 جاسازی شده) را به‌صورت یک استریم دریافت می‌کنید، همان‌طور که هر نتیجهٔ تبدیل دیگر است.

فرمت‌های هدف

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

هر منبعی به هر هدفی تبدیل نمی‌شود — افزونه خانوادهٔ فرمت هر منبع (Word، Excel، PowerPoint، PDF، CAD، Image، Email، Diagram، Project/Task، PSD، سند وب) را به مجموعهٔ ثابت هدف‌های مجاز خود نگاشت می‌کند. این 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;
    });
});

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>

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

سفارشی‌سازی ابزارک

گزینه‌های اولیه‌ای که به Doconut.convert(selector, options) ارسال می‌شوند:

گزینه	نوع	پیش‌فرض	یادداشت
`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() نمونهٔ ابزارک را خود باز می‌گرداند — آن را نگه دارید تا ابزارک را به‌صورت برنامه‌نویسی کنترل کنید:

javascript

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // بازگشت به صفحهٔ idle/drop؛ دوباره onReady فراخوانی نمی‌شود
conv.loadFile(file);  // شروع جریان با یک شیء File؛ هیچ عملی انجام نمی‌دهد مگر اینکه در حالت idle باشد
conv.destroy();       // حذف شنوندگان، خالی کردن mount؛ پس از این نمونه غیرقابل استفاده است

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

ابزارک فقط یک کلاینت برای این قرارداد HTTP است — برای تجربه کاربری متفاوت، رابط کاربری خود را مستقیماً در برابر آن بسازید. هر سه مسیر زیر شاخهٔ ASP.NET که در آن UseDoconut() نصب شده است (معمولاً /doconut) قرار دارند:

مسیر	هدف	پاسخ موفقیت
`POST ?convert=open` (چندبخشی، فیلد `file`)	بارگذاری و باز کردن یک سند منبع برای پیش‌نمایش	`200` — `{ token, pages, sourceExt, allowedTargets }`
`POST ?token=<token>&convert=run&target=<ext>`	تبدیل منبع ذخیره‌شده به `target`	`200` — `{ downloadToken, resultToken, resultPages, downloadName, watermarked }`
`GET ?convert=download&token=<downloadToken>`	پخش فایل تبدیل‌شده	`200` — بایت‌های فایل، `Content-Disposition: attachment`، `Cache-Control: no-store`

بایت‌های منبع بارگذاری‌شده در سمت سرور با زمان حیات ۳۰‑دقیقه ذخیره می‌شوند؛ پس از پایان این بازه، run پاسخ 404 می‌دهد و فایل باید دوباره باز شود. نتیجهٔ تبدیل‌شده در همان مخزن زندگی می‌کند — downloadToken پس از تکمیل تبدیل، بازهٔ تازهٔ ۳۰‑دقیقهٔ خود را دریافت می‌کند — در حالی که resultToken یک توکن جلسهٔ نمایشگر عادی است که طول عمر آن مطابق کش جلسهٔ نمایشگر است، مستقل از مخزن.

sourceExt در پاسخ open نقطهٔ پیش‌وندی ندارد (مثلاً "docx") — برعکس قرارداد پارامتر sourceExtension در DocumentConverter.ConvertAsync که نیاز به نقطه دارد.

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

مسیر	وضعیت	زمان	بدنه
همه	`404`	ابزارک فعال نیست (`AddConverterWidget()` هرگز فراخوانی نشده) — قبل از ارسال هر یک از سه مسیر بررسی می‌شود	فقط وضعیت
همه	`405`	روش HTTP نادرست (`open`/`run` به `POST` نیاز دارند؛ `download` به `GET` نیاز دارد)	فقط وضعیت
`open`	`413`	فایل بارگذاری‌شده از `MaxUploadMb` تجاوز می‌کند	`{ "error": "File is too large." }`
`open`	`400`	بدنهٔ چندبخشی وجود ندارد، فایلی نیست، یا پسوند منبعی که قابل تبدیل نیست	`{ "error": "..." }`
`run`	`400`	توکن خراب (نه GUID)، یا `target` که به `ConversionTarget` تجزیه نمی‌شود	`{ "error": "Invalid token." }` / `{ "error": "Unknown target format." }`
`run`	`400`	`target` در `allowedTargets` منبع وجود ندارد	`{ "error": "That target format is not available for this file." }`
`run`	`404`	بارگذاری ذخیره‌شده منقضی شده است (TTL ۳۰‑دقیقه) یا توکن هرگز باز نشده	`{ "error": "Upload expired — please re-open the file." }`
`open`، `run`	`500`	پردازش به‌صورت داخلی شکست خورد	`{ "error": "<sanitized message>" }` — همانند سایر مسیرهای خطای Doconut به‌صورت پاک‌سازی‌شده؛ هرگز نام‌های داخلی موتور را فاش نمی‌کند
`download`	`400`	توکن خراب (نه GUID)	فقط وضعیت
`download`	`404`	توکن دانلود ناشناخته یا منقضی شده	فقط وضعیت

مالکیت منبع

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

برای ویجت وب، مخازن بارگذاری و دانلود TTLهای مستقل ۳۰‑دقیقه‌ای دارند. یک resultToken نمایشگر به‌جای آن، عمر جلسه نمایشگر را دنبال می‌کند. بستن نتیجهٔ نمایشگر مخزن دانلود هنوز معتبر را حذف نمی‌کند، و بازنشانی ویجت مرورگر هیچ‌یک از TTLها را تمدید نمی‌کند.

عیب‌یابی

علائم	بررسی
حل `DocumentConverter` شکست می‌خورد	ثبت `ConverterPlugin` داخل `AddDoconut()` انجام شد
برنامه در هنگام راه‌اندازی شکست می‌خورد	مجوز بارگذاری‌شده `Converter` را اعطا می‌کند
تبدیل جریان می‌گوید قالب پشتیبانی نمی‌شود	`sourceExtension` شامل نقطهٔ پیش‌رو است
جاوااسکریپت ویجت بارگذاری می‌شود اما درخواست‌ها ۴۰۴ باز می‌گردانند	`AddConverterWidget()` فراخوانی نشد
درخواست‌های ویجت از URL اشتباه استفاده می‌کنند	`basePath` با شاخه‌ای که `UseDoconut()` در آن نگاشته شده مطابقت دارد
هدف موجود نیست	از `allowedTargets` که توسط `convert=open` برگردانده شده استفاده کنید؛ هر منبع همهٔ مقادیر enum هدف را پشتیبانی نمی‌کند
دانلود منقضی شد	دوباره `convert=open`/`convert=run` را انجام دهید؛ توکن‌های مخزن به‌صورت عمدی موقت هستند

افزودن واترمارک

با ثبت ConverterPlugin، مجوز میزبان در یکی از سه وضعیت است:

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

هر دو مسیر فراخوانی پرچم را بر اساس همان قانون محاسبه می‌کنند: واسط C# DocumentConverter به‌صورت داخلی آن را از وضعیت IsViewerLicensed و IsTemporary مجوز استخراج می‌کند، و پردازشگر ?convert=run ویجت بررسی معادل (IsViewerLicensed && !IsTrial && !IsTemporary) را انجام می‌دهد تا فیلد watermarked را که برمی‌گرداند پر کند. یک یکپارچه‌سازی می‌تواند پیش از خرید بر روی یک مجوز ارزیابی به‌صورت انتها‑به‑انتها ساخته و تست شود — فقط بایت‌های خروجی تغییر می‌کنند.