Plugin Convertidor

El plugin Convertidor transforma Doconut en un servicio de conversión de documentos. Contribuye con el motor detrás de la fachada pública DocumentConverter, y — opcionalmente — un widget listo para usar con su propio contrato HTTP, de modo que pueda convertir documentos desde C#, desde el widget, o desde un frontend que usted mismo escriba.

Instalar el paquete

Instale el último plugin Convertidor estable:

dotnet add package Doconut.NET6.Converter

Para fijar el plugin a la versión actual 26.7.0, pase la versión por separado:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Mantenga el paquete Convertidor en la misma versión que Doconut.NET6. El ID del paquete es Doconut.NET6.Converter; .26.7.0 aparece solo en el nombre de archivo descargado .nupkg.

Registrar el plugin

No existe un método AddConverter() — el modelo de plugins de Doconut es uniforme. Cada plugin, incluido Convertidor, se registra de la misma manera: llame a AddPlugin<TPlugin>() dentro de AddDoconut(). ConverterPlugin se entrega en su propio paquete NuGet, Doconut.NET6.Converter, instalado junto al paquete del visor base.

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

Esta llamada lanza una excepción al iniciar por una licencia faltante, un archivo heredado TRIAL, o una licencia no temporal que no otorga la capacidad Converter — un InvalidOperationException generado desde dentro de AddDoconut(), antes de que la aplicación sirva solicitudes. Se aceptan registros temporales Demo/NFR; después de su expiración de calendario, la conversión sigue disponible con salida con marca de agua. No hay un nivel gratuito silencioso. Consulte Configuración de Licencia para saber cómo se cargan las licencias.

Convertir desde C#

Cada conversión devuelve un MemoryStream buscable posicionado en 0, listo para leer o copiar inmediatamente. Resuelva DocumentConverter desde DI donde lo necesite — es sin estado por diseño, por lo que una única instancia es segura para reutilizarse en múltiples solicitudes.

// Inyecta DocumentConverter; su constructor es interno, así que nunca lo `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension incluye el punto inicial. password es null a menos que el documento esté protegido.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dos detalles que es fácil equivocarse: sourceExtension en la sobrecarga de stream debe incluir el punto inicial (".xlsx", no "xlsx") — el convertidor lo compara con el catálogo de formatos y una extensión sin punto no se resolverá. Y a pesar de su nombre, WordToHtmlAsync devuelve Task<Stream>, no Task<string> — obtiene el documento HTML (imágenes incrustadas como Base64) como un stream, igual que cualquier otro resultado de conversión.

Formatos de destino

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

No todas las fuentes se convierten a todos los destinos — el plugin asigna cada familia de formato de origen (Word, Excel, PowerPoint, PDF, CAD, Imagen, Correo electrónico, Diagrama, Proyecto/Tarea, PSD, documento web) a su propio conjunto fijo de destinos permitidos. No codifique este enum como la lista de destinos de su UI: ?convert=open devuelve el allowedTargets real para cualquier archivo que se haya subido, y eso es lo que debe impulsar el selector.

Widget incrustable

Los endpoints ?convert=open|run|download del widget son opcionales y están deshabilitados por defecto — seguros por defecto. Habilítelos del lado del servidor, junto con el registro del plugin:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Sin AddConverterWidget(), los tres endpoints ?convert= responden 404 — pero el archivo JS sigue sirviéndose de todos modos (es un recurso estático incrustado simple; solo los endpoints a los que se comunica están restringidos). AddConverterWidget() aún requiere que el plugin Converter esté registrado y una licencia que otorgue Converter — no concede derechos de conversión por sí mismo.

Personaliza el widget

Opciones de inicialización pasadas a Doconut.convert(selector, options):

Callbacks:

Doconut.convert() devuelve la propia instancia del widget — guárdala para controlar el widget programáticamente:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // volver a la pantalla idle/drop; no vuelve a disparar onReady
conv.loadFile(file);  // inicia el flujo con un objeto File; no-op a menos que esté actualmente idle
conv.destroy();       // elimina los listeners, vacía el mount; la instancia no es usable después de esto

Construye tu propio frontend

El widget es solo un cliente para este contrato HTTP — construye tu propio frontend directamente contra él para una experiencia de usuario diferente. Las tres rutas se encuentran bajo la rama ASP.NET donde UseDoconut() está montado (normalmente /doconut):

Los bytes de la fuente subidos se almacenan del lado del servidor con un TTL de 30 minutos; una vez que esa ventana expira, run responde 404 y el archivo debe volver a abrirse. El resultado convertido vive en el mismo almacén — downloadToken obtiene su propia ventana fresca de 30 minutos cuando la conversión se completa — mientras que resultToken es un token de sesión de visor ordinario cuyo tiempo de vida sigue la caché de sesión del visor, independiente del almacén.

sourceExt en la respuesta open no tiene punto inicial (p. ej. "docx") — la convención opuesta al parámetro sourceExtension en DocumentConverter.ConvertAsync, que sí lo requiere.

Modos de falla, agrupados por ruta:

Propiedad de recursos

El conversor devuelve un MemoryStream buscable posicionado en cero. El llamador posee ese flujo y debe descartarlo después de copiar o devolver su contenido. El servicio DocumentConverter en sí es sin estado y se resuelve mediante inyección de dependencias; no lo construya ni lo descarte manualmente.

Para el widget web, los almacenes de carga y descarga tienen TTLs independientes de 30 minutos. Un resultToken de visor sigue la duración de la sesión del visor en su lugar. Cerrar un resultado de visor no elimina un almacén de descarga aún válido, y restablecer el widget del navegador no extiende ninguno de los TTL.

Solución de problemas

Marca de agua

Con ConverterPlugin registrado, la licencia del host está en uno de tres estados:

Ambas rutas de llamada calculan la bandera a partir de la misma regla: la fachada C# DocumentConverter la deriva internamente del estado IsViewerLicensed y IsTemporary de la licencia, y el manejador ?convert=run del widget realiza la comprobación equivalente (IsViewerLicensed && !IsTrial && !IsTemporary) para rellenar el campo watermarked que devuelve. Se puede crear y probar una integración de extremo a extremo con una licencia de evaluación antes de la compra — solo cambian los bytes de salida.