Conversione di Documenti Server-Side in .NET con Doconut

Introduzione

La conversione di documenti lato server consente a un'applicazione di generare un output normalizzato senza automatizzare Microsoft Office o inviare la sorgente a un servizio di conversione online separato. Questo può semplificare portali di documenti, lavori in background e flussi di esportazione controllati, ma l'applicazione host mantiene il controllo su autorizzazioni, archiviazione, conservazione, monitoraggio e consegna del risultato.

Il Plugin Converter .NET 8 di Doconut espone la conversione tramite il servizio DocumentConverter iniettato tramite dipendenze. Questa guida si concentra sul modello di registrazione e API attuale ed evita di accoppiare la conversione a una sessione di visualizzatore.

---

Installa i pacchetti corrispondenti

Installa i pacchetti base del visualizzatore e del convertitore:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Mantieni entrambi i pacchetti sulla stessa versione di rilascio. Quando le build riproducibili sono importanti, fissa la versione nel file di progetto o passa lo stesso valore --version a entrambi i comandi.

Registra il Plugin Converter

I plugin si registrano all'interno della callback delle opzioni AddDoconut. Non esiste un metodo di registrazione separato AddConverter():

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

L'applicazione deve utilizzare una licenza che conceda la capacità Converter. Risolvi gli errori di avvio e licenza prima di accettare lavori di conversione; non rimandarli a una coda in background dove diventano più difficili da diagnosticare.

Converti un file da C#

Inietta DocumentConverter nel endpoint o nel servizio che gestisce la richiesta di conversione. Il costruttore del convertitore è interno, quindi il codice dell'applicazione non dovrebbe istanziarlo direttamente.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

Lo stream restituito è ricercabile e posizionato all'inizio. Il chiamante ne è proprietario e dovrebbe eliminarlo dopo aver copiato o restituito il contenuto.

Converti uno stream caricato

La sovraccarico per lo stream richiede l'estensione della sorgente — incluso il punto iniziale — perché il convertitore la utilizza per determinare il formato di origine:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Considera il nome file e l'estensione come input non attendibili. Applica limiti di upload, valida il tipo di sorgente, autorizza l'utente richiedente e evita di usare il nome file fornito come percorso di archiviazione.

Scegli i target in base alle capacità effettive

Il plugin espone un enum ConversionTarget, ma non tutti i formati di origine possono produrre tutti i target. Un'interfaccia UI personalizzata dovrebbe mostrare solo i target consentiti per la sorgente caricata, anziché visualizzare ogni valore dell'enum.

Quando si utilizza il widget opzionale del convertitore di Doconut, la sua risposta aperta contiene allowedTargets. Usa quella risposta come fonte di verità per il file corrente.

Progetta la conversione in background come flusso di lavoro dell'applicazione

Il convertitore può essere chiamato da un servizio applicativo o da un worker in coda. Un job robusto normalmente comprende:

1. Una richiesta autenticata che registra la sorgente e il target desiderato.
2. Un messaggio di coda contenente un ID job dell'applicazione, non credenziali grezze.
3. Un worker che recupera la sorgente tramite un'astrazione di archiviazione autorizzata.
4. Un'operazione di conversione limitata con cancellazione.
5. Archiviazione dell'output durevole con regole esplicite di conservazione.
6. Un aggiornamento di stato che non espone percorsi interni o dettagli sensibili delle eccezioni.

Misura la concorrenza con documenti rappresentativi prima di scegliere il numero di worker. Il costo di conversione varia in base al formato di origine, alla complessità del documento, ai font, alle immagini e al target di output.

Mantieni i claim di sicurezza precisi

Eseguire il convertitore all'interno della tua applicazione .NET significa che l'operazione di conversione non richiede l'automazione di Microsoft Office né un'API di conversione online separata. Non garantisce automaticamente privacy, conformità, cancellazione o crittografia per l'intero sistema.

Quelle proprietà dipendono da come l'applicazione autentica gli utenti, recupera i file sorgente, configura l'archiviazione, protegge i log, distribuisce l'output e rimuove dati temporanei o conservati.

Checklist operativa

• Mantieni le versioni di Doconut.NET8 e Doconut.NET8.Converter allineate.
• Registra ConverterPlugin durante la configurazione dei servizi.
• Risolvi DocumentConverter tramite iniezione delle dipendenze.
• Includi il punto iniziale nelle estensioni di sorgente degli stream.
• Elimina gli stream di sorgente e risultato.
• Usa la cancellazione e limiti di dimensione file a livello applicativo.
• Convalida il supporto sorgente‑target invece di presumere che ogni coppia funzioni.
• Testa fedeltà e consumo di risorse con file rappresentativi.
• Mantieni decisioni su archiviazione, autorizzazione, audit e conservazione nel codice dell'applicazione.

Vedi la panoramica ufficiale del Plugin Converter Doconut e la documentazione di Doconut per informazioni aggiornate su prodotto e integrazione.