הגירה משילוב הקלאסי של .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, מקושרות לאותה גרסת שחרור כמו חבילת הליבה.

לפני שאתה מבצע הגירה

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

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

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

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

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.9.0

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

text
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:

csharp
// אינטגרציה קלאסית — רק ניגוד; אל תקומפל זאת נגד ה‑SDK הנוכחי.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

csharp
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:

csharp
// אינטגרציה קלאסית — להסיר במהלך המעבר.
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, בקר, או שירות יישום עם תחום:

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

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

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

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

csharp
// אינטגרציה נוכחית של .NET 6: Viewer מגיע מ‑DI ופתיחת המסמך היא אסינכרונית.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

csharp
viewer.CloseDocument(token);

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

מחלקות תצורה

ה-API הנוכחי מפריד תחומי אחריות:

תחוםסוג נוכחי
נתיבי Middleware, רישוי, רישום תוספיםDoconutOptions
סיסמה, זמן קצוב, אבטחה, סימן מיםDocOptions
עיבוד פורמט ו-DPIPdfConfig, WordConfig, ExcelConfig, וסוגי BaseConfig נוספים
ברירות מחדל של וידג'ט הדפדפןViewerConfig או אפשרויות JavaScript המקבילות
CSS ו-scripts שנוצרוCssConfig וScriptConfig

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

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

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

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

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

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

רישום תוסף

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

csharp
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:

csharp
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 הנוכחי.

האם דף זה היה מועיל?