DoconutOptions

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

Jest to zmiana zarówno lokalizacji, jak i kształtu. W poprzedniej bibliotece .NET Standard instancja DoconutOptions była tworzona w czasie potoku i przekazywana do UseDoconut(new DoconutOptions { … }). Tutaj middleware nie przyjmuje żadnych opcji — wszystko jest ustawiane podczas rejestracji usług.

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

Właściwości

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

Metody

AddPlugin<TPlugin>()

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

Użyj tej metody dla wydanych pakietów Converter i DICOM dostępnych na zasadzie opt‑in. Anotacja i normalne wyszukiwanie są wbudowanymi funkcjami licencjonowanymi 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, która nie przyznaje możliwości wtyczki. Rejestracje tymczasowe/Demo są zachowywane po wygaśnięciu i podlegają bramce czasu wykonania (zobacz Core Concepts → Plugin System).

Widżet Converter w trybie opt‑in 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?)

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

Rejestruje niestandardową przeglądarkę dla rozszerzenia pliku. Niestandardowe przeglądarki mają pierwszeństwo przed wbudowanymi i przeglądarkami wtyczek oraz 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.

Walidacja przy uruchamianiu

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

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.

Typowe konfiguracje

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

Kiedy zmieniasz ResourcesPath, utrzymuj ResPath widżetu klienta w synchronizacji (zobacz ViewerConfig). To jedno z dwóch ustawień po stronie klienta, które powodują awarię bez komunikatu o błędzie.

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. Aplikacja referencyjna zamiast tego utrzymuje historyczną formę żądania DocImage.axd na gałęzi MapWhen z BasePath: '/'.