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

Introduzione

Esempi più vecchi di Doconut potrebbero costruire Viewer direttamente con argomenti di cache, contesto HTTP e percorso della licenza. Questo non è il modello di integrazione attuale di .NET 8. AddDoconut() registra Viewer con l’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 corrente: registra servizi e middleware, emette le risorse del visualizzatore incorporato, 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 del documento:

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 per browser Doconut è un plugin jQuery. In una pagina Razor, inietta Viewer e chiedi di emettere i tag delle risorse nell’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 sul 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);
    }
});

Il caso delle opzioni è significativo. 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 del punto finale, iniezione del 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 dimensione, estensione e autorizzazione dell’upload 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 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 abbandona 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. La scadenza della sessione resta un fallback, 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 agganciano 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 core separati dalla configurazione dei moduli opzionali.

Errori comuni di migrazione

Modello vecchio o errato	Direzione attuale di .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	Emetti risorse incorporate con `ReferenceCss` e `ReferenceScripts`
Un’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 di Doconut ufficiale e verifica gli esempi rispetto alla versione del pacchetto installato prima di adattarli al codice di produzione.