Conversione di Documenti Lato Server 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 i portali documentali, i processi in background e i flussi di lavoro di esportazione controllata, ma l'applicazione host mantiene il controllo degli accessi, l'archiviazione, la conservazione, il monitoraggio e la consegna del risultato.

Formati di documenti astratti che fluiscono attraverso una pipeline di conversione verso un unico output normalizzato

Il plugin Converter per .NET 8 di Doconut espone la conversione tramite il servizio DocumentConverter iniettato per dipendenza. Questa guida si concentra sulla registrazione attuale e sul modello API e 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.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

L'applicazione deve utilizzare una licenza che conceda la funzionalità Converter. Risolvi gli errori di avvio e di 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 nell'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 rilasciarlo dopo aver copiato o restituito il contenuto.

Converti uno stream caricato

La sovraccarico dello stream richiede l'estensione della sorgente—compreso il punto iniziale—poiché il convertitore la utilizza per determinare il formato della sorgente:

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 utilizzare il nome file inviato come percorso di archiviazione.

Scegli i target in base alle capacità effettive

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

Quando si utilizza il widget opzionale del convertitore di Doconut, la sua risposta aperta include 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 dell'applicazione o da un worker in coda. Un job robusto normalmente include:

Una richiesta autenticata che registra la sorgente e il target desiderato.
Un messaggio di coda contenente un ID job dell'applicazione, non credenziali grezze.
Un worker che recupera la sorgente tramite un'astrazione di storage autorizzata.
Un'operazione di conversione limitata con cancellazione.
Archiviazione dell'output duratura con regole di conservazione esplicite.
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 sorgente, alla complessità del documento, ai font, alle immagini e al target di output.

Mantieni le affermazioni di sicurezza precise

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.

Queste proprietà dipendono da come l'applicazione autentica gli utenti, recupera i file sorgente, configura lo storage, protegge i log, distribuisce l'output e rimuove i 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 della sorgente dello stream.
Rilascia gli stream di sorgente e di risultato.
Usa la cancellazione e i limiti di dimensione file a livello di applicazione.
Valida il supporto sorgente-target invece di presumere che ogni coppia funzioni.
Testa fedeltà e utilizzo delle risorse con file rappresentativi.
Mantieni le decisioni di storage, autorizzazione, audit e conservazione nel codice dell'applicazione.

Vedi la panoramica ufficiale del Plugin Converter di Doconut e la documentazione di Doconut per le informazioni attuali sul prodotto e sull'integrazione.