הגירה משילוב הקלאסי של .NET 6

Doconut יש שני שילובים נפרדים של .NET 6. הם יכולים להשתמש באותו שם חבילה Doconut.NET6, ולכן יש לזהות את הדור מה‑APIs ביישום לפני שינוי חבילות, אתחול, רשיונות, או משאבי דפדפן.

איזה שילוב של .NET 6 אתה משתמש?

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

מדוע שם חבילת NuGet עשוי לא לספק מידע

שני הדורות שוחררו תחת מזהה החבילה Doconut.NET6. ולכן הפנייה לחבילה, קובץ lock, או .nupkg שמור במטמון לא מזהים את ה‑API המארח בעצמם. רשום את גרסת החבילה המדויקת ובדוק יחד את Program.cs, בניית ה‑viewer, פתיחת המסמך, וסקריפטים של הדפדפן.

הגרסה הנוכחית שנבדקה למדריך זה היא Doconut.NET6 26.7.0. החבילות הציבוריות האופציונליות שלה הן Doconut.NET6.Converter ו‑Doconut.NET6.Dicom, קיבוע לאותה גרסת שחרור כמו חבילת הליבה.

לפני המיגרציה

1. צור סניף וגיבוי שניתן לפריסה של היישום הקיים.
2. רשום את גרסאות החבילות הליבה והתוספים המדויקות.
3. ערוך אינבנטורי של כל מיפוי DocImage.axd, קריאת new Viewer(...), קריאת טעינת רישיון, סקריפט Doconut שהועתק, פעולה מותאמת של סרגל כלים, ונקודת הקצה של פתיחת מסמך.
4. שמר את קבצי .lic הנוכחיים ואת סודות הפריסה מחוץ לבקרת גרסאות.
5. לכוד סט מייצג של מסמכי PDF, Office, תמונות, CAD, אימייל, DICOM, ניתנים לחיפוש, מוגנים בסיסמה, ומעוררים הערות.
6. רשום את זמן הקצאת הסשן הקיים, התנהגות האבטחה, הפונטים, והגדרות הפלטפורמה.

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

תאימות חבילות ורשיונות

החלף או עדכן את חבילת הליבה במכוון; אל תסתמך על מזהה חבילה זהה לבחירת ה‑API החדש. הפקודה ברירת המחדל מתקינה את הגרסה היציבה האחרונה:

dotnet add package Doconut.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

שמור כל תוסף Doconut באותה גרסה כמו חבילת הליבה. השילוב הנוכחי טוען רישיונות פעם אחת במהלך AddDoconut(), תוך שימוש בסדר עדיפויות זה:

LicenseStream > LicenseContent > LicensePath > automatic discovery

גילוי אוטומטי מחפש קבצים Doconut.Viewer.lic וקבצים נלווים Doconut.Viewer.<Capability>.lic. קריאה קלאסית ל‑Viewer.DoconutLicense(...) או Viewer.SetLicensePlugin(...) איננה מנגנון אתחול נוכחי. העבר את הרישיון ל‑DoconutOptions, שמור קבצים נלווים יחד כאשר משתמשים בגילוי אוטומטי, הפעל מחדש לאחר שינוי רישיון, ואמת יכולות דרך IDoconutLicenseService.

אל תניח שהימצאות רישיון תוסף ישן מוכיחה זכאות לבניית תוסף נוכחית. בדוק את Viewer, Search, Annotation, Converter, ו‑DICOM בנפרד עם הארטיפקטים המאושרים של הגרסה.

אתחול והזרקת תלויות

יישומים קלאסיים בונים את Viewer עם מטמון ASP.NET ותלויות של גישה לבקשה:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

האינטגרציה הנוכחית רושמת את Doconut פעם אחת ומקבלת את Viewer מהזרקת תלויות:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

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

Middleware וניתוב משאבים

הסר את הסניף הקלאסי MapWhen שמזהה את DocImage.axd:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

בצינור העבודה הנוכחי:

1. קרא ל-UseSession() לפני Doconut כאשר אבטחת הסשן מופעלת;
2. קרא ל-UseDoconutResources() לפני UseDoconut();
3. שמור על ResourcesPath, כתובות ה-URL של המשאבים שנוצרו, ו-ResPath של הלקוח מתואמים;
4. כאשר ממפים את UseDoconut() לסניף, שמור על הסניף ו-BasePath של הלקוח מתואמים.

MiddlewarePath הוא תצורה מאומתת; הוא לא יוצר סניף של ASP.NET Core בעצמו. השתמש באחת מהצינורות הפשוטים בדוגמה המהודרת למעלה או בסידור מפורש app.Map("/doconut", branch => branch.UseDoconut()) המשמש בעקביות על ידי הלקוח.

בניית Viewer ומשך החיים שלו

