Plugin de Conversión

El plugin Converter convierte 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 Converter estable:

dotnet add package Doconut.NET8.Converter

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

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

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

Registrar el plugin

No existe un método AddConverter() — el modelo de plugins de Doconut es uniforme. Cada plugin, incluido Converter, se registra de la misma manera: llame a AddPlugin<TPlugin>() dentro de AddDoconut(). ConverterPlugin se entrega en su propio paquete NuGet, Doconut.NET8.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 legado 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 vencimiento 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.

// Inyectar DocumentConverter; su constructor es interno, así que nunca lo `new`.
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 conversor 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 el archivo que se acaba de subir, y eso es lo que debe impulsar un selector.

Widget integrable

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í solo.

Personalizar el widget

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

Funciones de devolución de llamada:

Doconut.convert() devuelve la propia instancia del widget — manténgala 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 listeners, vacía el mount; la instancia no es utilizable después de esto

Construye tu propia interfaz

El widget es solo un cliente para este contrato HTTP — construye tu propia interfaz 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 cargada 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 requiere uno.

Modos de falla, agrupados por ruta:

Propiedad del recurso

El convertidor 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 visualizador sigue la duración de la sesión del visualizador en su lugar. Cerrar un resultado del visualizador 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 controlador ?convert=run del widget realiza la comprobación equivalente (IsViewerLicensed && !IsTrial && !IsTemporary) para rellenar el campo watermarked que devuelve. Se puede construir e integrar una prueba de extremo a extremo con una licencia de evaluación antes de la compra — solo cambian los bytes de salida.