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 → Validazione all'avvio), e registra l'intero grafo dei servizi:
| Servizio | Durata | Ruolo |
|---|---|---|
DoconutOptions | Singleton | L'oggetto di configurazione |
| Servizio di cache della sessione | Singleton | Token → cache della sessione (IMemoryCache è registrato anche) |
IDoconutLicenseService | Singleton | Licenza caricata una volta all'avvio (precedenza: LicenseStream → LicenseContent → LicensePath → ricerca automatica) |
| Pipeline di immagini di pagina | Singleton | Esegue l'elaborazione delle immagini per le pagine (filigrana, rotazione, scala, annotazioni) |
| Sicurezza del documento (archivio di accesso) | Singleton | Concede il binding token‑sessione |
Viewer | Transient | La facciata pubblica di apertura/chiusura |
DocumentConverter | Transient | Facciata di conversione — richiede il plugin Converter |
DocumentSigner | Transient | Facciata di firma — richiede il plugin Signer (vedi Plugin di firma) |
DistributedDocumentPublisher | Transient | Pubblica gli artefatti di un documento nello storage condiviso (vedi Distribuzioni distribuite) |
Controllo di integrità "doconut" | — | Riporta lo stato della licenza/scadenza tramite i controlli di integrità ASP.NET |
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 è validato all'avvio. Una licenza mancante, un file legacy
TRIAL, o una licenza a pagamento senza la capacità di un plugin registrato fallisce 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 la 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.
Un'alternativa comune mantiene la forma storica della richiesta DocImage.axd con un ramo MapWhen (il client poi usa BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Fornisce i JS, CSS, immagini e font incorporati a 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.
Serving from shared storage
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 : BaseCloudHandlerRiepilogo 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?