Schnellstart

Rendern Sie Ihr erstes Dokument in Minuten

Dieses Tutorial führt eine ASP.NET Core‑App von einem leeren Program.cs zu einem im Browser gerenderten Dokument: Serverregistrierung, das komplette Viewer‑Paket (Viewer‑Symbolleiste, Viewer‑Einbindung und optionale Such‑/Anmerkungs‑Bänder), Asset‑Referenzen, Client‑Initialisierung, Dokumentöffnung und Ausführung.

Die Host‑Anwendung muss auf ein Laufzeit‑Framework abzielen, das netstandard2.1 unterstützt — .NET Core 3.0 oder neuer.

Server‑Einrichtung

AddDoconut() registriert die Dienste; UseDoconutResources() und UseDoconut() verbinden die Middleware. Der Aufruf der Ressourcen muss zuerst erfolgen. UseDoconut() beantwortet jede Anfrage, die ihn erreicht, also binden Sie ihn auf einem eigenen Zweig mit app.Map ein. Die Sitzungsaufrufe sind ebenfalls erforderlich — Doconut's default document security prüft jede Seitenanfrage gegen den ASP.NET‑Sitzungsstatus. Der Sitzungsstatus benötigt einen Cache: AddDistributedMemoryCache() stellt einen bereit. Eine MVC‑ oder Razor‑Pages‑App registriert ihn bereits, aber eine Minimal‑API‑App nicht, und ohne ihn stoppt die App beim Start mit Unable to resolve service for type 'IDistributedCache'. Haben Sie Doconut bereits während der Installation registriert? Springen Sie zum nächsten Abschnitt.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // Der Sitzungszustand benötigt einen Cache (MVC/Razor Pages fügen bereits einen hinzu)
builder.Services.AddSession(); // Doconut-Dokumentsicherheit basiert auf dem ASP.NET-Sitzungszustand

app.UseSession();          // Rufen Sie UseSession() vor UseDoconut() auf
app.UseDoconutResources(); // Muss vor UseDoconut() registriert werden
app.Map("/doconut", branch => branch.UseDoconut());

Diese Konfiguration bewahrt die historische DocImage.axd‑Anfrageform und bindet die Dokument‑Middleware an einem passenden Zweig ein. Dies ist die Anordnung, die Sie kopieren sollten, wenn Sie eine bestehende .NET‑Standard‑Anwendung weiterführen, da der Client weiterhin dieselbe URL aufruft, die er immer verwendet hat:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // Behalten Sie Doconut's Sitzungsprüfung aktiviert
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // Der Sitzungszustand benötigt einen Cache (MVC/Razor Pages fügen bereits einen hinzu)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Erforderlich für Multi-Byte-Codierungen in einigen Dokumentformaten.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // VOR dem Dokumentzweig
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() nimmt in dieser Version keine Optionen entgegen — alles wurde zu AddDoconut() verschoben. MiddlewarePath ist ein Koordinationswert; er mappt keinen ASP.NET‑Core‑Zweig von selbst. Mit dem oben genannten DocImage.axd‑Zweig verwendet der Client BasePath: '/'; mit app.Map("/doconut", ...) aus der Minimal‑Einrichtung verwendet er BasePath: 'doconut'. ResourcesPath liefert das eingebettete Bundle unter /doconut-res, und der Bild‑Ressourcenpfad des Widgets ist daher ResPath: 'doconut-res/images'.

Viewer zur Seite hinzufügen

Der Viewer ist der erforderliche Kern der Seite. Seine Rendering‑Oberfläche verwendet zwei verschachtelte divs:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Behandeln Sie die Symbolleiste, Modul‑Einbindungen und die Viewer‑Oberfläche als eine Seitenkomposition. Suche und Anmerkung fügen ihre eingebetteten Bänder in optionale Einbindungen ein, aber diese Module stehen niemals eigenständig: Sie werden immer an den Viewer auf derselben Seite angehängt.

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer-Navigation, Zoom, Suche und Anmerkungs-Buttons -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Referenzieren der Viewer-Assets

In einer Razor‑Ansicht gibt der injizierte Viewer‑Dienst die <link>‑ und <script>‑Tags in Abhängigkeitsreihenfolge aus – das Widget ist ein jQuery‑Plugin, daher muss jQuery vor den Viewer‑Skripten geladen werden:

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss = true,
    IncludeViewerCss    = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery        = true,
    IncludeBootstrap     = true,
    IncludeViewerScripts = true
}))

