DoconutExtensions
Rejestracja usług i middleware
DoconutExtensions (namespace Doconut.Middleware) jest statyczną klasą z trzema wywołaniami, które każdy host Doconut wykonuje: jedną rejestrację usługi i dwie rejestracje middleware.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // wywołaj UseSession() przed UseDoconut()
app.UseDoconutResources(); // musi być zarejestrowany przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() odpowiada na każde żądanie, które do niego dotrze, więc zamontuj go na własnej gałęzi z app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Tworzy DoconutOptions, waliduje je natychmiastowo (zobacz DoconutOptions → Startup validation) i rejestruje pełny graf usług:
| Usługa | Żywotność | Rola |
|---|---|---|
DoconutOptions | Singleton | Obiekt konfiguracji |
| Usługa pamięci podręcznej sesji | Singleton | Token → pamięć podręczna sesji (IMemoryCache jest również zarejestrowany) |
IDoconutLicenseService | Singleton | Licencja ładowana raz przy starcie (priorytet: LicenseStream → LicenseContent → LicensePath → auto-wyszukiwanie) |
| Potok obrazów stron | Singleton | Wykonuje przetwarzanie obrazów dla stron (znak wodny, obrót, skalowanie, adnotacje) |
| Bezpieczeństwo dokumentu (magazyn dostępu) | Singleton | Udziela uprawnień do powiązania token‑sesja |
Viewer | Transient | Publiczna fasada otwierania/zamykania |
DocumentConverter | Transient | Fasada konwersji — wymaga wtyczki Converter |
DocumentSigner | Transient | Fasada podpisywania — wymaga wtyczki Signer (zobacz Wtyczka Signer) |
DistributedDocumentPublisher | Transient | Publikuje artefakty dokumentu w wspólnym magazynie (zobacz Rozproszone wdrożenia) |
Health check "doconut" | — | Raportuje stan licencji/wygaśnięcia poprzez kontrole zdrowia ASP.NET |
Dwa zachowania warte poznania:
- Converter wymaga swojej wtyczki. Rozwiązywanie
DocumentConverterbezoptions.AddPlugin<ConverterPlugin>()powoduje błąd:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner podąża za tą samą zasadą: bez options.AddPlugin<SignerPlugin>() wyrzuca No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- Uprawnienia wtyczki są walidowane przy starcie. Brakująca licencja, starszy plik
TRIALlub płatna licencja bez zarejestrowanej możliwości wtyczki powoduje niepowodzenie w czasieAddDoconut(). Rejestracje tymczasowe/demo przetrwają po dacie wygaśnięcia, podczas gdy bramki w czasie wykonywania 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 punkcie końcowym zdrowia:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Dodaje middleware Doconut page-image. Obsługuje każde żądanie zawierające parametr zapytania ?token= — strony, miniatury, wyszukiwanie, adnotacje, akcje stron (pełna tabela żądań znajduje się w Podstawowe pojęcia → Jak działa przeglądarka) — i odpowiada na każde inne żądanie samodzielnie przy użyciu 404 (lub baneru ShowDoconutInfo): nigdy nie przekazuje żądania dalej w potoku. Zamontuj go na własnej gałęzi, jak w przykładach na tej stronie. Gdy UnsafeMode jest false, warstwa bezpieczeństwa dokumentu jest automatycznie podłączana przed nim.
Popularna alternatywa zachowuje historyczny kształt żądania DocImage.axd z gałęzią MapWhen (klient następnie używa BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Serwuje 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 nie na miejscu.
Serwowanie ze wspólnego magazynu
Dwie dodatkowe rejestracje istnieją dla wdrożeń, w których węzeł renderujący dokument nie jest koniecznie węzłem serwującym jego strony. Obie są opisane od początku do końca w Rozproszone wdrożenia; sygnatury są:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // kolejka publikacji w tle z opcją włączenia
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // wspólne zaplecze dla przesyłania widgetówStrona odczytu jest osobnym middleware z zestawu Doconut.Clouds, który jest dostarczany w tym samym pakiecie:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerPodsumowanie kolejności
app.UseRouting();
app.UseSession(); // wywołaj UseSession() przed UseDoconut()
app.UseDoconutResources(); // musi być zarejestrowany przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // lub gałąź MapWhenCzy ta strona była pomocna?