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.
| Sobrecarga | Usar 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 |
// 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 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 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
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
| Miembro | Significado |
|---|---|
bool IsSearchEnabled | La licencia actual otorga Search |
bool IsAnnotationEnabled | La 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):
| 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. Observe la capitalización — la biblioteca anterior lo escribía como IsWebfarm. |
string | WebFarmPath | "" | Obsoleto — no tiene efecto. Use FileShareConfig.RootPath, como se describe en Despliegues distribuidos. Anteriormente escrito como WebfarmPath. |
bool | EditMode | false | Reservado 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~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 |
|---|---|---|
Inicial ^ | ^ | 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 con nombre entendido por la capa de dibujo. |
| TamañoFuente | 24 | Tamaño de fuente; una entrada numérica inválida recurre 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 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 licencia | Valor personalizado suministrado | Resultado renderizado |
|---|---|---|
| Licencia de visor pagada válida | No | Página limpia |
| Licencia de visor pagada 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 plugin 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 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:
| 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 |
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
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.
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).
@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?