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.

csharp
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

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:

ServizioDurataRuolo
DoconutOptionsSingletonL'oggetto di configurazione
Servizio di cache della sessioneSingletonToken → cache della sessione (IMemoryCache è registrato anche)
IDoconutLicenseServiceSingletonLicenza caricata una volta all'avvio (precedenza: LicenseStream → LicenseContent → LicensePath → auto-ricerca)
Pipeline di immagini di paginaSingletonEsegue l'elaborazione delle immagini per le pagine (filigrana, rotazione, scala, annotazioni)
Sicurezza del documento (archivio di accesso)SingletonConcessioni per il collegamento token-sessione
ViewerTransienteLa facciata pubblica di apertura/chiusura
DocumentConverterTransienteFacciata di conversione — richiede il plugin Converter
DocumentSignerTransienteFacciata di firma — richiede il plugin Signer (vedi Plugin Signer)
DistributedDocumentPublisherTransientePubblica gli artefatti di un documento nello storage condiviso (vedi Distribuzioni distribuite)
Controllo di salute "doconut"—Riporta lo stato della licenza/scadenza tramite i controlli di salute di ASP.NET

Due comportamenti da conoscere:

  • Converter richiede il suo plugin. Risolvendo DocumentConverter senza options.AddPlugin<ConverterPlugin>() genera un'eccezione:
text
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 falliscono al momento 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. 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 Visualizzatore) — 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 utilizza BasePath: '/'):

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 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 visualizzatore rimane vuota e la console del browser mostra 404 per /doconut-res/..., questa chiamata è mancante o posizionata in modo errato.

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:

text
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 widget

Il lato di lettura è un middleware separato dall'assembly Doconut.Clouds, che è incluso nello stesso pacchetto:

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

Riepilogo dell'ordinamento

csharp
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 MapWhen

Questa pagina è stata utile?