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

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

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

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

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 ותלויות של מבצע בקשה:

// אינטגרציה קלאסית — רק לצורך השוואה; אל תקומפל זאת נגד ה‑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()));

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

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(...):

// אינטגרציה נוכחית של .NET 6: Viewer מגיע מה‑DI ופתיחת המסמך היא אסינכרונית.
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. אתחל את רצועות Search ו‑Annotation עם רישיון;
8. קרא ל‑attach(objViewer) על כל רצועה;
9. פתח את המסמך וקרא ל‑objViewer.View(token).

חיפוש והערה הם מודולים המחוברים לאותו 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.AddDistributedMemoryCache(); // מצב הסשן דורש מטמון (MVC/Razor Pages כבר מוסיפים אחד)
builder.Services.AddSession();
app.UseSession();

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

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

בדיקת ההגירה

לפחות, וודא:

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

תוכנית שחזור

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

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

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

תיעוד ישן

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

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