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

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

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

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

למה שם חבילת NuGet לא תמיד אומר לך

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

הגרסה המ audited של מדריך זה היא 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. רשום את זמן הקצאת הסשן הקיים, התנהגות האבטחה, הפונטים והגדרות הפלטפורמה.

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

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

החלף או עדכן את החבילה המרכזית במודע; אל תסתמך על מזהה החבילה זהה לבחירת ה‑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 מה‑DI:

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 של ה‑client מסונכרנים;
4. כאשר ממפים UseDoconut() לענף, שמור את הענף ואת BasePath של ה‑client מסונכרנים.

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

בניית Viewer וחיי חיים

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

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

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

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

החלף 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, וה‑mount של Viewer הדרוש;
4. הפק סקריפטים של Viewer ומודול עם רישיון באמצעות ReferenceScripts;
5. טען את viewerToolbar.js של היישום;
6. אתחל objViewer אחד;
7. אתחל את ריבוני החיפוש וההערות המורשים;
8. קרא attach(objViewer) על כל ריבון;
9. פתח את המסמך וקרא objViewer.View(token).

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

הסר קבצים קלאסיים שהועתקו ידנית כגון 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 מוסיף כרטיסי גישה ופרטי תעבורה. API‑ים אלה אינם נדרשים למיגרציה רגילה של צומת יחיד.

בדיקת המיגרציה

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

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

תוכנית חזרה (Rollback)

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

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

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

תיעוד קלאסי

המדריך הקלאסי המתורגם עדיין זמין ב-Legacy .NET 6 setup. ה-Classic integration gateway החדש מסביר את אותות הזיהוי זהים ומקשר חזרה למדריך המיגרציה הזה.

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