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. Está sellado, registrado como un servicio transitorio mediante AddDoconut(), y se resuelve 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 ya no existe; el grafo de servicios proporciona esas dependencias.

Viewer no mantiene estado por solicitud y, intencionalmente, no implementa IDisposable: las sesiones de documentos 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 Visor).

OpenDocumentAsync

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

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
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 está concedida. 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 del motor de documentos 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.

Capability flags

Utilízalos en una vista Razor para renderizar una cinta con licencia solo cuando el servidor realmente la sirva — ver Inicio rápido.

DocOptions

Opciones por apertura, independientes del formato (namespace 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 utiliza seis campos separados por tildes. Un ^ opcional al inicio solicita el diseño en 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 inválida se reemplaza por la alternativa visible Invalid Watermark 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 animado se marca fotograma a fotograma. Por lo tanto, una marca de agua personalizada es una característica de 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. La guía completa se encuentra en Guías → Anotaciones; la superficie es:

Cada uno de estos requiere el token de sesión. La forma sin sesión de la biblioteca anterior GetAnnotationManager(pageWidth, pageHeight) 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 alinear la API, pero este paquete no puede proporcionar etiquetas DICOM técnicas: el lector de metadatos solo se distribuye 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

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

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (restringido a búsqueda), IncludeAnnotationCss (restringido a anotación).

ScriptConfig flags: IncludeJQuery (requerido por todos los demás), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + splitter + links), IncludeSearchScripts y IncludeSearchBar (restringido a búsqueda), IncludeAnnotationScripts y IncludeAnnotationBar (restringido a 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.