DoconutOptionen

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.

Dies ist sowohl eine Änderung des Ortes als auch der Form. In der vorherigen .NET Standard-Bibliothek wurde eine DoconutOptions-Instanz zur Pipeline-Zeit erstellt und an UseDoconut(new DoconutOptions { … }) übergeben. Hier nimmt die Middleware keinerlei Optionen entgegen — alles wird während der Service-Registrierung festgelegt.

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

Eigenschaften

Lizenz‑Präzedenz (durchgesetzt bei der Service‑Registrierung): LicenseStream → LicenseContent → LicensePath → automatische Erkennung (siehe Schnellstart → Lizenz‑Einrichtung).

Methoden

AddPlugin<TPlugin>()

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 über das Ablaufdatum hinaus 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?)

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — führender Punkt optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

Registriert einen benutzerdefinierten Viewer für eine Dateierweiterung. Benutzerdefinierte Viewer haben Vorrang vor eingebauten 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.

Startvalidierung

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

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

// Produktiv: explizite Lizenz, alles gesperrt (alle Sicherheitsstandards)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Benutzerdefinierte Pfade (z. B. um einen Routen-Konflikt zu vermeiden)
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). Dies ist eine der beiden clientseitigen Einstellungen, die ohne Fehlermeldung fehlschlagen.

MiddlewarePath ist kein automatischer ASP.NET Core‑Routenmapper. Wenn Doconut nur unter einem benutzerdefinierten Präfix antworten soll, mounten Sie UseDoconut() auf diesem Zweig (zum Beispiel mit app.Map("/docs-engine", branch => branch.UseDoconut())) und setzen Sie das Client‑BasePath auf dieselbe URL. Die Referenzanwendung behält stattdessen die historische DocImage.axd‑Anfrageform auf einem MapWhen‑Zweig mit BasePath: '/' bei.