Registra e abilita il widget convertitore drop‑in di Doconut in .NET 8

Il widget drop‑in è l'interfaccia pronta all'uso di Doconut per caricare un file, avviare una conversione e scaricare il risultato.
Di default i tre endpoint ?convert= del widget restituiscono 404; diventano attivi solo quando registri il plugin Converter e chiami AddConverterWidget() su DoconutOptions.

Di seguito trovi una configurazione di avvio completa, pronta per il copia‑incolla, che soddisfa entrambi i requisiti.

---

1. Prerequisiti – licenza e supporto sessione

• Licenza – Il plugin Converter richiede una licenza che conceda la capacità Converter. Posiziona il file (ad es., Doconut.Viewer.lic) in un percorso accessibile dall'app e punta DoconutOptions.LicensePath a esso.
• Stato della sessione – Il modello di sicurezza di Doconut memorizza i token di sessione dei documenti nella sessione di ASP.NET Core. Aggiungi una cache distribuita e AddSession() prima che il middleware sia configurato.

builder.Services.AddDistributedMemoryCache();   // necessario per la sessione
builder.Services.AddSession();                  // abilita sessione supportata da IDistributedCache

---

2. Registra i servizi principali di Doconut

AddDoconut() è il punto di ingresso unico che inietta il visualizzatore, il servizio di licenza e il registro dei plugin.

builder.Services.AddDoconut(options =>
{
    // Indica a Doconut dove trovare il file di licenza.
    options.LicensePath = "Doconut.Viewer.lic";

    // Registra il plugin Converter – questo valida anche la capacità di licenza.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Se la licenza non include la capacità Converter, la chiamata sopra genera InvalidOperationException e l'applicazione non avvierà. Questo comportamento fail‑fast impedisce di distribuire una build con licenza errata.

---

3. Attiva il widget con AddConverterWidget

Il widget è opzionale. Chiamando AddConverterWidget() si registrano i tre endpoint di conversione (?convert=open, ?convert=run, ?convert=download) e si configura una piccola quantità di impostazioni lato client (dimensione massima di upload, percorsi base, ecc.).

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

    // Abilita l'interfaccia UI drop‑in e imposta il limite di upload lato client.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // pre‑controllo client; il server applica il proprio limite
    });
});

Solo la chiamata AddConverterWidget crea gli endpoint; il file JavaScript statico (doconutConverter.js) è sempre servito come risorsa incorporata, ma non riuscirà a contattare il server se gli endpoint mancano.

---

4. Configura il middleware nell'ordine corretto

Il middleware che serve le risorse statiche (UseDoconutResources) deve essere eseguito prima del middleware terminale del visualizzatore (UseDoconut). Il middleware di sessione deve inoltre essere posizionato prima perché Doconut valida la sessione ad ogni richiesta.

app.UseSession();           // deve precedere UseDoconut()
app.UseDoconutResources();  // serve JS, CSS, immagini
app.UseDoconut();           // gestisce le richieste ?convert= e le pagine del documento

Con questa pipeline attiva, una richiesta a /doconut-res/doconutConverter.js ha successo, e il widget può chiamare /doconut?convert=open, /doconut?convert=run e /doconut?convert=download.

---

5. Cosa fa effettivamente il widget

Fase	Endpoint server	Risposta tipica
Apertura	?convert=open	Restituisce un payload JSON contenente un token, il conteggio delle pagine, l'estensione sorgente e l'elenco dei formati di destinazione consentiti.
Esecuzione	?convert=run	Avvia la conversione e restituisce un downloadToken, il conteggio delle pagine risultanti, un nome file suggerito e un flag che indica se l'output è watermarked.
Download	?convert=download	Trasmette in streaming il file convertito quando il client segue l'URL di download fornito.

Lato client, il widget esegue un controllo preliminare della dimensione di upload rispetto a widget.MaxUploadMb. Se il file supera tale limite, il widget interrompe l'upload e attiva il callback onError con phase = "open" e un messaggio amichevole. Il server impone il proprio limite e risponderà 413 Payload Too Large se la richiesta supera il controllo client.

---

6. Collegare gli eventi del widget (non è necessario il lato C#)

Tutti i callback (onReady, onSourceLoaded, onConverted, onError, ecc.) sono funzioni JavaScript fornite dalla pagina che ospita il widget. Poiché la domanda si concentra sul lato registrazione, non è necessario scrivere alcun codice C# aggiuntivo per gestire questi callback—il widget li invoca automaticamente una volta che gli endpoint sono attivi.

---

7. Problemi comuni e come evitarli

Sintomo	Causa probabile	Correzione
404 on /doconut?convert=open	AddConverterWidget() è stato omesso.	Aggiungi la chiamata come mostrato nella sezione 3.
L'applicazione non avvia con InvalidOperationException sulla capacità mancante	Il file di licenza non concede Converter.	Ottieni una licenza che includa la capacità Converter.
Errore 500 relativo alla sessione	UseSession() posizionato dopo UseDoconut() o registrazione della cache mancante.	Assicurati che app.UseSession() venga eseguito prima di app.UseDoconut() e che un servizio di cache sia registrato.

---

8. Esegui l'app e vedi il widget in azione

1. Compila ed esegui il progetto ASP.NET Core.
2. Apri una pagina che contiene un elemento <div id="doconut-convert"></div> e include lo script convertitore di Doconut (lo script è servito automaticamente da /doconut-res/doconutConverter.js).
3. Trascina un file supportato (PDF, DOCX, DWG, ecc.) nell'area di rilascio.
4. Il widget chiamerà ?convert=open, poi ?convert=run e infine presenterà un link Download che punta a ?convert=download.

Se i tre endpoint rispondono con JSON invece di 404, il widget è correttamente registrato e pronto per l'uso in produzione.

---

Passo successivo: Aggiungi gli snippet di codice sopra al tuo Program.cs (o Startup.cs), verifica che il file di licenza sia presente e avvia l'app. Il widget convertitore drop‑in sarà attivo senza ulteriori modifiche lato server.