تبدیل اسناد سمت سرور در .NET با Doconut

مقدمه

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

پلاگین مبدل .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");
});

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

تبدیل یک جریان بارگذاری‌شده

نسخهٔ overload برای جریان به پسوند منبع نیاز دارد—از جمله نقطهٔ پیش‌رو—چون مبدل از آن برای تشخیص فرمت منبع استفاده می‌کند:

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 را ببینید.