Installation

Fügen Sie Doconut zu Ihrer .NET Framework 4.7.2 Webanwendung hinzu

Doconut.NETFramework hostet den Doconut‑Viewer in einer klassischen ASP.NET‑Anwendung auf .NET Framework 4.7.2 — IIS oder IIS Express, MVC 5 oder Web Forms. Die Einrichtung besteht aus drei Teilen: dem NuGet‑Paket, zwei Registrierungen in Web.config und einem Aufruf in Global.asax. Diese Seite behandelt alle drei; Schnellstart legt dann ein Dokument auf einer Seite ab.

Voraussetzungen

  • Das Webprojekt zielt auf .NET Framework 4.7.2 oder höher ab. Ein 4.7‑Projekt kann dieses Paket nicht verwenden; richten Sie es zuerst neu aus.
  • Die Site läuft in der integrierten Pipeline (die Standardeinstellung für IIS‑ und IIS‑Express‑Anwendungspools).
  • Der Server läuft unter Windows. Das Paket ist nur für Windows verfügbar.

Diese Seite behandelt Doconut.NETFramework 26.9.0 und später. Versionen 26.8.0 und früher zielten auf .NET Framework 4.7 mit einer anderen API; diese Linie ist eingestellt. Das Aktualisieren einer bestehenden Anwendung über diese Grenze hinweg wird in Migration behandelt.

Paket installieren

Aus der Package‑Manager‑Konsole:

powershell
Install-Package Doconut.NETFramework

Oder in einem SDK‑basierten Projekt:

bash
dotnet add package Doconut.NETFramework

Die nicht versionierten Befehle installieren die neueste stabile Version. Um die in dieser Dokumentation beschriebene Version festzulegen, übergeben Sie die Versionsnummer:

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

Die Rendering‑Engine ist im Paket eingebettet: Es gibt keine separate Engine‑Assembly zum Referenzieren, Kopieren oder Bereitstellen. Optionale Funktionen werden als eigene Pakete ausgeliefert — zum Beispiel Doconut.NETFramework.Converter und Doconut.NETFramework.Dicom — und jedes davon benötigt eine Lizenz, die es gewährt (siehe Plugin‑System).

Web.config konfigurieren

