DoconutExtensions – Dokumentacja Doconut

DoconutExtensions (namespace Doconut.Middleware) jest statyczną klasą z trzema wywołaniami, które wykonuje każdy host Doconut: jedna rejestracja usługi i dwie rejestracje middleware.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Tworzy DoconutOptions, waliduje je natychmiast (zobacz DoconutOptions → walidacja przy starcie) i rejestruje pełny graf usług:

Usługa	Czas życia	Rola
`DoconutOptions`	Singleton	Obiekt konfiguracyjny
`IViewerFactory`	Singleton	Mapuje rozszerzenia na przeglądarki formatów
`IDocumentSessionManager`	Singleton	Token → pamięć podręczna sesji (`IMemoryCache` jest również zarejestrowany)
`IDoconutLicenseService`	Singleton	Licencja ładowana raz przy starcie (priorytet: `LicenseStream` → `LicenseContent` → `LicensePath` → automatyczne wyszukiwanie)
`PageImageService`	Singleton	Potok obrazów stron (znak wodny/obrót/skala/adnotacje)
Document security (access store)	Singleton	Uprawnienia do powiązania token‑session
`Viewer`	Transient	Publiczna fasada otwierania/zamykania
`DocumentConverter`	Transient	Fasada konwersji — wymaga wtyczki Converter
Health check `"doconut"`	—	Raportuje stan licencji/wygaśnięcia poprzez kontrole zdrowia ASP.NET

Dwa zachowania warte poznania:

Converter wymaga swojej wtyczki. Rozwiązanie DocumentConverter bez options.AddPlugin<ConverterPlugin>() powoduje wyjątek:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Uprawnienia wtyczki są weryfikowane przy starcie. Brak licencji, starszy plik TRIAL lub płatna licencja bez zarejestrowanej możliwości wtyczki powoduje błąd w czasie wywołania AddDoconut(). Rejestracje tymczasowe/demo przetrwają po upływie daty wygaśnięcia, podczas gdy mechanizmy w czasie działania odwołują wygasłe możliwości.

Kontrola zdrowia integruje się ze standardowym mechanizmem ASP.NET Core — zamapuj ją, jeśli chcesz stan licencji na swoim endpointzie zdrowia:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Dodaje middleware Doconut obsługujący obrazy stron. Odpowiada na każde żądanie zawierające parametr zapytania ?token= — strony, miniatury, wyszukiwanie, adnotacje, akcje stron (pełna tabela żądań znajduje się w Podstawowe koncepcje → Jak działa przeglądarka). Gdy UnsafeMode jest ustawione na false, warstwa zabezpieczeń dokumentu jest automatycznie podłączana przed nim.

Przykładowy kod kieruje żądania widgetu przez gałąź ścieżki:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Udostępnia osadzone pliki JS, CSS, obrazy i czcionki pod DoconutOptions.ResourcesPath (domyślnie /doconut-res). Są to pliki, dla których Viewer.ReferenceCss() / ReferenceScripts() generują znaczniki.

Zawsze wywołuj to przed UseDoconut(). Jeśli obszar przeglądarki pozostaje pusty, a konsola przeglądarki wyświetla 404 dla /doconut-res/..., to wywołanie jest brakujące lub umieszczone w niewłaściwym miejscu.

Ordering recap

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)