DoconutOptions – Doconut Dokumentation

DoconutOptions (Namespace Doconut) ist das einzige Konfigurationsobjekt für das gesamte SDK. Sie konfigurieren es einmal, innerhalb von AddDoconut(), und es wird als Singleton registriert.

csharp

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

Eigenschaften

Typ	Eigenschaft	Standard	Beschreibung
`bool`	`ShowDoconutInfo`	`false`	Wenn `true`, gibt eine Middleware-Anfrage ohne Token ein Versionsbanner (`Doconut <version> is running on <host>`) anstelle von 404 zurück. Nützlich als Schnelltest; lassen Sie `false` in der Produktion.
`bool`	`UnsafeMode`	`false`	Wenn `true`, wird die ASP.NET‑Session‑Sicherheitsprüfung bei Seitenanfragen übersprungen. Lassen Sie `false` in der Produktion (siehe Kernkonzepte → Sitzungen & Sicherheit).
`string`	`MiddlewarePath`	`"/doconut"`	Koordinationswert für den Seiten‑Bild‑Endpunkt. Er wird validiert, mountet jedoch keinen Pipeline‑Zweig; halten Sie ihn im Einklang mit dem tatsächlichen `UseDoconut()`‑Mapping und dem Client‑`BasePath`.
`string`	`ResourcesPath`	`"/doconut-res"`	URL-Pfadpräfix für die eingebetteten JS/CSS/Bild/Font‑Ressourcen.
`string`	`LicensePath`	`""`	Pfad zur Lizenzdatei. Leer → nächste Lizenzquelle, dann automatische Erkennung; nichts gefunden → Wasserzeichen‑Evaluierungszustand ohne Funktionen.
`string`	`LicenseContent`	`""`	Roh‑XML‑Lizenzinhalt (Datenbank, Umgebungsvariable, Secret Manager). Hat Vorrang vor `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Lizenz als Stream, einmal beim Start gelesen. Hat Vorrang vor beiden anderen Quellen.
`bool`	`ResetLicense`	`false`	Reserviertes Kompatibilitäts‑Flag. Die aktuelle .NET‑8‑Implementierung nutzt es nicht; starten Sie die Anwendung neu, nachdem Sie eine Lizenz ausgetauscht haben.
`DoconutPluginRegistry`	`PluginRegistry`	—	Nur‑lesbares Register, das Plugin‑Beiträge sammelt; wird von der Viewer‑Factory verwendet. Befüllen Sie es über `AddPlugin<T>()`.

Lizenz‑Priorität (bei der Service‑Registrierung erzwungen): LicenseStream → LicenseContent → LicensePath → automatische Erkennung (siehe Schnellstart → Lizenz‑Einrichtung).

Methoden

AddPlugin()()

text

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

Verwenden Sie diese Methode für die veröffentlichten optionalen Converter‑ und DICOM‑Pakete. Annotation und normale Suche sind integrierte lizenzierte Funktionen und verwenden nicht AddPlugin<TPlugin>().

Registriert ein First‑Party‑Plugin (Converter, DICOM). Fluent — gibt die Options‑Instanz zurück. AddDoconut() wirft InvalidOperationException bei fehlender Lizenz, veralteter TRIAL‑Datei oder bezahlter Lizenz, die die Plugin‑Fähigkeit nicht gewährt. Temporäre/Demo‑Registrierungen bleiben nach Ablauf erhalten und unterliegen dem Laufzeit‑Gate (siehe Kernkonzepte → Plugin‑System).

Das optionale Converter‑Widget wird mit AddConverterWidget() aktiviert und über die schreibgeschützte ConverterWidget‑Eigenschaft bereitgestellt; seine Optionen sind auf der Converter‑Plugin‑Seite dokumentiert (Plugins → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

text

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

Registriert einen benutzerdefinierten Viewer für eine Dateierweiterung. Benutzerdefinierte Viewer haben Vorrang vor integrierten und Plugin‑Viewern und sind nicht lizenzgebunden. Wenn defaultConfig weggelassen wird und ein Dokument ohne explizite Konfiguration geöffnet wird, wird ein ImageConfig verwendet.

Wirft ArgumentException (Extension must be a non-empty file extension.) bei einer leeren Erweiterung und ArgumentNullException bei einer null‑Factory.

Start‑up‑Validierung

AddDoconut() validiert die Optionen fail‑fast, sodass eine Fehlkonfiguration als klare Ausnahme beim Start erscheint statt verwirrender 404‑Fehler zur Anforderungszeit:

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.

Häufige Konfigurationen

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";
});

Wenn Sie ResourcesPath ändern, halten Sie das ResPath des Client‑Widgets synchron (siehe ViewerConfig).

MiddlewarePath ist kein automatischer ASP.NET‑Core‑Routen‑Mapper. Wenn Doconut nur unter einem benutzerdefinierten Präfix antworten soll, binden Sie UseDoconut() an diesem Zweig ein (z. B. mit app.Map("/docs-engine", branch => branch.UseDoconut())) und setzen Sie den Client‑BasePath auf dieselbe URL.