Doconut bedient zwei Arten von Anfragen, und IIS leitet beide über Web.config weiter:

  • DocImage.axd — die Seite des Viewers, das Thumbnail, die Suche und den Annotations‑Endpunkt, bereitgestellt von Doconut.DocImageHandler.
  • /doconut-res/* — die eigenen Skripte, Stylesheets und Icons des Viewers, eingebettet in die Assembly und bereitgestellt von Doconut.DoconutResourceModule.

Fügen Sie beide hinzu, zusammen mit den Einstellungen, von denen sie abhängen:

xml
<configuration>
  <system.web>
    <!-- MVC 5 nur: Razor kompiliert Views zur Laufzeit und benötigt die netstandard-Fassade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength ist in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Lese .cshtml- und .aspx-Dateien als UTF-8, nicht als die ANSI-Codepage des Servers. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength ist in BYTES: die gleichen 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>

Jede Zeile verhindert einen Fehler, der keine Ausnahme auslöst:

  • verb="GET,HEAD,POST" — behalten Sie HEAD. Der Viewer sendet eine HEAD‑Anfrage für Seite 1, um animierte Bilder zu erkennen. Ohne das Verb antwortet IIS mit 404, bevor der Handler ausgeführt wird: Dokumente werden weiterhin angezeigt, aber die Animationserkennung funktioniert nie und die Browser‑Konsole füllt sich mit 404‑Fehlern.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css und .png sehen aus wie statische Dateien, und IIS würde sie an seinen statischen Datei‑Handler übergeben, bevor das Ressourcen‑Modul sie sieht. Das Ergebnis ist ein Viewer ohne Skripte oder Icons.
  • <globalization fileEncoding="utf-8"> — Seiten‑Dateien, die als UTF‑8 ohne Byte‑Order‑Mark gespeichert sind, werden sonst mit der ANSI‑Code‑Seite des Servers gelesen, sodass jedes Nicht‑ASCII‑Zeichen doppelt codiert im Browser ankommt (ein Gedankenstrich wird als — angezeigt). Die Datei ist auf dem Datenträger korrekt, und die Seite deklariert weiterhin <meta charset="utf-8">.
  • Die netstandard‑Assembly (MVC 5) — Razor kompiliert Views, wenn sie erstmals angefordert werden, mit einer eigenen Referenzliste, die diese Fassade nicht enthält. Eine View, die etwas Dynamisches über einen einfachen Member‑Zugriff hinaus tut, schlägt dann mit CS0012 fehl und liefert ein leeres 500, und nur die Seiten, die darauf stoßen, schlagen fehl. Der Compiler‑Fehler erscheint nur im Windows‑Ereignis‑Log (Quelle ASP.NET). Web‑Forms‑Anwendungen benötigen diese Zeile nicht.
  • Upload‑Grenzen — ASP.NET liest den gesamten Anforderungstext, bevor ein Handler läuft, sodass ein Upload über diesen Grenzen von IIS mit einer eigenen Fehlermeldungsseite abgelehnt wird. Halten Sie maxRequestLength (Kilobytes) und maxAllowedContentLength (Bytes) im Gleichgewicht und über dem größten Dateiformat, das Ihre Benutzer öffnen oder hochladen.

Zwei weitere Einstellungen sind wichtig, und beide sind normalerweise bereits korrekt:

  • Der Sitzungsstatus bleibt aktiviert. Standardmäßig wird eine Seite nur an die ASP.NET‑Sitzung ausgeliefert, die das Dokument geöffnet hat, sodass die Site <sessionState mode="Off" /> nicht setzen darf. Siehe Sitzungen & Sicherheit.
  • Binding‑Redirects. Behalten Sie die <runtime>‑Binding‑Redirects bei, die NuGet in Web.config schreibt. In einem SDK‑basierten Projekt kopieren Sie sie aus dem generierten bin\<YourApp>.dll.config, da klassisches ASP.NET Redirects nur aus Web.config liest. Ein Redirect, der eine in bin\ fehlende Version nennt, stoppt die gesamte Anwendung beim Start mit einem leeren 500.

Registrieren Sie Doconut in Global.asax

Es gibt keinen Builder und keine Middleware-Pipeline in System.Web. Doconut wird einmal pro Worker-Prozess von DoconutHost.Initialize in Application_Start zusammengesetzt und von DoconutHost.Shutdown in Application_End freigegeben:

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 erstellt die Dienste, den Handler, das Ressourcenmodul und die Nutzung Ihres eigenen Codes. Ihr Code greift über DoconutHost.Services darauf zu (siehe DoconutHost). Nur der erste Aufruf konfiguriert etwas; ein zweiter Aufruf wird ignoriert. In einer MVC-Anwendung sollten Sie außerdem die beiden Doconut-Pfade aus dem Routing heraushalten — Schnellstart zeigt das vollständige Application_Start.

Alle Optionen

DoconutOptions akzeptiert die folgenden einstellbaren Eigenschaften. Jede ist optional.

EigenschaftStandardBeschreibung
UnsafeModefalseWenn false, liefert DocImage.axd eine Seite nur an die ASP.NET‑Sitzung, die das Dokument geöffnet hat. Wenn true, wird jede Anfrage, die das Token enthält, bedient. Lassen Sie es false.
ShowDoconutInfofalseWenn true, beantwortet eine DocImage.axd‑Anfrage ohne token ein Versionsbanner anstelle von 404. Nützlich als Schnelltest; in der Produktion deaktivieren.
ResourcesPath"/doconut-res"Wo das Ressourcenmodul die eingebetteten Skripte, Styles und Icons bereitstellt. Ändern Sie es nur zusammen mit dem Viewer‑ResPath und allen MVC‑IgnoreRoute.
LicensePath""Vollständiger Pfad zur Lizenzdatei. Leer bedeutet, dass zur nächsten Quelle und anschließend zur automatischen Erkennung übergegangen wird.
LicenseContent""Roh‑Lizenzinhalt — aus einer Umgebungsvariablen, einem Secret Store oder einer Datenbank.
LicenseStreamnullLizenz als Stream, einmalig beim Starten gelesen.
MiddlewarePath"/doconut"Wird in diesem Paket nicht verwendet. Der Seitenendpunkt ist der DocImage.axd‑Handler, deklariert in Web.config, egal wie dies eingestellt ist. Er wird weiterhin validiert: Er muss mit / beginnen und sich von ResourcesPath unterscheiden.
ResetLicensefalseWird in diesem Paket nicht verwendet. Die Lizenz wird einmal gelesen, in DoconutHost.Initialize; recyceln Sie den Anwendungspool, nachdem Sie eine Lizenzdatei ersetzt haben.
MaxConcurrentEditorSessions200Maximale Anzahl gleichzeitiger Editor‑Sitzungen (Dokumente, die mit DocOptions.EditMode geöffnet wurden). Bei Überschreitung wird die am wenigsten kürzlich genutzte inaktive Editor‑Sitzung geschlossen. Normale Viewer‑Sitzungen werden nie gezählt. 0 oder ein negativer Wert bedeutet keine Begrenzung.
EditorSnapshotEveryOps50Bei aktivierter Editor‑Persistenz (AddDoconutEditorPersistence) wird das Live‑Dokument alle N aufgezeichneten Änderungen als Schnappschuss gespeichert. 0 oder ein negativer Wert erzeugt niemals Schnappschüsse während einer Sitzung. Hat keine Wirkung, wenn die Persistenz deaktiviert ist.

Wenn mehr als eine Lizenzquelle festgelegt ist, hat LicenseStream Vorrang vor LicenseContent, das Vorrang vor LicensePath hat, das Vorrang vor der automatischen Erkennung hat — siehe License Setup.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // wo die JS/CSS/Bilder des Viewers bereitgestellt werden
    options.UnsafeMode      = false;          // Sitzungssicherheit aktiv lassen
    options.ShowDoconutInfo = false;
});
// Der Seitenendpunkt ist hier keine Option: Es ist der DocImage.axd-Handler, der in der Web.config deklariert ist.

Nächste Schritte

  • Schnellstart — öffnen Sie ein Dokument und rendern Sie es im Browser, in MVC 5 oder Web Forms.
  • Lizenz‑Einrichtung — wo Doconut nach Ihrer Lizenzdatei sucht.

War diese Seite hilfreich?