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.
Viewer no mantiene estado por solicitud y deliberadamente 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.
| Sobrecarga | Usar cuando |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Apertura 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 — es lo que impulsa la detección de formato |
// 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 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 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
(int Width, int Height) GetPageDimensions(string token, int page = 1)El tamaño de página predeterminado renderizado del documento al 100 % de zoom — el espacio de coordenadas para anotaciones construidas 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.
GetWorksheetNames
IReadOnlyList<string> GetWorksheetNames(string token)Devuelve los nombres de las hojas de cálculo de una hoja de cálculo abierta, en orden de 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 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
| Miembro | Significado |
|---|---|
bool IsSearchEnabled | La licencia actual otorga Search |
bool IsAnnotationEnabled | La licencia actual otorga Annotation |
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 (namespace Doconut):
| Tipo | Propiedad | Valor predeterminado | Descripción |
|---|---|---|---|
string | Password | "" | Contraseña para documentos protegidos (copiada automáticamente en la configuración de formato). |
int | ImageResolution | 0 | Obsoleto. Conservado solo por compatibilidad — establezca ImageResolution en la configuración de formato en su lugar. |
string | Watermark | "" | 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". |
int | TimeOut | 60 | Expiración deslizante de la sesión en minutos. |
bool | IsSecured | true | No 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:
| Tipo | Propiedad | Valor predeterminado | Descripción |
|---|---|---|---|
bool | IsWebFarm | false | Obsoleto — no tiene efecto. Publique el documento con DistributedDocumentPublisher.PublishAsync (o IDistributedPublishQueue.EnqueueAsync) y establezca FileShareConfig.RootPath en su lugar. |
string | WebFarmPath | "" | Obsoleto — no tiene efecto. Use FileShareConfig.RootPath en su lugar. |
bool | EditMode | false | Reservado para el flujo de trabajo del Editor distribuido por separado; deje false para el visor estándar. |
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~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Campo | Ejemplo | Significado |
|---|---|---|
Prefijo ^ | ^ | Diseño opcional de todas las esquinas. Sin él, se usa la colocación normal de la marca de agua. |
| Texto | Confidential | Texto renderizado en cada página. No debe estar vacío. |
| Color | Red | Color nombrado entendido por la capa de dibujo. |
| TamañoFuente | 24 | Tamaño de fuente; una entrada numérica no válida vuelve al valor predeterminado del renderizador. |
| NombreFuente | Verdana | Familia de fuente solicitada. Asegúrese de que esté instalada en el entorno de despliegue. |
| Opacidad | 80 | Valor de byte de 0 a 255. Debe analizarse correctamente. |
| Ángulo | -45 | Ángulo de rotación en grados; una entrada numérica no válida vuelve al valor predeterminado. |
El analizador espera exactamente seis campos después del ^ opcional. Una definición no válida se reemplaza por el fallback visible Invalid Watermark del SDK en lugar de desaparecer silenciosamente.
Decisión de licencia
| Estado de la licencia | Valor personalizado suministrado | Resultado renderizado |
|---|---|---|
| Licencia de visor pagado válida | No | Página limpia |
| Licencia de visor pagado válida | Sí | Marca de agua personalizada |
| Visor base Temporal/Demo activo | No | Página de visor base limpia |
| Visor base Temporal/Demo activo | Sí | 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álido | Cualquiera | Marca de agua de aplicación/evaluación; el valor personalizado no la sobrescribe |
| Renderizado de complemento bajo reglas de evaluación | Cualquiera | Marca 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 GIF animada 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 está en Guías → Anotaciones; la superficie es:
| Miembro | Propó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 |
Metadatos DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Devuelve los metadatos de etiquetas DICOM para sesiones abiertas a través del complemento DICOM; null para documentos que no son DICOM.
Ayudantes de recursos — ReferenceCss / ReferenceScripts
Emite 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 interfaz de usuario 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 (limitado por búsqueda), IncludeAnnotationCss (limitado por anotación).
ScriptConfig flags: 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), EmitFeatureFlags (predeterminado true: también escribe un script window.Doconut.features = { search, annotation, editor } en línea; configúralo a false bajo una Política de Seguridad de Contenido que bloquee scripts en línea).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))¿Fue útil esta página?