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

מבוא

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

תוסף הממיר של Doconut ל-.NET 8 חושף המרה דרך שירות 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");
});

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

בחירת יעדים על פי יכולות ממשיות

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

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

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

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

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

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

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

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

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

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

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

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