DoconutExtensions

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.UseDoconutResources(); // ANTES UseDoconut()
app.UseDoconut();

AddDoconut

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Construye el DoconutOptions, los valida de forma rápida al fallar (ver DoconutOptions → Validación de inicio), y registra el grafo completo de servicios:

No existe 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 DocumentConverter sin options.AddPlugin<ConverterPlugin>() lanza:

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

• El derecho del plugin se valida al iniciar. Falta una licencia, un archivo legacy TRIAL, o una licencia paga sin la capacidad de un plugin registrado falla en tiempo de AddDoconut(). Los registros temporales/demo sobreviven a su fecha de expiración, mientras que las puertas en tiempo de ejecución revocan las capacidades expiradas.

El chequeo de salud se integra con el mecanismo estándar de ASP.NET Core — mapealo si deseas el estado de la licencia en tu punto final de salud:

app.MapHealthChecks("/health");

UseDoconut

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Añade el middleware de imágenes de página de Doconut. Responde a 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). Cuando UnsafeMode está false, la capa de seguridad de documentos se conecta automáticamente antes de ella.

No toma argumentos. Pasar una instancia DoconutOptions aquí era la forma de la biblioteca anterior y ya no compila.

El ejemplo de referencia enruta las solicitudes del widget a través de una rama de ruta, conservando la forma histórica de la solicitud:

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 (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.

Esta es la sustitución soportada para conectar manualmente el middleware de manejo de recursos incrustados.

Serving from shared storage

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 Distributed Deployments; las firmas son:

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // cola de publicación en segundo plano opt-in
IServiceCollection AddDoconutDistributedWidgets(...)        // almacén de respaldo compartido para cargas de widgets

El lado de lectura es un middleware separado del paquete Doconut.Clouds:

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

UseDoconutWebFarm(...) y WebFarmOptions no existen en esta versión. Consulte la guía de migración para el mapeo configuración por configuración.

Ordering recap

app.UseRouting();
app.UseSession();          // requerido cuando UnsafeMode = false
app.UseDoconutResources(); // 1ª llamada a Doconut
app.UseDoconut();          // 2ª llamada a Doconut (o a través de una rama MapWhen)