המרת מסמכים בצד השרת ב-.NET עם Doconut

מבוא

המרת מסמכים בצד השרת מאפשרת ליישום ליצור פלט מנורמל ללא אוטומציה של Microsoft Office או שליחת המקור לשירות המרה מקוון נפרד. זה יכול לפשט פורטלי מסמכים, משימות רקע, וזרימות עבודה של ייצוא מבוקר—אך היישום המארח עדיין שולט בגישה, באחסון, בשמירה, במעקב ובמסירת התוצאה.

תוסף הממיר של Doconut ב‑.NET 8 מאפשר המרה דרך שירות DocumentConverter המוזרק באמצעות ה‑Dependency Injection. מדריך זה מתמקד ברישום הנוכחי ובמודל ה‑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");
});

התייחס לשם הקובץ והסיומת כקלט בלתי מהימן. הפעל מגבלות העלאה, אמת את סוג המקור, אשר את המשתמש המבקש, והימנע משימוש בשם הקובץ שהוגש כנתיב אחסון.

בחירת יעדים בהתאם ליכולות אמיתיות

התוסף מציג enum בשם ConversionTarget, אך לא כל פורמט מקור יכול לייצר כל יעד. ממשק משתמש מותאם צריך להציג רק את היעדים המותרים עבור המקור שהועלה במקום להציג את כל ערכי ה‑enum.

כאשר משתמשים בווידג'ט האופציונלי של Doconut לממיר, תגובת הפתיחה שלו כוללת allowedTargets. השתמש בתגובה זו כמקור האמת עבור הקובץ הנוכחי.

תכנון המרה ברקע כזרימת עבודה של יישום

ניתן לקרוא לממיר משירות יישום או מעבד בתור. משימה חזקה בדרך כלל כוללת:

1. בקשה מאומתת המתעדת את המקור והיעד הרצוי.
2. הודעת תור המכילה מזהה משימת יישום, ולא אישורים גולמיים.
3. מעבד שמושך את המקור דרך שכבת אחסון מורשית.
4. פעולת המרה מוגבלת עם אפשרות לביטול.
5. אחסון פלט עמיד עם כללי שמירה מפורטים.
6. עדכון סטטוס שאינו חושף נתיבים פנימיים או פרטי שגיאות רגישים.

מדוד קונקורנטיות עם מסמכים מייצגים לפני בחירת מספר העובדים. עלות ההמרה משתנה לפי פורמט המקור, מורכבות המסמך, גופנים, תמונות והיעד הפלט.

שמור על טענות אבטחה מדויקות

הפעלת הממיר בתוך יישום .NET שלך משמעותה שפעולת ההמרה אינה דורשת אוטומציה של Microsoft Office או API המרה מקוון נפרד. זה לא מבטיח באופן אוטומטי פרטיות, ציות, מחיקה או הצפנה עבור המערכת כולה.

תכונות אלו תלויות באופן שבו היישום מאמת משתמשים, מושך קבצי מקור, מגדיר אחסון, מגן על יומנים, מפיץ פלט ומסיר נתונים זמניים או שמורים.

רשימת בדיקה תפעולית

• שמור על גרסאות Doconut.NET8 ו‑Doconut.NET8.Converter מתואמות.
• רשום את ConverterPlugin במהלך קונפיגורציית השירות.
• קבל את DocumentConverter באמצעות הזרקת תלות.
• כלול את הנקודה המקדימה בסיומות המקור של הזרם.
• פנה את זרמי המקור והתוצאה.
• השתמש בביטול ובמגבלות גודל קובץ ברמת היישום.
• אמת את התמיכה ממקור ליעד במקום להניח שכל זוג עובד.
• בדוק דיוק ושימוש במשאבים עם קבצים מייצגים.
• שמור החלטות אחסון, הרשאה, ביקורת ושמירה בקוד היישום.

ראה את הסקירה הרשמית של תוסף ממיר של Doconut ואת תיעוד של Doconut למידע עדכני על המוצר והאינטגרציה.