Guida rapida

Visualizza il tuo primo documento in pochi minuti

Questa guida porta un'app ASP.NET Core da un Program.cs vuoto a un documento visualizzato nel browser: registrazione del server, il pacchetto completo Viewer (barra degli strumenti Viewer, montaggio Viewer e nastri opzionali di Ricerca/Annotazione), riferimenti alle risorse, inizializzazione del client, apertura del documento e esecuzione.

L'applicazione host deve puntare a un runtime che supporti netstandard2.1 — .NET Core 3.0 o versioni successive.

Configurazione del server

AddDoconut() registra i servizi; UseDoconutResources() e UseDoconut() collegano il middleware. La chiamata alle risorse deve avvenire per prima. UseDoconut() risponde a ogni richiesta che lo raggiunge, quindi montala su un ramo proprio con app.Map. Le chiamate di sessione sono necessarie anche — la sicurezza documentale predefinita di Doconut convalida ogni richiesta di pagina rispetto allo stato della sessione ASP.NET. Lo stato della sessione richiede una cache: AddDistributedMemoryCache() ne fornisce una. Un'app MVC o Razor Pages la registra già, ma un'app minimal-API no, e senza di essa l'app si arresta all'avvio con Unable to resolve service for type 'IDistributedCache'. Hai già registrato Doconut durante l'Installazione? Passa alla sezione successiva.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // lo stato della sessione richiede una cache (MVC/Razor Pages ne aggiungono già una)
builder.Services.AddSession(); // La sicurezza dei documenti Doconut si basa sullo stato della sessione ASP.NET

app.UseSession();          // chiama UseSession() prima di UseDoconut()
app.UseDoconutResources(); // deve essere registrato prima di UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Questa configurazione mantiene la forma storica della richiesta DocImage.axd e monta il middleware documento su un ramo corrispondente. Questa è la disposizione da copiare quando si porta avanti un'applicazione .NET Standard esistente, perché il client continua a chiamare lo stesso URL come sempre:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // mantieni abilitato il controllo della sessione di Doconut
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // lo stato della sessione richiede una cache (MVC/Razor Pages ne aggiungono già una)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Richiesto per codifiche multi-byte in alcuni formati di documento.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

UseDoconut() non accetta opzioni in questa versione — tutto è stato spostato su AddDoconut().

MiddlewarePath è un valore di coordinazione; non mappa un ramo ASP.NET Core da solo. Con il ramo DocImage.axd sopra, il client utilizza BasePath: '/'; con app.Map("/doconut", ...) dalla configurazione minimale, utilizza BasePath: 'doconut'.

ResourcesPath fornisce il pacchetto incorporato a /doconut-res, e il percorso della risorsa immagine del widget è quindi ResPath: 'doconut-res/images'.

Aggiungi il visualizzatore a una pagina

Il Viewer è il nucleo richiesto della pagina. La sua superficie di rendering utilizza due div nidificati:

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

Considera la barra degli strumenti, i montaggi dei moduli e la superficie del Viewer come un'unica composizione di pagina. Ricerca e Annotazione iniettano i loro nastri incorporati nei montaggi opzionali, ma questi moduli non sono mai autonomi: si collegano sempre al Viewer nella stessa pagina.

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Pulsanti di navigazione, zoom, Ricerca e Annotazione del visualizzatore -->
</nav>

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

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

Riferimento alle risorse del visualizzatore

In una vista Razor, il servizio Viewer iniettato emette i tag <link> e <script> del visualizzatore in ordine di dipendenza — il widget è un plugin jQuery, quindi jQuery deve essere caricato prima degli script del visualizzatore:

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

Per il pacchetto completo del Visualizzatore, richiedi le risorse del Visualizzatore e dei moduli insieme:

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 e IncludeViewerScripts sono le flag di base obbligatorie. Non pubblicare mai un esempio di Search o Annotation Ribbon senza di esse, il montaggio del Visualizzatore e un'istanza docViewer. ReferenceCss e ReferenceScripts omettono le risorse di un modulo opzionale quando la licenza corrente non concede tale capacità; il Visualizzatore di base si avvia comunque.

Queste chiamate sostituiscono i file script copiati manualmente. Se l'applicazione carica ancora i propri docViewer.js, documentLinks.js o docViewer.UI.js, rimuovi quei tag una volta che la pagina funziona con le risorse emesse — vedi la guida di migrazione.

Inizializza il visualizzatore

Il widget lato client è un plugin jQuery. Questo è un set minimale di vere opzioni di inizializzazione (non pseudocodice):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // il ramo DocImage.axd; 'doconut' con app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    onViewerReady: function () {
        // le pagine sono visibili; è sicuro nascondere lo spinner di caricamento qui
    },
    // Inoltra gli eventi del ciclo di vita dell'annotazione al ribbon incorporato quando è presente.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Quattro dettagli determinano se questa pagina funziona affatto:

  • I callback sono opzioni. onViewerReady, onViewerBusy, onCopy e onAutoLoadStatus vengono passati nell'oggetto delle opzioni. Il visualizzatore precedente derivava i nomi delle funzioni globali dall'ID del contenitore e le chiamava; questo non lo fa. Un gestore dichiarato solo come funzione globale non viene mai eseguito e non viene segnalato nulla.
  • ResPath punta al prefisso delle risorse, non alla radice dell'applicazione. Con il valore predefinito ResourcesPath, quel valore è doconut-res/images. Se hai modificato ResourcesPath, usa invece il tuo prefisso. Le icone si trovano una cartella sotto la radice delle risorse: con 'doconut-res', ogni icona restituisce 404 mentre il documento stesso viene ancora renderizzato.
  • BasePath non ha slash iniziale tranne il valore della radice del sito '/'. 'doconut' richiede /doconut/DocImage.axd; '/doconut' produce //doconut/DocImage.axd, che il browser interpreta come una richiesta a un altro host.
  • Mantieni il visualizzatore, poi chiama View separatamente. docViewer(...) restituisce l'oggetto con Zoom, Next e FitType; View(...) restituisce qualcos'altro. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) renderizza il documento, poi fallisce con objViewer.Zoom is not a function al primo clic sulla barra degli strumenti.

