ملحق المحول

تحويل المستندات إلى 45 صيغة مستهدفة

يقوم ملحق المحول بتحويل Doconut إلى خدمة تحويل المستندات. إنه يساهم بالمحرك وراء الواجهة العامة DocumentConverter، و— عند الاختيار — بأداة جاهزة مع عقد HTTP الخاص بها، بحيث يمكنك تحويل المستندات من C#، أو من الأداة، أو من واجهة أمامية تقوم بكتابتها بنفسك.

السطحاستخدمه عندما
DocumentConverter (C#)تقوم بالتحويل على الخادم، دون مشاركة المتصفح
أداة جاهزة للدمج (doconutConverter.js)تريد شاشة جاهزة للرفع والتحويل والتحميل في صفحتك
نقاط النهاية HTTP (?convert=open|run|download)تبني واجهة تحويل خاصة بك مقابل عقد خادم موثّق

تثبيت الحزمة

قم بتثبيت أحدث نسخة مستقرة من ملحق المحول:

bash
dotnet add package Doconut.NET8.Converter

لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:

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

احفظ حزمة المحول بنفس إصدار Doconut.NET8. معرف الحزمة هو Doconut.NET8.Converter؛ يظهر .<version> فقط في اسم الملف .nupkg الذي تم تنزيله.

ملف ترخيص الملحق، Doconut.Viewer.Converter.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يتم قراءته مع ترخيص العارض.

المنصات. يعمل الملحق حيثما يعمل Doconut.NET8: Windows، وLinux المبني على glibc على x64 (ليس Alpine أو توزيعات أخرى مبنية على musl). على Linux، قم بتثبيت مكتبة تكوين الخطوط قبل فتح أول مستند:

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 موحد. كل ملحق، بما في ذلك المحول، يُسجل بنفس الطريقة: استدعِ AddPlugin<TPlugin>() داخل AddDoconut(). ConverterPlugin يأتي في حزمة NuGet الخاصة به، Doconut.NET8.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 في التحميل الزائد للتيار النقطة الرائدة (".xlsx"، وليس "xlsx") — يقوم المحول بمطابقته مع كتالوج الصيغ ولا يمكن للامتداد المجرد أن يُحل. وعلى الرغم من اسمه، فإن WordToHtmlAsync يُعيد Task<Stream>، وليس Task<string> — ستحصل على مستند HTML (الصور مدمجة كـ Base64) كتيار، نفس نتيجة كل تحويل آخر.

المستدعي يملك التيار المعاد ويجب أن يتخلص منه بعد النسخ أو إرجاع محتوياته. خدمة DocumentConverter نفسها تُستخرج من حقن الاعتماد؛ لا تقم بإنشائها أو التخلص منها يدويًا.

صيغ الهدف

ConversionTarget (namespace Doconut.Configs.Conversion) لديها 45 عضوًا:

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. لا تُبرمج هذا التعداد صلبًا كقائمة أهداف لواجهة المستخدم الخاصة بك: ?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;
    });
});

AddConverterWidget() بدون أي معطى يُمكّن الودجت بالإعدادات الافتراضية (MaxUploadMb = 25). لا يمنح حقوق التحويل بنفسه: يحتاج إلى 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 أو عنصرًا، يرمي استثناءً إذا لم يُعثر على التركيب، ويُعيد مقبضًا. الودجت يرفع ملفًا، يعرض معاينة للصفحة 1، يسمح للمستخدم باختيار أحد allowedTargets، يحول، يعرض معاينة للنتيجة عندما يستطيع، ويقدم التحميل.

الخيارات

الخيارالنوعالافتراضيملاحظات
basePathstring/doconutالمسار الأساسي لنقاط النهاية ?convert=؛ يجب أن يتطابق مع فرع ASP.NET حيث يتم تثبيت UseDoconut() فعليًا (عادةً ما يتم تنسيق ذلك عبر MiddlewarePath)
resPathstring/doconut-resمقبول لتوافق التكوين مع أدوات Doconut الأخرى؛ أداة التحويل لا تُنشئ حاليًا أي عنوان URL منها
maxUploadMbnumber25فحص مسبق على جانب العميل فقط — يرفض ملفًا كبيرًا جدًا قبل الرفع. يفرض الخادم الحد الخاص به بشكل مستقل ويُجيب بـ 413 إذا تم تجاوز الحد
licenseUrlstring | nullnullعند التفعيل، يحول إشعار العلامة المائية على شاشة النتيجة إلى رابط لهذا العنوان
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، وخط واجهة المستخدم النظامي لـ --dcw-font.

أنشئ واجهة أمامية خاصة بك

