Instalación

Agregar Doconut a su aplicación web .NET Framework 4.7.2

Doconut.NETFramework aloja el visor Doconut en una aplicación clásica ASP.NET sobre .NET Framework 4.7.2 — IIS o IIS Express, MVC 5 o Web Forms. La configuración tiene tres partes: el paquete NuGet, dos registros en Web.config y una llamada en Global.asax. Esta página cubre las tres; Inicio rápido luego coloca un documento en una página.

Requisitos

  • El proyecto web tiene como objetivo .NET Framework 4.7.2 o posterior. Un proyecto 4.7 no puede consumir este paquete; vuelva a apuntar primero.
  • El sitio se ejecuta en la tubería integrada (el valor predeterminado para los grupos de aplicaciones de IIS e IIS Express).
  • El servidor ejecuta Windows. El paquete es solo para Windows.

Esta página cubre Doconut.NETFramework 26.9.0 y posteriores. Las versiones 26.8.0 y anteriores apuntaban a .NET Framework 4.7 con una API diferente; esa línea está descontinuada. Actualizar una aplicación existente a través de ese límite se cubre en Migración.

Instalar el paquete

Desde la consola del Administrador de paquetes:

powershell
Install-Package Doconut.NETFramework

O, en un proyecto de estilo SDK:

bash
dotnet add package Doconut.NETFramework

Los comandos sin versión instalan la última versión estable. Para fijar la versión que describe esta documentación, pase la versión:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

El motor de renderizado está incrustado en el paquete: no hay un ensamblado de motor separado para referenciar, copiar o desplegar. Las capacidades opcionales se entregan como paquetes propios — por ejemplo Doconut.NETFramework.Converter y Doconut.NETFramework.Dicom — y cada una necesita una licencia que la otorgue (ver Sistema de complementos).

Configurar Web.config

