Registrar y habilitar el widget convertidor de inserción de Doconut en .NET 8

El widget de inserción es la interfaz lista para usar de Doconut para cargar un archivo, ejecutar una conversión y descargar el resultado.
De fábrica, los tres puntos finales ?convert= del widget devuelven 404; solo se activan cuando registras el complemento Converter y llamas a AddConverterWidget() en DoconutOptions.

A continuación se muestra una configuración de inicio completa, lista para copiar y pegar, que satisface ambos requisitos.

---

1. Requisitos previos – licencia y soporte de sesión

• Licencia – El complemento Converter requiere una licencia que otorgue la capacidad Converter. Coloca el archivo (p. ej., Doconut.Viewer.lic) en un lugar accesible para la aplicación y apunta DoconutOptions.LicensePath a él.
• Estado de sesión – El modelo de seguridad de Doconut almacena los tokens de sesión de documentos en la sesión de ASP.NET Core. Añade una caché distribuida y AddSession() antes de que el middleware sea configurado.

builder.Services.AddDistributedMemoryCache();   // requerido para la sesión
builder.Services.AddSession();                  // habilita sesión respaldada por IDistributedCache‑backed

---

2. Registrar los servicios centrales de Doconut

AddDoconut() es el único punto de entrada que inyecta el visor, el servicio de licencia y el registro de complementos.

builder.Services.AddDoconut(options =>
{
    // Indique a Doconut dónde encontrar el archivo de licencia.
    options.LicensePath = "Doconut.Viewer.lic";

    // Registre el plugin Converter – esto también valida la capacidad de licencia.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Si la licencia no incluye la capacidad Converter, la llamada anterior lanza InvalidOperationException y la aplicación no se iniciará. Ese comportamiento de falla rápida evita que despliegues una compilación con licencia incorrecta.

---

3. Activar el widget con AddConverterWidget

El widget es opcional. Llamar a AddConverterWidget() registra los tres puntos finales de conversión (?convert=open, ?convert=run, ?convert=download) y configura una pequeña cantidad de ajustes del lado del cliente (tamaño máximo de carga, rutas base, etc.).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // Habilite la UI de drop‑in y establezca el límite de carga del lado del cliente.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // pre‑cheque del cliente; el servidor impone su propio límite
    });
});

Solo la llamada AddConverterWidget crea los puntos finales; el archivo JavaScript estático (doconutConverter.js) siempre se sirve como recurso incrustado, pero fallará al contactar el servidor si los puntos finales faltan.

---

4. Conectar el middleware en el orden correcto

El middleware que sirve los recursos estáticos (UseDoconutResources) debe ejecutarse antes del middleware de visor terminal (UseDoconut). El middleware de sesión también necesita estar colocado antes porque Doconut valida la sesión en cada solicitud.

app.UseSession();           // debe preceder a UseDoconut()
app.UseDoconutResources();  // sirve JS, CSS, imágenes
app.UseDoconut();           // maneja ?convert= y solicitudes de página de documento

Con esta canalización en su lugar, una solicitud a /doconut-res/doconutConverter.js tiene éxito, y el widget puede llamar a /doconut?convert=open, /doconut?convert=run y /doconut?convert=download.

---

5. Qué hace realmente el widget

Fase	Punto final del servidor	Respuesta típica
Abrir	?convert=open	Devuelve una carga JSON que contiene un token, el recuento de páginas, la extensión de origen y la lista de formatos de destino permitidos.
Ejecutar	?convert=run	Inicia la conversión y devuelve un downloadToken, el recuento de páginas resultantes, un nombre de archivo sugerido y una bandera que indica si la salida tiene marca de agua.
Descargar	?convert=download	Transmite el archivo convertido cuando el cliente sigue la URL de descarga proporcionada.

Del lado del cliente, el widget realiza una verificación de tamaño previo a la carga contra widget.MaxUploadMb. Si el archivo supera ese límite, el widget aborta la carga y dispara la devolución de llamada onError con phase = "open" y un mensaje amigable. El servidor impone su propio límite y responderá 413 Payload Too Large si la solicitud pasa la verificación del cliente.

---

6. Conectar a los eventos del widget (no se necesita código C#)

Todas las devoluciones de llamada (onReady, onSourceLoaded, onConverted, onError, etc.) son funciones JavaScript proporcionadas por la página que aloja el widget. Dado que la pregunta se centra en el lado de registro, no necesitas escribir código C# adicional para manejar esas devoluciones de llamada: el widget las invoca automáticamente una vez que los puntos finales están activos.

---

7. Errores comunes y cómo evitarlos

Síntoma	Causa probable	Solución
404 en /doconut?convert=open	Se omitió AddConverterWidget().	Añade la llamada como se muestra en la sección 3.
La aplicación no arranca con InvalidOperationException sobre capacidad faltante	El archivo de licencia no concede Converter.	Obtén una licencia que incluya la capacidad Converter.
Error de 500 relacionado con la sesión	UseSession() colocado después de UseDoconut() o falta el registro de caché.	Asegúrate de que app.UseSession() se ejecute antes de app.UseDoconut() y que un servicio de caché esté registrado.

---

8. Ejecutar la aplicación y ver el widget en acción

1. Compila y ejecuta el proyecto ASP.NET Core.
2. Abre una página que contenga un elemento <div id="doconut-convert"></div> e incluya el script del convertidor Doconut (el script se sirve automáticamente desde /doconut-res/doconutConverter.js).
3. Arrastra un archivo compatible (PDF, DOCX, DWG, etc.) al área de arrastre.
4. El widget llamará a ?convert=open, luego a ?convert=run y finalmente mostrará un enlace Descargar que apunta a ?convert=download.

Si los tres puntos finales responden con JSON en lugar de 404, el widget está registrado correctamente y listo para su uso en producción.

---

Próximo paso: Añade los fragmentos de código anteriores a tu Program.cs (o Startup.cs), verifica que el archivo de licencia esté presente y lanza la aplicación. El widget convertidor de inserción estará activo sin necesidad de más cambios del lado del servidor.