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 tramite AddDoconut(), e risolto tramite iniezione del costruttore — non va mai costruito 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 Visualizzatore).

OpenDocumentAsync

Apre un documento e restituisce il token di sessione che il widget client utilizza per tutte le richieste successive.

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
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 non più concessa. La scadenza del calendario senza messaggio di rifiuto degrada a rendering con filigrana anziché 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 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 indipendenti dal formato per ogni apertura (namespace Doconut):

La classe espone anche proprietà specializzate intenzionalmente al di fuori del normale flusso di visualizzazione 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 è marcato fotogramma per fotogramma. Una filigrana personalizzata è quindi una funzionalità dell’applicazione licenziata, non un modo per sostituire o sopprimere la filigrana di valutazione.

API delle annotazioni

Caricamento e esportazione delle annotazioni lato server. Il percorso completo è descritto in Guide → Annotazioni; l’interfaccia è:

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 delle risorse — ReferenceCss / ReferenceScripts

Emette 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 + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

**Flag CssConfig:** IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss(ricerca soggetta a licenza),IncludeAnnotationCss` (annotazione soggetta a licenza).

**Flag ScriptConfig:** IncludeJQuery(richiesto da tutti gli altri),IncludeBootstrap, IncludeViewerScripts(core:docViewer.js+ splitter + links),IncludeSearchScriptseIncludeSearchBar(ricerca soggetta a licenza),IncludeAnnotationScriptseIncludeAnnotationBar` (annotazione soggetta a licenza).

@inject Doconut.Viewer Viewer

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