Generare documenti PDF in C#: scegliere il flusso di lavoro giusto

2026-11-12 09:26:00 Allen Yang
AI Summarize:
ChatGPT
ChatGPT ✓
Claude ✓
Grok ✓
Perplexity ✓
Quick
Quick
Concise overview
Highlights
Key takeaways
Detailed
Structured explanation
Brief
One sentence summary
Summarize |

Three real PDF documents side by side, one highlighted: a composed report, an HTML dashboard and a filled form

Puoi generare un documento PDF in C# dai dati dell'applicazione, da una pagina HTML oppure compilando un PDF già esistente. Ogni punto di partenza porta a un flusso di lavoro diverso e la scelta dipende dal controllo del layout, dall'impaginazione quando il contenuto cresce, dalle dipendenze di rendering che la macchina di destinazione deve avere e da come verifichi l'output.

Le sezioni seguenti classificano i flussi di lavoro di Spire.PDF for .NET in base al materiale con cui inizi e riportano ciò che ciascuno ha fatto nei test, comprese le parti che non hanno funzionato. Testato con Spire.PDF for .NET 12.11.0 (novembre 2026, Windows 11 Pro, app console .NET 10).

Navigazione rapida

  1. Inizia con ciò che hai già
  2. Genera PDF dai dati dell'applicazione
  3. Converti HTML e CSS in PDF
  4. Lavora con moduli e modelli PDF esistenti
  5. Distribuzione e validazione dell'output
  6. FAQ
  7. Conclusione

1. Inizia con ciò che hai già

Parti dal materiale che il tuo programma ha in fase di esecuzione: record da una query, una pagina HTML o un PDF progettato da qualcun altro. La tabella associa ogni input a un flusso di lavoro.

Classe Input in fase di esecuzione Flusso di lavoro
Crea nuovo PDF Dati dell'applicazione / dati strutturati Layout basato su coordinate o layout a flusso nativo
Crea nuovo PDF Pagina o modello HTML/CSS Rendering da HTML a PDF
PDF esistente Modulo compilabile (AcroForm) Compilazione dei campi del modulo
PDF esistente Modulo compilabile (XFA) Elaborazione dei campi XFA
PDF esistente Layout fisso con testo segnaposto Sostituzione del testo

Le prime due righe creano un nuovo PDF, quindi il layout è tuo e devi decidere dove interrompere le pagine. Le ultime tre partono da un PDF esistente, in cui il file fissa il layout e il compito è inserire i valori nei punti previsti. Un'attività di generazione di un report PDF in C# dai risultati di una query, come il report QA mensile usato in questa guida, parte dalla prima riga. Un modello di fattura HTML mantenuto da un team front-end parte dalla seconda, mentre un modulo ricevuto da un fornitore parte da una delle ultime tre.

Questa guida illustra i flussi di lavoro supportati da Spire.PDF, non una tassonomia esaustiva di ogni tecnica PDF in C#.


2. Genera PDF dai dati dell'applicazione

Il disegno basato su coordinate posiziona ogni blocco di testo, linea e immagine nelle posizioni specificate. Offre un controllo esatto su un design fisso e non richiede altri motori di rendering oltre alla libreria. Il costo emerge quando la lunghezza del contenuto varia, perché l'impaginazione diventa compito del tuo codice: devi tenere traccia di dove è terminato l'ultimo elemento, aggiungere pagine autonomamente e ricalcolare le posizioni quando il contenuto cambia. Un breve estratto mostra il modello.

var font = new PdfTrueTypeFont("Segoe UI", 11f, PdfFontStyle.Regular, true);
var layout = new PdfTextLayout { Layout = PdfLayoutType.Paginate };
PdfPageBase page = doc.Pages.Add();
float y = 40;

foreach (string text in summaryParagraphs)
{
    var r = new PdfTextWidget(text, font, PdfBrushes.Black)
        .Draw(page, new RectangleF(40, y, 500, 0), layout);
    page = r.Page;                  // the text may have flowed onto a new page
    y = r.Bounds.Bottom + 10;
    if (y > 760) { page = doc.Pages.Add(); y = 40; }   // you own the page breaks
}

Il passaggio importante è seguire la pagina restituita dal risultato del layout: continua a disegnare sulla pagina indicata dal widget e aggiungi una nuova pagina quando il riquadro raggiunge il fondo. I report creati da un DataTable hanno il proprio tutorial da DataTable a PDF.

