DoconutOptions – Dokumentacja Doconut

DoconutOptions (namespace Doconut) jest jedynym obiektem konfiguracyjnym całego SDK. Konfigurujesz go raz, wewnątrz AddDoconut(), i jest rejestrowany jako singleton.

csharp

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

Properties

Type	Property	Default	Description
`bool`	`ShowDoconutInfo`	`false`	Gdy `true`, żądanie middleware bez tokenu zwraca baner wersji (`Doconut <version> is running on <host>`) zamiast 404. Przydatne jako szybka kontrola; w produkcji pozostaw `false`.
`bool`	`UnsafeMode`	`false`	Gdy `true`, pomija sprawdzenie bezpieczeństwa sesji ASP.NET przy żądaniach stron. W produkcji pozostaw `false` (zob. Core Concepts → Sessions & Security).
`string`	`MiddlewarePath`	`"/doconut"`	Wartość koordynująca dla punktu końcowego obrazu strony. Jest walidowana, ale nie montuje gałęzi potoku; utrzymuj ją zgodną z rzeczywistym mapowaniem `UseDoconut()` i `BasePath` klienta.
`string`	`ResourcesPath`	`"/doconut-res"`	Prefiks ścieżki URL dla osadzonych zasobów JS/CSS/obraz/font.
`string`	`LicensePath`	`""`	Ścieżka do pliku licencji. Pusta → następne źródło licencji, potem automatyczne wykrywanie; nic nie znaleziono → stan oceny z znakiem wodnym i brakiem funkcjonalności.
`string`	`LicenseContent`	`""`	Surowa zawartość licencji XML (baza danych, zmienna środowiskowa, manager sekretów). Ma pierwszeństwo przed `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Licencja jako strumień, odczytywana raz przy starcie. Ma pierwszeństwo przed oboma innymi źródłami.
`bool`	`ResetLicense`	`false`	Zarezerwowany znacznik kompatybilności. Aktualna implementacja .NET 6 nie wykorzystuje go; po wymianie licencji uruchom aplikację ponownie.
`DoconutPluginRegistry`	`PluginRegistry`	—	Rejestr tylko do odczytu zbierający wkłady wtyczek; wykorzystywany przez fabrykę przeglądarki. Wypełnij go za pomocą `AddPlugin<T>()`.

Priorytet licencji (wyegzekwowany przy rejestracji usług): LicenseStream → LicenseContent → LicensePath → automatyczne wykrywanie (zob. Getting Started → License Setup).

Methods

AddPlugin<TPlugin>()

text

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

Użyj tej metody dla wydanych pakietów Converter i DICOM, które wymagają opt‑in. Anotacja i normalne wyszukiwanie są wbudowanymi licencjonowanymi funkcjami i nie korzystają z AddPlugin<TPlugin>().

Rejestruje wtyczkę pierwszej strony (Converter, DICOM). Fluent — zwraca instancję opcji. AddDoconut() rzuca InvalidOperationException przy brakującej licencji, starszym pliku TRIAL lub płatnej licencji nieuprawniającej do funkcji wtyczki. Rejestracje tymczasowe/Demo są zachowywane po wygaśnięciu i podlegają bramce w czasie wykonywania (zob. Core Concepts → Plugin System).

Widget opt‑in Converter jest włączany za pomocą AddConverterWidget() i udostępniany przez właściwość tylko do odczytu ConverterWidget; jego opcje są opisane na stronie wtyczki Converter (Plugins → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

text

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

Rejestruje własną przeglądarkę dla rozszerzenia pliku. Własne przeglądarki mają pierwszeństwo przed wbudowanymi i przeglądarkami wtyczek i nie są ograniczone licencją. Gdy defaultConfig jest pominięte i dokument otwiera się bez wyraźnej konfiguracji, używany jest ImageConfig.

Rzuca ArgumentException (Extension must be a non-empty file extension.) przy pustym rozszerzeniu oraz ArgumentNullException przy nullowym fabryce.

Startup validation

AddDoconut() waliduje opcje fail-fast, więc niepoprawna konfiguracja objawia się wyraźnym wyjątkiem przy starcie zamiast mylących 404 w czasie żądania:

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.

Common configurations

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

Gdy zmieniasz ResourcesPath, utrzymuj ResPath widgetu klienta w synchronizacji (zob. ViewerConfig).

MiddlewarePath nie jest automatycznym mapowaniem trasy ASP.NET Core. Jeśli Doconut ma odpowiadać tylko pod niestandardowym prefiksem, zamontuj UseDoconut() na tej gałęzi (np. app.Map("/docs-engine", branch => branch.UseDoconut())) i ustaw BasePath klienta na ten sam URL.