DoconutOptions – Doconut תיעוד

DoconutOptions (namespace Doconut) הוא האובייקט הקונפיגורציה היחיד לכל ה‑SDK. אתה מגדיר אותו פעם אחת, בתוך AddDoconut(), והוא נרשם כסינגלטון.

זה שינוי במיקום כמו גם בצורה. בספריית .NET Standard הקודמת, מופע של DoconutOptions נבנה בזמן הצינור והועבר ל‑UseDoconut(new DoconutOptions { … }). כאן ה‑middleware אינו מקבל אפשרויות כלל — הכל מוגדר במהלך רישום השירות.

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

מאפיינים

סוג	מאפיין	ברירת מחדל	תיאור
`bool`	`ShowDoconutInfo`	`false`	כאשר `true`, בקשת middleware ללא אסימון מחזירה באנר גרסה במקום 404. שימושי כבדיקה מהירה; השאר את `false` בייצור.
`bool`	`UnsafeMode`	`false`	כאשר `true`, מדלג על בדיקת האבטחה של ASP.NET‑session בבקשות דף. השאר את `false` בייצור על צומת יחיד (ראה Core Concepts → Sessions & Security). בעבר נכתב `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	ערך תיאום עבור נקודת הקצה page-image. הוא מאומת, אך אינו יוצר ענף בצינור; שמור אותו תואם למיפוי `UseDoconut()` האמיתי ול‑`BasePath` של הלקוח.
`string`	`ResourcesPath`	`"/doconut-res"`	קידומת נתיב URL עבור המשאבים המוטמעים JS/CSS/תמונה/גופן.
`string`	`LicensePath`	`""`	נתיב לקובץ הרישיון. ריק → מקור רישיון הבא, ואז גילוי אוטומטי; אם לא נמצא → מצב הערכה עם סימן מים וללא יכולות.
`string`	`LicenseContent`	`""`	תוכן רישיון XML גולמי (מסד נתונים, משתנה סביבתי, מנהל סודות). עדיפות על פני `LicensePath`.
`Stream?`	`LicenseStream`	`null`	רישיון כזרם, נקרא פעם אחת בהפעלה. עדיפות על שני המקורות האחרים.
`bool`	`ResetLicense`	`false`	דגל תאימות שמור. המימוש הנוכחי אינו משתמש בו; הפעל מחדש את האפליקציה לאחר החלפת רישיון.
`DoconutPluginRegistry`	`PluginRegistry`	—	רישום קריאה בלבד שמאגד תרומות תוספים; נצרך על ידי מפעל הצופה. מלא באמצעות `AddPlugin<T>()`.

סדר עדיפות הרישיונות (המאולץ ברישום השירות): LicenseStream → LicenseContent → LicensePath → גילוי אוטומטי (ראה התחלה → הגדרת רישיון).

שיטות

AddPlugin<TPlugin>()

text

DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

השתמש בשיטה זו עבור חבילות ה‑Converter וה‑DICOM שהושקו באופציית opt‑in. אנוטציה ו‑Search רגיל הם תכונות מורשות מובנות ואינן משתמשות ב‑AddPlugin<TPlugin>().

רושמת תוסף צד‑ראשון (Converter, DICOM). Fluent — מחזירה את מופע האפשרויות. AddDoconut() זורק InvalidOperationException עבור רישיון חסר, קובץ TRIAL מיושן, או רישיון בתשלום שאינו מעניק את היכולת לתוסף. רישומים זמניים/דמו נשמרים לאחר תפוגה והופכים לנושא של שער זמן הריצה (ראה מושגים מרכזיים → מערכת תוספים).

הווידג'ט Converter באופציית opt‑in מופעל עם AddConverterWidget() ומוצג דרך המאפיין הקריאה‑בלבד ConverterWidget; האפשרויות שלו מתועדות בעמוד תוסף ה‑Converter (תוספים → תוסף Converter).

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — נקודה מובילה אופציונלית
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

רושמת צופה מותאם עבור סיומת קובץ. צופים מותאמים מקבלים עדיפות על פני צופים מובנים ותוספים ואינם תלויים ברישיון. כאשר defaultConfig מושמט וקובץ נפתח ללא תצורה מפורשת, משתמשים ב‑ImageConfig.

זורק ArgumentException (Extension must be a non-empty file extension.) עבור סיומת ריקה ו‑ArgumentNullException עבור מפעל null.

אימות אתחול

AddDoconut() מאמת את האפשרויות fail‑fast, כך שהגדרה שגויה מתגלה כחריגה ברורה בזמן האתחול במקום 404s מבלבלים בזמן הבקשה:

text

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

תצורות נפוצות

csharp

// ייצור: רישיון מפורש, הכל נעול (כל ברירות המחדל של האבטחה)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// נתיבים מותאמים (למשל כדי להימנע מקונפליקט נתיב)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

כאשר אתה משנה את ResourcesPath, שמור את ResPath של וידג'ט הלקוח מסונכרן (ראה ViewerConfig). זהו אחד משני ההגדרות בצד הלקוח שנכשלות ללא הודעת שגיאה.

MiddlewarePath אינו ממפה אוטומטי של נתיבי ASP.NET Core. אם Doconut צריך לענות רק מתחת לקידומת מותאמת, הרכב את UseDoconut() על הענף הזה (לדוגמה עם app.Map("/docs-engine", branch => branch.UseDoconut())) והגדר את BasePath של הלקוח לאותו URL. אפליקציית ההפניה במקום זאת שומרת על צורת הבקשה ההיסטורית DocImage.axd על ענף MapWhen עם BasePath: '/'.