Conversión de Documentos del Lado del Servidor en .NET con Doconut

Introducción

La conversión de documentos del lado del servidor permite que una aplicación genere una salida normalizada sin automatizar Microsoft Office ni enviar la fuente a un servicio de conversión en línea separado. Eso puede simplificar portales de documentos, trabajos en segundo plano y flujos de exportación controlados, pero la aplicación anfitriona sigue siendo la responsable del control de acceso, almacenamiento, retención, monitoreo y entrega del resultado.

El Plugin Convertidor .NET 8 de Doconut expone la conversión a través del servicio DocumentConverter inyectado por dependencia. Esta guía se centra en el modelo actual de registro y API y evita acoplar la conversión a una sesión de visor.

---

Instalar paquetes coincidentes

Instale los paquetes base del visor y del convertidor:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Mantenga ambos paquetes en la misma versión de lanzamiento. Cuando las compilaciones reproducibles son importantes, fije la versión en el archivo del proyecto o pase el mismo valor --version a ambos comandos.

Registrar el Plugin Convertidor

Los plugins se registran dentro de la devolución de llamada AddDoconut de opciones. No existe un método de registro separado AddConverter():

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

La aplicación debe usar una licencia que otorgue la capacidad de Convertidor. Resuelva los errores de inicio y licencia antes de aceptar trabajos de conversión; no los posponga a una cola en segundo plano donde se vuelvan más difíciles de diagnosticar.

Convertir un archivo desde C#

Inyecte DocumentConverter en el endpoint o servicio que posee la solicitud de conversión. El constructor del convertidor es interno, por lo que el código de la aplicación no debe instanciarlo directamente.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

El flujo devuelto es buscable y está posicionado al principio. El llamador es el propietario y debe disponerlo después de copiar o devolver el contenido.

Convertir un flujo subido

La sobrecarga de flujo necesita la extensión de origen —incluyendo su punto inicial— porque el convertidor la usa para resolver el formato de origen:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Trate el nombre de archivo y la extensión como entrada no confiable. Implemente límites de carga, valide el tipo de origen, autorice al usuario solicitante y evite usar el nombre de archivo enviado como ruta de almacenamiento.

Elegir destinos según capacidades reales

El plugin expone un enum ConversionTarget, pero no todos los formatos de origen pueden producir cada destino. Una UI personalizada debe mostrar solo los destinos permitidos para el origen subido en lugar de presentar cada valor del enum.

Al usar el widget opcional del convertidor de Doconut, su respuesta abierta incluye allowedTargets. Use esa respuesta como la fuente de verdad para el archivo actual.

Diseñar la conversión en segundo plano como un flujo de trabajo de aplicación

El convertidor puede ser llamado desde un servicio de aplicación o un trabajador en cola. Un trabajo robusto normalmente incluye:

1. Una solicitud autenticada que registre el origen y el destino deseado.
2. Un mensaje de cola que contenga un ID de trabajo de aplicación, no credenciales crudas.
3. Un trabajador que recupere el origen mediante una abstracción de almacenamiento autorizada.
4. Una operación de conversión limitada con cancelación.
5. Almacenamiento de salida duradero con reglas explícitas de retención.
6. Una actualización de estado que no exponga rutas internas ni detalles sensibles de excepciones.

Mida la concurrencia con documentos representativos antes de seleccionar la cantidad de trabajadores. El costo de conversión varía según el formato de origen, la complejidad del documento, fuentes, imágenes y el destino de salida.

Mantener las reclamaciones de seguridad precisas

Ejecutar el convertidor dentro de su aplicación .NET significa que la operación de conversión no requiere automatización de Microsoft Office ni una API de conversión en línea separada. No garantiza automáticamente privacidad, cumplimiento, eliminación o cifrado para todo el sistema.

Esas propiedades dependen de cómo la aplicación autentica a los usuarios, recupera los archivos de origen, configura el almacenamiento, protege los registros, distribuye la salida y elimina los datos temporales o retenidos.

Lista de verificación operativa

• Mantenga alineadas las versiones de Doconut.NET8 y Doconut.NET8.Converter.
• Registre ConverterPlugin durante la configuración de servicios.
• Resuelva DocumentConverter mediante inyección de dependencias.
• Incluya el punto inicial en las extensiones de origen de los flujos.
• Disponga los flujos de origen y resultado.
• Use cancelación y límites de tamaño de archivo a nivel de aplicación.
• Valide la compatibilidad origen‑destino en lugar de asumir que cada par funciona.
• Pruebe la fidelidad y el uso de recursos con archivos representativos.
• Mantenga decisiones de almacenamiento, autorización, auditoría y retención en el código de la aplicación.

Consulte la visión general oficial del Plugin Convertidor de Doconut y la documentación de Doconut para obtener información actual del producto e integración.