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

المقدمة

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

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

---

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

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

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

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

تسجيل ملحق المحول

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

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.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 للمعلومات الحالية حول المنتج والتكامل.