Plugin di Conversione

Il plugin Converter trasforma Doconut in un servizio di conversione di documenti. Contribuisce al motore dietro la facciata pubblica DocumentConverter, e — opzionale — un widget pronto all'uso 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'ultimo plugin Converter stabile:

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

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

Registra il plugin

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

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

Questa chiamata genera un'eccezione all'avvio per una licenza mancante, un file legacy TRIAL, o una licenza non temporanea che non concede la capacità Converter — un InvalidOperationException sollevato dall'interno di AddDoconut(), prima che l'app gestisca le richieste. Sono accettate registrazioni temporanee Demo/NFR; dopo la loro scadenza, la conversione rimane disponibile con output filigranato. Non esiste un livello gratuito silenzioso. Vedi Configurazione Licenza per 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 DI ovunque ne abbia bisogno — è senza stato per design, quindi una singola istanza è sicura da riutilizzare tra le richieste.

viewer.Converter.GetConverter() non esiste qui. La conversione non è più raggiunta tramite l'istanza del visualizzatore: inietta Doconut.DocumentConverter invece.

// Inietta DocumentConverter; il suo costruttore è interno, quindi non usarlo mai con `new`.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension include il punto iniziale. password è null a meno che il documento non sia protetto.
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 sul sovraccarico dello 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. E nonostante il nome, WordToHtmlAsync restituisce Task<Stream>, non Task<string> — ottieni il documento HTML (immagini incorporate come Base64) come stream, lo stesso di ogni altro risultato di conversione.

Formati di destinazione

ConversionTarget (namespace Doconut.Configs.Conversion) ha 45 membri:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Questo enum copre ogni famiglia di origine. La libreria precedente aveva un tipo *ConfigConverter per famiglia — WordConfigConverter, ExcelConfigConverter, e così via — ciascuno con il proprio enum EnTargetFormat annidato, più un enum SourceFormatConverter per l'input. Tutti sono scomparsi; vedi la guida alla migrazione.

Non ogni origine si converte in ogni destinazione — il plugin mappa la famiglia di formato di ogni origine (Word, Excel, PowerPoint, PDF, CAD, Immagine, Email, Diagramma, Progetto/Attività, PSD, documento web) al proprio set fisso di destinazioni consentite. Non codificare rigidamente questo enum come lista di destinazioni della tua UI: ?convert=open restituisce il reale allowedTargets per qualsiasi file appena caricato, e questo è ciò che dovrebbe guidare un selettore.

Widget integrabile

Il widget ha endpoint ?convert=open|run|download opzionali e disabilitati di default — sicuri per impostazione predefinita. Abilitale 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 stesso viene comunque servito (è una semplice risorsa statica incorporata; solo gli endpoint a cui si collega sono protetti). AddConverterWidget() richiede ancora che il plugin Converter sia registrato e una licenza che conceda Converter — non concede i 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 — tienila 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; no-op a meno che non sia attualmente idle
conv.destroy();       // rimuove i listener, svuota il mount; l'istanza non è più utilizzabile dopo questo

Costruisci il tuo frontend

Il widget è solo un client per questo contratto HTTP — costruisci il tuo frontend direttamente contro di esso per 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 archiviati lato server con un TTL di 30 minuti; una volta scaduto questo intervallo, run risponde 404 e il file deve essere riaperto. Il risultato convertito vive nello stesso archivio — downloadToken ottiene la propria finestra fresca di 30 minuti al completamento della conversione — mentre resultToken è un normale token di sessione del visualizzatore il cui ciclo di vita segue la cache di sessione del visualizzatore, indipendente dall'archivio.

sourceExt nella risposta open non ha punto iniziale (es. "docx") — la convenzione opposta rispetto al parametro sourceExtension su DocumentConverter.ConvertAsync, che ne richiede uno.

Modalità di errore, raggruppate per rotta:

Proprietà della risorsa

Il convertitore restituisce un MemoryStream ricercabile posizionato a zero. Il chiamante possiede quel flusso e dovrebbe eliminarlo dopo averlo copiato o restituito il suo contenuto. Il servizio DocumentConverter è senza stato e viene risolto tramite l'iniezione delle dipendenze; non costruire o eliminare manualmente il servizio.

Per il widget web, i depositi di caricamento e download hanno TTL indipendenti di 30 minuti. Un resultToken del visualizzatore segue invece la durata della sessione del visualizzatore. Chiudere un risultato del visualizzatore non elimina un deposito di download ancora valido, e il ripristino del widget del browser non estende nessuno dei due TTL.

Risoluzione dei problemi

Filigranatura

Con ConverterPlugin registrato, la licenza dell'host è 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 compilare il campo watermarked che restituisce. Un'integrazione può essere costruita e testata end-to-end su una licenza di valutazione prima dell'acquisto — solo i byte di output cambiano.