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.

Viewer non contiene stato per richiesta e intenzionalmente non implementa IDisposable: le sessioni dei documenti vivono indipendentemente nella cache della 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.

// 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 necessita di una capacità plugin non più concessa. La scadenza del calendario senza messaggio di rifiuto degrada a 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. Facoltativo — la scadenza scorrevole esegue la stessa pulizia — ma è consigliato per documenti di grandi dimensioni.

GetPageCount

int GetPageCount(string token)

Numero totale di pagine della sessione aperta. Lancia un'eccezione se il token è sconosciuto o scaduto.

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 all'inizio 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 è marcato 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 → Annotations; la superficie è:

Metadati DICOM

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Il metodo è presente per allineamento API, ma il visualizzatore DICOM .NET 6 non può fornire tag tecnici. Restituisce null per 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

Emettere 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 sono 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 (limitato alla ricerca), IncludeAnnotationCss (limitato alle annotazioni).

ScriptConfig flag: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (limitato alla ricerca), IncludeAnnotationScripts e IncludeAnnotationBar (limitato alle annotazioni).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

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.

Aggiunto in 26.9.0.