הסר מטמונים שבבעלות היישום של אובייקטי Viewer. הזרק את Viewer לנקודת קצה, דף Razor, בקר, או שירות יישום בעל תחום:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

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

פתיחה וסגירת מסמכים

החלף את OpenDocument(...) הסינכרוני ב-OpenDocumentAsync(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

viewer.CloseDocument(token);

אל תשתמש מחדש בטוקן קלאסי לאחר המעבר. פתח כל מסמך מחדש דרך ה-API הנוכחי.

מחלקות תצורה

ה-API הנוכחי מפריד בין תחומי עניין:

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

סרגל כלים של Viewer, חיפוש והערות

אל תעביר את הסקריפטים הישנים אחד אחרי השני. היישומים הרפרנסיים הנוכחיים מרכיבים חבילת דף שלמה:

1. הפץ CSS של Viewer ו-CSS מורשה של Search/Annotation עם ReferenceCss;
2. הצג את סרגל הכלים של Viewer שבבעלות היישום;
3. הצג את searchBarMount, annBarMount, ואת הרכיב הנדרש של Viewer;
4. הפץ סקריפטים של Viewer ומודול מורשה עם ReferenceScripts;
5. טען את viewerToolbar.js של היישום עצמו;
6. אתחל אחד objViewer;
7. אתחל את רצועות Search והערות המורשות;
8. קרא ל-attach(objViewer) על כל רצועה;
9. פתח את המסמך וקרא ל-objViewer.View(token).

Search והערות הם מודולים המחוברים לאותו Viewer, ולא סרגלי כלים נפרדים. סרגל הכלים הראשי שייך ליישום המארח; רצועות Search והערות משולבות, משאבים עם גישה מבוססת יכולות.

הסר קבצים קלאסיים שהועתקו ידנית כגון documentLinks.js ו-docViewer.UI.js רק לאחר שהדף הנוכחי פועל עם המשאבים שהופקו על ידי ReferenceCss ו-ReferenceScripts.

רישום תוסף

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

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() מאמתת את יכולות התוספים הרשומות בעת האתחול. Converter ו‑DICOM הם תוספי .NET 6 משוחררים. חיפוש רגיל והערות הם תכונות מורשות מובנות, ולא חבילות AddPlugin<TPlugin>().

אבטחת מושב ומסמך

האינטגרציה הנוכחית קושרת מסמכים לטוקנים אטומים ולמושבים במטמון. עם UnsafeMode = false כברירת מחדל, UseDoconut() מוסיף אבטחת גישה למסמכים והשרת חייב להגדיר מושב ASP.NET:

builder.Services.AddSession();
app.UseSession();

שמור על DocOptions.IsSecured = true אלא אם עיצוב שנבדק דורש אחרת. לעולם אל תשתמש ב‑UnsafeMode = true כקיצור למעבר. בדוק בקשות ללא טוקן, עם טוקן פגום, טוקן שפג תוקפו, וטוקן ממושב דפדפן שונה.

היישום ההפניה Distributed מוסיף כרטיסי גישה ופרטי העברה. ה‑APIs הללו אינם נדרשים למעבר רגיל של צומת יחיד.

בדיקת המעבר

במינימום, אמת:

• אתחול היישום עם רישיון הייצור וכל תוסף רשום;
• CSS/סקריפטים של Viewer וכל בקשות דף‑תמונה תחת הנתיבים שנבחרו;
• פתיחת מסמך, ניווט, זום, תמונות ממוזערות, הדפסה וסגירה מפורשת;
• חיפוש במסמך שמכיל טקסט והמצב הלא ניתן לחיפוש של קובץ שמורכב רק מתמונה;
• טעינת, שמירת, ייצוא והגבלת יכולות של הערות;
• גילוי יעד של Converter, פלט, הורדה ומצב סימן מים;
• דפי DICOM, פריימים ואנימציה; מטא‑נתונים טכניים של .NET 6 אינם זמינים;
• מסמכים מוגנים בסיסמה, גופנים מותאמים, טקסט לא לטיני, וזמני קצוב שהוגדרו;
• דחיית טוקן בין מושבים והתנהגות מושב שפג תוקפו;
• מובייל, מצב כהה, ונתיב reverse-proxy של הייצור.

תוכנית שחזור

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

לפני המעבר, תעד:

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

תיעוד מיושן

המדריך הקלאסי המתורגם עדיין זמין ב‑הגדרת Legacy .NET 6. ה‑שער אינטגרציה קלאסי החדש מסביר את אותות הזיהוי זהים ומקשר חזרה למדריך המעבר הזה.

שמור את כתובת ה‑URL ההיסטורית בסימניות ובכרטיסי תמיכה כל עוד קיימות התקנות קלאסיות. היא מתעדת דור שונה ולא מופנית מחדש ל‑API הנוכחי.