Visualizzatore
La classe principale del visualizzatore di documenti
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 usi:
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 compilante. Prima di Initialize, lancia 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 Viewer).
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).
| Sovraccarico | Quando usarlo |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Apertura da disco con rilevamento automatico del formato e configurazione predefinita del formato |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Hai bisogno di opzioni di rendering per formato (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Il documento non è un file su disco (un upload, un database, un blob). fileInfo deve contenere l'estensione corretta — seleziona il formato |
// 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), oppure il formato richiede una capacità 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)Ognuno 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 nel contesto della richiesta ASP.NET, quindi attendere su di esso non può causare deadlock. Lo stesso non è vero per ogni API asincrona Doconut — vedi la sezione Web Forms di Plugin del Convertitore.
ChiudiDocumento
void CloseDocument(string token)Rimuove la sessione (rilasciando immediatamente il motore del documento), rimuove il privilegio 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 della sessione
| Membro | Restituisce |
|---|---|
int GetPageCount(string token) | Numero totale di pagine del documento aperto |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Dimensione predefinita della pagina renderizzata al 100% di zoom — lo spazio di coordinate per le annotazioni costruito nel codice |
IReadOnlyList<string> GetWorksheetNames(string token) | Fogli di lavoro renderizzati di un foglio di calcolo, in ordine di cartella di lavoro; vuoto per altri documenti |
Ogni chiamata lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
OpzioniDoc
Opzioni per apertura, indipendenti dal formato (namespace Doconut):
| Tipo | Proprietà | Predefinito | Descrizione |
|---|---|---|---|
string | Password | "" | Password per documenti protetti (copiata automaticamente nella configurazione del formato). |
string | Watermark | "" | Testo del watermark personalizzato disegnato sulle pagine renderizzate — vedi sotto. |
int | TimeOut | 60 | Scadenza scorrevole della sessione, in minuti. |
string | BrowserId | "" | Web farm: il browser a cui è legato un ticket firmato. Impostalo con DoconutFarmBinding.EnsureBrowserId (vedi Sessioni e Sicurezza). |
string | UserId | "" | Web farm: l'utente autenticato a cui è legato un ticket, da DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Obsoleto. Imposta ImageResolution nella configurazione del formato invece. |
bool | IsSecured | true | Riservato; non applicato. Il controllo di accesso è DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Mantenuto per codice migrato dal pacchetto classico. Non attivano la modalità farm — lo fa AddDoconutDistributed. |
bool | EditMode | false | Riservato per l'editor distribuito separatamente; lascia false. |
Watermark personalizzato
DocOptions.Watermark accetta sei campi separati da tilde. Un ^ opzionale all'inizio richiede il layout a tutti gli angoli:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Campo | Esempio | Significato |
|---|---|---|
Iniziale ^ | ^ | Layout opzionale a tutti gli angoli. Senza di esso, viene usata la posizione normale. |
| Testo | Confidential | Testo disegnato su ogni pagina. Non deve essere vuoto. |
| Colore | Red | Un colore con nome. |
| DimensioneCarattere | 24 | Dimensione del carattere; input numerico non valido ripiega al valore predefinito. |
| FontName | Verdana | Famiglia di caratteri. Deve essere installata sul server — Windows Server ha meno font rispetto a un desktop. |
| Opacità | 80 | Da 0 a 255. Deve essere analizzabile. |
| Angolo | -45 | Rotazione in gradi; input numerico non valido ripiega al valore predefinito. |
Il parser si aspetta esattamente sei campi dopo il ^ opzionale. Una definizione non valida è sostituita da un testo Invalid Watermark visibile invece di scomparire silenziosamente.
Decisione di licenza
| Stato della licenza | Valore personalizzato fornito | Risultato renderizzato |
|---|---|---|
| Licenza viewer a pagamento valida | No | Pagina pulita |
| Licenza viewer a pagamento valida | Sì | Watermark personalizzato |
| Licenza Temporanea/Demo attiva | No | Pagina pulita |
| Licenza Temporanea/Demo attiva | Sì | Watermark personalizzato |
| Licenza mancante, rifiutata, scaduta, versione errata o dominio non valido | Qualsiasi | Watermark di valutazione; il valore personalizzato non lo sostituisce |
La stessa decisione si applica alle pagine servite e alle esportazioni di annotazioni. Un watermark personalizzato è una funzionalità di un'applicazione con licenza, non un modo per sostituire il watermark di valutazione.
API delle annotazioni
Caricamento e esportazione delle annotazioni lato server. La guida è in Annotazioni.
| Membro | Scopo |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Gestore legato alle dimensioni della pagina della sessione aperta |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Gestore con dimensioni della pagina esplicite |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Gestore indipendente dalla sessione |
void LoadAnnotationData(string token, AnnotationManager manager) | Carica le annotazioni create in C# nella sessione |
void LoadAnnotationData(string token, string annotationData) | Carica la busta codificata restituita da AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Carica le annotazioni da XML |
XmlDocument GetAnnotationXML(string token) | Esporta le annotazioni della sessione come XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF con annotazioni incorporate |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Un PNG per pagina, annotazioni incorporate, scritto in directoryPath (creato se mancante); restituisce il numero di immagini scritte |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP di PNG per pagina con annotazioni incorporate |
Metadati DICOM
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 Plugin DICOM.
Helper delle risorse — ReferenceCss / ReferenceScripts
Emette i tag <link> e <script> per le risorse che il modulo 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 li concede.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + ricerca + annotazione
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // stato della licenza, per proteggere il codice di init del ribbon
bool IsAnnotationEnabled { get; }Flag CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (con restrizione di ricerca), IncludeAnnotationCss (con restrizione di annotazione).
Flag ScriptConfig: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (gli script core del visualizzatore), IncludeSearchScripts e IncludeSearchBar (con restrizione di ricerca), IncludeAnnotationScripts e IncludeAnnotationBar (con restrizione di annotazione), EmitFeatureFlags (predefinito true: scrive anche uno script inline window.Doconut.features = { search, annotation, editor }; impostalo su false sotto una Content-Security-Policy che blocca gli script inline).
Entrambi restituiscono HTML: scrivili con @Html.Raw(...) in MVC 5 (generali nel controller — le view non hanno @inject) o <%= %> in Web Forms. Guida rapida 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 viewer, quindi una pagina con la propria barra degli strumenti dovrebbe inizializzare il widget manualmente. Vedi ViewerConfig.
Farm Web
string? AccessToken contiene il ticket firmato emesso dall'ultima apertura quando la modalità distribuita è attiva e UnsafeMode è false; è null su un singolo server. Inviarlo al widget con il token: objViewer.View(token, accessToken).
Questa pagina è stata utile?