Visor

Viewer (namespace Doconut) es el punto de entrada público para abrir documentos desde páginas Razor, controladores MVC, componentes Blazor o APIs mínimas. Es sellado, registrado como un servicio transitorio por AddDoconut(), y resuelto mediante inyección de constructor — nunca lo construyas directamente.

La biblioteca .NET Standard anterior exponía un constructor público que recibía la caché de memoria, el accesorio del contexto HTTP y una o más rutas de licencia. Ese constructor ha desaparecido; el grafo de servicios proporciona esas dependencias.

Viewer no mantiene estado por solicitud y deliberadamente no implementa IDisposable: las sesiones de documento viven de forma independiente en la caché de sesiones, por lo que disponer del servicio nunca podría cerrar un documento abierto (ver Conceptos básicos → Cómo funciona el Viewer).

OpenDocumentAsync

Abre un documento y devuelve el token de sesión que el widget cliente usa para todas las solicitudes posteriores. Cada apertura es asíncrona — no existe un OpenDocument sincrónico.

// Apertura simple
string token = await viewer.OpenDocumentAsync(path);

// Con configuración y opciones por formato
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Desde una carga
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Excepciones a manejar:

• LicenseException — una licencia encontrada es rechazada (el mensaje lleva la razón del rechazo), o el formato necesita una capacidad de complemento que ya no se concede. La expiración del calendario sin un mensaje de rechazo degrada a renderizado con marca de agua en lugar de lanzar una excepción.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — el contenido del archivo está corrupto o no coincide con su extensión.

CloseDocument

void CloseDocument(string token)

Elimina la sesión de la caché (disponiendo el motor del documento inmediatamente), borra el marcador de seguridad y revoca la concesión de acceso. Opcional — la expiración deslizante realiza la misma limpieza — pero se recomienda para documentos grandes.

GetPageCount

int GetPageCount(string token)

Número total de páginas de la sesión abierta. Lanza una excepción si el token es desconocido o ha expirado.

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Devuelve los nombres de las hojas de cálculo de una hoja de cálculo abierta, en orden del libro, o una lista vacía cuando el documento abierto no es una hoja de cálculo.

Solo se enumeran las hojas de cálculo renderizadas: las hojas ocultas y vacías se excluyen, y cuando ExcelConfig.SheetNames restringe el renderizado, solo aparecen esas hojas. Una hoja de cálculo no siempre corresponde a una página — una muy grande se renderiza en varias páginas. Lanza una excepción si el token es desconocido o ha expirado.

Añadido en 26.9.0.

Indicadores de capacidad

Utilice estos en una vista Razor para renderizar una cinta con licencia solo cuando el servidor realmente la sirva — vea Inicio rápido.

Opciones de documento

Opciones por apertura, independientes del formato (espacio de nombres Doconut):

La clase también expone propiedades especializadas que están intencionalmente fuera del flujo de visualización normal de un solo host:

Marca de agua personalizada

DocOptions.Watermark usa seis campos separados por tildes. Un ^ opcional al inicio solicita el diseño de todas las esquinas:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

El analizador espera exactamente seis campos después del ^ opcional. Una definición no válida se reemplaza por el Invalid Watermark visible del SDK en lugar de desaparecer silenciosamente.

Decisión de licencia

La misma decisión se aplica a las imágenes de página servidas y a las exportaciones de anotaciones. La salida GIF animada se marca fotograma a fotograma. Por lo tanto, una marca de agua personalizada es una característica de la aplicación con licencia, no una forma de reemplazar o suprimir la marca de agua de evaluación.

API de anotaciones

Carga y exportación de anotaciones del lado del servidor. El tutorial completo se encuentra en Guías → Anotaciones; la superficie es:

Cada una de estas requiere el token de sesión. La forma sin sesión GetAnnotationManager(pageWidth, pageHeight) de la biblioteca anterior sigue existiendo para crear anotaciones fuera de una sesión, pero cargarlas aún requiere un token.

Metadatos DICOM

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

El método está presente para la alineación de la API, pero este paquete no puede proporcionar etiquetas técnicas DICOM: el lector de metadatos solo se entrega con una compilación .NET 8. Devuelve null para sesiones DICOM y no DICOM; en una sesión DICOM también escribe una advertencia única que explica la limitación de la plataforma. El renderizado de página, fotograma y animación sigue siendo compatible.

Ayudantes de recursos — ReferenceCss / ReferenceScripts

Emita las etiquetas <link>/<script> para los recursos incrustados servidos por UseDoconutResources(), en el orden de dependencia correcto. Los paquetes para funciones limitadas por licencia, como búsqueda y anotación, se emiten solo cuando la licencia las habilita, manteniendo la UI del cliente coherente con el comportamiento del servidor.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + visor + búsqueda + anotación
string ReferenceScripts(ScriptConfig? config = null)

Banderas CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (limitado por búsqueda), IncludeAnnotationCss (limitado por anotación).

Banderas ScriptConfig: IncludeJQuery (requerido por todos los demás), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + divisor + enlaces), IncludeSearchScripts y IncludeSearchBar (limitado por búsqueda), IncludeAnnotationScripts y IncludeAnnotationBar (limitado por anotación).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Estos ayudantes son la forma soportada de entregar los recursos del navegador. Las aplicaciones que copiaron docViewer.js, documentLinks.js y docViewer.UI.js en wwwroot deberían eliminar esas copias una vez que la página se renderiza a partir de las etiquetas emitidas.