ملحق المحول

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

تثبيت الحزمة

قم بتثبيت أحدث ملحق Converter ثابت:

dotnet add package Doconut.NETStandard.Converter

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

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

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

تسجيل الملحق

لا توجد طريقة AddConverter() — نموذج ملحقات Doconut موحد. كل ملحق، بما في ذلك Converter، يُسجَّل بنفس الطريقة: استدعِ AddPlugin<TPlugin>() داخل AddDoconut(). ConverterPlugin يُوزَّع في حزمة NuGet الخاصة به، Doconut.NETStandard.Converter، المثبتة بجانب حزمة المشاهد الأساسية.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

ينتج هذا الاستدعاء استثناءً عند بدء التشغيل بسبب ترخيص مفقود، أو ملف TRIAL قديم، أو ترخيص غير مؤقت لا يمنح القدرة على Converter — InvalidOperationException يُرفع من داخل AddDoconut()، قبل أن يبدأ التطبيق في معالجة الطلبات. تُقبل تسجيلات Demo/NFR المؤقتة؛ بعد انتهاء صلاحيتها، يظل التحويل متاحًا مع مخرجات مائية. لا توجد طبقة مجانية صامتة. راجع إعداد الترخيص لمعرفة كيفية تحميل التراخيص.

التحويل من C#

كل عملية تحويل تُعيد MemoryStream قابل للبحث موضعه 0، جاهز للقراءة أو النسخ فورًا. احصل على DocumentConverter من DI أينما احتجته — فهو بلا حالة حسب التصميم، لذا يمكن إعادة استخدام نسخة واحدة بأمان عبر الطلبات.

viewer.Converter.GetConverter() غير موجود هنا. لم يعد الوصول إلى التحويل عبر نسخة المشاهد: قم بحقن Doconut.DocumentConverter بدلاً من ذلك.

// حقن DocumentConverter؛ مُنشئه داخلي، لذا لا تقم أبداً بـ `new` له.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension يتضمن النقطة الأولية. password هو null ما لم يكن المستند محمياً.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

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

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

تفصيلان سهلان الخطأ فيهما: يجب أن يتضمن sourceExtension في التحميل الزائد للمجرى النقطة الأولية (".xlsx"، وليس "xlsx") — يطابق المحول ذلك مع كتالوج الصيغ ولا يمكن للامتداد المجرد أن يُحل. وعلى الرغم من اسمه، يُعيد WordToHtmlAsync Task<Stream>، وليس Task<string> — تحصل على مستند HTML (الصور مدمجة كـ Base64) كمجرى، وهو نفس نتيجة كل تحويل آخر.

صيغ الهدف

ConversionTarget (المساحة الاسمية Doconut.Configs.Conversion) تحتوي على 45 عضوًا:

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

هذا التعداد يغطي كل عائلة مصدر. المكتبة السابقة كان لديها نوع *ConfigConverter لكل عائلة — WordConfigConverter، ExcelConfigConverter، وهكذا — كل منها يحتوي على تعداد EnTargetFormat المتداخل الخاص به، بالإضافة إلى تعداد SourceFormatConverter للمدخل. جميعها اختفت؛ راجع دليل الترحيل.

ليس كل مصدر يتحول إلى كل هدف — يقوم الملحق بربط كل عائلة صيغ المصدر (Word، Excel، PowerPoint، PDF، CAD، Image، Email، Diagram، Project/Task، PSD، مستند ويب) بمجموعة ثابتة من الأهداف المسموح بها. لا تقم بترميز ثابت لهذا التعداد كقائمة أهداف واجهة المستخدم الخاصة بك: ?convert=open يُعيد allowedTargets الفعلي لأي ملف تم تحميله للتو، وهذا ما يجب أن يُقود أداة الاختيار.

أداة الإدراج السريعة

نقاط النهاية ?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;
    });
});

<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):

النداءات الراجعة:

Doconut.convert() يُعيد كائن الأداة نفسه — احتفظ به لتوجيه الأداة برمجيًا:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // العودة إلى شاشة الخمول/الإسقاط؛ لا يعيد تشغيل onReady
conv.loadFile(file);  // يبدأ التدفق باستخدام كائن File؛ لا عملية إلا إذا كان النظام حاليًا في حالة idle
conv.destroy();       // يزيل المستمعين، يفرغ الـ mount؛ لا يمكن استخدام المثيل بعد ذلك

بناء الواجهة الأمامية الخاصة بك

الأداة مجرد عميل لهذا العقد HTTP — قم ببناء واجهة أمامية خاصة بك مباشرةً للحصول على تجربة مستخدم مختلفة. جميع المسارات الثلاثة تقع تحت فرع ASP.NET حيث يتم تثبيت UseDoconut() (عادةً /doconut):

يتم تخزين بايتات المصدر المرفوعة على الخادم مع عمر افتراضي 30 دقيقة؛ بمجرد انتهاء هذه النافذة، يجيب run بـ 404 ويجب إعادة فتح الملف. النتيجة المحولة تعيش في نفس التخزين — يحصل downloadToken على نافذة جديدة لمدة 30 دقيقة عند اكتمال التحويل — بينما resultToken هو رمز جلسة عارض عادي يتبع ذاكرة التخزين المؤقت لجلسة العارض، مستقلًا عن التخزين.

sourceExt في استجابة open لا يحتوي على نقطة بادئة (مثال: "docx") — وهو عكس الاتفاقية من معلمة sourceExtension على DocumentConverter.ConvertAsync، التي تتطلب واحدة.

أنماط الفشل، مجمعة حسب المسار:

ملكية المورد

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

بالنسبة لأداة الويب، فإن مخازن الرفع والتحميل لها فترات صلاحية مستقلة تبلغ 30 دقيقة. يتبع عارض resultToken بدلاً من ذلك عمر جلسة العارض. إغلاق نتيجة العارض لا يحذف مخزن التحميل الذي لا يزال صالحًا، وإعادة ضبط أداة المتصفح لا يمدد أيًا من فترات الصلاحية.

استكشاف الأخطاء وإصلاحها

وضع العلامة المائية

مع تسجيل ConverterPlugin، تكون رخصة المضيف في واحدة من ثلاث حالات:

كلا مساري الاستدعاء يحسبان العلامة وفقًا للقاعدة نفسها: الواجهة DocumentConverter بلغة C# تستخلصها داخليًا من حالة IsViewerLicensed وIsTemporary للرخصة، ومعالج ?convert=run للواجهة يقوم بالتحقق المكافئ (IsViewerLicensed && !IsTrial && !IsTemporary) لملء الحقل watermarked الذي يُرجعه. يمكن بناء واختبار تكامل من الطرف إلى الطرف على رخصة تقييم قبل الشراء — فقط بايتات الناتج تتغير.