Visualizzatore

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 è scomparso; 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 Visualizzatore).

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.

// 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 è rifiutata (il messaggio contiene il motivo del rifiuto), o il formato richiede una capacità di plugin che non è più concessa. La scadenza del calendario senza un messaggio di rifiuto degrada a rendering con filigrana invece di generare 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 del 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. Genera un'eccezione se il token è sconosciuto o scaduto.

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Restituisce i nomi dei fogli di lavoro di un foglio di calcolo aperto, nell'ordine della cartella di lavoro, o una lista vuota quando il documento aperto non è un foglio di calcolo.

Solo i fogli di lavoro renderizzati sono elencati: 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 pagina — uno molto grande è renderizzato su più pagine. Genera un'eccezione se il token è sconosciuto o scaduto.

Aggiunto in 26.9.0.

Flag di capacità

Usa questi in una vista Razor per renderizzare un Ribbon con licenza solo quando il server lo fornirà effettivamente — vedi Guida rapida.

DocOptions

Opzioni per apertura, indipendenti dal formato (namespace Doconut):

La classe espone anche proprietà specializzate che sono intenzionalmente al di fuori del normale flusso di visualizzazione a singolo host:

Filigrana personalizzata

DocOptions.Watermark utilizza sei campi separati da tilde. Un ^ opzionale iniziale richiede il layout a tutti gli angoli:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

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 di licenza

La stessa decisione viene applicata alle immagini delle pagine servite e alle esportazioni delle annotazioni. L'output GIF animato è marchiato fotogramma per fotogramma. Una filigrana personalizzata è quindi una funzionalità dell'applicazione con 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 Guides → Annotations; l'interfaccia è:

Ognuno di questi richiede il token di sessione. La forma GetAnnotationManager(pageWidth, pageHeight) senza sessione della libreria precedente rimane per creare 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 di risorse — ReferenceCss / ReferenceScripts

Emetti i tag <link>/<script> per le risorse incorporate servite da UseDoconutResources(), nell'ordine corretto di dipendenza. I bundle per funzionalità soggette a licenza, come ricerca e annotazione, 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)

CssConfig flag: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (soggetto a ricerca), IncludeAnnotationCss (soggetto a annotazione).

ScriptConfig flag: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (soggetto a ricerca), IncludeAnnotationScripts e IncludeAnnotationBar (soggetto a annotazione).

@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.