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

AddDoconut

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

Construye el DoconutOptions, lo 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
IViewerFactorySingletonAsocia extensiones a visores de formato
IDocumentSessionManagerSingletonToken → caché de sesión (IMemoryCache también está registrado)
IDoconutLicenseServiceSingletonLicencia cargada una vez al iniciar (precedencia: LicenseStream → LicenseContent → LicensePath → búsqueda automática)
PageImageServiceSingletonCanal de imágenes de página (marca de agua/rotar/escalar/anotaciones)
Document security (access store)SingletonConcesiones para la vinculación token‑sesión
ViewerTransientLa fachada pública de apertura/cierre
DocumentConverterTransientFachada de conversión — requiere el plugin Converter
DistributedDocumentPublisher—Publica los artefactos de un documento al almacenamiento compartido
Health check "doconut"—Informa el estado de licencia/vencimiento mediante los health checks de ASP.NET

En la biblioteca .NET Standard anterior no existía una llamada equivalente. 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:

  • El convertidor requiere su plugin. Resolver DocumentConverter sin options.AddPlugin<ConverterPlugin>() lanza:
text
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().
  • El derecho del plugin se valida al iniciar. Una licencia faltante, un archivo legado TRIAL, o una licencia paga sin la capacidad de un plugin registrado falla en el momento 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 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 salud:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Agrega el middleware de imágenes de página 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 Core Concepts → How the Viewer Works). Cuando UnsafeMode es false, la capa de seguridad del documento se conecta automáticamente antes de él.

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

La muestra de referencia dirige las solicitudes del widget a través de una rama de ruta, manteniendo la forma histórica de la solicitud:

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() 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 recursos incrustados con app.UseMiddleware<EmbeddedResourceMiddleware>().

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(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

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

text
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. Consulta la guía de migración para el mapeo configuración por configuración.

Recapitulación del orden

csharp
app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)

¿Fue útil esta página?