Handledning: Öppna dokument med den injicerade Doconut Viewer i .NET 8

Introduktion

Äldre Doconut-exempel kan konstruera Viewer direkt med cache, HTTP‑context och licens‑sökvägsargument. Det är inte den aktuella .NET 8‑integrationsmodellen. AddDoconut() registrerar Viewer med beroendeinjektion, och applikations‑endpoints får tjänsten istället för att anropa en konstruktor.

Abstrakta serverkomponenter som överför en opak sessions-token till en dokumentvisningsyta

Denna handledning följer det aktuella begäransflödet: registrera tjänster och middleware, generera de inbäddade visarresurserna, öppna ett dokument med OpenDocumentAsync, returnera en opak sessions‑token och skicka den token till webbläsarwidgeten.

1. Installera och registrera Doconut

Lägg till .NET 8‑paketet:

dotnet add package Doconut.NET8

Registrera Doconut och ASP.NET‑sessions‑tjänster:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

Koppla middleware i rätt ordning. Resurs‑middleware måste köras före den terminala dokument‑middleware:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath koordinerar konfiguration men skapar inte ASP.NET‑grenen själv. Den mappade /doconut‑sökvägen måste matcha widgetens BasePath.

2. Lägg till visarytan och resurserna

Doconut‑webbläsarvisaren är ett jQuery‑plugin. På en Razor‑sida injiceras Viewer och du ber den att generera resurs‑taggarna i beroendeordning:

@inject Doconut.Viewer Viewer

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

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

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

Initiera widgeten med sökvägar som matchar serverregistreringen:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Skiftlägesinställningarna är betydelsefulla. Använd de namn som visas av den installerade versionen istället för att normalisera dem till en enhetlig stil.

3. Injicera Viewer och öppna ett dokument

Viewer är registrerad som en transient tjänst. Hämta den via endpoint‑injektion, konstruktor‑injektion eller motsvarande funktion i din ASP.NET Core‑applikation.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

För en uppladdning, tillhandahåll en ström och en FileInfo vars filändelse identifierar källformatet:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

Validera uppladdningsstorlek, filändelse och behörighet innan du öppnar användargenererat innehåll. Gör inte den inskickade filnamnet till en server‑sökväg.

4. Skicka token till widgeten

Hämta öppnings‑endpointen och ge den returnerade token till objViewer.View:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

Behandla token som en bärartoken för en aktiv dokumentsession:

Logga eller spara den inte.
Returnera den endast till en auktoriserad klient.
Exponera inte källfilens sökväg.
Öppna dokumentet igen när en session löper ut.
Stäng sessionen när dokumentet inte längre behövs.

5. Stäng server‑sidiga sessioner medvetet

Klientkod kan anropa objViewer.Close() när användaren lämnar visaren. Server‑arbetsflöden kan också återkalla en känd token explicit:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

Explicit stängning är särskilt användbart för stora dokument. Sessionsutgång är en reservlösning, inte en ersättning för förutsägbar hantering av applikationens livscykel.

6. Lägg till valfria moduler först när kärnan fungerar

Sökning och annotationer fästs på samma initierade visare. Lägg till deras CSS, skript, montering, licenskontroller och livscykel‑callback‑funktioner först när basflödet lyckas:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

Detta upprätthåller en tydlig separation mellan kärnrenderingsfel och konfiguration av valfria moduler.

Vanliga migrationsmisstag

Gammalt eller felaktigt mönster	Aktuell .NET 8‑riktning
`new Viewer(cache, accessor, licensePath)`	Injicera `Viewer` efter `AddDoconut()`
Statiska licensladdnings‑anrop i begärandekod	Konfigurera licensinmatning i `AddDoconut()`
Synkrona `OpenDocument(...)`‑exempel	Använd `OpenDocumentAsync(...)`
En extern eller påhittad visare‑CDN	Generera inbäddade resurser med `ReferenceCss` och `ReferenceScripts`
Ett generiskt JavaScript `init()`‑API	Initiera `$('#div_ctlDoc').docViewer(...)`
Spara visartoken	Spara ditt dokument‑ID; behandla token som tillfällig

Använd den officiella Doconut-dokumentationen och verifiera exempel mot den installerade paketversionen innan du anpassar dem för produktionskod.