הגירה משילוב הקלאסי של .NET 6
העבר יישום Doconut.NET6 קיים לשירותי ה‑DI וה‑API האסינכרוני הנוכחי
Doconut יש שני שילובים נפרדים של .NET 6. הם יכולים להשתמש באותו שם חבילה Doconut.NET6, ולכן יש לזהות את הדור מה‑APIs ביישום לפני שינוי חבילות, אתחול, רשיונות או משאבי דפדפן.
איזה שילוב של .NET 6 אתה משתמש?
| אם הפרויקט מכיל… | דור |
|---|---|
app.MapWhen(... "DocImage.axd" ...) | ישן / קלאסי |
new Viewer(_cache, _accessor, ...) | ישן / קלאסי |
Viewer.DoconutLicense(...) או Viewer.SetLicensePlugin(...) | ישן / קלאסי |
הועתקו ידנית docViewer.js, documentLinks.js, או docViewer.UI.js | ישן / קלאסי |
builder.Services.AddDoconut(...) | שילוב נוכחי |
app.UseDoconutResources() ועוד app.UseDoconut() | שילוב נוכחי |
Viewer המסופק על‑ידי הזרקת תלות | שילוב נוכחי |
await viewer.OpenDocumentAsync(...) | שילוב נוכחי |
אם שני העמודות מופיעות באותו יישום, יש להתייחס להגרה כלא שלמה. אל תשלח אסימון מסמך אחד דרך משאבים או middleware מהדור השני.
למה שם חבילת NuGet עשוי לא לספר לך
שני הדורות שוחררו תחת מזהה החבילה Doconut.NET6. הפנייה לחבילה, קובץ נעילה, או .nupkg במטמון ולכן אינם מזהים את ה‑API המארח בעצמם. רשום את גרסת החבילה המדויקת ובדוק את Program.cs, בניית ה‑Viewer, פתיחת המסמך, וסקריפטי הדפדפן יחד.
הגרסה הנוכחית שנבדקה למדריך זה היא Doconut.NET6 26.7.0. החבילות הציבוריות האופציונליות שלה הן Doconut.NET6.Converter ו‑Doconut.NET6.Dicom, מקושרות לאותה גרסת שחרור כמו חבילת הליבה.
לפני שאתה מבצע הגירה
- צור סניף וגיבוי ניתנת לפריסה של היישום הקיים.
- רשום את גרסאות החבילות הליבה והתוספים המדויקות.
- בצע אינוונטורי של כל מיפוי
DocImage.axd, קריאתnew Viewer(...), קריאת טעינת רישיון, סקריפט Doconut שהועתק, פעולה מותאמת של סרגל הכלים, ונקודת קצה של פתיחת מסמך. - שמר את קבצי
.licהנוכחיים ואת סודות הפריסה מחוץ לבקרת גרסאות. - לכוד סט ייצוגי של מסמכי PDF, Office, תמונות, CAD, אימייל, DICOM, ניתנים לחיפוש, מוגנים בסיסמה, ומעורבים.
- רשום את זמן הקצאת הסשן הקיים, התנהגות האבטחה, הפונטים והגדרות הפלטפורמה.
הגר את סביבת אחת לפני שינוי הייצור. השילוב הנוכחי משנה את חיי השירות, ניתוב הבקשות, בעלות הסשן, והמסירה של משאבי הלקוח.
תאימות חבילות ורשיונות
החלף או עדכן את חבילת הליבה במכוון; אל תסתמך על מזהה החבילה זהה לבחירת ה‑API החדש. הפקודה ברירת המחדל מתקינה את הגרסה היציבה האחרונה:
dotnet add package Doconut.NET6להגירה ניתנת לשחזור לגרסה שנבדקה במדריך זה, העבר את הגרסה כאופציה נפרדת:
dotnet add package Doconut.NET6 --version 26.9.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 ותלויות של request-accessor:
// אינטגרציה קלאסית — רק ניגוד; אל תקומפל זאת נגד ה‑SDK הנוכחי.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);האינטגרציה הנוכחית רושמת את Doconut פעם אחת ומקבלת Viewer מהזרקת תלויות:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseSession();
app.UseDoconutResources();
app.UseDoconut();Viewer הוא שירות זמני. מנהל סשן המסמך והמטמון שלו מחזיקים את מצב המסמך בעל החיים הארוך יותר, ולא את המופע המוזרק המסוים של Viewer.
Middleware וניתוב משאבים
הסר את הסניף הקלאסי של MapWhen שמזהה את DocImage.axd:
// אינטגרציה קלאסית — להסיר במהלך המעבר.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
branch => branch.UseDoconut(new DoconutOptions()));בצינור העבודה הנוכחי:
- קרא
UseSession()לפני Doconut כאשר אבטחת הסשן מופעלת; - קרא
UseDoconutResources()לפניUseDoconut(); - שמור את
ResourcesPath, את כתובות ה-URL של המשאבים שנוצרו, ואתResPathשל הלקוח מיושרים; - כאשר ממפים את
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(...):
// אינטגרציה נוכחית של .NET 6: Viewer מגיע מ‑DI ופתיחת המסמך היא אסינכרונית.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });הגרסאות העודפות הנוכחיות מקבלות נתיב קובץ או זרם, תצורת פורמט אופציונלית, DocOptions אופציונלי, וטוקן ביטול. סגור את סשן השרת במפורש כאשר הדפדפן אינו זקוק לו יותר:
viewer.CloseDocument(token);אל תשתמש מחדש בטוקן קלאסי לאחר המעבר. פתח כל מסמך מחדש דרך ה-API הנוכחי.
מחלקות תצורה
ה-API הנוכחי מפריד תחומי אחריות:
| תחום | סוג נוכחי |
|---|---|
| נתיבי Middleware, רישוי, רישום תוספים | DoconutOptions |
| סיסמה, זמן קצוב, אבטחה, סימן מים | DocOptions |
| עיבוד פורמט ו-DPI | PdfConfig, WordConfig, ExcelConfig, וסוגי BaseConfig נוספים |
| ברירות מחדל של וידג'ט הדפדפן | ViewerConfig או אפשרויות JavaScript המקבילות |
| CSS ו-scripts שנוצרו | CssConfig וScriptConfig |
אל תמשיך את DocOptions.ImageResolution כפקד העיבוד. הוא מיושן; הגדר את BaseConfig.ImageResolution בתצורת הפורמט הספציפית. בדוק את כל ברירות המחדל במקום להניח שתצורת קלאסית מתנהגת באותו אופן.
סרגל כלים של Viewer, חיפוש והערות
אל תעביר את הסקריפטים הישנים אחד אחרי השני. היישומים הרפרנסיים הנוכחיים מרכיבים חבילת עמוד שלמה:
- הפץ CSS של Viewer ו-CSS של Search/Annotation ברישיון עם
ReferenceCss; - הצג את סרגל הכלים של Viewer שבבעלות היישום;
- הצג את
searchBarMount,annBarMount, ואת ה-Mount של Viewer הנדרש; - הפץ את ה-Viewer ואת סקריפטי המודול ברישיון עם
ReferenceScripts; - טען את
viewerToolbar.jsשל היישום עצמו; - אתחל אחד
objViewer; - אתחל את ה-Ribbons של Search וה-Annotation ברישיון;
- קרא
attach(objViewer)על כל Ribbon; - פתח את המסמך וקרא
objViewer.View(token).
Search ו-Annotation הם מודולים המחוברים לאותו Viewer, ולא סרגלי כלים עצמאיים. סרגל הכלים הראשי שייך ליישום המארח; ה-Ribbons של Search ו-Annotation משובצים, משאבים עם בקרת יכולות.
הסר קבצים קלאסיים שהועתקו ידנית כגון 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.AddDistributedMemoryCache(); // למצב הסשן נדרש מטמון (MVC/Razor Pages כבר מוסיפים אחד)
builder.Services.AddSession();
app.UseSession();להשאיר את DocOptions.IsSecured = true אלא אם תכנון שנבדק דורש אחרת. לעולם אל תשתמש ב‑UnsafeMode = true כקיצור דרך למיגרציה. יש לבדוק בקשות ללא טוקן, טוקן פגום, טוקן שפג תוקפו, וטוקן ממושב דפדפן שונה.
היישום ההפניה המפוזר מוסיף כרטיסי גישה ופרטי תעבורה. ה‑APIs הללו אינם נדרשים למיגרציה רגילה של צומת יחיד.
בדיקת המיגרציה
במינימום, יש לאמת:
- אתחול היישום עם רישיון הייצור וכל תוסף רשום;
- קבצי CSS/סקריפטים של Viewer וכל בקשות דף‑תמונה בנתיבים שנבחרו;
- פתיחת מסמך, ניווט, זום, תמונות ממוזערות, הדפסה וסגירה מפורשת;
- חיפוש במסמך שמכיל טקסט והמצב הלא-ניתן לחיפוש של קובץ תמונה בלבד;
- טעינת, שמירת, ייצוא והגבלת יכולות של הערות;
- גילוי יעד הממיר, פלט, הורדה ומצב סימן מים;
- דפי DICOM, פריימים והנפשה; מטא‑נתונים טכניים של .NET 6 אינם זמינים;
- מסמכים מוגנים בסיסמה, גופנים מותאמים, טקסט לא‑לטיני וזמני קצוב שהוגדרו;
- דחיית טוקן בין מושבים והתנהגות מושב שפג תוקפו;
- נייד, מצב כהה, ונתיב ה‑reverse‑proxy של הייצור.
תוכנית שחזור
להשאיר את ארטיפקט הפריסה הקלאסי, חבילות תואמות, קבצי רישיון ומשאבי דפדפן מועתקים יחד. שחזור בטוח מחליף את כל דור היישום; הוא אינו מערבב שרת קלאסי עם סקריפטים נוכחיים או שרת נוכחי עם קריאות קלאסיות של DocImage.axd.
לפני המעבר, תעד:
- את משבצת הפריסה או הארטיפקט המשמשים לשחזור;
- את השפעת מסד הנתונים/מטמון, אם קיימת;
- כיצד מושבי מסמכים פעילים יבוטלו;
- את בדיקת הבריאות והמסמך המהיר המשמשים להחלטת שחזור;
- מי יכול לשחזר את קבוצת החבילות וההגדרות הקודמות.
תיעוד מורשת
המדריך הקלאסי המתורגם זמין בכתובת הגדרת .NET 6 הישנה. ה‑שער אינטגרציה קלאסי החדש מסביר את אותות הזיהוי זהים ומקשר חזרה למדריך המיגרציה הזה.
להשאיר את כתובת ה‑URL ההיסטורית במועדפים ובכרטיסי תמיכה כל עוד התקנות קלאסיות קיימות. היא מתעדת דור שונה ואינה מופנית ל‑API הנוכחי.
האם דף זה היה מועיל?