Installazione

Aggiungi Doconut alla tua applicazione web .NET Framework 4.7.2

Doconut.NETFramework ospita il visualizzatore Doconut in un'applicazione ASP.NET classica su .NET Framework 4.7.2 — IIS o IIS Express, MVC 5 o Web Forms. L'installazione ha tre parti: il pacchetto NuGet, due registrazioni in Web.config e una chiamata in Global.asax. Questa pagina copre tutte e tre; Avvio rapido poi inserisce un documento in una pagina.

Requisiti

  • Il progetto web mira a .NET Framework 4.7.2 o versioni successive. Un progetto 4.7 non può consumare questo pacchetto; è necessario reindirizzarlo prima.
  • Il sito è in esecuzione nella pipeline integrata (impostazione predefinita per i pool di applicazioni IIS e IIS Express).

Questa pagina copre Doconut.NETFramework 26.9.0 e successive. Le versioni 26.8.0 e precedenti miravano a .NET Framework 4.7 con un'API diversa; quella linea è stata interrotta. L'aggiornamento di un'applicazione esistente oltre quel confine è trattato in Migrazione.

Installa il pacchetto

Dal Package Manager Console:

powershell
Install-Package Doconut.NETFramework

Oppure, in un progetto in stile SDK:

bash
dotnet add package Doconut.NETFramework

Il motore di rendering è incorporato nel pacchetto: non esiste un'assembly del motore separata da riferire, copiare o distribuire. Le funzionalità opzionali sono fornite come pacchetti autonomi — ad esempio Doconut.NETFramework.Converter e Doconut.NETFramework.Dicom — e ciascuno richiede una licenza che lo conceda (vedi Sistema di plugin).

Configura Web.config

Doconut gestisce due tipi di richieste, e IIS le instrada entrambe tramite Web.config:

  • DocImage.axd — la pagina del visualizzatore, miniatura, ricerca e endpoint di annotazione, servita da Doconut.DocImageHandler.
  • /doconut-res/* — gli script, i fogli di stile e le icone del visualizzatore, incorporati nell'assembly e serviti da Doconut.DoconutResourceModule.

Aggiungi entrambi, più le impostazioni da cui dipendono:

xml
<configuration>
  <system.web>
    <!-- MVC 5 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 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>

Ogni riga previene un errore che non genera eccezione:

  • verb="GET,HEAD,POST" — mantieni HEAD. Il visualizzatore invia una richiesta HEAD per la pagina 1 per rilevare immagini animate. Senza questo verbo, IIS risponde 404 prima che l'handler venga eseguito: i documenti vengono comunque visualizzati, ma il rilevamento delle animazioni non funziona mai e la console del browser si riempie di 404.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css e .png sembrano file statici, e IIS li consegnerebbe al gestore di file statici prima che il modulo di risorse li veda. Il risultato è un visualizzatore senza script o icone.
  • <globalization fileEncoding="utf-8"> — i file di pagina salvati come UTF-8 senza BOM vengono altrimenti letti con la pagina di codice ANSI del server, quindi ogni carattere non ASCII arriva al browser doppio codificato (un trattino lungo appare come —). Il file è corretto su disco, e la pagina dichiara ancora <meta charset="utf-8">.
  • L'assembly netstandard (MVC 5) — Razor compila le viste al primo accesso, con la propria lista di riferimenti che non include questa facciata. Una vista che esegue qualsiasi operazione dinamica oltre un semplice accesso a membro fallisce con CS0012 e restituisce un 500 vuoto, e solo le pagine che la attivano falliscono. L'errore del compilatore appare solo nel registro eventi di Windows (origine ASP.NET). Le applicazioni Web Forms non necessitano di questa riga.
  • Limiti di upload — ASP.NET legge l'intero corpo della richiesta prima che qualsiasi handler venga eseguito, quindi un upload superiore a questi limiti viene rifiutato da IIS con la sua pagina di errore. Mantieni maxRequestLength (kilobyte) e maxAllowedContentLength (byte) coerenti, e superiori al file più grande che i tuoi utenti aprono o caricano.

Altre due impostazioni sono importanti, e di solito sono già corrette:

  • Lo stato della sessione rimane attivo. Per impostazione predefinita una pagina è servita solo alla sessione ASP.NET che ha aperto il documento, quindi il sito non deve impostare <sessionState mode="Off" />. Vedi Sessioni e Sicurezza.
  • Redirect di binding. Mantieni i redirect di binding <runtime> che NuGet scrive in Web.config. In un progetto in stile SDK, copiali dal file generato bin\<YourApp>.dll.config, poiché ASP.NET classico legge i redirect solo da Web.config. Un redirect che indica una versione mancante in bin\ interrompe l'intera applicazione con un 500 vuoto all'avvio.

Registra Doconut in Global.asax

Non esiste un builder né una pipeline middleware in System.Web. Doconut viene composto una sola volta per processo worker da DoconutHost.Initialize in Application_Start, e rilasciato da DoconutHost.Shutdown in 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 crea i servizi, l'handler, il modulo delle risorse e il codice personalizzato. Il tuo codice li raggiunge tramite DoconutHost.Services (vedi DoconutHost). Solo la prima chiamata configura qualcosa; una seconda chiamata viene ignorata. In un'applicazione MVC, tieni anche i due percorsi Doconut fuori dal routing — la Guida rapida (Guida rapida) mostra il Application_Start completo.

Tutte le opzioni

DoconutOptions accetta le seguenti proprietà impostabili. Ognuna è opzionale.

PropertyDefaultDescription
UnsafeModefalseQuando false, DocImage.axd fornisce una pagina solo alla sessione ASP.NET che ha aperto il documento. Quando true, qualsiasi richiesta che porta il token viene servita. Lascialo false.
ShowDoconutInfofalseQuando true, una richiesta a DocImage.axd senza token restituisce un banner di versione invece di 404. Utile come verifica rapida; disattivalo in produzione.
ResourcesPath"/doconut-res"Dove il modulo delle risorse serve gli script, gli stili e le icone incorporati. Cambialo solo insieme al ResPath del visualizzatore e a eventuali IgnoreRoute MVC.
LicensePath""Percorso completo al file di licenza. Vuoto significa passare alla fonte successiva, poi alla scoperta automatica.
LicenseContent""Contenuto grezzo della licenza — da una variabile d'ambiente, un archivio segreto o un database.
LicenseStreamnullLicenza come stream, letta una sola volta all'avvio.
MiddlewarePath"/doconut"Non usato in questo pacchetto. Il punto finale della pagina è l'handler DocImage.axd dichiarato in Web.config, indipendentemente da questo valore. Viene comunque convalidato: deve iniziare con / e differire da ResourcesPath.
ResetLicensefalseNon usato in questo pacchetto. La licenza viene letta una sola volta, in DoconutHost.Initialize; ricicla il pool di applicazioni dopo aver sostituito un file di licenza.

Quando è impostata più di una fonte di licenza, LicenseStream prevale su LicenseContent, che prevale su LicensePath, che prevale sulla scoperta automatica — vedi Configurazione licenza.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // where the viewer's JS/CSS/images are served from
    options.UnsafeMode      = false;          // keep session security on
    options.ShowDoconutInfo = false;
});
// The page endpoint is not an option here: it is the DocImage.axd handler declared in Web.config.

Passi successivi

Questa pagina è stata utile?