تبدیل اسناد سمت سرور در .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.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");
});

نام فایل و پسوند را به‌عنوان ورودی نامطمئن در نظر بگیرید. محدودیت‌های بارگذاری را اعمال کنید، نوع منبع را اعتبارسنجی کنید، کاربر درخواست‌کننده را مجاز کنید و از استفاده از نام فایل ارسال‌شده به‌عنوان مسیر ذخیره‌سازی خودداری کنید.

انتخاب هدف‌ها بر اساس قابلیت‌های واقعی

افزونه یک enum به نام ConversionTarget ارائه می‌دهد، اما هر قالب منبع نمی‌تواند هر هدفی را تولید کند. یک رابط کاربری سفارشی باید فقط هدف‌های مجاز برای منبع بارگذاری‌شده را نشان دهد نه تمام مقادیر enum.

هنگام استفاده از ویجت اختیاری مبدل Doconut، پاسخ باز آن شامل allowedTargets است. از این پاسخ به‌عنوان منبع حقیقت برای فایل فعلی استفاده کنید.

طراحی تبدیل پس‌زمینه به‌عنوان یک جریان کار برنامه

مبدل می‌تواند از یک سرویس برنامه یا کارگر صف‌گذاری‌شده فراخوانی شود. یک کار مقاوم معمولاً شامل موارد زیر است:

1. درخواست احراز هویت‌شده‌ای که منبع و هدف موردنظر را ثبت می‌کند.
2. پیام صف حاوی شناسهٔ کار برنامه، نه اعتبارنامه‌های خام.
3. کارگری که منبع را از طریق یک لایهٔ ذخیره‌سازی مجاز بازیابی می‌کند.
4. عملیات تبدیل محدود شده با قابلیت لغو.
5. ذخیره‌سازی خروجی بادوام با قوانین نگهداری صریح.
6. به‌روزرسانی وضعیت که مسیرهای داخلی یا جزئیات استثناهای حساس را فاش نمی‌کند.

قبل از تعیین تعداد کارگرها، همزمانی را با اسناد نماینده آزمایش کنید. هزینهٔ تبدیل بسته به قالب منبع، پیچیدگی سند، فونت‌ها، تصاویر و هدف خروجی متفاوت است.

حفظ ادعاهای امنیتی دقیق

اجرای مبدل داخل برنامهٔ .NET شما به این معناست که عملیات تبدیل نیازی به خودکارسازی Microsoft Office یا API تبدیل آنلاین جداگانه‌ای ندارد. این به‌طور خودکار حریم خصوصی، انطباق، حذف یا رمزنگاری برای کل سیستم را تضمین نمی‌کند.

این ویژگی‌ها به این بستگی دارد که برنامه چگونه کاربران را احراز هویت می‌کند، فایل‌های منبع را بازیابی می‌کند، ذخیره‌سازی را پیکربندی می‌کند، لاگ‌ها را محافظت می‌کند، خروجی را توزیع می‌کند و داده‌های موقت یا نگهداری‌شده را حذف می‌کند.

فهرست بررسی عملیاتی

• نسخه‌های Doconut.NET8 و Doconut.NET8.Converter را هم‌راستا نگه دارید.
• ConverterPlugin را در زمان پیکربندی سرویس ثبت کنید.
• DocumentConverter را از طریق تزریق وابستگی دریافت کنید.
• نقطهٔ پیش‌رو را در پسوندهای منبع جریان گنجانید.
• جریان‌های منبع و نتیجه را آزاد کنید.
• از لغو و محدودیت‌های اندازهٔ فایل در سطح برنامه استفاده کنید.
• پشتیبانی منبع‑به‑هدف را اعتبارسنجی کنید، نه این‌که فرض کنید هر جفتی کار می‌کند.
• صحت و مصرف منابع را با فایل‌های نماینده تست کنید.
• تصمیمات مربوط به ذخیره‌سازی، مجوزدهی، حسابرسی و نگهداری را در کد برنامه نگه دارید.

به نمای کلی رسمی افزونه مبدل Doconut و مستندات Doconut برای اطلاعات به‌روز محصول و یکپارچه‌سازی مراجعه کنید.