Tutti questi falliscono silenziosamente — vedi Risoluzione dei problemi e la guida di migrazione.

La capitalizzazione delle opzioni è davvero mista — showThumbs, autoLoad e pageZoom sono in camelCase, ma FitType, BasePath e ResPath sono in PascalCase. Non esiste una regola coerente; se la capitalizzazione è errata l'opzione viene ignorata silenziosamente (il widget ripiega sul valore predefinito invece di generare un errore).

Assembla il pacchetto Viewer completo

Una pagina viewer completa installa le seguenti parti insieme:

Parte del pacchettoRequisitoCome è collegata
Risorse del Viewer, mount e objViewerObbligatorioRenderer di documento core
Barra degli strumenti del ViewerObbligatorio per una pagina completaMarkup host; i pulsanti chiamano lo stesso objViewer
Barra di ricercaOpzionale, modulo con licenzadoconutSearchBar(...).attach(objViewer)
Barra di annotazioneOpzionale, modulo con licenzadoconutAnnotationBar(...).attach(objViewer)

Sebbene la barra degli strumenti principale del Viewer sia markup host, viene installata insieme al Viewer e non deve mai essere documentata come un controllo isolato. Questo mantiene il suo layout, le etichette, le icone e le regole di autorizzazione sotto il controllo della tua applicazione, mentre ogni pulsante utilizza la stessa istanza del Viewer:

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>

Mantieni questo ordine di inizializzazione:

  1. Emessi CSS per il Viewer e i moduli con licenza.
  2. Renderizza la barra degli strumenti del Viewer, i mount di Ricerca/Annotazione e il mount del Viewer insieme.
  3. Emessi script per il Viewer e i moduli con licenza.
  4. Carica lo script di supporto della barra degli strumenti dell'applicazione host.
  5. Inizializza docViewer e conserva il risultato objViewer.
  6. Inizializza ogni barra di Ricerca o Annotazione con licenza.
  7. Chiama attach(objViewer) su ogni barra.
  8. Apri il documento e conserva il suo token per le richieste del Viewer e dei moduli.

Le protezioni lato server sono importanti: quando una funzionalità opzionale non è disponibile, il suo script non viene emesso, quindi la sua funzione plug-in jQuery non esiste.

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>

Entrambi i componenti incorporati generano il proprio DOM della barra. La ricerca contiene i gruppi Trova, Opzioni e Risultati. L'annotazione contiene i suoi strumenti di authoring, i controlli di stile, le azioni di salvataggio e le azioni opzionali di esportazione/immagine. Le barre espongono open(), close(), reset() e isOpen(); chiama sempre attach(objViewer) una volta dopo averle create.

L'esempio sopra omette i callback opzionali dell'host e gli endpoint di esportazione/immagine dell'Annotazione per mantenere l'avvio al minimo. Vedi Ricerca e Annotazioni per la configurazione completa delle funzionalità specifiche, o Temi personalizzati per stilizzare o sostituire la barra degli strumenti del Viewer di proprietà dell'host.

Apri un documento

Il lato server è un unico endpoint: il servizio iniettato Viewer apre il documento e restituisce un token di sessione. L'apertura è asincrona in questa versione.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Il token è opaco — passalo al widget, non registrarlo né conservarlo.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Il client recupera quel token e lo passa al widget con objViewer.View(token):

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

Non c'è nulla da preparare prima della prima apertura. Se stai portando avanti un'applicazione, elimina qualsiasi chiamata InitCache() e il flag che la protegge — il metodo non esiste più.

Chiudi il documento

Chiama objViewer.Close(true) quando l'utente lascia il visualizzatore o apre un documento di sostituzione: pulisce il widget e invia una richiesta di chiusura al server. objViewer.Close() senza argomenti pulisce solo il widget. Nei flussi di lavoro guidati dal server, viewer.CloseDocument(token) rimuove immediatamente la sessione nella cache, elimina il motore di rendering, cancella il suo marcatore di sicurezza e revoca il token. La scadenza scorrevole alla fine esegue la stessa pulizia, ma è consigliata una chiusura esplicita per documenti di grandi dimensioni.

Il flusso di richiesta completato è:

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

Tratta il token come una credenziale di tipo portatore: non registrarlo mai, non conservarlo mai, consegnalo solo al widget. Identifica una sessione di documento attiva sul server e smette di funzionare quando quella sessione scade — riapri il documento per ottenerne uno nuovo.

Esegui

Posiziona un PDF in wwwroot/files/Sample.pdf, esegui dotnet run e apri la pagina che ospita il widget. La prima pagina viene renderizzata nel visualizzatore, con un pannello di miniature a sinistra. Se non succede, consulta Risoluzione dei problemi.

Cosa ottieni senza licenza

Una licenza mancante non genera eccezioni. Il visualizzatore rende normalmente, ma ogni pagina porta una filigrana di valutazione. Consulta Configurazione della licenza per sapere come Doconut trova una licenza e cosa cambia una volta trovata.

Questa pagina è stata utile?