الأداة هي مجرد عميل لهذا العقد HTTP — يمكنك بناء واجهة أمامية خاصة بك تتعامل معه مباشرة لتجربة مستخدم مختلفة. جميع المسارات الثلاثة تقع تحت فرع ASP.NET حيث يتم تركيب UseDoconut() (عادةً /doconut)، وتستجيب بـ 404 حتى يتم استدعاء AddConverterWidget(). الأخطاء تحمل جسم JSON، { "error": "..." }، باستثناء الحالات التي تقول فيها الجدول "status only". قيمة غير معروفة لـ ?convert= تجيب بـ 400.

المسارالغرضاستجابة النجاح
POST ?convert=open (multipart, one file)رفع وفتح مستند مصدر للمعاينة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 الملف الأول في جسم multipart.

resultToken هو null، وresultPages هو 0، عندما لا يمكن معاينة النتيجة. downloadName هو اسم ملف المصدر مع امتداد الهدف.

تستخدم صور المعاينة مسار صورة المشاهد القياسي، {basePath}?token={token}&page=1&thumb=1&width={px}، مع الـ token من open أو الـ resultToken من run. تطلب الأداة width=240.

يتم تخزين بايتات المصدر المرفوعة على الخادم وتبقى لمدة 30 دقيقة بعد آخر قراءة لها؛ بمجرد انتهاء هذه الفترة، يرد run بـ 404 ويجب إعادة فتح الملف. النتيجة المحوّلة تعيش في نفس التخزين — يحصل downloadToken على نافذة جديدة لمدة 30 دقيقة عند اكتمال التحويل — بينما 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.
run400target لا يمكن تحليله إلى ConversionTargetUnknown 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، أو استخدم reverse-proxy لكلا مساري /doconut (مسار الوسيط ومسار الموارد) تحت أصل واجهة المستخدم الخاصة بك.

في الإنتاج

  1. تثبيت الإضافة بجوار حزمة النواة، بنفس الإصدار: dotnet add package Doconut.NET8.Converter.
  2. إضافة ملف الترخيص. ضع Doconut.Viewer.Converter.lic في نفس المجلد مع Doconut.Viewer.lic.
  3. تعيين الحد الأقصى للخادم. MaxUploadMb في AddConverterWidget هو الحد الذي يفرضه الخادم؛ فـ maxUploadMb الخاص بالأداة هو مجرد فحص من جانب العميل. حافظ على مساواة الاثنين.
  4. خدمة واجهة المستخدم من نفس الأصل كما نقاط نهاية Doconut، أو استخدم عكس الوكيل لها (انظر بناء الواجهة الأمامية الخاصة بك).
  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 bytes، متطابقة على كل عقدة
    // store.Ttl = TimeSpan.FromMinutes(30);   // كم من الوقت يُحتفظ بالتحميل (الإعداد الافتراضي)
});
  • يحتاج خادم واحد إلى لا شيء: بدون هذا النداء يُستخدم المخزن في الذاكرة.
  • يتم تشفير التحميلات والنتائج أثناء التخزين على المشاركة (AES-256، تشفير ثم MAC)، ويرتبط كل ملف برمز الوصول الخاص به، لذا لا يمكن لأي رمز قراءة ملف آخر.
  • على المشاركة، يُحتفظ بالتحميل أو النتيجة لمدة Ttl بعد كتابتها؛ القراءة لا تُطيل تلك الفترة.
  • FarmKey يجب أن يكون على الأقل 32 بايت ومتساوٍ على كل عقدة. حمّله من مخزن سري؛ لا تُبرمجه صراحة. التسجيل يُطلق ArgumentException عندما يكون RootPath مفقودًا أو FarmKey أقصر من 32 بايت.
  • وجه 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

الصيغ الـ45 للإخراج المذكورة في صيغ الهدف.

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ارفع MaxUploadMb في AddConverterWidget؛ فـ 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)انقضت نافذة الـ 30 دقيقة، أو عقدة مزارع الويب لا تملك التحميلافتح الملف مرة أخرى؛ في المزرعة، سجِّل AddDoconutDistributedWidgets
الأداة تفشل عندما تكون واجهة المستخدم على أصل آخرنقاط النهاية لا تدعم CORSقدِّم واجهة المستخدم من نفس الأصل، أو استخدم عكس الوكيل لمسارات Doconut
السمة لا تُطبقالمتغيرات مُعينة على سلف أو على عنصر داخل التركيب؛ قاعدة .dcw الخاصة بالأداة تُعيّنها على التركيباستهدف التركيب نفسه: #doconut-convert.dcw أو #doconut-convert

هل كانت هذه الصفحة مفيدة؟