Visualizzatore
La classe principale del visualizzatore di documenti
Viewer (namespace Doconut) è il punto di ingresso pubblico per aprire documenti da pagine Razor, controller MVC, componenti Blazor o API minime. È sealed, registrato come servizio transient da AddDoconut(), e risolto tramite iniezione del costruttore — non costruirlo mai direttamente.
La precedente libreria .NET Standard esponeva un costruttore pubblico che accettava la cache di memoria, l'accessor del contesto HTTP e uno o più percorsi di licenza. Quel costruttore non esiste più; il grafo dei servizi fornisce tali dipendenze.
Viewer non mantiene alcuno stato per richiesta e intenzionalmente non implementa IDisposable: le sessioni dei documenti vivono indipendentemente nella cache di sessione, quindi la disposizione del servizio non potrebbe mai chiudere un documento aperto (vedi Concetti di base → Come funziona il Viewer).
OpenDocumentAsync
Apre un documento e restituisce il token di sessione che il widget client utilizza per tutte le richieste successive. Ogni apertura è asincrona — non esiste un OpenDocument sincrono.
| Sovraccarico | Quando usarlo |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Apertura da disco con rilevamento automatico del formato e configurazione predefinita del formato |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Hai bisogno di opzioni di rendering per formato (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Il documento non è un file su disco (upload, database, blob). fileInfo deve contenere l'estensione corretta — guida il rilevamento del formato |
// Apertura semplice
string token = await viewer.OpenDocumentAsync(path);
// Con configurazione e opzioni per formato
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Da un caricamento
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));Eccezioni da gestire:
LicenseException— una licenza trovata viene rifiutata (il messaggio contiene il motivo del rifiuto), o il formato richiede una capacità plugin che non è più concessa. La scadenza del calendario senza un messaggio di rifiuto degrada al rendering con filigrana invece di lanciare un'eccezione.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— il contenuto del file è corrotto o non corrisponde alla sua estensione.
CloseDocument
void CloseDocument(string token)Rimuove la sessione dalla cache (disponendo immediatamente il motore del documento), elimina il marcatore di sicurezza e revoca il permesso di accesso. Opzionale — la scadenza scorrevole esegue la stessa pulizia — ma è consigliata per documenti di grandi dimensioni.
GetPageCount
int GetPageCount(string token)Numero totale di pagine della sessione aperta. Lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)La dimensione di pagina predefinita del documento renderizzata al 100% di zoom — lo spazio di coordinate per le annotazioni costruite nel codice. page è accettato per compatibilità; il risultato è il valore predefinito del documento. Lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
GetWorksheetNames
IReadOnlyList<string> GetWorksheetNames(string token)Restituisce i nomi dei fogli di lavoro di un foglio di calcolo aperto, nell'ordine del workbook, oppure una lista vuota quando il documento aperto non è un foglio di calcolo.
Vengono elencati solo i fogli di lavoro renderizzati: i fogli nascosti e vuoti sono esclusi, e quando ExcelConfig.SheetNames limita il rendering, compaiono solo quei fogli. Un foglio di lavoro non è sempre una singola pagina — uno molto grande viene renderizzato su più pagine. Lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
Aggiunto nella 26.9.0.
Capability flags
| Membro | Significato |
|---|---|
bool IsSearchEnabled | La licenza corrente concede Search |
bool IsAnnotationEnabled | La licenza corrente concede Annotation |
Usa questi in una vista Razor per renderizzare un Ribbon con licenza solo quando il server lo fornirà effettivamente — vedi Avvio rapido.
DocOptions
Opzioni per apertura, indipendenti dal formato (namespace Doconut):
| Tipo | Proprietà | Predefinito | Descrizione |
|---|---|---|---|
string | Password | "" | Password per documenti protetti (copiata automaticamente nella configurazione del formato). |
int | ImageResolution | 0 | Obsoleto. Conservato solo per compatibilità — impostare ImageResolution nella configurazione del formato invece. |
string | Watermark | "" | Testo personalizzato del watermark disegnato sulle pagine renderizzate. Stringa di formato: "^Text~Color~FontSize~FontName~Opacity~Angle", ad es. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Scadenza scorrevole della sessione in minuti. |
bool | IsSecured | true | Non attualmente applicato — riservato. Il binding del token è controllato globalmente da DoconutOptions.UnsafeMode (vedi Concetti di base → Sessioni e Sicurezza). |
La classe espone anche proprietà specializzate che sono intenzionalmente al di fuori del normale flusso di visualizzazione a singolo host:
| Tipo | Proprietà | Predefinito | Descrizione |
|---|---|---|---|
bool | IsWebFarm | false | Obsoleto — non ha effetto. Pubblica il documento con DistributedDocumentPublisher.PublishAsync (o IDistributedPublishQueue.EnqueueAsync) e imposta FileShareConfig.RootPath invece. Nota la capitalizzazione — la libreria precedente scriveva questo IsWebfarm. |
string | WebFarmPath | "" | Obsoleto — non ha effetto. Usa FileShareConfig.RootPath, come descritto in Distribuzioni distribuite. Precedentemente scritto WebfarmPath. |
bool | EditMode | false | Riservato per un flusso di lavoro di modifica distribuito separatamente; lascia false per il visualizzatore standard. |
Custom watermark
DocOptions.Watermark utilizza sei campi separati da tilde. Un ^ opzionale all'inizio richiede il layout a tutti gli angoli:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Campo | Esempio | Significato |
|---|---|---|
Leading ^ | ^ | Layout opzionale a tutti gli angoli. Senza di esso, viene usato il posizionamento normale del watermark. |
| Text | Confidential | Testo renderizzato su ogni pagina. Non deve essere vuoto. |
| Color | Red | Colore denominato compreso dal livello di disegno. |
| FontSize | 24 | Dimensione del carattere; input numerico non valido ricade sul valore predefinito del renderer. |
| FontName | Verdana | Famiglia di caratteri richiesta. Assicurati che sia installata nell'ambiente di distribuzione. |
| Opacity | 80 | Valore byte da 0 a 255. Deve essere analizzato correttamente. |
| Angle | -45 | Angolo di rotazione in gradi; input numerico non valido ricade sul valore predefinito. |
Il parser si aspetta esattamente sei campi dopo il ^ opzionale. Una definizione non valida viene sostituita dal fallback visibile Invalid Watermark dell'SDK invece di scomparire silenziosamente.
Decisione della licenza
| Stato della licenza | Valore personalizzato fornito | Risultato renderizzato |
|---|---|---|
| Licenza visualizzatore a pagamento valida | No | Pagina pulita |
| Licenza visualizzatore a pagamento valida | Sì | Filigrana personalizzata |
| Visualizzatore base temporaneo/demo attivo | No | Pagina del visualizzatore base pulita |
| Visualizzatore base temporaneo/demo attivo | Sì | Filigrana personalizzata quando si applica il percorso del visualizzatore base pulito |
| Licenza mancante, rifiutata, scaduta, versione errata o dominio non valido | Qualsiasi | Filigrana di applicazione/valutazione; il valore personalizzato non la sovrascrive |
| Rendering del plugin secondo le regole di valutazione | Qualsiasi | Filigrana di valutazione |
La stessa decisione viene applicata alle immagini delle pagine servite e alle esportazioni di annotazioni. L'output GIF animato viene marchiato fotogramma per fotogramma. Una filigrana personalizzata è quindi una funzionalità dell'applicazione concessa in licenza, non un modo per sostituire o sopprimere la filigrana di valutazione.
API delle annotazioni
Caricamento e esportazione delle annotazioni lato server. La guida completa si trova in Guide → Annotazioni; la sintesi è:
| Membro | Scopo |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Manager legato alle dimensioni della pagina della sessione aperta |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Manager con dimensioni della pagina esplicite |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Manager indipendente dalla sessione |
void LoadAnnotationData(string token, AnnotationManager manager) | Carica le annotazioni create in C# nella sessione |
void LoadAnnotationData(string token, string annotationData) | Carica le annotazioni dalla pagina codificata/involucro Base64 restituito da AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Carica le annotazioni da XML |
XmlDocument GetAnnotationXML(string token) | Esporta le annotazioni della sessione come XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF con annotazioni incorporate |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Un PNG per pagina, annotazioni incorporate, scritto in directoryPath (creato se mancante); restituisce il numero di immagini scritte |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP di PNG per pagina con annotazioni incorporate |
Ognuno di questi richiede il token di sessione. La forma GetAnnotationManager(pageWidth, pageHeight) senza sessione della libreria precedente rimane disponibile per la creazione di annotazioni al di fuori di una sessione, ma il loro caricamento richiede comunque un token.
Metadati DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Il metodo è presente per l'allineamento dell'API, ma questo pacchetto non può fornire i tag tecnici DICOM: il lettore di metadati è distribuito solo con una build .NET 8. Restituisce null per le sessioni DICOM e non DICOM; in una sessione DICOM scrive anche un avviso una tantum che spiega la limitazione della piattaforma. Il rendering di pagine, fotogrammi e animazioni rimane supportato.
Helper delle risorse — ReferenceCss / ReferenceScripts
Emetti i tag <link>/<script> per le risorse incorporate servite da UseDoconutResources(), nell'ordine corretto di dipendenza. I bundle per le funzionalità soggette a licenza, come la ricerca e le annotazioni, vengono emessi solo quando la licenza le abilita, mantenendo l'interfaccia client coerente con il comportamento del server.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + visualizzatore + ricerca + annotazione
string ReferenceScripts(ScriptConfig? config = null)Flag CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (soggette a ricerca), IncludeAnnotationCss (soggette a annotazione).
Flag ScriptConfig: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (soggette a ricerca), IncludeAnnotationScripts e IncludeAnnotationBar (soggette a annotazione), EmitFeatureFlags (predefinito true: scrive anche uno script inline window.Doconut.features = { search, annotation, editor }; impostalo su false sotto una Content-Security-Policy che blocca gli script inline).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Questi helper sono il modo supportato per fornire le risorse del browser. Le applicazioni che hanno copiato docViewer.js, documentLinks.js e docViewer.UI.js in wwwroot dovrebbero rimuovere tali copie una volta che la pagina viene renderizzata dai tag emessi.
Questa pagina è stata utile?