הגירה

דף זה מתאר שדרוג של יישום ASP.NET קיים מ‑Doconut.NETFramework 26.8.0 או גרסה קודמת (.NET Framework 4.7) ל‑26.9.0 ומעלה (.NET Framework 4.7.2). חבילת הדוגמאות של Doconut כוללת את מדריך ההגירה המלא ואת הדוגמאות הקלאסיות שהועברו ל‑API החדש — MVC 5, חוות רשת, ו‑Web Forms. השוואת היישום שלך לדוגמה שממנה התחלת היא הדרך המהירה ביותר.

חבילה אחת, שני גרסאות

שתי הספריות מתפרסמות תחת אותו מזהה חבילה, Doconut.NETFramework. הגרסה מבחינה ביניהן:

עדכון החבילה הוא השדרוג. אין חבילה נפרדת להתקנה ואין שכבת תאימות: 26.9.0 היא משטח API שונה, ולכן יש לצפות לשגיאות קומפילציה לאחר העדכון — המשך הדף. קו .NET Framework 4.7 הושבת ו‑26.8.0 הוא הגרסה האחרונה שלו. ניתן להישאר עליו — אין כאן תיקון אבטחה שתפספס — אך גרסאות חדשות, תוספים, המצב המבוזר, והווידג'טים הניתנים להטמעה מגיעים רק ב‑26.9.0 ומעלה.

1. שינוי מטרה ועדכון החבילה

ראשית, שנה את מטרה של פרויקט האינטרנט ל‑.NET Framework 4.7.2: פרויקט שעדיין ממקד ב‑4.7 אינו יכול להתקין 26.9.0, ו‑NuGet מסרב לעדכון. לאחר מכן עדכן את Doconut.NETFramework והוסף את חבילות התוספים שבהן אתה משתמש (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). לכל תוסף נדרש רישיון שמאפשר זאת.

אם הפרויקט משתמש ב‑packages.config, העדכון מריץ את שלב ההסרה של הגרסה הקודמת, שמסיר את המנהל DocImage מ‑Web.config, ו‑26.9.0 אינו מוסיף אותו בחזרה. רשום אותו שוב כפי שמופיע בצעד 3; עד שתעשה זאת, DocImage.axd מחזיר 404 ואין דף שמוצג.

2. מרחבי שמות: כמעט כל דבר הועבר לשורש

שם הסוגים לא השתנו: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig והיתר עדיין קיימים. ברוב הקבצים כל העריכה היא מחיקת שורות using.

3. אתחול: DoconutHost.Initialize ושתי ערכי Web.config

החבילה הקלאסית בנתה את הצופה לכל בקשה, עם אפשרויות כתכונות של המופע הזה. החבילה החדשה כוללת שורש הרכבה, שנבנה פעם אחת ב‑Application_Start, והצופה הוא שירות שאתה מקבל:

// לפני - Doconut.NETFramework 26.8.0 וקודמות, לפי בקשה
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0\u002B - הצופה נפתר מ‑DoconutHost, הרישיון מוגדר פעם אחת ב‑DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize נכנס ב‑Application_Start ו‑DoconutHost.Shutdown ב‑Application_End, ו‑Web.config מקבל את המנהל DocImage.axd ואת מודול המשאבים — שניהם נמצאים בהתקנה. הגדרות המראה לכל עמוד (FitType, FixedZoom, ShowHyperlinks, …) הועברו ממופע הצופה לאפשרויות הווידג'ט, או ל‑ViewerConfig שעובר ל‑Viewer.RenderViewer (ראה תצורת הצופה). new Viewer() עדיין מתקמפל לאחר שה‑DoconutHost.Initialize רץ, ולכן קוד‑בקר המומר יכול לשמור על השורה הזו בזמן שאתה מזיז את ההגדרות.

האבטחה פועלת כמו לפני. פתיחת מסמך מעניקה למושב ASP.NET הנוכחי גישה לדפים שלו, ו‑DocImage.axd מסרב לכולם. הגדרת האפליקציה DoconutUnSafeMode שהפכה זאת לכיבוי היא כעת options.UnsafeMode ב‑DoconutHost.Initialize — השאר אותה false. ראה הפעלות ואבטחה.

כשל האתחול שמוריד את כל האתר. תוסף רשום שהיכולת שלו לא ניתנת ברישיון זורק ב‑Application_Start, והיישום משיב 500 ריק לכל בקשה — ללא דף שגיאה, ללא רישום ביומן IIS, רק רשומה ביומן אירועי Windows (מקור ASP.NET). הרישיונות נקראים מ‑wwwroot תחת שורש האתר ולא ממקום אחר, וה‑Doconut.Viewer.lic הבסיסי חייב להיות קיים אחרת רישיונות התוסף שלידו לא ייקראו. ראה הגדרת רישיון.

