DoconutExtensions – Documentazione Doconut

DoconutExtensions (namespace Doconut.Middleware) è la classe statica con le tre chiamate che ogni host Doconut esegue: 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 di servizi:

Service	Lifetime	Role
`DoconutOptions`	Singleton	L'oggetto di configurazione
`IViewerFactory`	Singleton	Mappa le estensioni ai visualizzatori di formato
`IDocumentSessionManager`	Singleton	Token → cache della sessione (`IMemoryCache` è registrata anch'essa)
`IDoconutLicenseService`	Singleton	Licenza caricata una sola volta all'avvio (precedenza: `LicenseStream` → `LicenseContent` → `LicensePath` → ricerca automatica)
`PageImageService`	Singleton	Pipeline di immagini di pagina (watermark/rotazione/scalatura/annotazioni)
Document security (access store)	Singleton	Concessioni per il binding token‑sessione
`Viewer`	Transient	La facciata pubblica di apertura/chiusura
`DocumentConverter`	Transient	Facciata di conversione — richiede il plugin Converter
`DistributedDocumentPublisher`	—	Pubblica gli artefatti di un documento nello storage condiviso
Health check `"doconut"`	—	Riporta lo stato della licenza/scadenza tramite i controlli di salute di ASP.NET

Non esiste una chiamata equivalente nella precedente libreria .NET Standard. Essa costruiva new Viewer(cache, accessor) per ogni richiesta e passava le opzioni al middleware; entrambi sono sostituiti da questa singola registrazione.

Due comportamenti da conoscere:

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à del plugin registrato falliscono al momento di AddDoconut(). Le registrazioni temporanee/Demo sopravvivono alla data di scadenza, mentre i controlli a 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 il parametro di query ?token= — pagine, thumbnail, ricerca, annotazioni, azioni di pagina (la tabella completa delle richieste è in Concetti Base → Come funziona il Viewer). Quando UnsafeMode è false, lo strato di sicurezza del documento è collegato automaticamente prima di esso.

Non accetta argomenti. Passare un'istanza di DoconutOptions qui era la forma della libreria precedente e non compila più.

Il campione di riferimento instrada le richieste del widget attraverso un ramo di percorso, mantenendo la forma storica della richiesta:

csharp

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

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Serve 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.

Questa è la sostituzione supportata per collegare manualmente il middleware di risorse incorporate con app.UseMiddleware<EmbeddedResourceMiddleware>().

Servire dallo storage condiviso

Due ulteriori registrazioni esistono per le distribuzioni in cui il nodo che rende un documento non è necessariamente il nodo che ne serve le pagine. Entrambe sono coperte end‑to‑end in Distribuzioni distribuite; le firme sono:

text

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // coda di pubblicazione in background opzionale
IServiceCollection AddDoconutDistributedWidgets(...)        // storage condiviso per upload di widget

Il lato lettura è un middleware separato dal pacchetto Doconut.Clouds:

text

IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) e WebFarmOptions non esistono in questa versione. Consulta la guida di migrazione per la mappatura impostazione per impostazione.

Riepilogo dell'ordine

csharp

app.UseRouting();
app.UseSession();          // richiesto quando UnsafeMode = false
app.UseDoconutResources(); // prima chiamata Doconut
app.UseDoconut();          // seconda chiamata Doconut (o tramite un ramo MapWhen)