Instalacja

Dodaj Doconut do swojej aplikacji internetowej .NET Framework 4.7.2

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. Instalacja 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).
  • Serwer działa na Windows. Pakiet jest dostępny wyłącznie dla Windows.

Ta strona opisuje Doconut.NETFramework 26.9.0 i późniejsze. Wersje 26.8.0 i wcześniejsze były skierowane do .NET Framework 4.7 z innym API; ta linia została wycofana. Aktualizacja istniejącej aplikacji przekraczającej tę granicę jest opisana w Migracja.

Zainstaluj pakiet

Z konsoli Menedżera Pakietów:

powershell
Install-Package Doconut.NETFramework

Lub w projekcie w stylu SDK:

bash
dotnet add package Doconut.NETFramework

Polecenia bez wersji instalują najnowsze stabilne wydanie. Aby przypiąć wersję opisaną w tej dokumentacji, podaj wersję:

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

Silnik renderujący jest wbudowany w pakiet: nie ma osobnego zestawu silnika do odwoływania się, 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, która je udziela (zobacz System wtyczek).

Konfiguracja 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, plus ustawienia, od których zależą:

xml
<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 w KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Odczytuj pliki .cshtml i .aspx jako UTF-8, nie jako ANSI code page serwera. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength jest w BYTES: 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 czasownika IIS odpowiada 404 przed uruchomieniem obsługi: dokumenty nadal się wyświetlają, ale wykrywanie animacji nigdy nie działa i konsola przeglądarki wypełnia się błędami 404.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css i .png wyglądają jak pliki statyczne, a IIS przekazałby je swojemu obsługującemu pliki statyczne przed modułem zasobów. 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 (em dash 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 odwołań, która nie zawiera tej fasady. Widok, który robi cokolwiek dynamicznego poza prostym dostępem do pola, wtedy kończy się błędem CS0012 i zwraca pusty 500, a tylko strony, które go wywołują, zawodzą. Błąd kompilatora pojawia się tylko 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ł powyżej tych limitów jest odrzucany przez IIS z własną stroną błędu. Zachowaj 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>, które NuGet zapisuje w Web.config. W projekcie w stylu SDK skopiuj je z wygenerowanego bin\<YourApp>.dll.config, ponieważ klasyczny ASP.NET odczytuje przekierowania tylko z Web.config. Przekierowanie, które wskazuje 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:

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 buduje usługi, handler, moduł zasobów oraz 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, również trzymaj dwie ścieżki Doconut poza routingiem — 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.

WłaściwośćDomyślnieOpis
UnsafeModefalseGdy false, DocImage.axd serwuje stronę tylko do sesji ASP.NET, która otworzyła dokument. Gdy true, obsługiwane jest każde żądanie niosące token. Pozostaw false.
ShowDoconutInfofalseGdy true, żądanie DocImage.axd bez token zwraca baner wersji zamiast 404. Przydatne jako szybki test; pozostaw wyłączone w produkcji.
ResourcesPath"/doconut-res"Gdzie moduł zasobów serwuje osadzone skrypty, style i ikony. Zmieniaj to tylko razem z ResPath przeglądarki i dowolnym MVC IgnoreRoute.
LicensePath""Pełna ścieżka do pliku licencji. Pusty oznacza przejście do następnego źródła, a potem do automatycznego wykrywania.
LicenseContent""Surowa zawartość licencji — z zmiennej środowiskowej, magazynu tajemnic lub bazy danych.
LicenseStreamnullLicencja jako strumień, odczytywana raz przy uruchomieniu.
MiddlewarePath"/doconut"Nie używane w tym pakiecie. Punkt końcowy strony to obsługa DocImage.axd zadeklarowana w Web.config, niezależnie od ustawienia. Nadal jest weryfikowany: musi zaczynać się od / i różnić się od ResourcesPath.
ResetLicensefalseNie używane w tym pakiecie. Licencja jest odczytywana raz, w DoconutHost.Initialize; po wymianie pliku licencji należy zrestartować pulę aplikacji.
MaxConcurrentEditorSessions200Maksymalna liczba aktywnych sesji edytora (dokumenty otwarte przy użyciu DocOptions.EditMode). Po jej przekroczeniu najstarsza nieużywana sesja edytora jest zamykana. Normalne sesje przeglądarki nie są liczone. 0 lub wartość ujemna oznacza brak limitu.
EditorSnapshotEveryOps50Gdy włączona jest trwałość edytora (AddDoconutEditorPersistence), twórz migawkę bieżącego dokumentu co N zarejestrowanych zmian. 0 lub wartość ujemna nigdy nie tworzy migawki w trakcie sesji. Brak efektu, gdy trwałość jest wyłączona.

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

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

Kolejne kroki

Czy ta strona była pomocna?