Instalacja

Doconut.NETFramework hostuje przeglądarkę Doconut w klasycznej aplikacji ASP.NET na .NET Framework 4.7.2 — IIS lub IIS Express, MVC 5 lub Web Forms. Konfiguracja składa się z trzech części: pakietu NuGet, dwóch rejestracji w Web.config oraz jednego wywołania w Global.asax. Ta strona opisuje wszystkie trzy; Szybki start następnie umieszcza dokument na stronie.

Wymagania

• Projekt internetowy docelowo używa .NET Framework 4.7.2 lub nowszego. Projekt 4.7 nie może korzystać z tego pakietu; najpierw zmień docelową wersję.
• Strona działa w zintegrowanym potoku (domyślnie dla pul aplikacji IIS i IIS Express).

Ta strona opisuje Doconut.NETFramework 26.9.0 i nowsze. Wersje 26.8.0 i wcześniejsze celowały w .NET Framework 4.7 z innym API; ta linia została wycofana. Aktualizacja istniejącej aplikacji przekraczającej tę granicę jest opisana w Migracji.

Zainstaluj pakiet

Z konsoli Menedżera Pakietów:

Install-Package Doconut.NETFramework

Lub w projekcie w stylu SDK:

dotnet add package Doconut.NETFramework

Silnik renderujący jest osadzony w pakiecie: nie ma osobnego zestawu silnika do odwoływania, kopiowania ani wdrażania. Opcjonalne możliwości są dostarczane jako osobne pakiety — na przykład Doconut.NETFramework.Converter i Doconut.NETFramework.Dicom — i każdy z nich wymaga licencji (zobacz System wtyczek).

Skonfiguruj Web.config

Doconut obsługuje dwa rodzaje żądań, a IIS kieruje oba przez Web.config:

• DocImage.axd — strona przeglądarki, miniaturka, wyszukiwanie i punkt końcowy adnotacji, obsługiwane przez Doconut.DocImageHandler.
• /doconut-res/* — własne skrypty, arkusze stylów i ikony przeglądarki, osadzone w zestawie i obsługiwane przez Doconut.DoconutResourceModule.

Dodaj oba, wraz z zależnymi ustawieniami:

<configuration>
  <system.web>
    <!-- Tylko MVC 5: Razor kompiluje widoki w czasie wykonywania i wymaga fasady netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength jest podany w KILOBAJTACH: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Odczytuj pliki .cshtml i .aspx jako UTF-8, a nie jako kodowanie ANSI serwera. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength jest podany w BAJTACH: te 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żda linia zapobiega awarii, która nie generuje wyjątku:

• verb="GET,HEAD,POST" — zachowaj HEAD. Przeglądarka wysyła żądanie HEAD dla strony 1, aby wykryć animowane obrazy. Bez tego atrybutu IIS zwraca 404 zanim uruchomi się obsługa: dokumenty nadal się wyświetlają, ale wykrywanie animacji nie działa i konsola przeglądarki wypełnia się 404.
• runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css i .png wyglądają jak pliki statyczne i IIS przekazałby je do swojego obsługiwacza plików statycznych, zanim moduł zasobów je zobaczy. Efektem jest przeglądarka bez skryptów i ikon.
• <globalization fileEncoding="utf-8"> — pliki stron zapisane jako UTF-8 bez znacznika kolejności bajtów są w przeciwnym razie odczytywane przy użyciu kodowania ANSI serwera, więc każdy znak nie‑ASCII dociera do przeglądarki podwójnie zakodowany (np. myślnik em wyświetla się jako —). Plik jest poprawny na dysku, a strona nadal deklaruje <meta charset="utf-8">.
• Zestaw netstandard (MVC 5) — Razor kompiluje widoki przy pierwszym żądaniu, używając własnej listy referencji, która nie zawiera tej fasady. Widok, który wykonuje jakąkolwiek dynamikę poza prostym dostępem do pola, kończy się błędem CS0012 i zwraca pusty 500; tylko strony, które to wywołują, przestają działać. Błąd kompilatora pojawia się wyłącznie w dzienniku zdarzeń Windows (źródło ASP.NET). Aplikacje Web Forms nie potrzebują tej linii.
• Limity przesyłania — ASP.NET odczytuje całe ciało żądania przed uruchomieniem jakiejkolwiek obsługi, więc przesyłanie powyżej tych limitów jest odrzucane przez IIS z własną stroną błędu. Utrzymuj maxRequestLength (kilobajty) i maxAllowedContentLength (bajty) w zgodzie oraz powyżej największego pliku, który użytkownicy otwierają lub przesyłają.

Dwa dodatkowe ustawienia mają znaczenie i zazwyczaj są już prawidłowe:

• Stan sesji pozostaje włączony. Domyślnie strona jest serwowana tylko do sesji ASP.NET, która otworzyła dokument, więc witryna nie powinna ustawiać <sessionState mode="Off" />. Zobacz Sesje i bezpieczeństwo.
• Przekierowania wiązań. Zachowaj przekierowania wiązań <runtime> zapisane przez NuGet w Web.config. W projekcie w stylu SDK skopiuj je z wygenerowanego pliku bin\<YourApp>.dll.config, ponieważ klasyczny ASP.NET odczytuje przekierowania wyłącznie z Web.config. Przekierowanie wskazujące wersję nieobecną w bin\ zatrzymuje całą aplikację z pustym 500 przy uruchamianiu.

Zarejestruj Doconut w Global.asax

W System.Web nie ma buildera ani potoku middleware. Doconut jest tworzony raz na proces roboczy przez DoconutHost.Initialize w Application_Start i zwalniany przez DoconutHost.Shutdown w 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 buduje usługi, które używa obsługa, moduł zasobów oraz Twój własny kod. Twój kod uzyskuje do nich dostęp przez DoconutHost.Services (zobacz DoconutHost). Tylko pierwsze wywołanie konfiguruje cokolwiek; drugie wywołanie jest ignorowane. W aplikacji MVC należy również wykluczyć dwa ścieżki Doconut z routingu — Szybki start pokazuje pełny Application_Start.

Wszystkie opcje

DoconutOptions akceptuje następujące konfigurowalne właściwości. Każda z nich jest opcjonalna.

Gdy ustawiono więcej niż jedno źródło licencji, LicenseStream ma pierwszeństwo przed LicenseContent, które ma pierwszeństwo przed LicensePath, które ma pierwszeństwo przed automatycznym wykrywaniem — zobacz Konfiguracja licencji.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // gdzie serwowane są skrypty/ style/ obrazy przeglądarki
    options.UnsafeMode      = false;          // zachowaj bezpieczeństwo sesji
    options.ShowDoconutInfo = false;
});
// Punkt końcowy strony nie jest tutaj opcją: jest to obsługa DocImage.axd zadeklarowana w Web.config.

Kolejne kroki

• Szybki start — otwórz dokument i wyświetl go w przeglądarce, w MVC 5 lub Web Forms.
• Konfiguracja licencji — gdzie Doconut szuka pliku licencji.