DoconutOptions – Dokumentacja Doconut

DoconutOptions (przestrzeń nazw Doconut) jest jedynym obiektem konfiguracyjnym dla 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>();
});

Właściwości

Typ	Właściwość	Domyślne	Opis
`bool`	`ShowDoconutInfo`	`false`	Gdy `true`, żądanie middleware bez tokenu zwraca baner wersji (`Doconut <version> is running on <host>`) zamiast 404. Przydatne jako szybka kontrola; pozostaw `false` w produkcji.
`bool`	`UnsafeMode`	`false`	Gdy `true`, pomija kontrolę bezpieczeństwa sesji ASP.NET przy żądaniach stron. Pozostaw `false` w produkcji (zobacz Podstawowe koncepcje → Sesje i bezpieczeństwo).
`string`	`MiddlewarePath`	`"/doconut"`	Wartość koordynująca dla punktu końcowego page-image. Jest walidowana, ale nie montuje gałęzi potoku; utrzymuj ją zgodnie z rzeczywistym mapowaniem `UseDoconut()` i `BasePath` klienta.
`string`	`ResourcesPath`	`"/doconut-res"`	Prefiks ścieżki URL dla osadzonych zasobów JS/CSS/obrazów/czcionek.
`string`	`LicensePath`	`""`	Ścieżka do pliku licencji. Pusta → kolejny źródło licencji, potem automatyczne wykrywanie; brak wyniku → stan oceny z znakowaniem wodnym bez możliwości.
`string`	`LicenseContent`	`""`	Surowa zawartość licencji w formacie XML (baza danych, zmienna środowiskowa, manager sekretów). Ma pierwszeństwo przed `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Licencja jako strumień, odczytywana raz przy uruchomieniu. Ma pierwszeństwo przed oboma innymi źródłami.
`bool`	`ResetLicense`	`false`	Zarezerwowany znacznik kompatybilności. Aktualna implementacja .NET 8 go nie wykorzystuje; uruchom ponownie aplikację po wymianie licencji.
`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 (zobacz Rozpoczęcie → Konfiguracja licencji).

Metody

AddPlugin()

Użyj tej metody dla wydanych, opcjonalnych pakietów Converter i DICOM. Anotacja i zwykłe wyszukiwanie są wbudowanymi funkcjami licencjonowanymi i nie używają AddPlugin<TPlugin>().

Rejestruje wtyczkę pierwszej strony (Converter, DICOM). Fluent — zwraca instancję opcji. AddDoconut() rzuca InvalidOperationException w przypadku brakującej licencji, starszego 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 w czasie wykonywania (zobacz Podstawowe koncepcje → System wtyczek).

Opcjonalny widżet Converter jest włączany za pomocą AddConverterWidget() i udostępniany poprzez właściwość tylko do odczytu ConverterWidget; jego opcje są udokumentowane na stronie wtyczki Converter (Wtyczki → Wtyczka konwertera).

RegisterViewer(extension, factory, defaultConfig?)

Rejestruje niestandardowy przegląd dla rozszerzenia pliku. Niestandardowe przeglądy mają pierwszeństwo przed wbudowanymi i przeglądami 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 null factory.

Walidacja przy uruchomieniu

AddDoconut() waliduje opcje szybko wykrywając błędy, więc nieprawidłowa konfiguracja objawia się wyraźnym wyjątkiem przy uruchomieniu 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.

Typowe konfiguracje

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 zmienisz ResourcesPath, utrzymaj ResPath widżetu klienta w synchronizacji (zobacz ViewerConfig).

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