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

// 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 è rifiutata (il messaggio contiene il motivo del rifiuto), oppure il formato richiede una capacità di plugin 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. 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.

Flag di capacità

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

DocOptions

Opzioni indipendenti dal formato per ogni apertura (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
    });

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 contrassegnato 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; l'interfaccia è:

Ognuna di queste richiede il token di sessione. La forma GetAnnotationManager(pageWidth, pageHeight) della libreria precedente, priva di sessione, 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 allineamento 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

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 la ricerca e l'annotazione, vengono emessi solo quando la licenza le abilita, mantenendo l'interfaccia utente client coerente con il comportamento del server.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flag: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig flag: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (search-gated), IncludeAnnotationScripts e IncludeAnnotationBar (annotation-gated).

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