Instalace

Přidejte Doconut do vaší webové aplikace .NET Framework 4.7.2

Doconut.NETFramework hostuje Doconut viewer v klasické aplikaci ASP.NET na .NET Framework 4.7.2 — IIS nebo IIS Express, MVC 5 nebo Web Forms. Instalace má tři části: NuGet balíček, dvě registrace v Web.config a jedno volání v Global.asax. Tato stránka pokrývá všechny tři; Rychlý start pak umístí dokument na stránku.

Požadavky

  • Webový projekt cílí na .NET Framework 4.7.2 nebo novější. Projekt 4.7 nemůže tento balíček použít; nejprve jej přesměřujte.
  • Stránka běží v integrovaném pipeline (výchozí nastavení pro aplikační pooly IIS a IIS Express).
  • Server běží na Windows. Balíček je určen pouze pro Windows.

Tato stránka pokrývá Doconut.NETFramework 26.9.0 a novější. Verze 26.8.0 a starší cílily .NET Framework 4.7 s odlišným API; tato řada je ukončena. Aktualizace existující aplikace přes tuto hranici je popsána v Migrace.

Instalace balíčku

Z Package Manager Console:

powershell
Install-Package Doconut.NETFramework

Nebo v projektu typu SDK:

bash
dotnet add package Doconut.NETFramework

Příkazy bez verze nainstalují nejnovější stabilní verzi. Pro upřesnění verze, kterou tato dokumentace popisuje, zadejte verzi:

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

Renderovací engine je součástí balíčku: neexistuje samostatná sestava engine, kterou by bylo nutné odkazovat, kopírovat nebo nasazovat. Volitelné funkce jsou dodávány jako samostatné balíčky — například Doconut.NETFramework.Converter a Doconut.NETFramework.Dicom — a každá z nich vyžaduje licenci, která ji povoluje (viz Systém pluginů).

Konfigurace Web.config

