DoconutOptions – Doconut תיעוד

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

זה שינוי במיקום וגם בצורה. בספריית .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` בייצור על צומת יחיד (ראה מושגים מרכזיים → Sessions & Security). בעבר נכתב `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	ערך תיאום לנקודת הקצה של דף‑תמונה. הוא מאומת, אך אינו מייצר ענף צינור; שמור אותו תואם למיפוי האמיתי של `UseDoconut()` ו‑`BasePath` של הלקוח.
`string`	`ResourcesPath`	`"/doconut-res"`	קידומת נתיב URL למשאבים המוטמעים של JS/CSS/תמונה/גופן.
`string`	`LicensePath`	`""`	נתיב לקובץ הרישיון. ריק → מקור רישיון הבא, ואז גילוי אוטומטי; אם לא נמצא דבר → מצב הערכה עם סימן מים וללא יכולות.
`string`	`LicenseContent`	`""`	תוכן רישיון XML גולמי (מסד נתונים, משתנה סביבתי, מנהל סודות). גובר על `LicensePath`.
`Stream?`	`LicenseStream`	`null`	רישיון כ‑stream, נקרא פעם אחת באתחול. גובר על שני המקורות האחרים.
`bool`	`ResetLicense`	`false`	דגל תאימות שמור. המימוש הנוכחי אינו משתמש בו; הפעל מחדש את האפליקציה לאחר החלפת רישיון.
`DoconutPluginRegistry`	`PluginRegistry`	—	רישום קריאה‑בלבד שמאגד תרומות תוספים; נצרך על ידי מפעל הצופה. מלא באמצעות `AddPlugin<T>()`.

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

שיטות

AddPlugin()

text

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

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

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

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

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

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

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

אימות אתחול

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: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
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: '/'.