Installazione

Aggiungi Doconut al tuo progetto .NET Standard 2.1

Il visualizzatore base Doconut per .NET Standard è distribuito come un unico pacchetto NuGet che si integra in qualsiasi applicazione ASP.NET Core. I plugin opzionali usano pacchetti separati. Questa pagina installa il pacchetto base, conferma che il tuo host possa consumarlo e registra il middleware — il minimo necessario prima del tuo primo rendering.

Verifica prima il framework host

La libreria punta a netstandard2.1. È un contratto più ristretto rispetto alla precedente build netstandard2.0, ed è la prima cosa da verificare:

HostSupportato
.NET Core 3.0 o versioni successive, inclusi .NET 5/6/7/8Sì
.NET Framework (qualunque versione)No — netstandard2.1 non può essere consumato da .NET Framework

Il pacchetto funziona solo su Windows. Per un host Linux, usa Doconut.NET8 o Doconut.NET6.

Se l'applicazione gira su .NET Framework, questo non è il pacchetto corretto. Usa Doconut.NETFramework invece; dalla versione 26.9.0 richiede .NET Framework 4.7.2.

Installa il pacchetto

bash
dotnet add package Doconut.NETStandard

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

bash
dotnet add package Doconut.NETStandard --version 26.10.0

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

Il numero di versione indica la generazione

Questo è più importante qui rispetto al nome del pacchetto. Entrambe le generazioni della libreria .NET Standard vengono pubblicate sotto lo stesso ID di pacchetto, e solo la versione le distingue:

VersioneObiettivoAPI
26.7.0 e precedentinetstandard2.0l'integrazione precedente
26.8.0 e successivenetstandard2.1l'integrazione documentata qui

Non esiste alcun shim di compatibilità né pacchetti side‑by‑side. Incrementare la versione è l'aggiornamento, e il compilatore segnalerà immediatamente le differenze API.

Non selezionare la documentazione solo dal nome del pacchetto:

  • new Viewer(_cache, _accessor, …), UnSafeMode, synchronous OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm, e script visualizzatore copiati manualmente identificano la integrazione precedente;
  • AddDoconut(), UseDoconutResources(), un Viewer iniettato, e OpenDocumentAsync(...) identificano l'integrazione corrente documentata qui.

Il manuale di configurazione precedente tradotto rimane disponibile. Usa la guida alla migrazione per cambiare generazione; un aggiornamento del pacchetto non converte automaticamente startup, durata del visualizzatore o risorse del browser.

Registra Doconut

AddDoconut() è l'unico punto di ingresso per la registrazione — esiste 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() è middleware terminale, quindi chiamarlo per primo fa sì che ogni richiesta a una risorsa /doconut-res non raggiunga il gestore delle risorse e ritorni 404. UseDoconut() risponde a ogni richiesta che lo raggiunge, quindi montalo su un ramo proprio con app.Map. Il wiring della sessione è richiesto comunque — la sicurezza documentale predefinita di Doconut valida ogni richiesta di pagina contro lo 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());

Spazi dei nomi

I tipi di configurazione non sono più sparsi in quattro namespace. In questa release quasi tutto vive nello spazio dei nomi radice Doconut:

csharp
using Doconut;                       // Viewer, DoconutOptions, DocOptions, tutte le configurazioni di formato
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // configurazioni cloud e di condivisione file
using Doconut.Configs.Conversion;    // ConversionTarget

I nomi dei tipi stessi non sono cambiati — PdfConfig, WordConfig, ExcelConfig, CssConfig, ScriptConfig e il resto sono ancora presenti. Se stai spostando un'applicazione esistente, la maggior parte dei file ha bisogno solo di due righe using cancellate; vedi la guida alla migrazione.

Tutte le opzioni

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

ProprietàPredefinitoDescrizione
ShowDoconutInfofalseQuando true, una richiesta senza token restituisce un banner di versione invece di un 404. Utile come verifica rapida; rimuovere in produzione.
UnsafeModefalseQuando true, salta il controllo di sicurezza della sessione ASP.NET nelle richieste di pagina. Rimuovere in produzione. Nota l'ortografia — la libreria precedente chiamava questo UnSafeMode.
MiddlewarePath"/doconut"Valore di coordinamento per l'endpoint pagina-immagine. Viene convalidato, ma non crea un ramo da solo; mantienilo allineato con la mappatura reale UseDoconut() e il client BasePath.
ResourcesPath"/doconut-res"Dove vengono servite le risorse incorporate JS/CSS/immagine.
LicensePath"" (empty string)Percorso al file di licenza. Vuoto significa passare alla fonte successiva, poi ricerca automatica.
LicenseContent"" (empty string)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. La licenza viene letta durante AddDoconut(); riavvia l'app dopo aver sostituito una licenza.
MaxConcurrentEditorSessions200Numero massimo di sessioni editor live (documenti aperti con DocOptions.EditMode). Superato, la sessione editor inattiva meno recentemente usata viene chiusa. Le sessioni visualizzatore normali non sono mai contate. 0 o un valore negativo significa nessun limite.
EditorSnapshotEveryOps50Con la persistenza dell'editor abilitata (AddDoconutEditorPersistence), esegui uno snapshot del documento live ogni N modifiche registrate. 0 o un valore negativo non esegue mai snapshot a metà sessione. Nessun effetto quando la persistenza è disabilitata.

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

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

Passi successivi

Questa pagina è stata utile?