Visualizzatore

Viewer (namespace Doconut) è il punto di ingresso pubblico per aprire documenti da controller MVC, pagine Web Forms e gestori. È un servizio transient composto da DoconutHost.Initialize; risolvilo dove lo utilizzi:

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() funziona anche una volta che DoconutHost.Initialize è stato eseguito — risolve gli stessi servizi — il che mantiene il codice migrato dal pacchetto classico compilabile. Prima di Initialize, genera InvalidOperationException.

Viewer non mantiene alcuno stato del documento per richiesta e intenzionalmente non implementa IDisposable: le sessioni dei documenti vivono indipendentemente da esso, quindi la disposizione di un Viewer non potrebbe mai chiudere un documento aperto (vedi Come funziona il visualizzatore).

OpenDocumentAsync

Apre un documento e restituisce il token di sessione che il widget utilizza per ogni successiva richiesta. Quando UnsafeMode è false (impostazione predefinita), il token viene assegnato alla sessione ASP.NET della richiesta corrente — chiamalo da una richiesta che dispone di stato di sessione (vedi Sessioni e sicurezza).

// 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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

Eccezioni da gestire:

• LicenseException — è stata trovata una licenza ma è stata rifiutata (il messaggio contiene il motivo), o il formato richiede una funzionalità plugin che la licenza non concede.
• FormatNotSupportedException — nessun visualizzatore gestisce l'estensione del file.
• InvalidDataException — il contenuto è corrotto o non corrisponde alla sua estensione.

OpenDocument (sincrono)

Per il code-behind di Web Forms e altro codice che non utilizza pagine asincrone:

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

Ciascuno restituisce il token e lo memorizza anche in viewer.Token. fileName deve contenere l'estensione corretta. Questi wrapper sono sicuri da chiamare da una pagina Web Forms: il percorso di apertura non riprende mai sul contesto di richiesta ASP.NET, quindi attendere su di esso non può causare deadlock. Lo stesso non è vero per tutte le API asincrone Doconut — vedi la sezione Web Forms di Plugin di conversione.

CloseDocument

void CloseDocument(string token)

Rimuove la sessione (rilasciando immediatamente il motore del documento), rimuove il grant del token dalla sessione ASP.NET della richiesta corrente e revoca il token. Opzionale — la scadenza scorrevole esegue la stessa pulizia — ma è consigliata per documenti di grandi dimensioni.

Query di sessione

Ogni metodo genera un'eccezione se il token è sconosciuto o scaduto.

DocOptions

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

Filigrana personalizzata

DocOptions.Watermark accetta 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 da un testo Invalid Watermark visibile invece di scomparire silenziosamente.

Decisione di licenza

La stessa decisione si applica alle pagine servite e alle esportazioni di annotazioni. Una filigrana personalizzata è una funzionalità di un'applicazione con licenza, non un modo per sostituire la filigrana di valutazione.

API delle Annotazioni

Caricamento e esportazione di annotazioni lato server. La guida è in Annotazioni.

DICOM metadata

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

In questo pacchetto restituisce sempre null, e la richiesta di metadati del widget risponde 501 Not Implemented: la lettura dei tag DICOM non è disponibile su .NET Framework. Il rendering DICOM — pagine, fotogrammi e animazione — funziona. Vedi DICOM Plugin.

Helper di risorse — ReferenceCss / ReferenceScripts

Emetti i tag <link> e <script> per le risorse che il modulo di risorse serve sotto DoconutOptions.ResourcesPath, in ordine di dipendenza. I file per le funzionalità soggette a licenza (Search, Annotation) vengono emessi solo quando la licenza le concede.

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + visualizzatore + ricerca + annotazione
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // stato della licenza, per proteggere il codice di inizializzazione del ribbon
bool IsAnnotationEnabled { get; }

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

ScriptConfig flag: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (gli script principali del visualizzatore), IncludeSearchScripts e IncludeSearchBar (search-gated), IncludeAnnotationScripts e IncludeAnnotationBar (annotation-gated).

Entrambi restituiscono HTML: scrivili con @Html.Raw(...) in MVC 5 (generali nel controller — le view non hanno @inject) o <%= %> in Web Forms. Quick Start mostra entrambi.

RenderViewer

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

Restituisce un blocco <script> che inizializza il widget sull'elemento con id elementId e mostra il documento: docViewer({...}) costruito dal ViewerConfig (predefinito: BasePath: '/', ResPath: 'doconut-res/images'), poi .View(token). Scrivilo dopo gli script del visualizzatore. Lo script generato non mantiene alcun riferimento all'oggetto del visualizzatore, quindi una pagina con la propria barra degli strumenti dovrebbe inizializzare il widget manualmente. Vedi ViewerConfig.

Web farm

string? AccessToken contiene il ticket firmato emesso dall'ultima apertura quando la modalità distribuita è attiva e UnsafeMode è false; è null su un singolo server. Invialo al widget con il token: objViewer.View(token, access).