Tutorial: Apri Documenti con il Visualizzatore Doconut Iniettato in .NET 8

Introduzione

Esempi più vecchi di Doconut potrebbero costruire Viewer direttamente con argomenti cache, HTTP-context e license-path. Questo non è il modello di integrazione attuale per .NET 8. AddDoconut() registra Viewer tramite iniezione delle dipendenze, e i punti finali dell'applicazione ricevono il servizio invece di chiamare un costruttore.

Componenti server astratti che passano un token di sessione opaco a una superficie di visualizzazione del documento

Questo tutorial segue il flusso di richiesta attuale: registra i servizi e il middleware, emette le risorse del visualizzatore incorporate, apre un documento con OpenDocumentAsync, restituisce un token di sessione opaco e passa quel token al widget del browser.

1. Installa e registra Doconut

Aggiungi il pacchetto .NET 8:

dotnet add package Doconut.NET8

Registra Doconut e i servizi di sessione ASP.NET:

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

builder.Services.AddSession();

Collega il middleware nell'ordine richiesto. Il middleware delle risorse deve essere eseguito prima del middleware terminale dei documenti:

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

MiddlewarePath coordina la configurazione ma non crea il ramo ASP.NET da solo. Il percorso mappato /doconut deve corrispondere al BasePath del widget.

2. Aggiungi la superficie del visualizzatore e le risorse

Il visualizzatore browser Doconut è un plugin jQuery. In una pagina Razor, inietta Viewer e chiedi di emettere i tag delle risorse in ordine di dipendenza:

@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>

Inizializza il widget con percorsi che corrispondono alla registrazione del server:

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);
    }
});

La capitalizzazione delle opzioni è significativa. Usa i nomi mostrati dalla versione installata invece di normalizzarli a uno stile unico.

3. Inietta Viewer e apri un documento

Viewer è registrato come servizio transiente. Risolvilo tramite iniezione nei punti finali, iniezione nel costruttore, o la struttura equivalente nella tua applicazione ASP.NET Core.

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 });
});

Per un upload, fornisci uno stream e un FileInfo la cui estensione identifica il formato di origine:

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 });
});

Convalida la dimensione dell'upload, l'estensione e l'autorizzazione prima di aprire contenuti forniti dall'utente. Non trasformare il nome file inviato in un percorso server.

Recupera il punto finale di apertura e passa il token restituito a 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));

Tratta il token come credenziale di tipo bearer per una sessione di documento attiva:

Non registrarlo né conservarlo.
Restituiscilo solo a un client autorizzato.
Non esporre il percorso del file sorgente.
Riapri il documento quando una sessione scade.
Chiudi la sessione quando il documento non è più necessario.

5. Chiudi deliberatamente le sessioni lato server

Il codice client può chiamare objViewer.Close() quando l'utente lascia il visualizzatore. I flussi di lavoro server possono anche revocare esplicitamente un token noto:

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

La chiusura esplicita è particolarmente utile per documenti di grandi dimensioni. L'espirazione della sessione rimane una soluzione di riserva, non un sostituto per una gestione prevedibile del ciclo di vita dell'applicazione.

6. Aggiungi moduli opzionali solo dopo che il core funziona

Ricerca e annotazioni si collegano allo stesso visualizzatore inizializzato. Aggiungi i loro CSS, script, mount, controlli di licenza e callback di ciclo di vita solo dopo che il flusso di base ha avuto successo:

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

Questo ordine mantiene i fallimenti di rendering del core separati dalla configurazione dei moduli opzionali.

Errori comuni di migrazione

Modello vecchio o errato	Direzione attuale .NET 8
`new Viewer(cache, accessor, licensePath)`	Inietta `Viewer` dopo `AddDoconut()`
Chiamate statiche di caricamento licenza nel codice di richiesta	Configura l'input della licenza in `AddDoconut()`
Esempi sincroni di `OpenDocument(...)`	Usa `OpenDocumentAsync(...)`
Un CDN esterno o inventato per il visualizzatore	Emessi risorse incorporate con `ReferenceCss` e `ReferenceScripts`
Una API JavaScript generica `init()`	Inizializza `$('#div_ctlDoc').docViewer(...)`
Persistenza del token del visualizzatore	Persisti il tuo ID documento; tratta il token come temporaneo

Usa la documentazione ufficiale di Doconut e verifica gli esempi rispetto alla versione del pacchetto installato prima di adattarli al codice di produzione.