DoconutExtensions
Registrace služeb a middleware
DoconutExtensions (namespace Doconut.Middleware) je statická třída se třemi voláními, která každý host Doconut provádí: jedna registrace služby a dvě registrace middleware.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // zavolejte UseSession() před UseDoconut()
app.UseDoconutResources(); // musí být zaregistrováno před UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() odpovídá na každý požadavek, který k ní dorazí, takže ji připojte na vlastní větev s app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Vytváří DoconutOptions, provádí jejich okamžitou validaci (viz DoconutOptions → Startup validation) a registruje kompletní graf služeb:
| Služba | Životnost | Role |
|---|---|---|
DoconutOptions | Singleton | Konfigurační objekt |
| Služba mezipaměti relace | Singleton | Token → mezipaměť relace (IMemoryCache je také registrován) |
IDoconutLicenseService | Singleton | Licence načtená jednou při startu (precedence: LicenseStream → LicenseContent → LicensePath → auto-search) |
| Pipeline pro obrázky stránek | Singleton | Provádí zpracování obrázků pro stránky (vodoznak, otáčení, škálování, anotace) |
| Zabezpečení dokumentu (úložiště přístupu) | Singleton | Oprávnění pro vazbu token‑session |
Viewer | Transient | Veřejná rozhraní pro otevření/uzavření |
DocumentConverter | Transient | Rozhraní pro konverzi — vyžaduje plugin Converter |
DocumentSigner | Transient | Rozhraní pro podepisování — vyžaduje plugin Signer (viz Plugin pro podepisování) |
DistributedDocumentPublisher | Transient | Publikuje artefakty dokumentu do sdíleného úložiště |
Health check "doconut" | — | Zprávy o stavu licence/expirace prostřednictvím ASP.NET health checks |
V předchozí knihovně .NET Standard neexistuje ekvivalentní volání. Vytvářela new Viewer(cache, accessor) na požadavek a předávala možnosti middleware; oba jsou nahrazeny touto jednou registrací.
Dvě chování, která stojí za to znát:
- Converter vyžaduje svůj plugin. Vyřešení
DocumentConverterbezoptions.AddPlugin<ConverterPlugin>()vyvolá výjimku:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner následuje stejné pravidlo: bez options.AddPlugin<SignerPlugin>() vyvolá No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- Oprávnění pluginu je ověřováno při startu. Chybějící licence, starý soubor
TRIALnebo placená licence bez registrované schopnosti pluginu selže v časeAddDoconut(). Dočasné/Demo registrace přežijí datum expirace, zatímco runtime brány odeberou vypršené schopnosti.
Health check se integruje se standardním mechanismem ASP.NET Core — namapujte jej, pokud chcete stav licence na vašem health endpointu:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Přidává middleware Doconut pro obrázky stránek. Obsluhuje každý požadavek nesoucí parametr dotazu ?token= — stránky, miniatury, vyhledávání, anotace, akce na stránkách (úplná tabulka požadavků je v Základní koncepty → Jak funguje prohlížeč) — a na jakýkoli jiný požadavek odpovídá pomocí 404 (nebo banneru ShowDoconutInfo): nikdy nepředává požadavek dál do zbytku pipeline. Připojte jej na vlastní větev, jako ve vzorcích na této stránce. Když je UnsafeMode false, vrstva zabezpečení dokumentu je automaticky zapojena před ním.
Nevyžaduje žádné argumenty. Předání instance DoconutOptions zde bylo ve staré knihovně a již se nekóduje.
Běžné nastavení zachovává historický tvar požadavku DocImage.axd s větví MapWhen (klient pak používá BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Obsluhuje vložené JS, CSS, obrázky a fonty na DoconutOptions.ResourcesPath (výchozí /doconut-res). Jedná se o soubory, pro které Viewer.ReferenceCss() / ReferenceScripts() generují značky.
Vždy jej zavolejte před UseDoconut(). Pokud je oblast prohlížeče prázdná a konzole prohlížeče ukazuje 404 pro /doconut-res/..., toto volání chybí nebo je na špatném místě.
Jedná se o podporovanou náhradu za ruční zapojení middleware pro zpracování vložených zdrojů.
Serving from shared storage
Další dvě registrace existují pro nasazení, kde uzel, který vykresluje dokument, není nutně uzel, který obsluhuje jeho stránky. Obě jsou kompletně pokryty v Distribuovaná nasazení; podpisy jsou:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // dobrovolná fronta pro publikování na pozadí
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // sdílené úložiště pro nahrávání widgetůČtecí část je samostatný middleware z assembly Doconut.Clouds, který je součástí stejného balíčku:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) a WebFarmOptions v tomto vydání neexistují. Viz průvodce migrací pro mapování nastavení po nastavení.
Ordering recap
app.UseRouting();
app.UseSession(); // zavolejte UseSession() před UseDoconut()
app.UseDoconutResources(); // musí být zaregistrováno před UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // nebo větev MapWhenByla tato stránka užitečná?