מדריך: פתיחת מסמכים עם מציג Doconut המוזרק ב‑.NET 8

מבוא

דוגמאות ישנות של Doconut עשויות לבנות את Viewer ישירות עם ארגומנטים של מטמון, הקשר HTTP, ונתיב רישיון. זה אינו מודל האינטגרציה של .NET 8 הנוכחי. AddDoconut() רושמת את Viewer באמצעות הזרקת תלויות, וקצות האפליקציה מקבלים את השירות במקום לקרוא לבונה.

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

---

1. התקנת והגדרת Doconut

הוסף את חבילת .NET 8:

dotnet add package Doconut.NET8

רשום את Doconut ושירותי הסשן של ASP.NET:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

חבר את ה‑middleware בסדר הנדרש. middleware של המשאבים חייב לרוץ לפני middleware של המסמך הסופי:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath מתאם את ההגדרה אך אינו יוצר את הענף של ASP.NET בעצמו. הנתיב הממופה /doconut חייב להתאים ל‑BasePath של ה‑widget.

2. הוספת משטח המציג והמשאבים

מציג הדפדפן של Doconut הוא תוסף jQuery. בדף Razor, הזרק את Viewer ובקש ממנו להפיק את תגי המשאבים בסדר תלותי:

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true
}))

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

אתחל את ה‑widget עם נתיבים התואמים לרישום השרת:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

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

3. הזרקת Viewer ופתיחת מסמך

Viewer נרשם כשירות זמני. קבל אותו דרך הזרקת קצה, הזרקת קונסטרקטור, או המנגנון המקביל באפליקציית ASP.NET Core שלך.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

להעלאה, ספק זרם ו‑FileInfo שהרחבה שלו מזהה את פורמט המקור:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

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

4. העברת האסימון ל‑widget

קבל את קצה ה‑open והעבר את האסימון שהוחזר ל‑objViewer.View:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

התייחס לאסימון כקרדנציאל נושא עבור מושב מסמך חי:

• אל תתעד או תשמור אותו.
• החזר אותו רק ללקוח מורשה.
• אל תחשוף את נתיב קובץ המקור.
• פתח מחדש את המסמך כאשר מושב פג תוקף.
• סגור את המושב כאשר המסמך אינו נדרש יותר.

5. סגירת מושבי צד השרת במכוון

קוד הלקוח יכול לקרוא ל‑objViewer.Close() כאשר המשתמש עוזב את המציג. זרימות עבודה בצד השרת יכולות גם לבטל אסימון ידוע במפורש:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

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

6. הוספת מודולים אופציונליים רק אחרי שהליבה עובדת

חיפוש והערות מצורפים לאותו מציג מאותחל. הוסף את ה‑CSS, הסקריפטים, ההרכבות, בדיקות הרישוי והקריאות חזרה למחזור החיים רק אחרי שהזרימה הבסיסית מצליחה:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

סדר זה משאיר כשלי רינדור הליבה נפרדים מהגדרת המודול האופציונלי.

טעויות נפוצות במיגרציה

תבנית ישנה או שגויה	הכיוון הנוכחי ב‑.NET 8
new Viewer(cache, accessor, licensePath)	הזרק Viewer אחרי AddDoconut()
קריאות טעינת רישיון סטטיות בקוד הבקשה	הגדר קלט רישיון ב‑AddDoconut()
דוגמאות סינכרוניות של OpenDocument(...)	השתמש ב‑OpenDocumentAsync(...)
CDN חיצוני או מומצא של מציג	הפץ משאבים מוטמעים עם ReferenceCss ו‑ReferenceScripts
API init() ג'אווהסקריפט גנרי	אתחל $('#div_ctlDoc').docViewer(...)
שמירת אסימון המציג	שמור את מזהה המסמך שלך; התייחס לאסימון כזמני

תיעוד רשמי של Doconut וודא את הדוגמאות מול גרסת החבילה המותקנת לפני התאמתן לקוד ייצור.