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 → ricerca automatica)
Pipeline di immagini di paginaSingletonEsegue l'elaborazione delle immagini per le pagine (filigrana, rotazione, scala, annotazioni)
Sicurezza del documento (archivio di accesso)SingletonConcede il binding token‑sessione
ViewerTransientLa facciata pubblica di apertura/chiusura
DocumentConverterTransientFacciata di conversione — richiede il plugin Converter
DocumentSignerTransientFacciata di firma — richiede il plugin Signer (vedi Plugin di firma)
DistributedDocumentPublisherTransientPubblica 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 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 fallisce 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 integrità si integra con il meccanismo standard di ASP.NET Core — mappalo se vuoi lo stato della licenza sul tuo endpoint di integrità:

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 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: '/'):

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 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:

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 viene fornito 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?