Doconut sirve dos tipos de solicitud, y IIS enruta ambos a través de Web.config:

  • DocImage.axd — la página del visor, miniatura, búsqueda y punto final de anotaciones, servidos por Doconut.DocImageHandler.
  • /doconut-res/* — los propios scripts, hojas de estilo e íconos del visor, incrustados en el ensamblado y servidos por Doconut.DoconutResourceModule.

Agregue ambos, más la configuración de la que dependen:

xml
<configuration>
  <system.web>
    <!-- Solo MVC 5: Razor compila vistas en tiempo de ejecución y necesita la fachada netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength está en KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Leer archivos .cshtml y .aspx como UTF-8, no como la página de códigos ANSI del servidor. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength está en BYTES: los mismos 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

Cada línea evita una falla que no genera excepción:

  • verb="GET,HEAD,POST" — mantenga HEAD. El visor envía una solicitud HEAD para la página 1 para detectar imágenes animadas. Sin el verbo, IIS responde 404 antes de que el controlador se ejecute: los documentos aún se muestran, pero la detección de animación nunca funciona y la consola del navegador se llena de 404.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css y .png parecen archivos estáticos, e IIS los entregaría a su controlador de archivos estáticos antes de que el módulo de recursos los vea. El resultado es un visor sin scripts ni íconos.
  • <globalization fileEncoding="utf-8"> — los archivos de página guardados como UTF-8 sin marca de orden de bytes se leen con la página de códigos ANSI del servidor, por lo que cada carácter no ASCII llega al navegador doblemente codificado (un guión largo se muestra como —). El archivo es correcto en disco, y la página aún declara <meta charset="utf-8">.
  • El ensamblado netstandard (MVC 5) — Razor compila vistas cuando se solicitan por primera vez, con su propia lista de referencias que no incluye esta fachada. Una vista que haga algo dinámico más allá de un simple acceso a miembro falla con CS0012 y devuelve un 500 vacío, y solo las páginas que lo disparan fallan. El error del compilador aparece solo en el registro de eventos de Windows (fuente ASP.NET). Las aplicaciones Web Forms no necesitan esta línea.
  • Límites de carga — ASP.NET lee todo el cuerpo de la solicitud antes de que cualquier controlador se ejecute, por lo que una carga que supere estos límites es rechazada por IIS con su propia página de error. Mantenga maxRequestLength (kilobytes) y maxAllowedContentLength (bytes) alineados, y por encima del archivo más grande que sus usuarios abran o carguen.

Dos configuraciones más son importantes, y ambas suelen estar correctas ya:

  • El estado de sesión permanece activo. Por defecto una página se sirve solo a la sesión ASP.NET que abrió el documento, por lo que el sitio no debe establecer <sessionState mode="Off" />. Ver Sesiones y seguridad.
  • Redirecciones de enlace. Mantenga las redirecciones de enlace <runtime> que NuGet escribe en Web.config. En un proyecto de estilo SDK, cópielas del bin\<YourApp>.dll.config generado, porque el ASP.NET clásico solo lee redirecciones de Web.config. Una redirección que nombre una versión ausente de bin\ detiene toda la aplicación con un 500 vacío al iniciar.

Registrar Doconut en Global.asax

No hay un constructor ni una canalización de middleware en System.Web. Doconut se compone una vez por proceso de trabajo mediante DoconutHost.Initialize en Application_Start, y se libera mediante DoconutHost.Shutdown en Application_End:

csharp
// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize construye los servicios del manejador, el módulo de recursos y el uso de su propio código. Su código los alcanza a través de DoconutHost.Services (ver DoconutHost). Sólo la primera llamada configura algo; una segunda llamada se ignora. En una aplicación MVC, también mantenga los dos caminos de Doconut fuera del enrutamiento — Quick Start muestra el Application_Start completo.

Todas las opciones

DoconutOptions acepta el siguiente conjunto de propiedades configurables. Cada una es opcional.

PropiedadPredeterminadoDescripción
UnsafeModefalseCuando false, DocImage.axd sirve una página solo a la sesión ASP.NET que abrió el documento. Cuando true, se sirve cualquier solicitud que lleve el token. Déjelo false.
ShowDoconutInfofalseCuando true, una solicitud DocImage.axd sin token responde con una pancarta de versión en lugar de 404. Útil como una verificación rápida; déjelo desactivado en producción.
ResourcesPath"/doconut-res"Dónde el módulo de recursos sirve los scripts, estilos e íconos incrustados. Cambie esto solo junto con el ResPath del visor y cualquier IgnoreRoute de MVC.
LicensePath""Ruta completa al archivo de licencia. Vacío significa pasar al siguiente origen, luego al descubrimiento automático.
LicenseContent""Contenido bruto de la licencia — de una variable de entorno, un almacén secreto o una base de datos.
LicenseStreamnullLicencia como flujo, leída una vez al iniciar.
MiddlewarePath"/doconut"No se usa en este paquete. El punto final de la página es el manejador DocImage.axd declarado en Web.config, sea lo que sea que esté configurado. Aún se valida: debe comenzar con / y diferir de ResourcesPath.
ResetLicensefalseNo se usa en este paquete. La licencia se lee una vez, en DoconutHost.Initialize; recicle el grupo de aplicaciones después de reemplazar un archivo de licencia.
MaxConcurrentEditorSessions200Número máximo de sesiones de editor en vivo (documentos abiertos con DocOptions.EditMode). Por encima de este, la sesión de editor inactiva menos recientemente usada se cierra. Las sesiones normales del visor nunca se cuentan. 0 o un valor negativo significa sin límite.
EditorSnapshotEveryOps50Con la persistencia del editor habilitada (AddDoconutEditorPersistence), capture una instantánea del documento en vivo cada N cambios registrados. 0 o un valor negativo nunca captura instantáneas durante la sesión. No tiene efecto cuando la persistencia está deshabilitada.

Cuando se establece más de una fuente de licencia, LicenseStream prevalece sobre LicenseContent, que prevalece sobre LicensePath, que prevalece sobre el descubrimiento automático — ver License Setup.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // de donde se sirven los JS/CSS/images del visor
    options.UnsafeMode      = false;          // mantener la seguridad de la sesión activada
    options.ShowDoconutInfo = false;
});
// El punto final de la página no es una opción aquí: es el controlador DocImage.axd declarado en Web.config.

Próximos pasos

  • Quick Start — abra un documento y rinda en el navegador, en MVC 5 o Web Forms.
  • License Setup — donde Doconut busca su archivo de licencia.

¿Fue útil esta página?