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 el origen a un servicio de conversión en línea separado. Esto puede simplificar portales de documentos, trabajos en segundo plano y flujos de exportación controlados, pero la aplicación anfitriona sigue controlando el acceso, el almacenamiento, la retención, la monitorización y la 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 del 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 de opciones AddDoconut. No existe un método de registro separado AddConverter():

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "doconut.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 de 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 gestiona 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 inicio. El llamador lo posee y debe disponerlo después de copiar o devolver el contenido.

Convertir un flujo subido

La sobrecarga de flujo necesita la extensión del origen —incluyendo su punto inicial— porque el convertidor la utiliza 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 generar todos los destinos. Una interfaz personalizada debe mostrar solo los destinos permitidos para el origen subido en lugar de mostrar todos los valores del enum.

Al usar el widget opcional de conversión de Doconut, su respuesta abierta incluye allowedTargets. Utilice 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 en la cola que contenga un ID de trabajo de la aplicación, no credenciales sin procesar.
3. Un trabajador que recupere el origen a través de una abstracción de almacenamiento autorizada.
4. Una operación de conversión limitada con cancelación.
5. Almacenamiento de salida duradero con reglas de retención explícitas.
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.

Estas 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 las versiones de Doconut.NET8 y Doconut.NET8.Converter alineadas.
• Registre ConverterPlugin durante la configuración de servicios.
• Resuelva DocumentConverter mediante inyección de dependencias.
• Incluya el punto inicial en las extensiones de origen del flujo.
• Dispose los flujos de origen y de resultado.
• Utilice 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 las 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 información actual del producto e integración.