Générer des documents PDF en C# : choisir le bon workflow

Vous pouvez générer un document PDF en C# à partir des données de l'application, d'une page HTML ou en remplissant un PDF existant. Chaque point de départ mène à un flux de travail différent, et le choix dépend du contrôle de la mise en page, de la pagination lorsque le contenu croît, des dépendances de rendu que la machine cible doit porter et de la manière dont vous vérifiez le résultat.

Les sections ci-dessous classent les flux de travail de Spire.PDF for .NET selon la matière dont vous partez et rapportent ce que chacun a fait lors des tests, y compris les points qui ont mal tourné. Testé avec Spire.PDF for .NET 12.11.0 (novembre 2026, Windows 11 Pro, application console .NET 10).

Navigation rapide

1. Partir de ce que vous avez déjà
2. Générer des PDF à partir des données de l'application
3. Convertir HTML et CSS en PDF
4. Travailler avec des formulaires et modèles PDF existants
5. Déploiement et validation de la sortie
6. FAQ
7. Conclusion

1. Partir de ce que vous avez déjà

Partez de la matière que votre programme détient à l'exécution : les enregistrements d'une requête, une page HTML ou un PDF conçu par quelqu'un d'autre. Le tableau associe chaque entrée à un flux de travail.

Les deux premières lignes créent un nouveau PDF : vous maîtrisez donc la mise en page et devez décider comment les pages se coupent. Les trois dernières partent d'un PDF existant, où le fichier fixe la mise en page et où le travail consiste à placer des valeurs aux endroits qu'il prévoit. Une tâche consistant à générer un rapport PDF en C# à partir de résultats de requête, comme le rapport QA mensuel utilisé tout au long de ce guide, relève de la première ligne. Un modèle de facture HTML maintenu par une équipe front-end relève de la deuxième, et un formulaire reçu d'un fournisseur relève de l'une des trois dernières.

Ce guide couvre les flux de travail pris en charge par Spire.PDF, et non une taxonomie exhaustive de toutes les techniques PDF en C#.

2. Générer des PDF à partir des données de l'application

Le dessin par coordonnées place chaque bloc de texte, ligne et image aux positions que vous spécifiez. Il offre un contrôle exact sur une conception fixe et ne nécessite aucun moteur de rendu au-delà de la bibliothèque. Le coût apparaît lorsque la longueur du contenu varie, car la pagination devient le travail de votre code : vous suivez où le dernier élément s'est terminé, ajoutez des pages vous-même et recalculez les positions lorsque le contenu change. Un court extrait montre le schéma.

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
}

L'étape importante consiste à suivre la page renvoyée par le résultat de la mise en page : continuez à dessiner sur la page indiquée par le widget et ajoutez une nouvelle page lorsque le cadre atteint le bas. Les rapports construits à partir d'un DataTable disposent de leur propre tutoriel DataTable vers PDF.

La mise en page en flux natif retire la pagination de votre code. PdfContentBuilder, disponible depuis Spire.PDF for .NET 12.9.18, diffuse le contenu dans des sections et pagine au fur et à mesure de sa croissance. Il propose des titres, des paragraphes, des tableaux construits à partir d'un string[][], des images, des listes, des blocs de code, six types de graphiques, des sauts de page et une table des matières. Il crée uniquement de nouveaux documents, sans point d'entrée pour charger un fichier existant.