Für das vollständige Viewer‑Paket fordern Sie die Viewer‑ und Modul‑Ressourcen gemeinsam an:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss  = true,
    IncludeViewerCss     = true,
    IncludeSearchCss     = true,
    IncludeAnnotationCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery            = true,
    IncludeBootstrap         = true,
    IncludeViewerScripts     = true,
    IncludeSearchScripts     = true,
    IncludeSearchBar         = true,
    IncludeAnnotationScripts = true,
    IncludeAnnotationBar     = true
}))

IncludeViewerCss und IncludeViewerScripts sind die obligatorischen Kern‑Flags. Veröffentlichen Sie niemals ein Beispiel für die Such‑ oder Annotations‑Ribbon, ohne diese, den Viewer‑Mount und eine docViewer‑Instanz. ReferenceCss und ReferenceScripts lassen die Ressourcen eines optionalen Moduls weg, wenn die aktuelle Lizenz diese Fähigkeit nicht gewährt; der Kern‑Viewer startet dennoch.

Diese Aufrufe ersetzen handkopierte Skriptdateien. Wenn die Anwendung weiterhin ihre eigenen docViewer.js, documentLinks.js oder docViewer.UI.js lädt, entfernen Sie diese Tags, sobald die Seite aus den emittierten Ressourcen funktioniert – siehe den Migrationsleitfaden.

Initialisieren des Viewers

Das clientseitige Widget ist ein jQuery‑Plugin. Dies ist ein minimaler Satz echter Initialisierungsoptionen (kein Pseudocode):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // der DocImage.axd Zweig; 'doconut' mit app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    onViewerReady: function () {
        // Seiten sind sichtbar; hier kann ein Ladespinner sicher ausgeblendet werden
    },
    // Leite Annotations-Lebenszyklusereignisse an das eingebettete Ribbon weiter, wenn es vorhanden ist.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Vier Details entscheiden, ob diese Seite überhaupt funktioniert:

  • Callbacks sind Optionen. onViewerReady, onViewerBusy, onCopy und onAutoLoadStatus werden im Options‑Objekt übergeben. Der vorherige Viewer leitete globale Funktionsnamen aus der Container‑ID ab und rief sie auf; dieser tut es nicht. Ein Handler, der nur als globale Funktion deklariert ist, wird nie ausgeführt, und es wird nichts gemeldet.
  • ResPath verweist auf das Ressourcen‑Präfix, nicht auf die Anwendungswurzel. Mit dem Standard‑ResourcesPath ist dieser Wert doconut-res/images. Wenn Sie ResourcesPath geändert haben, verwenden Sie stattdessen Ihr eigenes Präfix. Die Symbole befinden sich einen Ordner unterhalb der Ressourcenwurzel: Mit 'doconut-res' liefert jedes Symbol 404, während das Dokument selbst weiterhin gerendert wird.
  • BasePath hat keinen führenden Schrägstrich außer dem site‑root‑Wert '/'. 'doconut' fordert /doconut/DocImage.axd an; '/doconut' erzeugt //doconut/DocImage.axd, das der Browser als Anfrage an einen anderen Host interpretiert.
  • Behalten Sie den Viewer, und rufen Sie dann View separat auf. docViewer(...) gibt das Objekt mit Zoom, Next und FitType zurück; View(...) gibt etwas anderes zurück. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) rendert das Dokument, schlägt dann beim ersten Klick auf die Symbolleiste mit objViewer.Zoom is not a function fehl.

All dies schlägt stillschweigend fehl – siehe Fehlerbehebung und den Migrationsleitfaden.

Die Groß‑/Kleinschreibung der Optionen ist tatsächlich gemischt – showThumbs, autoLoad und pageZoom sind camelCase, aber FitType, BasePath und ResPath sind PascalCase. Es gibt keine konsistente Regel; ist die Schreibweise falsch, wird die Option stillschweigend ignoriert (das Widget greift auf seine Standardeinstellung zurück, anstatt einen Fehler zu werfen).

Zusammenstellung des vollständigen Viewer-Pakets

Eine komplette Viewer-Seite installiert die folgenden Teile zusammen:

Teil des PaketsAnforderungWie es verbunden ist
Viewer-Ressourcen, Einbindung und objViewerErforderlichKern-Dokument-Renderer
Viewer-WerkzeugleisteErforderlich für eine vollständige SeiteHost-Markup; Buttons rufen das gleiche objViewer auf
SuchleisteOptional, lizenziertes ModuldoconutSearchBar(...).attach(objViewer)
AnmerkungsleisteOptional, lizenziertes ModuldoconutAnnotationBar(...).attach(objViewer)