Doconut obsluhuje dva typy požadavků a IIS je směruje oba přes Web.config:

  • DocImage.axd — stránka vieweru, miniatura, vyhledávání a koncový bod anotací, poskytované Doconut.DocImageHandler.
  • /doconut-res/* — vlastní skripty, styly a ikony vieweru, vložené do sestavy a poskytované Doconut.DoconutResourceModule.

Přidejte oba a také nastavení, na kterých závisí:

xml
<configuration>
  <system.web>
    <!-- Pouze MVC 5: Razor kompiluje pohledy za běhu a potřebuje netstandard fasádu. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength je v KILOBYTECH: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Čtěte soubory .cshtml a .aspx jako UTF-8, ne jako ANSI kódovou stránku serveru. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength je v BYTÉCH: stejných 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>

Každý řádek zabraňuje selhání, které nevyvolá výjimku:

  • verb="GET,HEAD,POST" — zachovejte HEAD. Viewer odesílá HEAD požadavek na stránku 1 pro detekci animovaných obrázků. Bez tohoto slovesa IIS odpoví 404 před spuštěním handleru: dokumenty se stále zobrazí, ale detekce animací nefunguje a konzole prohlížeče se zaplní 404 chybami.

  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css a .png vypadají jako statické soubory a IIS by je předal svému handleru pro statické soubory dříve, než je zachytí modul zdrojů. Výsledkem je viewer bez skriptů a ikon.

  • <globalization fileEncoding="utf-8"> — soubory stránek uložené jako UTF-8 bez značky pořadí bajtů jsou jinak čteny pomocí ANSI kódové stránky serveru, takže každý ne-ASCII znak je do prohlížeče předán dvojitě zakódovaný (em dash se zobrazí jako —). Soubor je na disku v pořádku a stránka stále deklaruje <meta charset="utf-8">.

  • Sestava netstandard (MVC 5) — Razor kompiluje pohledy při jejich prvním požadavku s vlastní seznamem referencí, který tuto fasádu neobsahuje. Pohled, který dělá něco dynamického nad rámec prostého přístupu k členu, selže s CS0012 a vrátí prázdný 500, a selžou jen stránky, které ho spustí. Chyba kompilátoru se objeví jen v protokolu událostí Windows (zdroj ASP.NET). Aplikace Web Forms tuto řádku nepotřebují.

  • Limity nahrávání — ASP.NET načte celé tělo požadavku před spuštěním jakéhokoli handleru, takže nahrání přesahující tyto limity je odmítnuto IIS s vlastní chybovou stránkou. Udržujte maxRequestLength (kilobajty) a maxAllowedContentLength (bajty) v souladu a nad největším souborem, který uživatelé otevírají nebo nahrávají.

  • Stav relace zůstává zapnutý. Ve výchozím nastavení je stránka podávána jen ASP.NET relaci, která dokument otevřela, takže stránka nesmí nastavit <sessionState mode="Off" />. Viz Relace a zabezpečení.

  • Přesměrování vazeb. Zachovejte přesměrování vazeb <runtime>, která NuGet zapisuje do Web.config. V projektu typu SDK je zkopírujte z vygenerovaného bin\<YourApp>.dll.config, protože klasické ASP.NET čte přesměrování jen z Web.config. Přesměrování, které uvádí verzi chybějící v bin\, zastaví celou aplikaci s prázdným 500 při spuštění.

Zaregistrovat Doconut v Global.asax

V System.Web neexistuje žádný builder ani middleware pipeline. Doconut je složen jednou na pracovní proces pomocí DoconutHost.Initialize v Application_Start a uvolněn pomocí DoconutHost.Shutdown v 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 vytváří služby, handler, modul zdrojů a používání vašeho vlastního kódu. Váš kód k nim přistupuje přes DoconutHost.Services (viz DoconutHost). Pouze první volání něco nakonfiguruje; druhé volání je ignorováno. V MVC aplikaci také nechte dvě cesty Doconut mimo směrování — Quick Start ukazuje kompletní Application_Start.

Všechny možnosti

DoconutOptions přijímá následující nastavitelná vlastnosti. Každá je volitelná.

VlastnostVýchozíPopis
UnsafeModefalseKdyž false, DocImage.axd poskytuje stránku pouze ASP.NET relaci, která dokument otevřela. Když true, je obsloužena jakákoli žádost nesoucí token. Nechte to false.
ShowDoconutInfofalseKdyž true, požadavek DocImage.axd bez token odpovídá bannerem verze místo 404. Užitečné jako rychlá kontrola; v produkci nechte vypnuté.
ResourcesPath"/doconut-res"Kde modul zdrojů poskytuje vložené skripty, styly a ikony. Změňte to pouze společně s ResPath vieweru a jakýmkoli MVC IgnoreRoute.
LicensePath""Úplná cesta k souboru licence. Prázdná hodnota znamená přechod na další zdroj, poté na automatické vyhledání.
LicenseContent""Surový obsah licence — z proměnné prostředí, tajného úložiště nebo databáze.
LicenseStreamnullLicence jako stream, načtená jednou při spuštění.
MiddlewarePath"/doconut"Není v tomto balíčku používáno. Koncový bod stránky je handler DocImage.axd deklarovaný v Web.config, ať je nastavený jakkoli. Stále se validuje: musí začínat / a lišit se od ResourcesPath.
ResetLicensefalseNení v tomto balíčku používáno. Licence je načtena jednou, v DoconutHost.Initialize; po výměně souboru licence recyklujte aplikační pool.
MaxConcurrentEditorSessions200Maximální počet aktivních editorových sezení (dokumenty otevřené pomocí DocOptions.EditMode). Při překročení je uzavřeno nejméně nedávno použité nečinné editorové sezení. Normální sezení vieweru se nepočítají. 0 nebo záporná hodnota znamená neomezený limit.
EditorSnapshotEveryOps50Při povolené perzistenci editoru (AddDoconutEditorPersistence) se po každých N zaznamenaných změnách vytvoří snímek živého dokumentu. 0 nebo záporná hodnota nikdy neprovádí snímky během sezení. Nemá žádný efekt, když je perzistence vypnuta.

Když je nastaveno více než jedno zdroj licence, LicenseStream má přednost před LicenseContent, který má přednost před LicensePath, který má přednost před automatickým vyhledáním — viz License Setup.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // odkud jsou servírovány JS/CSS/obrázky prohlížeče
    options.UnsafeMode      = false;          // zachovat zabezpečení relace
    options.ShowDoconutInfo = false;
});
// Koncový bod stránky zde není možností: jedná se o handler DocImage.axd deklarovaný v souboru Web.config.

Další kroky

  • Rychlý start — otevřete dokument a vykreslete jej v prohlížeči, v MVC 5 nebo Web Forms.
  • Nastavení licence — kde Doconut hledá váš soubor licence.

Byla tato stránka užitečná?