Visor

Viewer (namespace Doconut) es el punto de entrada público para abrir documentos desde controladores MVC, páginas Web Forms y manejadores. Es un servicio transitorio compuesto por DoconutHost.Initialize; resuélvelo donde lo uses:

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() también funciona una vez que DoconutHost.Initialize se ha ejecutado — resuelve los mismos servicios — lo que permite que el código migrado del paquete clásico siga compilando. Antes de Initialize, lanza InvalidOperationException.

Viewer no mantiene estado de documento por solicitud y deliberadamente no implementa IDisposable: las sesiones de documento viven independientemente de él, por lo que disponer un Viewer nunca podría cerrar un documento abierto (ver Cómo funciona el Visor).

OpenDocumentAsync

Abre un documento y devuelve el token de sesión que el widget utiliza para cada solicitud posterior. Cuando UnsafeMode es false (el valor predeterminado), el token se otorga a la sesión ASP.NET de la solicitud actual — llámalo desde una solicitud que tenga estado de sesión (ver Sesiones y Seguridad).

// 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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

Excepciones a manejar:

• LicenseException — se encontró una licencia pero fue rechazada (el mensaje contiene la razón), o el formato necesita una capacidad de complemento que la licencia no otorga.
• FormatNotSupportedException — ningún visor maneja la extensión del archivo.
• InvalidDataException — el contenido está corrupto o no coincide con su extensión.

OpenDocument (sincrónico)

Para el código behind de Web Forms y otro código que no utiliza páginas asíncronas:

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

Cada una devuelve el token y también lo almacena en viewer.Token. fileName debe contener la extensión correcta. Estos envoltorios son seguros para llamar desde una página Web Forms: la ruta de apertura nunca se reanuda en el contexto de solicitud ASP.NET, por lo que esperar en ella no puede causar un bloqueo. Lo mismo no es cierto para todas las API asíncronas de Doconut — vea la sección de Web Forms de Complemento de Convertidor.

CerrarDocumento

void CloseDocument(string token)

Elimina la sesión (liberando el motor de documentos inmediatamente), elimina la concesión del token de la sesión ASP.NET de la solicitud actual y revoca el token. Opcional — la expiración deslizante realiza la misma limpieza — pero se recomienda para documentos grandes.

Consultas de sesión

Cada uno lanza una excepción si el token es desconocido o ha expirado.

OpcionesDoc

Opciones por apertura, independientes del formato (namespace Doconut):

Marca de agua personalizada

DocOptions.Watermark acepta seis campos separados por tildes. Un ^ opcional al inicio solicita la disposición 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 no válida se reemplaza por un texto visible Invalid Watermark en lugar de desaparecer silenciosamente.

Decisión de licencia

La misma decisión se aplica a las páginas servidas y a las exportaciones de anotaciones. Una marca de agua personalizada es una característica de una aplicación con licencia, no una forma de sustituir la marca de agua de evaluación.

API de anotaciones

Carga y exportación de anotaciones del lado del servidor. La guía práctica está en Anotaciones.

Metadatos DICOM

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

En este paquete siempre devuelve null, y la solicitud de metadatos del widget responde 501 Not Implemented: la lectura de etiquetas DICOM no está disponible en .NET Framework. El renderizado DICOM — páginas, fotogramas y animación — funciona. Ver Complemento DICOM.

Ayudantes de recursos — ReferenceCss / ReferenceScripts

Emite las etiquetas <link> y <script> para los recursos que el módulo de recursos sirve bajo DoconutOptions.ResourcesPath, en orden de dependencia. Los archivos de funciones limitadas por licencia (Search, Annotation) se emiten solo cuando la licencia los concede.

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // license state, for guarding ribbon init code
bool IsAnnotationEnabled { get; }

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

ScriptConfig banderas: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (the core viewer scripts), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated).

Ambos devuelven HTML: escríbelos con @Html.Raw(...) en MVC 5 (genéralos en el controlador — las vistas no tienen @inject) o <%= %> en Web Forms. Ver Inicio rápido muestra ambos.

Renderizador de visor

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

Devuelve un bloque <script> que inicializa el widget en el elemento con id elementId y muestra el documento: docViewer({...}) construido a partir del ViewerConfig (por defecto: BasePath: '/', ResPath: 'doconut-res/images'), luego .View(token). Escríbelo después de los scripts del visor. El script generado no mantiene referencia al objeto del visor, por lo que una página con su propia barra de herramientas debe inicializar el widget manualmente. Ver ViewerConfig.

Granja web

string? AccessToken contiene el ticket firmado emitido por la apertura más reciente cuando el modo distribuido está activo y UnsafeMode es false; es null en un solo servidor. Envíalo al widget con el token: objViewer.View(token, access).