Visor

La clase principal del visor de documentos

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 ya no existe; 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 Visor).

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.

SobrecargaUsar cuando
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Abrir desde disco con detección automática de formato y la configuración predeterminada del formato
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Necesitas opciones de renderizado por formato (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)El documento no es un archivo en disco (carga, base de datos, blob). fileInfo debe llevar la extensión correcta — esto impulsa la detección de formato
csharp
// 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

text
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

text
int GetPageCount(string token)

Número total de páginas de la sesión abierta. Lanza InvalidOperationException (Document session not found. Please re-open document.) si el token es desconocido o ha expirado, y ArgumentException para un token vacío.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

El tamaño de página renderizado por defecto del documento al 100 % de zoom — el espacio de coordenadas para anotaciones construido en código. page se acepta por compatibilidad; el resultado es el valor predeterminado del documento. Lanza InvalidOperationException (Document session not found. Please re-open document.) si el token es desconocido o ha expirado, y ArgumentException para un token vacío.

Obtener nombres de hoja

text
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: se excluyen las hojas ocultas y vacías, 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 InvalidOperationException (Document session not found. Please re-open document.) si el token es desconocido o ha expirado, y ArgumentException para un token vacío.

Añadido en 26.9.0.

Banderas de capacidad

MiembroSignificado
bool IsSearchEnabledLa licencia actual otorga Search
bool IsAnnotationEnabledLa licencia actual otorga Annotation

Utilízalos 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 independientes del formato por apertura (espacio de nombres Doconut):

TipoPropiedadValor predeterminadoDescripción
stringPassword""Contraseña para documentos protegidos (copiada automáticamente en la configuración de formato).
intImageResolution0Obsoleto. Conservado solo por compatibilidad — establezca ImageResolution en la configuración de formato en su lugar.
stringWatermark""Texto de marca de agua personalizada dibujado en las páginas renderizadas. Cadena de formato: "^Text~Color~FontSize~FontName~Opacity~Angle", p. ej. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Expiración deslizante de la sesión en minutos.
boolIsSecuredtrueNo se aplica actualmente — reservado. La vinculación de tokens se controla globalmente mediante DoconutOptions.UnsafeMode (ver Conceptos básicos → Sesiones y seguridad).

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

TipoPropiedadValor predeterminadoDescripción
boolIsWebFarmfalseObsoleto — no tiene efecto. Publique el documento con DistributedDocumentPublisher.PublishAsync (o IDistributedPublishQueue.EnqueueAsync) y establezca FileShareConfig.RootPath en su lugar. Observe la capitalización — la biblioteca anterior lo escribía como IsWebfarm.
stringWebFarmPath""Obsoleto — no tiene efecto. Use FileShareConfig.RootPath, como se describe en Despliegues distribuidos. Anteriormente escrito como WebfarmPath.
boolEditModefalseReservado para un flujo de trabajo de edición distribuido por separado; deje false para el visor estándar.

Marca de agua personalizada

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

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
CampoEjemploSignificado
Inicial ^^Diseño opcional de todas las esquinas. Sin él, se usa la colocación normal de la marca de agua.
TextoConfidentialTexto renderizado en cada página. No debe estar vacío.
ColorRedColor con nombre entendido por la capa de dibujo.
TamañoFuente24Tamaño de fuente; una entrada numérica inválida recurre al valor predeterminado del renderizador.
NombreFuenteVerdanaFamilia de fuente solicitada. Asegúrese de que esté instalada en el entorno de despliegue.
Opacidad80Valor de byte de 0 a 255. Debe analizarse correctamente.
Ángulo-45Ángulo de rotación en grados; una entrada numérica inválida recurre al valor predeterminado.

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

Decisión de licencia

Estado de licenciaValor personalizado suministradoResultado renderizado
Licencia de visor pagada válidaNoPágina limpia
Licencia de visor pagada válidaSíMarca de agua personalizada
Visor base temporal/demo activoNoPágina de visor base limpia
Visor base temporal/demo activoSíMarca de agua personalizada cuando se aplica la ruta del visor base limpio
Licencia faltante, rechazada, expirada, de versión incorrecta o de dominio inválidoCualquieraMarca de agua de aplicación/evaluación; el valor personalizado no la sobrescribe
Renderizado de plugin bajo reglas de evaluaciónCualquieraMarca de agua de evaluación

La misma decisión se aplica a las imágenes de página servidas y a las exportaciones de anotaciones. La salida de GIF animado se marca fotograma a fotograma. Por lo tanto, una marca de agua personalizada es una característica de la aplicación bajo 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:

MiembroPropósito
AnnotationManager GetAnnotationManager(string token)Administrador vinculado a las dimensiones de página de la sesión abierta
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Administrador con dimensiones de página explícitas
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Administrador independiente de la sesión
void LoadAnnotationData(string token, AnnotationManager manager)Cargar anotaciones construidas en C# en la sesión
void LoadAnnotationData(string token, string annotationData)Cargar anotaciones desde la página codificada/envoltorio Base64 devuelto por AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Cargar anotaciones desde XML
XmlDocument GetAnnotationXML(string token)Exportar las anotaciones de la sesión como XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF con anotaciones incrustadas
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Un PNG por página, anotaciones incrustadas, escrito a directoryPath (creado si falta); devuelve el número de imágenes escritas
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP de PNGs por página con anotaciones incrustadas

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

Metadatos DICOM

text
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 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.

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

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

Banderas ScriptConfig: IncludeJQuery (requerido por todas las demás), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + divisor + enlaces), IncludeSearchScripts y IncludeSearchBar (restringidas por búsqueda), IncludeAnnotationScripts y IncludeAnnotationBar (restringidas por anotación), EmitFeatureFlags (predeterminado true: también escribe un script inline window.Doconut.features = { search, annotation, editor }; configúrelo a false bajo una Content-Security-Policy que bloquea scripts inline).

html
@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 renderice a partir de las etiquetas emitidas.

¿Fue útil esta página?