Plugin di Conversione

Il plugin Converter trasforma Doconut in un servizio di conversione documenti. Contribuisce al motore dietro la facciata pubblica DocumentConverter e — opzionale — un widget integrabile con il proprio contratto HTTP, così puoi convertire documenti da C#, dal widget o da un frontend che scrivi tu stesso.

Installa il pacchetto

Installa l'ultima versione stabile del plugin Converter:

dotnet add package Doconut.NET8.Converter

Per fissare il plugin alla release corrente 26.7.0, passa la versione separatamente:

dotnet add package Doconut.NET8.Converter --version 26.7.0

Mantieni il pacchetto Converter alla stessa versione di Doconut.NET8. L'ID del pacchetto è Doconut.NET8.Converter; .26.7.0 appare solo nel nome del file .nupkg scaricato.

Registra il plugin

Non esiste un metodo AddConverter() — il modello dei plugin di Doconut è uniforme. Ogni plugin, incluso Converter, si registra allo stesso modo: chiama AddPlugin<TPlugin>() all'interno di AddDoconut(). ConverterPlugin è distribuito nel proprio pacchetto NuGet, Doconut.NET8.Converter, installato accanto al pacchetto base del visualizzatore.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Questa chiamata genera un'eccezione all'avvio se manca la licenza, se è presente un file legacy TRIAL, o se una licenza non temporanea non concede la funzionalità Converter — un InvalidOperationException sollevato all'interno di AddDoconut(), prima che l'app inizi a servire richieste. Le registrazioni temporanee Demo/NFR sono accettate; dopo la scadenza del loro periodo, la conversione rimane disponibile con output filigranato. Non esiste un livello gratuito silenzioso. Vedi Configurazione della licenza per capire come vengono caricate le licenze.

Converti da C#

Ogni conversione restituisce un MemoryStream ricercabile posizionato a 0, pronto per la lettura o la copia immediata. Risolvi DocumentConverter dal contenitore DI dove ne hai bisogno — è senza stato per design, quindi una singola istanza è sicura da riutilizzare tra le richieste.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Due dettagli facili da sbagliare: sourceExtension nella sovraccarico a stream deve includere il punto iniziale (".xlsx", non "xlsx" ) — il convertitore lo confronta con il catalogo dei formati e un'estensione senza punto non verrà risolta. Inoltre, nonostante il nome, WordToHtmlAsync restituisce Task<Stream>, non Task<string> — ottieni il documento HTML (immagini incorporate come Base64) come stream, come per tutti gli altri risultati di conversione.

Formati di destinazione

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Non tutte le sorgenti si convertono in tutti i target — il plugin mappa la famiglia di formato di ogni sorgente (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) al proprio insieme fisso di target consentiti. Non codificare in modo statico questo enum nella tua UI: ?convert=open restituisce gli allowedTargets effettivi per il file appena caricato, ed è questo l'elenco da usare per il selettore.

Widget integrabile

Gli endpoint ?convert=open|run|download del widget sono opzionali e disabilitati di default — sicuri per impostazione predefinita. Abilitali lato server, insieme alla registrazione del plugin:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Senza AddConverterWidget(), i tre endpoint ?convert= rispondono 404 — ma il file JS viene comunque servito (è una risorsa statica incorporata; solo gli endpoint a cui fa riferimento sono protetti). AddConverterWidget() richiede comunque che il plugin Converter sia registrato e che la licenza conceda Converter — non concede diritti di conversione da solo.

Personalizza il widget

Opzioni di inizializzazione passate a Doconut.convert(selector, options):

Callback:

Doconut.convert() restituisce l'istanza del widget stessa — conservala per controllare il widget programmaticamente:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // torna alla schermata idle/drop; non riattiva onReady
conv.loadFile(file);  // avvia il flusso con un oggetto File; non fa nulla se non è idle
conv.destroy();       // rimuove i listener, svuota il mount; l'istanza non è più utilizzabile dopo questo

Crea il tuo frontend

Il widget è solo un client per questo contratto HTTP — costruisci il tuo frontend direttamente contro di esso per ottenere un'esperienza utente diversa. Tutte e tre le rotte si trovano sotto il ramo ASP.NET dove UseDoconut() è montato (normalmente /doconut):

I byte della sorgente caricata sono conservati sul server con un TTL di 30 minuti; una volta scaduto quel periodo, run risponde 404 e il file deve essere riaperto. Il risultato convertito vive nella stessa area di stoccaggio — downloadToken ottiene una nuova finestra di 30 minuti al completamento della conversione — mentre resultToken è un normale token di sessione del visualizzatore, la cui durata segue la cache della sessione del visualizzatore, indipendente dallo stash.

sourceExt nella risposta open non ha il punto iniziale (es. "docx" ) — è l'opposto della convenzione del parametro sourceExtension di DocumentConverter.ConvertAsync, che richiede il punto.

Modalità di errore, raggruppate per rotta

Proprietà delle risorse

Il convertitore restituisce un MemoryStream ricercabile posizionato a zero. Chi chiama possiede quello stream e deve eliminarlo dopo averne copiato o restituito il contenuto. Il servizio DocumentConverter stesso è senza stato e viene risolto tramite l'iniezione delle dipendenze; non costruirlo né eliminarlo manualmente.

Per il widget web, gli stash di upload e download hanno TTL indipendenti di 30 minuti. Un resultToken del visualizzatore segue la durata della sessione del visualizzatore. Chiudere un risultato del visualizzatore non elimina uno stash di download ancora valido, e il reset del widget nel browser non estende nessuno dei due TTL.

Risoluzione dei problemi

Filigrana

Con ConverterPlugin registrato, la licenza dell'host si trova in uno dei tre stati:

Entrambi i percorsi di chiamata calcolano il flag dalla stessa regola: la facciata C# DocumentConverter lo deriva internamente dallo stato IsViewerLicensed e IsTemporary della licenza, e il gestore ?convert=run del widget esegue il controllo equivalente (IsViewerLicensed && !IsTrial && !IsTemporary) per riempire il campo watermarked restituito. Un'integrazione può essere costruita e testata end‑to‑end su una licenza di valutazione prima dell'acquisto — cambiano solo i byte di output.