DoconutOptions – Doconut תיעוד

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

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 ללא טוקן מחזירה באנר גרסה (`Doconut <version> is running on <host>`) במקום 404. שימושי כבדיקת עישון; השאר את `false` בייצור.
`bool`	`UnsafeMode`	`false`	כאשר `true`, מדלג על בדיקת האבטחה של ASP.NET‑session בבקשות דף. השאר את `false` בייצור (ראה מושגים מרכזיים → מושבים ואבטחה).
`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`	דגל תאימות שמור. המימוש הנוכחי של .NET 8 אינו משתמש בו; הפעל מחדש את היישום לאחר החלפת רישיון.
`DoconutPluginRegistry`	`PluginRegistry`	—	רישום קריאה בלבד האוסף תרומות תוספים; נצרך על ידי מפעל הצופים. מלא באמצעות `AddPlugin<T>()`.

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

מתודות

AddPlugin<TPlugin>()

text

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

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

// Production: רישיון מפורש, הכל נעול (כל ברירות המחדל של האבטחה)
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.