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 le llega, así que colóquelo 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 fail-fast (ver DoconutOptions → Validación de inicio), y registra el grafo completo de servicios:

ServicioDuración de vidaRol
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 procesamiento de imágenes de páginaSingletonRealiza 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-a-sesión
ViewerTransientLa fachada pública de abrir/cerrar
DocumentConverterTransientFachada de conversión — requiere el plugin Converter
DocumentSignerTransientFachada de firma — requiere el plugin Signer (ver Plugin Signer)
DistributedDocumentPublisherTransientPublica los artefactos de un documento en almacenamiento compartido (ver Despliegues distribuidos)
Chequeo de salud "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 plugin. 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>().

  • 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 tiempo de AddDoconut(). Los registros temporales/Demo sobreviven a su fecha de expiración, mientras que las puertas de 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 endpoint de salud:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Agrega el middleware de imágenes de página 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 por sí mismo con 404 (o el banner ShowDoconutInfo): nunca pasa una solicitud al resto del pipeline. Montelo 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 (predeterminado /doconut-res). Estos son los archivos para los que Viewer.ReferenceCss() / ReferenceScripts() emiten etiquetas.

Siempre llámelo 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.

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // cola de publicación en segundo plano con opción de suscripción
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure)                     // almacén de respaldo compartido para cargas de widgets

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

Ordering recap

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?