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

نصب بسته

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

bash

dotnet add package Doconut.NETStandard.Converter

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

bash

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

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

ثبت افزونه

متد AddConverter() وجود ندارد — مدل افزونهٔ Doconut یکنواخت است. هر افزونه، از جمله Converter، به همان روش ثبت می‌شود: داخل AddDoconut()، AddPlugin<TPlugin>() را فراخوانی کنید. ConverterPlugin در بستهٔ NuGet خود به نام Doconut.NETStandard.Converter عرضه می‌شود و همراه با بستهٔ پایهٔ viewer نصب می‌شود.

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

viewer.Converter.GetConverter() در اینجا وجود ندارد. دیگر تبدیل از طریق نمونهٔ viewer انجام نمی‌شود: به‌جای آن Doconut.DocumentConverter را تزریق کنید.

csharp

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

csharp

// sourceExtension includes the leading dot. password is null unless the document is protected.
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 در overload مربوط به استریم باید نقطهٔ پیش‌رو را شامل شود (".xlsx" نه "xlsx") — مبدل آن را با فهرست فرمت‌ها مقایسه می‌کند و یک پسوند بدون نقطه حل نمی‌شود. و با وجود نامش، WordToHtmlAsync یک Task<Stream> برمی‌گرداند، نه Task<string> — شما سند HTML (تصاویر به‌صورت Base64 جاسازی شده) را به‌صورت یک استریم دریافت می‌کنید، همانند تمام نتایج دیگر تبدیل.

فرمت‌های هدف

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

این enum تمام خانواده‌های منبع را پوشش می‌دهد. کتابخانهٔ قبلی یک نوع *ConfigConverter برای هر خانواده داشت — WordConfigConverter، ExcelConfigConverter و غیره — که هر کدام enum تو در توی EnTargetFormat خود را داشتند، به‌علاوه یک enum SourceFormatConverter برای ورودی. همهٔ آن‌ها حذف شده‌اند؛ راهنمای راهنمای مهاجرت را ببینید.

هر منبع به هر هدف تبدیل نمی‌شود — افزونه خانوادهٔ فرمت هر منبع (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` موفق می‌شود	همان فیلدهای پاسخ run، به‌علاوه `target` درخواست‌شده
`onDownload({ downloadName, downloadToken })`	کاربر روی لینک دانلود کلیک می‌کند	همراه با دانلود بومی مرورگر اجرا می‌شود — آن را رهگیری یا جایگزین نمی‌کند
`onError({ phase, message })`	یک درخواست open یا run با خطا مواجه می‌شود	`phase` مقدار `'open'` یا `'run'` است؛ `message` خطای سرور تصفیه‌شده (یا پیام سمت کلاینت برای پیش‌چک اندازه بارگذاری) است

Doconut.convert() نمونهٔ ویجت را برمی‌گرداند — آن را نگه دارید تا ویجت را به‌صورت برنامه‌نویسی کنترل کنید:

javascript

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

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

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

مسیر	هدف	پاسخ موفق
`POST ?convert=open` (multipart, field `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`

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

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

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

مسیر	وضعیت	زمان	بدنه
any	`404`	ویجت فعال نیست (`AddConverterWidget()` هرگز فراخوانی نشده) — قبل از پردازش هر یک از سه مسیر بررسی می‌شود	فقط وضعیت
any	`405`	روش HTTP نادرست (`open`/`run` نیاز به `POST` دارند؛ `download` نیاز به `GET` دارد)	فقط وضعیت
`open`	`413`	فایل بارگذاری‌شده از `MaxUploadMb` بزرگ‌تر است	`{ "error": "File is too large." }`
`open`	`400`	بدنه multipart وجود ندارد، فایل نیست، یا پسوند منبعی که قابل تبدیل نیست	`{ "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 که برمی‌گرداند را پر کند. یک یکپارچه‌سازی می‌تواند قبل از خرید بر روی یک مجوز ارزیابی به‌صورت انتها‑به‑انتها ساخته و تست شود — فقط بایت‌های خروجی تغییر می‌کنند.