Obwohl die Haupt-Viewer-Werkzeugleiste Host-Markup ist, wird sie zusammen mit dem Viewer installiert und darf niemals als isoliertes Steuerelement dokumentiert werden. Dadurch bleiben Layout, Beschriftungen, Symbole und Autorisierungsregeln unter der Kontrolle Ihrer Anwendung, während jeder Button dieselbe Viewer-Instanz steuert:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

Behalten Sie diese Initialisierungsreihenfolge bei:

  1. CSS für den Viewer und lizensierte Module ausgeben.
  2. Die Viewer-Werkzeugleiste, Such-/Anmerkungs-Einbindungen und die Viewer-Einbindung gemeinsam rendern.
  3. Skripte für den Viewer und lizensierte Module ausgeben.
  4. Das Hilfsskript der Werkzeugleiste der Host-Anwendung laden.
  5. Initialisieren Sie docViewer und behalten Sie das resultierende objViewer.
  6. Initialisieren Sie jede lizensierte Such- oder Anmerkungsleiste.
  7. Rufen Sie attach(objViewer) für jede Leiste auf.
  8. Öffnen Sie das Dokument und bewahren Sie dessen Token für Viewer- und Modul-Anfragen auf.

Die serverseitigen Schutzmechanismen sind wichtig: Wenn eine optionale Fähigkeit nicht verfügbar ist, wird ihr Skript nicht ausgegeben, sodass ihre jQuery-Plugin-Funktion nicht existiert.

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

Beide eingebetteten Komponenten erzeugen ihr eigenes Ribbon-DOM. Die Suche enthält Gruppen für Finden, Optionen und Ergebnisse. Die Anmerkung enthält ihre Autorentools, Stilsteuerungen, Speicheraktionen und optionale Export-/Bild-Aktionen. Die Leisten stellen open(), close(), reset() und isOpen() bereit; rufen Sie stets attach(objViewer) einmal nach deren Erstellung auf.

Das obige Beispiel lässt optionale Host-Callbacks und Anmerkungs-Export-/Bild-Endpunkte weg, um den Start minimal zu halten. Siehe Suche und Anmerkungen für die vollständige funktionsspezifische Einrichtung, oder Benutzerdefinierte Themen, um die vom Host besessene Viewer-Werkzeugleiste zu stylen oder zu ersetzen.

Dokument öffnen

Die Serverseite ist ein Endpunkt: Der injizierte Viewer Service öffnet das Dokument und gibt ein Sitzungstoken zurück. Das Öffnen ist in dieser Version asynchron.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Das Token ist undurchsichtig — übergebe es dem Widget, logge es niemals oder speichere es nicht.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Der Client holt dieses Token ab und übergibt es dem Widget mit objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

Es gibt nichts vorzubereiten, bevor das erste Öffnen erfolgt. Wenn Sie eine Anwendung weiterführen, löschen Sie jeden InitCache() Aufruf und das dazugehörige Flag — die Methode existiert nicht mehr.

Dokument schließen

Rufen Sie objViewer.Close(true) auf, wenn der Benutzer den Viewer verlässt oder ein Ersatzdokument öffnet: Es leert das Widget und sendet eine Schließanforderung an den Server. objViewer.Close() ohne Argument löscht nur das Widget. Bei servergesteuerten Workflows entfernt viewer.CloseDocument(token) sofort die zwischengespeicherte Sitzung, gibt die Rendering‑Engine frei, löscht dessen Sicherheitsmarker und widerruft das Token. Das gleitende Ablaufdatum führt schließlich dieselbe Bereinigung durch, aber ein explizites Schließen wird für große Dokumente empfohlen.

Der abgeschlossene Anforderungsablauf ist:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Behandeln Sie das Token wie eine Bearer‑Anmeldeinformation: Loggen Sie es nie, speichern Sie es nie, geben Sie es nur an das Widget weiter. Es identifiziert eine aktive Dokumentsitzung auf dem Server und hört auf zu funktionieren, wenn diese Sitzung abläuft — öffnen Sie das Dokument erneut, um ein frisches Token zu erhalten.

Ausführen

Legen Sie ein PDF unter wwwroot/files/Sample.pdf ab, führen Sie dotnet run aus und öffnen Sie die Seite, die das Widget hostet. Die erste Seite wird im Viewer gerendert, mit einer Miniatur‑Leiste links. Wenn dies nicht geschieht, siehe Fehlerbehebung.

Was Sie ohne Lizenz erhalten

Eine fehlende Lizenz löst keinen Fehler aus. Der Viewer rendert normal, aber jede Seite trägt ein Evaluierungs‑Wasserzeichen. Siehe Lizenzsetup für Informationen, wie Doconut eine Lizenz findet und welche Änderungen danach auftreten.

War diese Seite hilfreich?