پلاگین مبدل
سندها را به ۴۵ قالب هدف تبدیل کنید
پلاگین Converter Doconut را به یک سرویس تبدیل سند تبدیل میکند. این پلاگین موتور پشت رابط عمومی DocumentConverter را فراهم میکند و — به صورت اختیاری — یک ویجت آماده با قرارداد HTTP خود دارد، به طوری که میتوانید اسناد را از C#، از ویجت یا از یک فرانتاند که خودتان مینویسید، تبدیل کنید.
| سطح | زمانیکه استفاده میکنید |
|---|---|
DocumentConverter (C#) | شما در سرور تبدیل میکنید، بدون درگیر شدن مرورگر |
Drop-in widget (doconutConverter.js) | اگر میخواهید یک صفحه بارگذاری، تبدیل و دانلود آماده در صفحه خود داشته باشید |
HTTP endpoints (?convert=open|run|download) | اگر رابط کاربری تبدیل خود را بر پایه قرارداد سرور مستند ساختهاید |
نصب بسته
پلاگین Converter پایدار آخرین نسخه را نصب کنید:
dotnet add package Doconut.NETStandard.Converterبرای قفل کردن پلاگین به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
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، که همراه با بسته پایه ویور نصب میشود، ارائه میشود.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});این تمام نیازهای رابط C# است. ویجت و نقاط انتهایی HTTP آن یک گزینه جداگانه، AddConverterWidget() هستند (به ویجت آماده مراجعه کنید).
پلاگین به مجوزی نیاز دارد که قابلیت Converter را بدهد. بدون آن، AddDoconut() در زمان راهاندازی یک InvalidOperationException پرتاب میکند، پیش از این که برنامه درخواست را سرو کند:
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 در هر جایی که نیاز دارید حل کنید — این بهصورت بدون حالت طراحی شده است، بنابراین یک نمونه واحد برای استفاده مجدد در درخواستها ایمن است.
// DocumentConverter را تزریق کنید؛ سازندهاش داخلی است، بنابراین هرگز `new` آن را انجام ندهید.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension شامل نقطهٔ پیشرو است. password در صورتی که سند محافظت نشده باشد، null است.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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) ۴۵ عضو دارد:
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 ویجت بهصورت اختیاری هستند و بهطور پیشفرض غیرفعالاند — بهصورت پیشفرض امن هستند. آنها را در سمت سرور فعال کنید، همراه با ثبت افزونه:
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() استثنا میاندازد:
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 خودش همچنان سرو میشود (این یک منبع ایستاتیک ساده جاسازیشده است؛ فقط نقطههای انتهایی که به آنها مراجعه میکند محدود شدهاند).
جاسازی آن
<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 را انتخاب کند، تبدیل میکند، وقتی امکانپذیر باشد نتیجه را پیشنمایش میدهد و امکان دانلود را فراهم میکند.
گزینهها
| گزینه | نوع | پیشفرض | یادداشت |
|---|---|---|---|
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() خود نمونه ویجت را برمیگرداند — آن را نگه دارید تا ویجت را بهصورت برنامهنویسی کنترل کنید:
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'.
| کلید | پیشفرض انگلیسی |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could 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 میخواند، بنابراین میتوانید بدون دستکاری داخلی آن، تم آن را تنظیم کنید:
#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> | تبدیل منبع ذخیرهشده به target | 200 — { 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 مقدار یکسانی دارند. بستن نتیجهٔ مشاهدهگر مخزن دانلود هنوز معتبر را حذف نمیکند، و بازنشانی ویجت مرورگر هیچیک از این بازهها را تمدید نمیکند.
حالتهای خطا، گروهبندی بر حسب مسیر:
| مسیر | وضعیت | زمان | بدنه |
|---|---|---|---|
| any | 404 | ویجت فعال نیست (AddConverterWidget() هرگز فراخوانی نشده است) — قبل از هر یک از سه مسیر بررسی میشود | فقط وضعیت |
| any | 405 | متد HTTP نادرست (open/run نیاز به POST دارند؛ download نیاز به GET دارد) | فقط وضعیت |
open | 400 | بارگذاری چندبخشی نیست | Expected a multipart file upload. |
open | 400 | فایلی وجود ندارد یا خالی است | No file uploaded. |
open | 400 | پسوند منبعی که قابل تبدیل نیست | This file type cannot be converted. |
open | 403 | نوع فایل به قابلیتای نیاز دارد که مجوز آن را نمیدهد (فایل DICOM بدون Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | فایل بارگذاریشده از MaxUploadMb بیشتر است، در برابر Content-Length بررسی میشود و در حین خواندن بارگذاری | File is too large. |
run | 400 | توکن خراب (GUID نیست) | Invalid token. |
run | 400 | یک target که به ConversionTarget تجزیه نمیشود | Unknown target format. |
run | 400 | target در allowedTargets منبع وجود ندارد | That target format is not available for this file. |
run | 404 | بارگذاری ذخیرهشده منقضی شده یا توکن هرگز باز نشده است | Upload expired — please re-open the file. |
open, run | 500 | پردازش بهصورت داخلی شکست خورد | یک پیام پاکسازیشده — به همان شیوهای که تمام مسیرهای خطای Doconut پاکسازی میشوند؛ هرگز جزئیات داخلی را فاش نمیکند |
download | 400 | توکن خراب (GUID نیست) | فقط وضعیت |
download | 404 | توکن دانلود ناشناخته یا منقضی شده | فقط وضعیت |
یک مسیر کامل با fetch:
// 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 خود قرار دهید.
در تولید
- نصب افزونه در کنار بستهٔ هسته، با همان نسخه:
dotnet add package Doconut.NETStandard.Converter. - فایل مجوز را اضافه کنید.
Doconut.Viewer.Converter.licرا در همان پوشهای کهDoconut.Viewer.licقرار دارد بگذارید. - حداکثر سرور را تنظیم کنید.
MaxUploadMbدرAddConverterWidgetمحدودیتی است که سرور اعمال میکند؛maxUploadMbویجت فقط یک بررسی سمتکلاینت است. دو مقدار را برابر نگه دارید. - رابط کاربری را از همان مبدا که نقاط انتهایی Doconut هستند سرو کنید، یا با reverse-proxy آنها (به ساخت رابط کاربری خودتان مراجعه کنید).
- نتایج تبدیل را آزاد کنید. جریانی که
ConvertAsyncبرمیگرداند در استخر است؛ آزاد کردن آن بافرهایش را به استخر برمیگرداند.
مزارع وب
ویجت هر بارگذاری و نتیجهٔ آن را در حافظهٔ گرهای که open را سرو کرده نگه میدارد. پشت یک بارگذاریکنندهٔ بار بدون نشستهای چسبنده، یک درخواست بعدی run، download یا پیشنمایش میتواند به گرهٔ دیگری برسد و بارگذاری را پیدا نکند. فروشگاه مشترک و رمزگذاریشدهٔ ویجت را یکبار، پس از AddDoconut() ثبت کنید:
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
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
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 را اعطا میکند استفاده کنید |
ویجت بارگیری میشود اما درخواستهای آن پاسخ میدهند 404 | AddConverterWidget() فراخوانی نشده است، یا 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را تزریق کنید.- این
ConversionTargetenum تمام خانوادههای منبع را پوشش میدهد. کتابخانهٔ قبلی یک نوع*ConfigConverterبرای هر خانواده داشت —WordConfigConverter،ExcelConfigConverter، و غیره — که هر کدام enum تو در تویEnTargetFormatخود را داشتند، بهعلاوه یک enumSourceFormatConverterبرای ورودی. همهٔ آنها حذف شدهاند؛ راهنمای راهنمای مهاجرت را ببینید. - فقط ویندوز، مانند بقیهٔ بستهٔ .NET Standard.
آیا این صفحه مفید بود؟