4. חוות רשת: מדגל למצב מבוזר

המודל הקלאסי היה viewer.IsWebfarm = true בתוספת ExportToPng(path). המודל החדש נרשם פעם אחת: כל צומת חולק מאגר אחד ומפתח חתימה אחד, וכרטיס חתום הקשור לדפדפן מחליף את „כל צומת שמגיב“:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath הוא שם נרדף
        d.SigningKey        = farmKey;                           // >= 32 bytes, זהה בכל צומת
    }));

לאחר מכן פתחו מסמכים כרגיל, קושרו לדפדפן (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) והעבירו viewer.AccessToken לוידג'ט עם האסימון. הפעלות ואבטחה מפרטת את הצעדים; דוגמת חוות הרשת היא צומת שלמה. IsWebfarm ו‑WebfarmPath עדיין מתקומפלות, אך הן אינן מפעילות דבר יותר.

שתי דברים שנראים כהצלחה אך אינם: DistributedDocumentPublisher.PublishAsync כותב קבצים מעובדים של מסמך אך אינו פותח סשן, ולכן צופה שמצביע על אסימון שפורסם מקבל את תמונת השגיאה של ~2 KB עם סטטוס 200; וגם לקוח בדיקה ללא העוגייה doconut-client מקבל את אותה תמונה, ולא 401. ניתן להבדיל בין דף אמיתי לתמונת השגיאה לפי גודל.

5. המרה היא תוסף, וקטן הרבה יותר

ה‑enum SourceFormatConverter, שני‑עשר המחלקות *ConfigConverter וה‑enums המטרה המקוננים שלהם מוחלפים ב‑enum אחד, ConversionTarget, ובקריאה אחת:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// הנח ש DoconutHost כבר מאותחל ו CancellationToken בשם ct זמין.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* זרם הקלט שלך */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

פורמט המקור מגיע מההרחבה שאתה מעביר. אין שכבת התאמה: כל הפנייה ל‑SourceFormatConverter היא שגיאת קומפילציה שאתה פותר על‑ידי מחיקתה. אובייקטי האפשרויות לכל פורמט לא שרדו — WordConfigConverter.HtmlOptions ו‑CadConfigConverter.CadOptions.ShowColor אין להם מקבילה דרך ConvertAsync. ב‑Web Forms, לעולם אל תחסום על‑ConvertAsync — ראה תוסף המרה.

6. אחסון בענן: גישה אליו כתיקייה משותפת

סוגי תצורת הענן הועברו ל‑Doconut.Clouds ללא שינוי. מטפלי הבקשות בענן, עם זאת, הם רכיבי ASP.NET Core, וליישום קלאסי אין צינור עבודה להרצתם. מאתר System.Web, ניתן לגשת לאחסון בענן כתיקייה משותפת — ב‑Azure, שיתוף Azure Files שמותקן על כל צומת — נגיש דרך FileShareConfig.

7. השינויים בצד הלקוח שנכשלים בשקט

כל פריט למטה מתקומפל, רץ, אינו רושם דבר, ועושה את הדבר הלא נכון:

שלושה נוספים: הצופה אינו מצייר את סרגל הכלים שלו (הדף שלך מחבר את Zoom, Next, GotoPage ואת השאר לכפתורים שלו); צופה שנוצר בתוך מודל Bootstrap מוסתר מודד 0×0 ומצייר כלום עד שתיתן למיכל שלו גובה מפורש ותתאים אותו מחדש ב‑shown.bs.modal; ו‑AllowSearch בברירת מחדל הוא false עבור PDF, ולכן מסמך מוצג באופן מושלם בעוד שכל חיפוש מחזיר כלום.

8. מה נעלם

סדר עבודה מומלץ

1. הפנה מחדש, החלף את החבילה, וקבל את Global.asax מתורגם עם DoconutHost.Initialize ושתי הרשימות Web.config. האתר צריך להתחיל.
2. דף צופה אחד: קבל מסמך להצגה, ואז עבוד דרך סעיף 7 עד שהסרגל, החיפוש וההערות מתפקדים. אמת בדפדפן אמיתי — שום דבר באותו סעיף אינו גורם לשגיאה.
3. המרה (סעיף 5): מכנית, ורוב שגיאות ההידור.
4. הדפים הנותרים, תוך שימוש בדוגמאות המיועדות כיעד ההבדל.
5. חוות האתרים (סעיף 4), אם יש לך אחת. בדוק עם שני צמתים ודפדפן, או לקוח ששומר קבצי cookie.