DoconutExtensions
Registro de servicios y middleware
DoconutExtensions (namespace Doconut.Middleware) es la clase estática con las tres llamadas que cada host Doconut realiza: un registro de servicio y dos registros de middleware.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // llame a UseSession() antes de UseDoconut()
app.UseDoconutResources(); // debe estar registrado antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() responde a cada solicitud que le llega, así que móntalo en su propia rama con app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Construye el DoconutOptions, los valida de forma rápida (ver DoconutOptions → Validación de inicio), y registra el grafo completo de servicios:
| Servicio | Duración | Rol |
|---|---|---|
DoconutOptions | Singleton | El objeto de configuración |
| Servicio de caché de sesión | Singleton | Token → caché de sesión (IMemoryCache también está registrado) |
IDoconutLicenseService | Singleton | Licencia cargada una vez al iniciar (precedencia: LicenseStream → LicenseContent → LicensePath → búsqueda automática) |
| Pipeline de imágenes de página | Singleton | Realiza procesamiento de imágenes para páginas (marca de agua, rotación, escalado, anotaciones) |
| Seguridad de documentos (almacén de acceso) | Singleton | Concede vinculaciones token-a-sesión |
Viewer | Transient | La fachada pública de apertura/cierre |
DocumentConverter | Transient | Fachada de conversión — requiere el plugin Converter |
DocumentSigner | Transient | Fachada de firma — requiere el plugin Signer (ver Signer Plugin) |
DistributedDocumentPublisher | Transient | Publica los artefactos de un documento al almacenamiento compartido |
Comprobación de salud "doconut" | — | Informa el estado de licencia/vencimiento mediante comprobaciones de salud de ASP.NET |
No hay una llamada equivalente en la biblioteca .NET Standard anterior. Construía new Viewer(cache, accessor) por solicitud y pasaba opciones al middleware; ambos son reemplazados por este único registro.
Dos comportamientos que vale la pena conocer:
- Converter requiere su plugin. Resolver
DocumentConvertersinoptions.AddPlugin<ConverterPlugin>()lanza:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner sigue la misma regla: sin options.AddPlugin<SignerPlugin>() lanza No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- La autorización del plugin se valida al iniciar. Una licencia faltante, un archivo legacy
TRIAL, o una licencia paga sin la capacidad de un plugin registrado falla en tiempoAddDoconut(). Los registros temporales/Demo sobreviven a su fecha de vencimiento, mientras que las puertas en tiempo de ejecución revocan las capacidades expiradas.
La comprobación de salud se integra con el mecanismo estándar de ASP.NET Core — mapeala si deseas el estado de licencia en tu endpoint de salud:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Agrega el middleware de imágenes de página Doconut. Sirve cada solicitud que lleva un parámetro de consulta ?token= — páginas, miniaturas, búsqueda, anotaciones, acciones de página (la tabla completa de solicitudes está en Conceptos básicos → Cómo funciona el visor) — y responde cualquier otra solicitud con 404 (o el banner ShowDoconutInfo): nunca pasa una solicitud al resto del pipeline. Móntalo en su propia rama, como en los ejemplos de esta página. Cuando UnsafeMode está false, la capa de seguridad de documentos se conecta automáticamente antes de él.
No toma argumentos. Pasar una instancia DoconutOptions aquí era la forma de la biblioteca anterior y ya no compila.
Una configuración común mantiene la forma histórica de solicitud DocImage.axd con una rama MapWhen (el cliente entonces usa BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Sirve los JS, CSS, imágenes y fuentes incrustados en DoconutOptions.ResourcesPath (predeterminado /doconut-res). Estos son los archivos para los que Viewer.ReferenceCss() / ReferenceScripts() generan etiquetas.
Siempre llámalo antes de UseDoconut(). Si el área del visor permanece vacía y la consola del navegador muestra 404 para /doconut-res/..., esta llamada falta o está mal ubicada.
Esta es la sustitución soportada para conectar manualmente el middleware de manejo de recursos incrustados.
Servir desde almacenamiento compartido
Existen dos registros adicionales para implementaciones donde el nodo que renderiza un documento no es necesariamente el nodo que sirve sus páginas. Ambos están cubiertos de extremo a extremo en Implementaciones distribuidas; las firmas son:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // cola de publicación en segundo plano opt-in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // almacén de respaldo compartido para cargas de widgetsEl lado de lectura es un middleware separado del ensamblado Doconut.Clouds, que se incluye en el mismo paquete:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) y WebFarmOptions no existen en esta versión. Consulte la guía de migración para el mapeo configuración por configuración.
Recapitulación del orden
app.UseRouting();
app.UseSession(); // llame a UseSession() antes de UseDoconut()
app.UseDoconutResources(); // debe estar registrado antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // o una rama MapWhen¿Fue útil esta página?