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 → convalida all'avvio), e registra il grafo completo dei servizi:

ServizioDurataRuolo
DoconutOptionsSingoloL'oggetto di configurazione
Servizio di cache della sessioneSingoloToken → cache della sessione (IMemoryCache è registrato anche)
IDoconutLicenseServiceSingoloLicenza caricata una volta all'avvio (precedenza: LicenseStream → LicenseContent → LicensePath → ricerca automatica)
Pipeline di immagini di paginaSingoloEsegue l'elaborazione delle immagini per le pagine (filigrana, rotazione, scala, annotazioni)
Sicurezza del documento (archivio di accesso)SingoloConcessioni per il binding token‑sessione
ViewerTransitorioLa facciata pubblica di apertura/chiusura
DocumentConverterTransitorioFacciata di conversione — richiede il plugin Converter
DocumentSignerTransitorioFacciata di firma — richiede il plugin Signer (vedi Plugin Signer)
DistributedDocumentPublisherTransitorioPubblica 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 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 è convalidato 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 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 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: '/'):

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

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

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

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?