Viewer

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 mantiene 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 Viewer).

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 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 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 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 su singolo host:

Filigrana personalizzata

DocOptions.Watermark utilizza sei campi separati da tilde. Un ^ opzionale precedente 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
    });

L'analizzatore 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 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 Guides → Annotations; la sintesi è:

Metadati DICOM

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

Restituisce i metadati dei tag DICOM per le sessioni aperte tramite il plugin DICOM; null per documenti non DICOM.

Helper di risorse — ReferenceCss / ReferenceScripts

Emette i tag <link>/<script> per le risorse incorporate servite da UseDoconutResources(), nell'ordine di dipendenza corretto. 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 ad 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 ad 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 }))

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

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

Aggiunto nella 26.9.0.