Installazione

Aggiungi Doconut al tuo progetto .NET 6

La visualizzatore base Doconut per .NET 6 viene fornito come un unico pacchetto NuGet che si integra in qualsiasi applicazione ASP.NET Core. I plugin opzionali utilizzano pacchetti separati. Questa pagina installa il pacchetto base e registra il middleware — il minimo necessario prima del tuo primo rendering.

Requisiti

Il pacchetto funziona su queste piattaforme:

PiattaformaSupportato
Windows x64 / x86Sì
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:6.0-bookworm-slim image)Sì
Alpine and other musl-based distributionsNo
macOSNo

Su Linux, installa la libreria di configurazione dei font prima che il primo documento venga aperto:

bash
apt-get update && apt-get install -y libfontconfig1

Su RHEL, Fedora e distribuzioni simili il pacchetto è fontconfig (dnf install -y fontconfig). È l'unico pacchetto di sistema di cui Doconut ha bisogno: le librerie native che utilizza sono incluse nel pacchetto NuGet, e libgdiplus non è richiesto. In Docker, prefer aspnet:6.0-bookworm-slim (Debian 12): il tag predefinito aspnet:6.0 è Debian 11, i cui mirror dei pacchetti possono fallire nell'installare libfontconfig1. Le pagine sono renderizzate con i font installati sul server, quindi vedi Risoluzione dei problemi per i font e i messaggi di errore di Linux.

Installa il pacchetto

bash
dotnet add package Doconut.NET6

Il comando senza versione installa l'ultima versione stabile. Per fissare la versione descritta in questa documentazione, passa la versione come opzione separata:

bash
dotnet add package Doconut.NET6 --version 26.10.0

Doconut.NET6 è l'ID del pacchetto. Il suffisso di versione appartiene al nome file Doconut.NET6.<version>.nupkg scaricato e non fa parte dell'ID.

Identifica l'integrazione prima dell'aggiornamento

L'ID del pacchetto Doconut.NET6 è stato usato sia dall'integrazione classica sia da quella attuale .NET 6. Non selezionare la documentazione solo dal nome del pacchetto:

  • DocImage.axd, new Viewer(_cache, _accessor, ...), sincrono OpenDocument(...), e script del visualizzatore copiati manualmente identificano l' integrazione classica;
  • AddDoconut(), UseDoconutResources(), un Viewer iniettato, e OpenDocumentAsync(...) identificano l'integrazione corrente documentata qui.

Il manuale di configurazione classica tradotto è ancora disponibile. Usa la guida di migrazione per cambiare le generazioni; un normale aggiornamento del pacchetto non converte automaticamente l'avvio, la durata del visualizzatore o le risorse del browser.

Registra Doconut

AddDoconut() è l'unico punto di ingresso per la registrazione — c'è un unico overload, e collega il servizio Viewer, il servizio licenza e l'infrastruttura di rendering al contenitore DI.

Due chiamate middleware completano la configurazione, e il loro ordine è importante: UseDoconutResources() deve essere eseguito prima di UseDoconut(). UseDoconut() è un middleware terminale, quindi chiamarlo per primo significa che ogni richiesta a una risorsa /doconut-res non raggiunge mai il gestore delle risorse e restituisce 404. UseDoconut() risponde a ogni richiesta che lo raggiunge, quindi montalo su un ramo proprio con app.Map. Il collegamento della sessione è richiesto anche — la sicurezza predefinita dei documenti di Doconut convalida ogni richiesta di pagina rispetto allo stato della sessione ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // lo stato della sessione necessita di 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());

Tutte le opzioni

DoconutOptions accetta le seguenti proprietà configurabili. Ognuna è opzionale — i valori predefiniti qui sotto si applicano quando una proprietà rimane non impostata.

ProprietàPredefinitoDescrizione
ShowDoconutInfofalseQuando true, una richiesta senza token restituisce un banner di versione invece di un 404. Utile come controllo rapido; disattivare in produzione.
UnsafeModefalseQuando true, salta il controllo di sicurezza della sessione ASP.NET sulle richieste di pagina. Disattivare in produzione.
MiddlewarePath"/doconut"Valore di coordinamento per l'endpoint pagina-immagine. Viene validato, ma non monta un ramo da solo; mantienilo allineato con la mappatura reale UseDoconut() e il client BasePath.
ResourcesPath"/doconut-res"Da dove vengono servite le risorse incorporate JS/CSS/immagine.
LicensePath"" (stringa vuota)Percorso al file di licenza. Vuoto significa passare alla fonte successiva, poi ricerca automatica.
LicenseContent"" (stringa vuota)Contenuto grezzo della licenza — da una variabile d'ambiente, un gestore di segreti o un database.
LicenseStreamnullLicenza come stream, letta una volta all'avvio.
ResetLicensefalseFlag di compatibilità riservata. I servizi .NET 6 attuali leggono la licenza durante AddDoconut(); riavvia l'app dopo aver sostituito una licenza.
MaxConcurrentEditorSessions200Numero massimo di sessioni editor live (documenti aperti con DocOptions.EditMode). Superato questo limite, la sessione editor inattiva meno recentemente usata viene chiusa. Le sessioni visualizzatore normali non sono mai conteggiate. 0 o un valore negativo indica nessun limite.
EditorSnapshotEveryOps50Con la persistenza dell'editor abilitata (AddDoconutEditorPersistence), crea uno snapshot del documento live ogni N modifiche registrate. 0 o un valore negativo non crea snapshot a metà sessione. Nessun effetto quando la persistenza è disabilitata.

Priorità della licenza quando è impostata più di una fonte: LicenseStream prevale su LicenseContent, che prevale su LicensePath, che prevale sulla ricerca automatica — vedi Configurazione della licenza.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // coordina con la mappatura dell'app e il BasePath del client
    options.ResourcesPath   = "/doconut-res"; // da dove vengono serviti i JS/CSS/immagini del visualizzatore
    options.UnsafeMode      = false;          // mantieni attiva la sicurezza della sessione
    options.ShowDoconutInfo = false;
});

Prossimi passi

Questa pagina è stata utile?