Visor Doconut es una biblioteca .NET para visualizar documentos diseñada para colocar PDF, Office, CAD, imágenes y otras familias de documentos compatibles dentro de una aplicación. Una integración sólida de Doconut no se trata de encontrar el fragmento más corto, sino de elegir un límite limpio entre su aplicación, el visor y el navegador.
El Centro de documentación de Doconut enlaza a las rutas de configuración mantenidas para los tipos de proyecto .NET compatibles. Use la guía que coincida con la versión instalada en su aplicación, y trate la página circundante, las verificaciones de identidad y el flujo de acceso como código de aplicación que su equipo posee.
Comience con el límite de integración
Existen tres formas comunes de colocar una vista previa de documento en un producto. La elección correcta depende de quién controla la navegación, la autenticación y el ciclo de vida del visor.
| Patrón | Mejor ajuste | Compensación principal |
|---|---|---|
| Vista de aplicación | Una página .NET que renderiza el visor junto a los controles del producto | Integración estrecha, pero el ciclo de vida de la página y del visor están acoplados |
| Iframe de propiedad de la aplicación | Un portal que necesita aislamiento entre la UI anfitriona y la ruta de vista previa | Límite claro, pero la comunicación debe diseñarse explícitamente |
| Componente de framework alrededor de una ruta del servidor | Una capa de React, Angular o Vue respaldada por una aplicación .NET | Composición front‑end familiar, con más estados del ciclo de vida que gestionar |
El patrón iframe no tiene que apuntar a una URL pública de documento. Puede apuntar a una ruta autenticada dentro de su propia aplicación. Esa ruta puede verificar el acceso y renderizar la página del visor sin exponer una ruta de almacenamiento a la página anfitriona.
Construya una superficie de vista previa estable y responsiva
No reconstruya el marcado del visor ni la inicialización a partir de un fragmento ilustrativo de blog. Doconut publica los archivos, pasos de middleware, espacios de nombres y la configuración del visor apropiados para cada línea .NET soportada. Por ejemplo, la guía oficial de configuración para .NET 6 o superior explica el middleware del servidor, el objeto visor, las opciones del documento, la configuración de renderizado y los activos cliente requeridos.
Utilice esos materiales versionados para crear el visor, y luego asigne a su región anfitriona un ancho y alto estables en su propio diseño. Reserve suficiente espacio antes de cargar para que la página circundante no salte, y pruebe la barra de herramientas y la primera página en los puntos de quiebre reales que soporta su producto.
Antes de comprometerse con una composición, compárela con las demostraciones en vivo de Doconut. Las demos cubren múltiples estilos de integración .NET y front‑end, incluido un ejemplo dedicado de iframe, y ayudan a distinguir un camino oficialmente soportado de un fragmento que parece plausible.
Mantenga las decisiones de acceso en el servidor
La página anfitriona nunca debe decidir si un usuario puede ver un documento. Antes de renderizar la ruta de vista previa, la aplicación debe:
- Autenticar la solicitud.
- Autorizar al usuario para el documento y el inquilino solicitados.
- Resolver el documento mediante un identificador controlado por el servidor.
- Abrirlo a través del visor solo después de que esas verificaciones pasen.
- Devolver un estado genérico de no encontrado o prohibido sin filtrar detalles de almacenamiento.
Un identificador opaco mejora la higiene de la URL, pero no es autorización. Aplique las mismas verificaciones a solicitudes de página, miniatura, búsqueda, anotación, exportación e impresión que exponga.
Decida cómo se comunican el anfitrión y el visor
Una vista de aplicación puede llamar a sus propios componentes directamente. Un iframe necesita un contrato más estrecho. Defina solo los eventos que el anfitrión realmente necesita, tales como:
- Vista previa lista
- Documento no pudo abrirse
- Página actual cambiada
- Sesión expirada
- Usuario solicitó cerrar la vista previa
Si usa postMessage, valide tanto event.origin como la forma del mensaje. No acepte orígenes comodín en producción, y nunca pase credenciales, ubicaciones de almacenamiento o contenido bruto del documento a través de los mensajes.
Trate las restricciones del navegador como defensa en profundidad
Un iframe no está aislado automáticamente. Un atributo sandbox puede reducir capacidades, pero un valor excesivamente estricto también puede romper scripts del visor, descargas o comportamientos de mismo origen. Comience con el conjunto de capacidades más pequeño documentado para su integración y pruébelo con su Política de Seguridad de Contenidos.
Revise también:
frame-ancestorsoX-Frame-Optionspara la ruta de vista previaframe-srcpara la página anfitriona- Comportamiento de cookies same‑site si el iframe requiere una sesión
- Política de referer para URLs que contengan identificadores de enrutamiento
- Cabeceras de caché para páginas que muestren material sensible
Estos controles pertenecen a la aplicación e infraestructura circundantes. Un componente de visor no puede elegir la política correcta para su arrendamiento y modelo de amenazas.
Diseñe estados de carga, error y expiración
Un rectángulo vacío no es un mensaje de error útil. Proporcione a la página anfitriona estados explícitos para fallos de autorización, entrada no soportada, archivos dañados, tiempos de espera y sesiones expiradas. Mantenga la redacción accionable sin revelar rutas internas o detalles de excepciones.
Para documentos extensos, conserve el contenedor del visor mientras se prepara la primera página. Si los usuarios pueden cambiar de documento sin abandonar la página, cancele solicitudes obsoletas y restablezca el título visible, el recuento de páginas y el foco antes de cargar el siguiente ítem.
Accesibilidad y comportamiento del teclado
Asigne a cada iframe un title útil. Haga que la vista previa sea accesible mediante el teclado, proporcione una forma visible de devolver el foco a la página anfitriona y no atrape el foco dentro de superposiciones personalizadas. Si el visor tiene sus propios atajos de teclado, documente los conflictos con los atajos usados por la capa de su producto.
Una alternativa accesible puede ofrecer una descarga controlada o una representación alternativa cuando sus reglas de negocio lo permitan. No añada un enlace público a un archivo solo como alternativa.
Lista de verificación práctica de validación
Antes del lanzamiento, verifique la ruta completa de la solicitud y no solo la carga inicial de la página:
- Un usuario autorizado puede abrir un documento permitido.
- Un usuario de otro inquilino no puede reutilizar la URL de vista previa.
- Las solicitudes directas a los puntos finales relacionados con el visor reciben las mismas verificaciones de autorización.
- Actualizar, navegar hacia atrás y la expiración de sesión generan estados comprensibles.
- La vista previa sigue siendo usable en los tamaños de viewport y niveles de zoom soportados.
- Los errores en la consola del navegador y las solicitudes de red fallidas son visibles en la monitorización.
- Los registros de almacenamiento y de aplicación no registran secretos ni URLs completas de documentos.
Conclusión
El embed de Doconut más mantenible es aquel con un contrato pequeño y explícito. Deje que Doconut maneje el rol de visualización de documentos descrito en su documentación versionada, mientras su aplicación posee la identidad, autorización, enrutamiento, retención, política del navegador y retroalimentación al usuario. Cuando esté listo para evaluar los ejemplos empaquetados localmente, use los recursos de descarga oficiales de Doconut en lugar de copiar código fuente de un artículo no relacionado.