Il layout a flusso nativo toglie l'impaginazione dal tuo codice. PdfContentBuilder, disponibile da Spire.PDF for .NET 12.9.18, trasmette il contenuto in sezioni e lo impagina man mano che cresce. Offre intestazioni, paragrafi, tabelle costruite da un string[][], immagini, elenchi, blocchi di codice, sei tipi di grafico, interruzioni di pagina e un indice. Crea solo nuovi documenti, senza un punto di ingresso per caricare un file esistente.

Il report QA mensile seguente usa due sezioni e una tabella. summaryParagraphs, results (un string[][] con l'intestazione nella prima riga) e closing provengono dal tuo codice.

using Spire.Pdf;
using Spire.Pdf.Layout;

PdfDocument doc = new PdfDocument();
PdfContentBuilder builder = new PdfContentBuilder(doc);

var s1 = builder.AddSection();
s1.AddHeading1("Monthly QA Report - October");
foreach (var p in summaryParagraphs) s1.AddParagraph(p);
s1.AddTable(results);            // string[][] rows; header row repeats on page breaks

var s2 = builder.AddSection();
s2.AddHeading1("Next Month Outlook");
s2.AddParagraph(closing);

builder.Build();
doc.SaveToFile("QA-Report.pdf");
doc.Dispose();

Il volume del contenuto distingue i due approcci. Un report piccolo (due sezioni, una tabella da cinque righe) è risultato di due pagine in 676 ms. Uno più grande con otto paragrafi lunghi e una tabella da 40 righe è stato impaginato in cinque pagine in 1.369 ms (10,8 KB). Lo stesso contenuto disegnato con coordinate ha prodotto tre pagine in 510 ms (28,7 KB). Questi tempi provengono da un'unica macchina Windows e servono come controllo di sanità per questa configurazione. Confronta l'aspetto di ciascun file prima di confrontare la velocità di esecuzione.

The flow-layout table starting on page 2 and continuing on page 3

Il disegno basato su coordinate è adatto a pagine la cui struttura non dipende dal volume dei dati. Il layout a flusso è adatto a documenti la cui lunghezza segue i dati, come report ed elenchi. Gli sviluppatori che desiderano maggiori dettagli sul percorso di composizione manuale possono partire dal tutorial Creare un documento PDF in C#.

Coordinate-based pages: the outlook section on a hand-added page, and the table tail on a manually tracked page

Il layout a flusso nativo e il rendering HTML sono meccanismi separati. Il builder organizza il contenuto tramite la propria API e non legge i CSS, mentre un renderer HTML analizza markup e fogli di stile, quindi le opzioni di stile e i requisiti di runtime differiscono. La tabella confronta tutti i flussi di lavoro di questa guida.

Flusso di lavoro Controllo del layout Contenuto dinamico Requisiti di runtime esterni Limite principale
Basato su coordinate Coordinate esplicite, elemento per elemento Gestisci autonomamente layout e impaginazione (PdfTextLayout.Paginate) Nessun motore di rendering aggiuntivo Le variazioni di dimensione del contenuto richiedono di rifare le coordinate
Layout a flusso nativo (PdfContentBuilder, 12.9.18+) Streaming di sezioni, intestazioni e paragrafi Contenuto in streaming; impaginazione automatica verificata nei test Nessun motore di rendering aggiuntivo Solo creazione; la copertura degli elementi corrisponde a ciò che offre l'API (tabelle, immagini, elenchi, blocchi di codice, grafici, indice)
Da HTML a PDF CSS più un motore di rendering Adatto a contenuti guidati da HTML Chromium (percorso Chrome o Edge) o plugin di rendering Qt Dipende dall'ambiente di rendering; gli sfondi CSS differiscono in base al motore
Compilazione AcroForm Layout originale dei campi del modulo Compilazione per nome del campo Nessun motore di rendering aggiuntivo Limitato dalle definizioni dei campi nel file
Sostituzione di testo statico Layout originale della pagina Sostituzione di testo fisso Nessun motore di rendering aggiuntivo Nessun ridisegno dinamico generale del layout

3. Converti HTML e CSS in PDF

Per generare un PDF da HTML in C#, Spire.PDF passa la pagina a un motore di rendering e salva il risultato stampato. Sono disponibili due motori. ChromeHtmlConverter guida Chromium e richiede il percorso di un eseguibile Chrome o Edge. L'opzione Qt, Spire.Additions.Qt.HtmlConverter, dipende dal pacchetto ufficiale dei plugin, che contiene HTMLConverter.dll, il runtime Qt5 e Html2Pdf.exe. La cartella dei plugin va accanto all'eseguibile dell'applicazione. Se manca, la chiamata fallisce con Fail to load ...\plugins\HTMLConverter.dll : error 126.

Nei test lo stesso HTML è stato inviato a entrambi i motori. Entrambi hanno prodotto due pagine e rispettato page-break-before dei CSS. L'esecuzione Qt ha impiegato 4.398 ms e scritto un file da 60,6 KB con lo sfondo blu scuro dell'intestazione della tabella intatto. L'esecuzione Chromium ha usato Edge 157.0.4341.42, carta A4 e margini di 0,4 pollici, riutilizzando il browser già presente sulla macchina.

Le due strade comportano compromessi diversi. Qt richiede un'installazione separata dei plugin, mentre Chromium riutilizza un'installazione di Chrome o Edge. Ogni motore ha le proprie regole per la stampa degli sfondi CSS e il foglio di stile decide cosa richiedere, ad esempio con print-color-adjust: exact. In un'applicazione web, esegui la conversione come processo in background anziché all'interno della richiesta.

The same dashboard converted by the Chromium path and the Qt path; CSS backgrounds print in one and not the other

Diversi aspetti non sono stati coperti: pagine che dipendono da JavaScript per il rendering, risorse esterne, font personalizzati, carico simultaneo su un server e Linux o Docker. Un convertitore che funziona su una macchina di sviluppo non ha dimostrato di funzionare in un container di produzione, e questa guida non ha verificato Linux. Per pagine basate su modelli con una procedura completa, vedi generare un PDF da un modello HTML in C#.


4. Lavora con moduli e modelli PDF esistenti

Creare un PDF da un modello in C# significa due cose diverse quando il modello è già un PDF. Un modulo compilabile contiene oggetti campo AcroForm con un nome. Una pagina progettata può contenere solo testo segnaposto che sembra uno spazio vuoto. Sullo schermo sembrano uguali, ma nel codice si comportano diversamente.

Proprietà Campo AcroForm Testo segnaposto statico
Esiste nel file come Un oggetto campo con un proprio nome Testo normale della pagina
Individuato tramite Nome del campo Il testo stesso
Interattività Mantenuta finché non appiattisci Mai interattivo
Dopo l'appiattimento Il valore diventa testo della pagina Non applicabile

A static template whose placeholders are ordinary page text

Un campo reale viene individuato per nome, compilato e facoltativamente appiattito. L'API AcroForm nello spazio dei nomi Spire.Pdf.Interactive.Forms è arrivata nella versione 12.10.7 ed è stata testata sulla 12.11.0.

using Spire.Pdf.Interactive.Forms;

PdfDocument doc = new PdfDocument();
doc.LoadFromFile("existing-form.pdf");
PdfForm form = PdfForm.Create(doc);
var field = form.GetField("team") as PdfTextField;
field.Text = "Release QA";
field.RefreshAppearances();     // without this the value is stored but renders invisible
form.Flatten();                 // after this the value sits in the page text layer
doc.SaveToFile("final.pdf");

Tre comportamenti sono emersi durante i test:

  1. Chiama RefreshAppearances() dopo aver impostato Text, così il valore viene disegnato nell'aspetto del campo e appare subito.
  2. I valori nei campi ancora interattivi risiedono nel livello del modulo; dopo l'appiattimento, il numero di campi è passato da 4 a 0 e i valori si sono uniti al testo della pagina, dove PdfTextExtractor li legge.
  3. AddWidget usa coordinate a livello di pagina, mentre le posizioni di page.Canvas sono relative ai margini; tieni separati i due sistemi quando posizioni i widget.

AcroForm fields filled by name, values visible before flattening

I dati del modulo possono anche uscire dal file come XFDF tramite form.ExportData(path, DataFormat.XFDF, ...), che nei test ha prodotto XFDF standard. Il tutorial Importare ed esportare i dati dei moduli PDF approfondisce l'argomento.

Il testo segnaposto fisso funziona su una pagina finita quando i valori inseriti hanno dimensioni simili ai marcatori che sostituiscono. La sostituzione mantiene il layout originale, quindi verifica che ogni nuovo valore si adatti allo spazio lasciato dall'originale.

I moduli XFA sono un tipo di modulo separato. La funzionalità documentata consiste nel leggere e modificare i campi supportati tramite l'oggetto modulo XFA; convalida il flusso di lavoro con i tuoi campioni nell'ambito della valutazione.


5. Distribuzione e validazione dell'output

Tutto ciò che è descritto in questa guida è stato eseguito su una macchina di sviluppo Windows. Linux, Docker e l'hosting su server non sono stati verificati in questa guida. I motori HTML richiedono la massima attenzione altrove: il percorso Chromium richiede un eseguibile del browser sulla macchina di destinazione, mentre il percorso Qt richiede la cartella dei plugin accanto all'applicazione. Spire.PDF pubblica pacchetti plugin ufficiali per Linux e macOS. Testali nella tua immagine di distribuzione prima di affidarti a essi e misura il tempo di conversione sull'host di destinazione, poiché i tempi sopra provengono da una macchina di sviluppo.

I problemi di generazione raramente generano eccezioni: il file viene prodotto e qualsiasi errore compare solo nell'output stesso. Per questo i controlli seguenti ispezionano il file invece di affidarsi all'esecuzione del codice senza errori.

Controllo Cosa rileva Come
Numero di pagine Impaginazione troppo lunga, interrotta presto o mai avanzata check.Pages.Count
Estrazione del testo Titoli o dati mancanti, marcatori segnaposto rimasti PdfTextExtractor su ogni pagina
Validazione del modulo Valori che non hanno mai raggiunto un campo Leggi i valori dei campi tramite l'API prima dell'appiattimento; dopo l'appiattimento, riapri il file e controlla il contenuto visibile
Ispezione visiva Testo in overflow, interruzioni di pagina errate, font sostituiti, immagini mancanti Apri il PDF e osserva ogni pagina
PdfDocument check = new PdfDocument();
check.LoadFromFile("QA-Report.pdf");
Console.WriteLine(check.Pages.Count);                        // expected page count

string text = new PdfTextExtractor(check.Pages[0])
    .ExtractText(new PdfTextExtractOptions());               // titles, data, leftovers
Console.WriteLine(text.Contains("#"));                       // a stray placeholder marker

L'estrazione del testo non sostituisce l'osservazione delle pagine. Conferma che i caratteri esistano nel file e non dice nulla su overflow, ritaglio o sfondo di un'intestazione che non è stato stampato. Abbina i controlli al flusso di lavoro: numero di pagine e un controllo visivo per l'output basato su coordinate e a flusso, un controllo visivo per gli sfondi nell'output HTML e una rilettura tramite API prima dell'appiattimento per i moduli. Per i processi di report, esegui i primi tre controlli nella tua pipeline di test e ripeti il controllo visivo ogni volta che il modello o il layout cambiano. Conserva un output noto come corretto per ogni flusso di lavoro e confrontalo dopo gli aggiornamenti della libreria, perché ogni risultato qui è legato alla versione 12.11.0.


6. FAQ

Qual è la differenza tra creare e generare un PDF in C#?

A livello di API non ce n'è alcuna. Entrambe le espressioni descrivono la produzione di un file PDF dal codice. Ciò che conta è l'input: dati dell'applicazione, una pagina HTML o un PDF esistente con campi o testo segnaposto. Scegli il flusso di lavoro in base a quell'input, come mostra la tabella decisionale in questa guida.

Posso generare un PDF in C# senza una libreria?

Tecnicamente sì, perché il PDF è un formato di file documentato che il codice può scrivere direttamente. In pratica il costo ricade sull'incorporamento dei font, la compressione degli stream, il supporto all'estrazione del testo e la coerenza del rendering tra i vari visualizzatori. Ognuno di questi aspetti richiede codice e test propri, e una libreria assorbe quel lavoro.

Come scelgo tra creazione basata su codice e rendering HTML?

Decidi in base a chi possiede il layout. Se lo possiedono gli sviluppatori e i dati determinano la struttura, crea il PDF nel codice. Se i designer mantengono già HTML e CSS, esegui il rendering di quella pagina e accetta la dipendenza dal motore di rendering. Scegli il codice quando sono i dati a definire la pagina e l'HTML quando è una pagina a definire l'output.


7. Conclusione

I dati dell'applicazione indicano il disegno basato su coordinate o il layout a flusso nativo, e il layout a flusso si è impaginato da solo nei test. Una pagina HTML indica un motore di rendering, che nei test ha cambiato il tempo di conversione, la stampa degli sfondi e ciò di cui aveva bisogno la macchina di destinazione. Un PDF esistente indica i campi modulo dove esistono e la sostituzione del testo dove il layout è fisso. Controlla il numero di pagine, il testo estratto e le pagine renderizzate prima che uno di questi file venga distribuito.

Se devi testare Spire.PDF for .NET in un ambiente aziendale reale, puoi richiedere una licenza temporanea.

Vedi anche