DoconutExtensions
Registrazione di servizi e middleware
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.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // chiama UseSession() prima di UseDoconut()
app.UseDoconutResources(); // deve essere registrato prima di UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() risponde a ogni richiesta che lo raggiunge, quindi montalo sul suo ramo dedicato con app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Costruisce il DoconutOptions, lo valida in modo fail-fast (vedi DoconutOptions → convalida all'avvio), e registra il grafo completo dei servizi:
| Servizio | Durata | Ruolo |
|---|---|---|
DoconutOptions | Singolo | L'oggetto di configurazione |
| Servizio di cache della sessione | Singolo | Token → cache della sessione (IMemoryCache è registrato anche) |
IDoconutLicenseService | Singolo | Licenza caricata una volta all'avvio (precedenza: LicenseStream → LicenseContent → LicensePath → ricerca automatica) |
| Pipeline di immagini di pagina | Singolo | Esegue l'elaborazione delle immagini per le pagine (filigrana, rotazione, scala, annotazioni) |
| Sicurezza del documento (archivio di accesso) | Singolo | Concessioni per il binding token‑sessione |
Viewer | Transitorio | La facciata pubblica di apertura/chiusura |
DocumentConverter | Transitorio | Facciata di conversione — richiede il plugin Converter |
DocumentSigner | Transitorio | Facciata di firma — richiede il plugin Signer (vedi Plugin Signer) |
DistributedDocumentPublisher | Transitorio | Pubblica gli artefatti di un documento nello storage condiviso |
Controllo di integrità "doconut" | — | Riporta lo stato della licenza/scadenza tramite i controlli di integrità di ASP.NET |
Non esiste una chiamata equivalente nella precedente libreria .NET Standard. Costruiva new Viewer(cache, accessor) per richiesta e passava le opzioni al middleware; entrambi sono sostituiti da questa singola registrazione.
Due comportamenti da conoscere:
- Converter richiede il suo plugin. Risolvere
DocumentConvertersenzaoptions.AddPlugin<ConverterPlugin>()genera un'eccezione:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner segue la stessa regola: senza options.AddPlugin<SignerPlugin>() genera No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- L'entitlement del plugin è convalidato all'avvio. Una licenza mancante, un file legacy
TRIAL, o una licenza a pagamento senza la capacità di un plugin registrato falliscono al momentoAddDoconut(). Le registrazioni temporanee/Demo sopravvivono alla loro data di scadenza, mentre i gate di runtime revocano le capacità scadute.
Il controllo di integrità si integra con il meccanismo standard di ASP.NET Core — mappalo se vuoi lo stato della licenza sul tuo endpoint di integrità:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Aggiunge il middleware di immagini di pagina Doconut. Serve 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) — e risponde a qualsiasi altra richiesta con 404 (o il banner ShowDoconutInfo): non passa mai una richiesta al resto della pipeline. Montalo sul suo ramo dedicato, come negli esempi di questa pagina. Quando UnsafeMode è false, lo strato di sicurezza del documento viene collegato automaticamente prima di esso.
Non accetta argomenti. Passare un'istanza DoconutOptions qui era la forma della libreria precedente e non compila più.
Una configurazione comune mantiene la forma storica della richiesta DocImage.axd con un ramo MapWhen (il client poi utilizza BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Serve i JS, CSS, immagini e font incorporati su 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 gestione delle risorse incorporate.
Servire dallo storage condiviso
Altre due registrazioni esistono per le distribuzioni in cui il nodo che rende un documento non è necessariamente il nodo che serve le sue pagine. Entrambe sono coperte end‑to‑end in Distribuzioni distribuite; le firme sono:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // coda di pubblicazione in background con opt-in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // archivio di supporto condiviso per i caricamenti dei widgetIl lato di lettura è un middleware separato dall'assembly Doconut.Clouds, che viene fornito nello stesso pacchetto:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) e WebFarmOptions non esistono in questa versione. Vedi la guida di migrazione per la mappatura impostazione per impostazione.
Riepilogo dell'ordinamento
app.UseRouting();
app.UseSession(); // chiama UseSession() prima di UseDoconut()
app.UseDoconutResources(); // deve essere registrato prima di UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // o un ramo MapWhenQuesta pagina è stata utile?