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

מבוא

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

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

---

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();

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

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

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

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>

אתחלו את הווידג'ט עם נתיבים התואמים לרישום השרת:

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. העברת האסימון לווידג'ט

קבלו את קצה הפתיחה והעבירו את האסימון שהוחזר ל‑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 גנרי של JavaScript init()	אתחלו את $('#div_ctlDoc').docViewer(...)
שמירת אסימון המציג	שמרו את מזהה המסמך שלכם; התייחסו לאסימון כזמני

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