Instalace

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: balíček NuGet, 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řecilte.
• Stránka běží v integrovaném pipeline (výchozí nastavení pro aplikační pooly IIS a IIS Express).

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 linie je ukončena. Aktualizace existující aplikace přes tuto hranici je popsána v Migraci.

Instalace balíčku

Z konzole Package Manager:

Install-Package Doconut.NETFramework

Nebo v projektu typu SDK:

dotnet add package Doconut.NETFramework

Renderovací engine je zabudován v balíčku: neexistuje samostatný engine assembly, který byste museli 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á mu to umožňuje (viz Systém pluginů).

Konfigurace Web.config

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

• DocImage.axd — stránka prohlížeče, miniatury, vyhledávání a koncový bod anotací, obsluhovaný Doconut.DocImageHandler.
• /doconut-res/* — vlastní skripty, stylové soubory a ikony prohlížeče, vložené do assembly a obsluhované Doconut.DoconutResourceModule.

Přidejte oba spolu s nastaveními, na nichž závisí:

<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>

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

• verb="GET,HEAD,POST" — ponechte HEAD. Prohlížeč odesílá požadavek HEAD na stránku 1, aby zjistil animované obrázky. Bez tohoto slovesa IIS odpoví 404 před spuštěním handleru: dokumenty se stále zobrazí, ale detekce animace nikdy nefunguje a konzole prohlížeče se zaplní 404.
• 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 prohlížeč bez skriptů a ikon.
• <globalization fileEncoding="utf-8"> — soubory stránek uložené jako UTF‑8 bez BOM jsou jinak čteny s ANSI kódovou stránkou serveru, takže každý ne‑ASCII znak dorazí do prohlížeče dvojitě zakódovaný (em dash se zobrazí jako —). Soubor je na disku správný a stránka stále deklaruje <meta charset="utf-8">.
• Assemblie netstandard (MVC 5) — Razor kompiluje pohledy při první žádosti, 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é to vyvolají. 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 tím, než se spustí jakýkoli handler, takže nahrání přesahující tyto limity je IIS odmítne se svou chybovou stránkou. Udržujte maxRequestLength (kilobajty) a maxAllowedContentLength (bajty) v souladu a nad největší soubor, který uživatelé otevírají nebo nahrávají.

Další dvě nastavení jsou důležitá a obvykle jsou již správně nastavena:

• 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í.

Zaregistrujte Doconut v Global.asax

V System.Web neexistuje žádný builder ani middleware pipeline. Doconut je sestaven jednou na pracovní proces pomocí DoconutHost.Initialize v Application_Start a uvolněn pomocí DoconutHost.Shutdown v Application_End:

// 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 vytvoří služby, které používá handler, modul zdrojů a váš vlastní kód. 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 aplikaci MVC také udržujte dvě cesty Doconut mimo směrování — Rychlý start ukazuje kompletní Application_Start.

Všechny možnosti

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

Když je nastaveno více 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 Nastavení licence.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // kde jsou servírovány JS/CSS/obrázky prohlížeče
    options.UnsafeMode      = false;          // zachovat zabezpečení relace
    options.ShowDoconutInfo = false;
});
// Cílový bod stránky zde není volitelný: je to 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.