DoconutExtensions – Doconut Documentazione

DoconutExtensions (namespace Doconut.Middleware) è la classe statica con le tre chiamate che ogni host Doconut effettua: una registrazione di servizio e due registrazioni di middleware.

csharp

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

AddDoconut

text

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

Costruisce il DoconutOptions, lo valida in modo fail-fast (vedi DoconutOptions → Validazione all'avvio), e registra l'intero grafo dei servizi:

Servizio	Durata	Ruolo
`DoconutOptions`	Singleton	L'oggetto di configurazione
`IViewerFactory`	Singleton	Mappa le estensioni ai visualizzatori di formato
`IDocumentSessionManager`	Singleton	Token → cache della sessione (`IMemoryCache` è registrato anche)
`IDoconutLicenseService`	Singleton	Licenza caricata una volta all'avvio (precedenza: `LicenseStream` → `LicenseContent` → `LicensePath` → ricerca automatica)
`PageImageService`	Singleton	Pipeline di immagini di pagina (filigrana/rotazione/scalatura/annotazioni)
Document security (access store)	Singleton	Concessioni per il collegamento token‑sessione
`Viewer`	Transient	La facciata pubblica di apertura/chiusura
`DocumentConverter`	Transient	Facciata di conversione — richiede il plugin Converter
Health check `"doconut"`	—	Riporta lo stato della licenza/scadenza tramite i controlli di salute di ASP.NET

Due comportamenti da conoscere:

Il Converter richiede il suo plugin. Risolvere DocumentConverter senza options.AddPlugin<ConverterPlugin>() genera:

text

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

L'entitlement del plugin è validato all'avvio. Una licenza mancante, un file legacy TRIAL o una licenza a pagamento senza la capacità di un plugin registrato falliscono al momento di AddDoconut(). Le registrazioni temporanee/Demo sopravvivono alla loro data di scadenza, mentre i gate di runtime revocano le capacità scadute.

Il controllo di salute si integra con il meccanismo standard di ASP.NET Core — mappalo se vuoi lo stato della licenza sul tuo endpoint di salute:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Aggiunge il middleware di immagini di pagina Doconut. Risponde a ogni richiesta che contiene un parametro di query ?token= — pagine, miniature, ricerca, annotazioni, azioni di pagina (la tabella completa delle richieste è in Concetti di base → Come funziona il Viewer). Quando UnsafeMode è false, lo strato di sicurezza del documento viene collegato automaticamente prima di esso.

Il campione di riferimento instrada le richieste del widget attraverso un ramo di percorso:

csharp

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

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Fornisce i JS, CSS, immagini e font incorporati in DoconutOptions.ResourcesPath (predefinito /doconut-res). Questi sono i file per i quali Viewer.ReferenceCss() / ReferenceScripts() emettono i tag.

Chiamalo sempre prima di UseDoconut(). Se l'area del viewer rimane vuota e la console del browser mostra 404 per /doconut-res/..., questa chiamata è mancante o posizionata in modo errato.

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)