Installazione

Aggiungi Doconut alla tua applicazione web .NET Framework 4.7.2

Doconut.NETFramework ospita il visualizzatore Doconut in una classica applicazione ASP.NET 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; reindirizzalo prima.
  • Il sito gira nella integrated pipeline (l'impostazione predefinita per i pool di applicazioni IIS e IIS Express).
  • Il server gira su Windows. Il pacchetto è disponibile solo per Windows.

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 limite è trattato in Migrazione.

Installa il pacchetto

Dalla console di Package Manager:

powershell
Install-Package Doconut.NETFramework

Oppure, in un progetto in stile SDK:

bash
dotnet add package Doconut.NETFramework

I comandi senza versione installano l'ultima versione stabile. Per fissare la versione descritta in questa documentazione, passa la versione:

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

Il motore di rendering è incorporato nel pacchetto: non esiste un'assembly del motore separata da riferire, copiare o distribuire. Le funzionalità opzionali vengono fornite come pacchetti separati — ad esempio Doconut.NETFramework.Converter e Doconut.NETFramework.Dicom — e ognuna richiede una licenza che la 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>
    <!-- Solo MVC 5: Razor compila le viste a tempo di esecuzione e richiede la facciata netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength è in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Leggi i file .cshtml e .aspx come UTF-8, non come la pagina di codice ANSI del server. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength è in BYTES: gli stessi 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 il verbo, IIS risponde 404 prima che l'handler venga eseguito: i documenti vengono comunque mostrati, ma il rilevamento dell'animazione 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 passerebbe al suo handler di file statici prima che il modulo risorsa li veda. Il risultato è un visualizzatore senza script o icone.
  • <globalization fileEncoding="utf-8"> — i file di pagina salvati come UTF-8 senza byte-order mark vengono altrimenti letti con la pagina di codice ANSI del server, così ogni carattere non ASCII arriva al browser doppiamente 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 sua lista di riferimenti che non include questa facciata. Una vista che fa qualcosa di dinamico oltre un semplice accesso a un 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 (fonte ASP.NET). Le applicazioni Web Forms non hanno bisogno di questa riga.
  • Limiti di upload — ASP.NET legge l'intero corpo della richiesta prima che qualsiasi handler venga eseguito, quindi un upload sopra questi limiti viene rifiutato da IIS con la sua pagina di errore. Mantieni maxRequestLength (kilobyte) e maxAllowedContentLength (byte) in linea, e al di sopra del 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 bin\<YourApp>.dll.config generato, perché il classico ASP.NET legge i redirect solo da Web.config. Un redirect che nomina una versione mancante da bin\ blocca 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 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 costruisce i servizi, l'handler, il modulo risorsa e l'uso del tuo codice. 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 — Guida rapida mostra il completo Application_Start.

Tutte le opzioni

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

ProprietàPredefinitoDescrizione
UnsafeModefalseQuando false, DocImage.axd serve 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 DocImage.axd senza token risponde con un banner di versione invece di 404. Utile come verifica rapida; disattivalo in produzione.
ResourcesPath"/doconut-res"Dove il modulo risorsa serve gli script, gli stili e le icone incorporati. Cambialo solo insieme al ResPath del visualizzatore e a qualsiasi 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 volta all'avvio.
MiddlewarePath"/doconut"Non usato in questo pacchetto. L'endpoint della pagina è l'handler DocImage.axd dichiarato in Web.config, qualunque sia impostato. Viene comunque convalidato: deve iniziare con / e differire da ResourcesPath.
ResetLicensefalseNon usato in questo pacchetto. La licenza viene letta una volta, in DoconutHost.Initialize; ricicla il pool dell'applicazione dopo aver sostituito un file di licenza.
MaxConcurrentEditorSessions200Numero massimo di sessioni editor attive (documenti aperti con DocOptions.EditMode). Superato questo limite, la sessione editor inattiva meno recentemente usata viene chiusa. Le sessioni normali del visualizzatore non vengono mai contate. 0 o un valore negativo significa nessun limite.
EditorSnapshotEveryOps50Con la persistenza dell'editor abilitata (AddDoconutEditorPersistence), crea uno snapshot del documento attivo ogni N modifiche registrate. 0 o un valore negativo non crea mai snapshot a metà sessione. Nessun effetto quando la persistenza è disabilitata.

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"; // da dove vengono serviti i JS/CSS/immagini del visualizzatore
    options.UnsafeMode      = false;          // mantieni attiva la sicurezza della sessione
    options.ShowDoconutInfo = false;
});
// L'endpoint della pagina non è un'opzione qui: è il gestore DocImage.axd dichiarato in Web.config.

Prossimi passi

Questa pagina è stata utile?