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.

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // llame a UseSession() antes de UseDoconut()
app.UseDoconutResources(); // debe registrarse antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

UseDoconut() responde a cada solicitud que llega a él, así que móntalo en su propia rama con app.Map.

AddDoconut

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

ServicioDuraciónRol
DoconutOptionsSingletonEl objeto de configuración
Servicio de caché de sesiónSingletonToken → caché de sesión (IMemoryCache también está registrado)
IDoconutLicenseServiceSingletonLicencia cargada una vez al iniciar (precedencia: LicenseStream → LicenseContent → LicensePath → búsqueda automática)
Canal de página‑imagenSingletonRealiza procesamiento de imágenes para páginas (marca de agua, rotación, escala, anotaciones)
Seguridad de documentos (almacén de acceso)SingletonConcede la vinculación token‑sesión
ViewerTransientLa fachada pública de apertura/cierre
DocumentConverterTransientFachada de conversión — requiere el complemento Converter
DocumentSignerTransientFachada de firma — requiere el complemento Signer (ver Plugin de firma)
DistributedDocumentPublisherTransientPublica los artefactos de un documento en almacenamiento compartido (ver Despliegues distribuidos)
Health check "doconut"—Informa el estado de licencia/vencimiento a través de los health checks de ASP.NET

Dos comportamientos que vale la pena conocer:

  • Converter requiere su complemento. Resolver DocumentConverter sin options.AddPlugin<ConverterPlugin>() lanza:
text
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>().

  • El derecho al complemento se valida al iniciar. Una licencia faltante, un archivo legacy TRIAL, o una licencia de pago sin la capacidad de un complemento registrado falla en tiempo de AddDoconut(). Los registros temporales/Demo sobreviven a su fecha de vencimiento, mientras que las puertas en tiempo de ejecución revocan las capacidades expiradas.

El health check se integra con el mecanismo estándar de ASP.NET Core — mapealo si deseas el estado de la licencia en tu endpoint de health:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Añade el middleware de página‑imagen de 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.

Una alternativa común mantiene la forma histórica de solicitud DocImage.axd con una rama MapWhen (el cliente entonces 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)

Sirve los JS, CSS, imágenes y fuentes incrustados en DoconutOptions.ResourcesPath (por defecto /doconut-res). Estos son los archivos para los que Viewer.ReferenceCss() / ReferenceScripts() emiten 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.

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 Despliegues distribuidos; las firmas son:

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

El lado de lectura es un middleware separado del ensamblado Doconut.Clouds, que se entrega en el mismo paquete:

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

Recapitulación del orden

csharp
app.UseRouting();
app.UseSession();          // llame a UseSession() antes de UseDoconut()
app.UseDoconutResources(); // debe registrarse antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // o una rama MapWhen

¿Fue útil esta página?