Le rapport QA mensuel ci-dessous utilise deux sections et un tableau. summaryParagraphs, results (un string[][] dont la première ligne contient l'en-tête) et closing proviennent de votre propre code.

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();

Le volume de contenu différencie les deux approches. Un petit rapport (deux sections, un tableau de cinq lignes) a produit deux pages en 676 ms. Un rapport plus volumineux avec huit longs paragraphes et un tableau de 40 lignes a été paginé sur cinq pages en 1 369 ms (10,8 Ko). Le même contenu dessiné avec des coordonnées a donné trois pages en 510 ms (28,7 Ko). Ces durées proviennent d'une seule machine Windows et servent de contrôle de bon sens pour cette configuration. Comparez l'aspect de chaque fichier avant de comparer sa vitesse d'exécution.

Le dessin par coordonnées convient aux pages dont la structure ne dépend pas du volume de données. La mise en page en flux convient aux documents dont la longueur suit les données, comme les rapports et les listings. Les développeurs qui souhaitent plus de détails sur la composition manuelle peuvent partir du tutoriel de création d'un document PDF en C#.

La mise en page en flux natif et le rendu HTML sont des mécanismes distincts. Le générateur organise le contenu via sa propre API et ne lit pas le CSS, tandis qu'un moteur de rendu HTML analyse le balisage et les feuilles de style : les options de style et les exigences d'exécution diffèrent donc. Le tableau compare chaque flux de travail de ce guide.

3. Convertir HTML et CSS en PDF

Pour générer un PDF à partir de HTML en C#, Spire.PDF transmet la page à un moteur de rendu et enregistre le résultat imprimé. Deux moteurs sont disponibles. ChromeHtmlConverter pilote Chromium et prend le chemin d'un exécutable Chrome ou Edge. L'option Qt, Spire.Additions.Qt.HtmlConverter, dépend du paquet officiel de plugins, qui contient HTMLConverter.dll, le runtime Qt5 et Html2Pdf.exe. Le dossier des plugins doit être placé à côté de l'exécutable de l'application. S'il manque, l'appel échoue avec Fail to load ...\plugins\HTMLConverter.dll : error 126.

Les tests ont envoyé le même HTML dans les deux moteurs. Tous deux ont produit deux pages et respecté le CSS page-break-before. L'exécution Qt a pris 4 398 ms et a écrit un fichier de 60,6 Ko avec l'arrière-plan bleu foncé de l'en-tête du tableau intact. L'exécution Chromium a utilisé Edge 157.0.4341.42, du papier A4 et des marges de 0,4 pouce, en réutilisant le navigateur déjà présent sur la machine.

Les deux voies présentent des compromis différents. Qt exige une installation séparée de plugin, tandis que Chromium réutilise une installation de Chrome ou Edge. Chaque moteur applique ses propres règles pour l'impression des arrière-plans CSS, et la feuille de style décide de ce qui est demandé, par exemple avec print-color-adjust: exact. Dans une application web, exécutez la conversion comme tâche en arrière-plan plutôt qu'à l'intérieur de la requête.

Plusieurs points n'ont pas été couverts : les pages qui dépendent de JavaScript pour s'afficher, les ressources externes, les polices personnalisées, la charge concurrente sur un serveur, et Linux ou Docker. Un convertisseur qui fonctionne sur une machine de développement n'a pas démontré qu'il fonctionne dans un conteneur de production, et ce guide n'a pas vérifié Linux. Pour des pages pilotées par modèle avec une procédure complète, consultez générer un PDF à partir d'un modèle HTML en C#.

4. Travailler avec des formulaires et modèles PDF existants

Créer un PDF à partir d'un modèle en C# signifie deux choses différentes lorsque le modèle est déjà un PDF. Un formulaire remplissable contient des objets de champ AcroForm nommés. Une page conçue peut ne contenir qu'un texte de substitution qui ressemble à un champ vide. Ils se ressemblent à l'écran et se comportent différemment dans le code.

Un véritable champ est localisé par nom, rempli et éventuellement aplati. L'API AcroForm de l'espace de noms Spire.Pdf.Interactive.Forms est arrivée en 12.10.7 et a été testée en 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");

Trois comportements sont apparus lors des tests :

1. Appelez RefreshAppearances() après avoir défini Text, afin que la valeur soit dessinée dans l'apparence du champ et s'affiche immédiatement.
2. Les valeurs des champs encore interactifs vivent dans la couche de formulaire ; après aplatissement, le nombre de champs est passé de 4 à 0 et les valeurs ont rejoint le texte de la page, où PdfTextExtractor les lit.
3. AddWidget utilise des coordonnées au niveau de la page, tandis que les positions de page.Canvas sont relatives aux marges ; gardez les deux systèmes distincts lors du placement des widgets.

Les données de formulaire peuvent aussi quitter le fichier au format XFDF via form.ExportData(path, DataFormat.XFDF, ...), qui a produit du XFDF standard lors des tests. Le tutoriel d'importation et d'exportation des données de formulaire PDF approfondit le sujet.

Le texte de substitution fixe fonctionne sur une page terminée lorsque les valeurs insérées sont de taille proche des repères qu'elles remplacent. Le remplacement conserve la mise en page d'origine : vérifiez donc que chaque nouvelle valeur tient dans l'espace laissé par l'original.

Les formulaires XFA constituent un type de formulaire distinct. La capacité documentée consiste à lire et modifier les champs pris en charge via l'objet de formulaire XFA ; validez le flux de travail avec vos propres exemples dans le cadre de l'évaluation.

5. Déploiement et validation de la sortie

Tout ce qui figure dans ce guide a été exécuté sur une machine de développement Windows. Linux, Docker et l'hébergement sur serveur n'ont pas été vérifiés dans ce guide. Les moteurs HTML nécessitent le plus d'attention ailleurs : la voie Chromium a besoin d'un exécutable de navigateur sur la machine cible, et la voie Qt a besoin de son dossier de plugins à côté de l'application. Spire.PDF publie des paquets de plugins officiels pour Linux et macOS. Testez-les dans votre propre image de déploiement avant de vous y fier, et mesurez le temps de conversion sur l'hôte cible, car les durées ci-dessus proviennent d'une machine de développement.

Les problèmes de génération déclenchent rarement des exceptions : le fichier est produit, et tout ce qui a mal tourné n'apparaît que dans la sortie elle-même. C'est pourquoi les vérifications ci-dessous inspectent le fichier plutôt que de se fier à l'exécution du code sans erreur.

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'extraction de texte ne remplace pas l'examen visuel des pages. Elle confirme que des caractères existent dans le fichier, mais ne dit rien sur le débordement, le rognage ou un arrière-plan d'en-tête qui ne s'est pas imprimé. Adaptez les vérifications au flux de travail : nombre de pages et contrôle visuel pour les sorties par coordonnées et en flux, contrôle visuel des arrière-plans pour les sorties HTML, et relecture via l'API avant aplatissement pour les formulaires. Pour les tâches de rapport, exécutez les trois premières vérifications dans votre pipeline de test et répétez le contrôle visuel chaque fois que le modèle ou la mise en page change. Conservez une sortie de référence par flux de travail et comparez-la après les mises à niveau de la bibliothèque, car chaque résultat ici est lié à la version 12.11.0.

6. FAQ

Quelle est la différence entre créer et générer un PDF en C# ?

Au niveau de l'API, il n'y en a aucune. Les deux expressions décrivent la production d'un fichier PDF à partir de code. Ce qui compte, c'est l'entrée : des données d'application, une page HTML ou un PDF existant avec des champs ou du texte de substitution. Choisissez le flux de travail en fonction de cette entrée, comme le montre le tableau de décision de ce guide.

Puis-je générer un PDF en C# sans bibliothèque ?

Techniquement oui, car le PDF est un format de fichier documenté que le code peut écrire directement. En pratique, le coût se reporte sur l'intégration des polices, la compression des flux, la prise en charge de l'extraction de texte et la cohérence du rendu entre les visionneuses. Chacun de ces points nécessite son propre code et ses propres tests, et une bibliothèque absorbe ce travail.

Comment choisir entre création par code et rendu HTML ?

Décidez selon qui maîtrise la mise en page. Si ce sont les développeurs et que les données façonnent la structure, créez le PDF par code. Si les designers maintiennent déjà le HTML et le CSS, effectuez le rendu de cette page et acceptez la dépendance au moteur de rendu. Choisissez le code lorsque les données définissent la page, et le HTML lorsqu'une page définit la sortie.

7. Conclusion

Les données d'application orientent vers le dessin par coordonnées ou la mise en page en flux natif, et la mise en page en flux s'est paginée d'elle-même lors des tests. Une page HTML oriente vers un moteur de rendu, qui lors des tests a modifié le temps de conversion, l'impression des arrière-plans et les besoins de la machine cible. Un PDF existant oriente vers les champs de formulaire lorsqu'ils existent, et vers le remplacement de texte lorsque la mise en page est fixe. Vérifiez le nombre de pages, le texte extrait et les pages rendues avant l'envoi de l'un de ces fichiers.

Si vous devez tester Spire.PDF for .NET dans un environnement professionnel réel, vous pouvez demander une licence temporaire.

Voir aussi

• Comment créer des PDF en C# : de zéro, HTML et modèles
• Générer un PDF à partir d'un modèle HTML en C# – Tutoriel complet
• Transformer des DataTables en rapports PDF professionnels avec C#
• Comment créer un PDF dans ASP.NET et ASP.NET Core avec C#