تحويل المستندات من جانب الخادم في .NET باستخدام Doconut

المقدمة

يتيح تحويل المستندات من جانب الخادم للتطبيق إنشاء مخرجات موحدة دون أتمتة Microsoft Office أو إرسال المصدر إلى خدمة تحويل عبر الإنترنت منفصلة. يمكن أن يبسط ذلك بوابات المستندات، والوظائف الخلفية، وسير عمل التصدير المتحكم فيه—لكن التطبيق المضيف لا يزال يتحكم في التحكم بالوصول، والتخزين، والاحتفاظ، والمراقبة، وتسليم النتيجة.

يُتيح مكوّن Doconut .NET 8 Converter Plugin تحويل المستندات عبر خدمة DocumentConverter المُحقنة بالاعتماديات. يركّز هذا الدليل على نموذج التسجيل وواجهة برمجة التطبيقات الحالية ويتجنّب ربط التحويل بجلسة العارض.

---

تثبيت الحزم المتطابقة

قم بتثبيت حزم العارض الأساسي ومحول الملفات:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

احرص على أن تكون الحزمتان على نفس نسخة الإصدار. عندما تكون عمليات البناء القابلة لإعادة الإنتاج مهمة، قم بتثبيت النسخة في ملف المشروع أو مرّر نفس قيمة --version لكلا الأمرين.

تسجيل مكوّن التحويل

تُسجَّل الإضافات داخل رد الاتصال AddDoconut للخيارات. لا توجد طريقة تسجيل منفصلة AddConverter():

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

يجب على التطبيق استخدام ترخيص يمنح صلاحية التحويل. حلّ أخطاء بدء التشغيل والترخيص قبل قبول طلبات التحويل؛ لا تؤجّلها إلى طابور خلفي حيث يصبح تشخيصها أصعب.

تحويل ملف من C#

قم بحقن DocumentConverter في نقطة النهاية أو الخدمة التي تتولى طلب التحويل. مُنشئ المحول داخلي، لذا لا ينبغي لكود التطبيق إنشاءه مباشرة.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

التدفق المعاد قابل للتمرير وموقعه في البداية. يمتلكه المستدعي ويجب إغلاقه بعد النسخ أو إرجاع المحتوى.

تحويل تدفق تم تحميله

يتطلب التحميل الزائد للتدفق امتداد المصدر — بما في ذلك النقطة الأولية — لأن المحول يستخدمه لتحديد تنسيق المصدر:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

عامل اسم الملف والامتداد كمدخلات غير موثوقة. فرض حدود للتحميل، والتحقق من نوع المصدر، وتفويض المستخدم الطالب، وتجنّب استخدام اسم الملف المرسل كمسار تخزين.

اختيار الأهداف بناءً على القدرات الفعلية

تُظهر الإضافة تعداد ConversionTarget، لكن ليس كل تنسيق مصدر يمكنه إنتاج كل هدف. يجب على واجهة المستخدم المخصصة إظهار الأهداف المسموح بها فقط للمصدر المرفوع بدلاً من عرض جميع قيم التعداد.

عند استخدام أداة التحويل الاختيارية الخاصة بـ Doconut، يتضمن الرد المفتوح الخاص بها allowedTargets. استخدم هذا الرد كمصدر الحقيقة للملف الحالي.

تصميم تحويل الخلفية كسير عمل تطبيق

يمكن استدعاء المحول من خدمة تطبيق أو عامل في طابور. عادةً ما يتضمن عمل قوي ما يلي:

1. طلب موثّق يسجل المصدر والهدف المطلوب.
2. رسالة طابور تحتوي على معرف وظيفة التطبيق، وليس بيانات اعتماد خام.
3. عامل يسترجع المصدر عبر تجريد تخزين مخوَّل.
4. عملية تحويل محدودة مع إمكانية الإلغاء.
5. تخزين ناتج دائم مع قواعد احتفاظ صريحة.
6. تحديث حالة لا يكشف عن المسارات الداخلية أو تفاصيل الاستثناء الحساسة.

قِسّ التوازي باستخدام مستندات تمثيلية قبل اختيار عدد العاملين. تختلف تكلفة التحويل حسب تنسيق المصدر، وتعقيد المستند، والخطوط، والصور، والهدف النهائي.

الحفاظ على دقة مطالبات الأمان

تشغيل المحول داخل تطبيق .NET يعني أن عملية التحويل لا تتطلب أتمتة Microsoft Office أو واجهة برمجة تطبيقات تحويل عبر الإنترنت منفصلة. ولا يضمن ذلك تلقائيًا الخصوصية أو الامتثال أو الحذف أو التشفير للنظام بالكامل.

تعتمد هذه الخصائص على طريقة توثيق التطبيق للمستخدمين، واسترجاع ملفات المصدر، وتكوين التخزين، وحماية السجلات، وتوزيع المخرجات، وإزالة البيانات المؤقتة أو المحتفظ بها.

قائمة التحقق التشغيلية

• حافظ على توافق إصدارات Doconut.NET8 و Doconut.NET8.Converter.
• سجّل ConverterPlugin أثناء تكوين الخدمات.
• احصل على DocumentConverter عبر حقن التبعيات.
• ضمن النقطة الأولية في امتدادات مصدر التدفق.
• قم بإغلاق تدفقات المصدر والنتيجة.
• استخدم الإلغاء وحدود حجم الملفات على مستوى التطبيق.
• تحقق من دعم المصدر إلى الهدف بدلاً من افتراض أن كل زوج يعمل.
• اختبر الدقة واستخدام الموارد باستخدام ملفات تمثيلية.
• احتفظ بقرارات التخزين، والتفويض، والتدقيق، والاحتفاظ في كود التطبيق.

اطلع على النظرة العامة الرسمية لـ مكوّن محول Doconut وتوثيق Doconut للحصول على معلومات محدثة حول المنتج والتكامل.