Comment créer des documents PDF en C# et VB.NET

Traduit par Bit Miracle. Article original de Vitaliy Shibaev

Mis à jour le 7 mai 2026

Cet article décrit différentes méthodes de création de documents PDF en .NET à l'aide de la bibliothèque Docotic.Pdf. Il s'agit d'une bibliothèque .NET C# pure, performante et sans dépendances externes, permettant de créer, modifier, convertir et traiter des documents PDF.

Dans les sections suivantes, je présente les principales méthodes de création de PDF avec Docotic.Pdf :

• Utilisation de l’API Core, qui offre un contrôle précis du texte, des graphiques et des éléments internes du PDF. Cette option est idéale pour les mises en page personnalisées, les documents riches en graphiques et les fonctionnalités avancées.
• Utilisation de l’API Layout de haut niveau, qui prend en charge les paragraphes, les tableaux, les en-têtes, les pieds de page et la pagination automatique. Cette API est idéale pour créer des documents structurés sans avoir à calculer manuellement les positions.
• Conversion de HTML en PDF avec prise en charge du SVG et d’autres formats web. Cette méthode est particulièrement utile si votre solution génère déjà des documents HTML et que vous avez besoin de versions PDF de ces fichiers HTML et CSS.
• Création de PDF à partir d’images. Cette méthode est utile pour les documents numérisés, les rapports basés sur des images, les reçus et tout flux de travail commençant par des images raster.
• Fusion ou division de PDF. Cette option est idéale pour assembler des rapports, traiter les fichiers téléchargés par les utilisateurs, combiner des documents associés et restructurer les PDF volumineux.
• Création de PDF à partir de modèles. Cette approche est idéale lorsqu'une mise en forme uniforme est requise pour les documents générés par lots, tels que les reçus, les formulaires fiscaux, les contrats de travail et autres documents récurrents.

Ce guide aborde également les points suivants :

• Fonctionnalités interactives : liens et actions JavaScript
• Méthodes pour tester la sortie PDF afin de garantir des résultats conformes aux attentes

Création de PDF avec l'API principale

L'API Core est la base de la création de PDF dans Docotic.Pdf. Elle offre un contrôle total et précis sur le placement de texte, d'images et de graphiques vectoriels sur un canevas PDF grâce à son API Canvas. Cette API de dessin, sous-ensemble de l'API Core, fournit les méthodes et propriétés permettant d'ajouter du contenu aux pages et autres objets dotés d'un canevas. Outre le rendu, l'API Core prend également en charge les annotations, les champs de formulaire, les calques, les signets et d'autres fonctionnalités PDF.

Voici un exemple de code C# qui crée un PDF simple à l'aide de trois opérations fondamentales : le dessin de texte, l'insertion d'une image et le rendu de graphiques vectoriels sur un canevas.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Font = pdf.CreateFont(PdfBuiltInFont.HelveticaBold);
canvas.FontSize = 14;
canvas.DrawString(40, 100, "Core API demo: text, images, and vector graphics");

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 40, 180, 120, 120, 0);

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 2;
canvas.Brush.Color = new PdfRgbColor(200, 230, 255);
canvas.DrawRectangle(new PdfRectangle(200, 200, 150, 80), PdfDrawMode.FillAndStroke);

pdf.Save("core-api-demo.pdf");

Cet aperçu ne présente qu'une petite partie des possibilités offertes par l'API Core. Pour des sujets plus avancés, consultez l'article détaillé sur la création de PDF avec l'API Core. Cet article aborde la mesure du texte, la gestion des espaces colorimétriques, le détourage, le remplissage de zones avec des motifs, la gestion de la transparence et d'autres fonctionnalités.

Générer des PDF avec l'API Layout

L'API Layout est un moteur de création de documents de haut niveau qui offre la méthode la plus simple et la plus efficace pour générer des PDF complexes et riches en contenu.

Avec cette API, vous composez des PDF à partir d'éléments structurels tels que des pages, des conteneurs, des blocs de texte, des images, des tableaux, des liens, des en-têtes, des pieds de page, etc. Au lieu de calculer des coordonnées ou de gérer manuellement la pagination, vous décrivez la structure du document et laissez le moteur de mise en page se charger du reste.

Cet exemple illustre la création d'un PDF à l'aide de l'API Layout, en utilisant une mise en page déclarative plutôt qu'un positionnement manuel.

PdfDocumentBuilder.Create()
    .Info(info => info.Title = "Docotic.Pdf Layout API demo")
    .Generate("layout-api-demo.pdf", doc => doc.Pages(pages =>
    {
        pages.Content().Padding(100).Text(text =>
        {
            text.Span("The Layout API lets you compose PDFs from structural elements ");
            text.Line("without manually calculating coordinates or handling pagination.")
                .Style(s => s.Strong);
        });
    }));

Consultez le guide détaillé pour apprendre comment utiliser l'API Layout lors de la génération de PDF dans les applications .NET.

Conversion de contenu web avec l'API HTML vers PDF

Docotic.Pdf, associé à son extension gratuite HtmlToPdf, offre un moteur HTML vers PDF moderne et performant, basé sur Chrome. Grâce à l'API fournie par l'extension, vous pouvez convertir du HTML moderne et d'autres contenus web, tels que des images SVG ou WebP, en documents PDF de haute qualité.

L'API HTML vers PDF permet de créer des PDF à partir de pages HTML complètes ou de fragments HTML. Vous pouvez convertir du contenu provenant d'URL, de chaînes HTML brutes et de fichiers HTML locaux. Ces deux dernières options facilitent la génération de PDF à partir de modèles HTML.

Voir un exemple de génération d'un PDF à partir d'un modèle HTML :

public static async Task HelloHtmlTemplate()
{
    static string GetUserName()
    {
        // Replace with real logic: form input, API call, config, etc.
        return "World";
    }

    string html = $@"
        <h1>Hello, {GetUserName()}!</h1>
        <p>This PDF was generated from an HTML template.</p>";

    using var converter = await HtmlConverter.CreateAsync();
    using var pdf = await converter.CreatePdfFromStringAsync(html);
    pdf.Save("hello-html-template.pdf");
}

Pour plus de détails et d'exemples, consultez notre aperçu détaillé de HTML vers PDF.

Création de PDF à partir d'images

Docotic.Pdf offre une solution flexible et conviviale pour les développeurs afin de convertir des images en PDF. La bibliothèque prend en charge les formats d'image JPEG, BMP, GIF, PNG, TIFF et JPEG 2000 via son API principale.

Lorsque le format PDF le prend en charge, Docotic.Pdf intègre les octets des images tels quels, évitant ainsi le décodage et le réencodage des pixels afin de préserver la compression d'origine. La bibliothèque préserve également l'espace colorimétrique lorsque cela est possible.

De plus, les formats SVG et WebP sont pris en charge via l'API HTML vers PDF. Pour insérer des images à côté d'étiquettes ou de descriptions, l'API Layout vous permet d'agencer et d'aligner les éléments très facilement.

Comment combiner plusieurs images en un seul PDF

Avec Docotic.Pdf, vous pouvez facilement convertir un ensemble d'images en un seul PDF, en plaçant une image par page.

L'exemple ci-dessous charge des images à partir de fichiers et les affiche chacune sur sa propre page. Chaque image est redimensionnée pour s'adapter à la page et centrée pour une mise en page claire et harmonieuse.

public static void ImagesOnToPdf(string[] imagePaths, string outputPath)
{
    using var pdf = new PdfDocument();

    foreach (string path in imagePaths)
    {
        var image = pdf.CreateImage(path);

        var page = pdf.AddPage();
        var pageWidth = page.Width;
        var pageHeight = page.Height;

        var scale = Math.Min(pageWidth / image.Width, pageHeight / image.Height);
        var drawWidth = image.Width * scale;
        var drawHeight = image.Height * scale;
        var x = (pageWidth - drawWidth) / 2;
        var y = (pageHeight - drawHeight) / 2;

        page.Canvas.DrawImage(image, x, y, drawWidth, drawHeight, 0);
    }

    pdf.RemovePage(0);

    pdf.Save(outputPath);
}

Gestion des images TIFF et GIF multipages

Docotic.Pdf prend entièrement en charge les fichiers TIFF et GIF multipages. Lors de l'ajout d'images à un PDF, utilisez la méthode OpenImage plutôt que CreateImage si certaines images peuvent contenir plusieurs pages.

Le code suivant illustre la conversion d'un fichier TIFF en PDF ; il fonctionne aussi bien pour les images monopages que pour les images multipages.

public static void OddFramesToPdf(string[] imagePaths, string outputPath)
{
    using var pdf = new PdfDocument();
    foreach (string path in imagePaths)
    {
        var imageFrames = pdf.OpenImage(path);
        for (int i = 0; i < imageFrames.Count; i++)
        {
            if (i % 2 != 0)
                continue;

            var image = pdf.CreateImage(imageFrames[i]);
            var page = pdf.AddPage();

            page.Width = image.Width;
            page.Height = image.Height;

            page.Canvas.DrawImage(image, 0, 0, image.Width, image.Height, 0);
        }
    }

    pdf.RemovePage(0);

    pdf.Save(outputPath);
}

Vous pouvez utiliser la même méthode pour convertir un GIF en PDF. Elle s'applique également à d'autres formats d'image, bien qu'elle soit plus complexe que nécessaire pour les formats ne contenant qu'une seule image.

Fusion et division de fichiers PDF

Docotic.Pdf, une bibliothèque .NET complète, permet de créer de nouveaux PDF en fusionnant, extrayant et réorganisant les pages de documents existants.

Lors de la fusion de PDF, la bibliothèque ajoute non seulement les pages d'un autre document, mais aussi les calques, les signets, les étiquettes de page, le JavaScript partagé, les destinations (cibles des liens) et les fichiers incorporés. Pour plus de détails et des conseils sur la réduction de la taille des PDF fusionnés, consultez l'article sur la fusion de PDF.

Les PDF signés numériquement ne peuvent pas être fusionnés sans invalider leurs signatures existantes. Pour conserver les signatures, créez un portefeuille PDF au lieu d'ajouter des documents. Une autre option consiste à fusionner d'abord les PDF, puis à appliquer une nouvelle signature numérique au document fusionné.

Docotic.Pdf vous permet également de copier et d'extraire des pages dans de nouveaux documents. Tout le contenu associé aux pages copiées est conservé, y compris les annotations, les contrôles de formulaire, le contenu structuré, les calques et autres données connexes. Pour des exemples pratiques, consultez l'article sur la division des PDF en .NET. Il explique également comment extraire ou supprimer des pages.

Utilisation des modèles PDF

Les modèles PDF sont des fichiers PDF prédéfinis servant de structure de base pour la création de nouveaux documents. Ils sont utiles pour produire des PDF à la mise en page homogène, même avec des données différentes. Si vous souhaitez dissocier la conception visuelle des données elles-mêmes, les modèles PDF constituent également une excellente solution.

Les modèles peuvent être des PDF avec formulaires ou des PDF statiques sans formulaires. Les deux types ont la même fonction. De plus, les modèles avec formulaires incluent des éléments interactifs qui, s'ils ne sont pas aplatis, permettent de recueillir des informations auprès des utilisateurs.

Création de PDF à partir de modèles basés sur des formulaires

Les modèles basés sur des formulaires contiennent généralement des AcroForms, le type standard et largement répandu de formulaire PDF interactif. Pour générer un PDF à partir d'un tel modèle, il faut généralement :

• remplir chaque champ d'espace réservé
• aplatir les champs pour empêcher toute modification ultérieure
• enregistrer le résultat dans un nouveau PDF

Voici un exemple de code C# qui recherche un champ de texte d'espace réservé par son nom, lui attribue une valeur, aplatit le champ et enregistre le résultat, créant ainsi un PDF à partir du modèle :

var nameOnCertificate = "Eva Marin";
using var pdf = new PdfDocument("certificate-template.pdf");
if (pdf.TryGetControl("name", out var field))
{
    if (field is PdfTextBox nameField)
    {
        nameField.Text = nameOnCertificate;
        nameField.Flatten();
    }
}

pdf.Save($"certificate-{nameOnCertificate}.pdf");

Si votre modèle contient de nombreux espaces réservés, vous pouvez importer des données FDF au lieu de remplir chaque champ individuellement. Vous pouvez également utiliser PdfDocument.FlattenControls pour aplatir tous les champs en une seule fois.

Création de PDF à partir de modèles statiques sans formulaires

Si votre modèle ne contient pas de champs de formulaire, vous devrez dessiner les noms et autres données directement sur la page. Les modèles PDF statiques contiennent généralement des espaces réservés visuels fixes, tels que du texte, des images ou des zones vides. Pour générer un PDF à partir de ce modèle, vous devrez remplir ces zones vides et remplacer le texte et les images par programmation.

Zones vides

Utilisez l'API Canvas pour placer du texte et des images dans les zones vides. Dans les cas simples, lorsque vous n'avez besoin que de modifications mineures, comme l'ajout d'un nom et d'une photo, cette approche est idéale. Vous devez connaître les coordonnées et la taille des zones, et pour positionner correctement le texte, il peut être nécessaire de le mesurer au préalable, puis de l'aligner en conséquence.

Travailler avec du texte de longueur variable ou multiligne est plus complexe, mais reste possible. En combinant DrawText, DrawString et les méthodes de mesure du texte, vous pouvez gérer le retour à la ligne et positionner les lignes selon vos besoins. Si votre modèle contient plusieurs zones de ce type, envisagez une autre approche, comme la génération de PDF avec l'API Layout.

Texte de remplacement

Docotic.Pdf propose également des méthodes pour rechercher et remplacer du texte. Cependant, utiliser la recherche de texte comme mécanisme de création de modèles n'est généralement pas plus simple que de travailler avec des zones vides. Avant d'insérer un nouveau contenu, vous devez localiser précisément le fragment de texte et le supprimer proprement.

Images de substitution

Les modèles statiques peuvent inclure des images de substitution pour les avatars des utilisateurs ou les photos de produits. Pour trouver une image de substitution, parcourez la collection d'images affichées sur chaque page. Pour chaque image affichée, vous pouvez obtenir sa taille et sa position visibles. Pour remplacer l'image de substitution, utilisez PdfImage.ReplaceWith.

using var pdf = new PdfDocument("invoice-template.pdf");
var paintedImages = pdf.Pages[0].GetPaintedImages();

var placeholder = paintedImages.First();
placeholder.Image.ReplaceWith("company-logo.jpg");

pdf.Save($"invoice.pdf");

Une autre option consiste à dessiner une nouvelle image par-dessus la zone occupée par l'image de remplacement, mais cela augmente généralement la taille du PDF résultant sans raison valable.

Conception d'espaces réservés pour un remplacement facile

Pour les modèles statiques, il est conseillé de concevoir la mise en page avec des zones prévisibles et bien définies pour le texte et les images. Prévoyez un espacement suffisant autour des zones contenant du contenu de longueur variable et utilisez des images de substitution neutres dont les proportions correspondent à celles des images que vous prévoyez d'insérer ultérieurement.

Si votre modèle utilise du texte de substitution que vous prévoyez de remplacer, vous pouvez simplifier le processus en utilisant des zones de texte plutôt que du texte brut. Ajoutez une zone de texte en lecture seule et sans bordure au modèle et insérez-y le texte de substitution. Lors de la génération du PDF final, ouvrez le modèle, localisez la zone de texte par son nom et attribuez-lui directement la nouvelle valeur avec box.Text = "nouveau texte";. Enfin, aplatissez la zone de texte pour empêcher toute modification ultérieure.

Ajout d'éléments interactifs

Les fonctionnalités interactives transforment un PDF statique en un document dynamique et facile à parcourir, enrichi d'annotations et de balises. Les actions et JavaScript permettent l'automatisation directement dans le PDF.

Annotations

Les annotations sont des objets ajoutés à une page et représentant des commentaires, des surlignages, des pièces jointes et d'autres éléments interactifs. Elles sont visibles dans le contenu de la page et facilitent les processus de révision et la collaboration.

L'exemple C# suivant montre comment ajouter des annotations textuelles, également appelées notes adhésives, à une page PDF à l'aide de Docotic.Pdf.

using var pdf = new PdfDocument("example.pdf");
var page = pdf.Pages[0];

var textAnnot = page.AddTextAnnotation(new PdfPoint(50, 100), "Reviewer comment");
textAnnot.Contents = "Please check the figures on this page.";

pdf.Save("text-annotation.pdf");

L'exemple suivant montre comment mettre en évidence du texte et d'autres contenus pour attirer l'attention sur les parties clés d'un document.

using var pdf = new PdfDocument("example.pdf");
var page = pdf.Pages[0];

var color = new PdfRgbColor(255, 255, 120);
var annotationText = "Please confirm this part.";
var bounds = new PdfRectangle(50, 250, 120, 40);
page.AddHighlightAnnotation(annotationText, bounds, color);

pdf.Save("highlight-annotation.pdf");

Links

Les normes PDF définissent plusieurs types de liens. Les plus importants et les plus utilisés sont les liens internes et les hyperliens.

Les liens internes, également appelés actions GoTo, permettent d'accéder directement à une page ou à une destination nommée au sein du même PDF. Ils sont utiles pour les renvois et la navigation interne.

Voici un exemple de code C# qui crée un lien de la première page vers la page d'index 5 :

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

int targetPageIndex = 5;
for (int i = 0; i < targetPageIndex; i++)
    pdf.AddPage();

var rect = new PdfRectangle(50, 50, 100, 40);
page.Canvas.DrawRectangle(rect);
page.AddLinkToPage(rect, targetPageIndex);

pdf.Pages[targetPageIndex].Canvas.DrawString(50, 50, "Glad to have you here.");

pdf.Save("link-to-page.pdf");

L'API Layout offre une autre méthode pour créer des liens internes, sans nécessiter de positionnement absolu.

Les liens externes, également appelés actions URI, ouvrent une URL web. Vous pouvez ajouter un lien hypertexte à une page PDF à l'aide de la méthode PdfPage.AddHyperlink. La procédure est par ailleurs identique à celle des liens internes.

Signets

Les signets, aussi appelés plans, sont des raccourcis ou des liens spéciaux qui permettent aux lecteurs d'accéder rapidement à des sections ou des pages spécifiques. Lorsqu'un lecteur clique sur un signet, l'application de visualisation se dirige vers la partie correspondante du document.

Les plans apparaissent dans le panneau des signets de l'application et offrent une arborescence de navigation hiérarchique, interactive, semblable à une table des matières. Les plans des PDF peuvent inclure des signets principaux et des signets imbriqués, ce qui facilite la structuration des documents volumineux.

L'exemple suivant montre comment créer des signets dans un PDF à l'aide de C# et de Docotic.Pdf. Le code crée trois signets de premier niveau. Le deuxième signet contient un signet imbriqué.

using var pdf = new PdfDocument();

for (int i = 0; i < 5; i++)
{
    var page = i == 0 ? pdf.Pages[0] : pdf.AddPage();

    var canvas = page.Canvas;
    canvas.FontSize = 14;
    canvas.DrawString(50, 50, $"Page {i + 1}");
}

var root = pdf.OutlineRoot;
root.AddChild("Getting Started", 1);

var child = root.AddChild("Things You Can Do", 2);
child.AddChild("Making Quick Improvements", 3);

root.AddChild("Keeping Everything Running Smoothly", 4);

pdf.PageMode = PdfPageMode.UseOutlines;

pdf.Save("bookmarks.pdf");

Les signets diffèrent des tables des matières que l'on trouve dans un livre papier ou un PDF. Vous pouvez créer une table des matières par programmation en dimensionnant les titres et en ajoutant des numéros de page.

Pour découvrir une autre méthode de création d'une table des matières à l'aide de l'API Layout, consultez le code correspondant dans notre dépôt d'exemples.

Scripting PDF

Les actions JavaScript comptent parmi les fonctionnalités interactives les plus puissantes. JavaScript pour PDF est un sous-ensemble de JavaScript qui expose des API pour les documents et les visionneuses. Il est utilisé pour la validation de formulaires, les calculs, les boîtes de dialogue d'interface utilisateur et les petites tâches d'automatisation.

Vous pouvez associer des scripts à des annotations, des signets, des contrôles de formulaire ou des actions d'ouverture. Avec Docotic.Pdf, vous pouvez intégrer du code JavaScript dans un PDF. Ce code peut valider les données saisies dans un formulaire, calculer des valeurs, afficher ou masquer des champs ou interagir avec la visionneuse.

La collection de JavaScript partagé contient des scripts stockés au niveau du document. Ces scripts peuvent être réutilisés par plusieurs actions. En d'autres termes, les scripts partagés sont utiles pour les fonctions utilitaires et la logique partagée. Ils contribuent à réduire la duplication et à simplifier la maintenance.

Le code ci-dessous définit un script partagé qui affiche un message d'alerte dans la visionneuse PDF, puis montre comment déclencher ce script en l'associant à l'action de clic du bouton.

using var pdf = new PdfDocument();

pdf.SharedScripts.Add(
    pdf.CreateJavaScriptAction("function messageBox(message) { app.alert(message,3); }")
);

var button = pdf.Pages[0].AddButton(50, 50, 100, 40);
button.Text = "Click me";
button.OnMouseUp = pdf.CreateJavaScriptAction("messageBox('Hello, dear!');");

pdf.Save("shared-javascript.pdf");

Le script de l'exemple est simple, mais vous pouvez créer des actions JavaScript de toute complexité. La documentation de l'API JavaScript d'Adobe fournit de nombreuses méthodes utilisables. Notez que les visionneuses non Adobe ne prennent généralement en charge qu'une partie de l'API.

Actions ouvertes

Une action d'ouverture est une action exécutée par le lecteur PDF à l'ouverture du document. Elle peut notamment permettre d'ouvrir le document à une page spécifique, d'exécuter une routine d'initialisation JavaScript ou de définir les préférences du lecteur. Le type d'action d'ouverture est libre.

L'exemple suivant montre comment créer une action d'ouverture GoTo. Le code ajoute du texte à la deuxième page et configure une action d'ouverture qui permet au lecteur d'accéder automatiquement à cette page à l'ouverture du PDF.

using var pdf = new PdfDocument();

var canvas = pdf.AddPage().Canvas;
canvas.FontSize = 14;

var message =
    "If you see this immediately after opening the file, " +
    "your PDF viewer supports open actions.";
var options = new PdfTextDrawingOptions(new PdfRectangle(100, 100, 100, 150));
canvas.DrawText(message, options);

pdf.OnOpenDocument = pdf.CreateGoToPageAction(1, 0);

pdf.Save("open-action.pdf");

Notez que tous les visualiseurs n'exécutent pas les actions d'ouverture JavaScript. Certains les ignorent ou demandent confirmation à l'utilisateur. D'autres les bloquent complètement.

Pour vérifier si un PDF contient une action d'ouverture, chargez-le dans un objet PdfDocument et examinez la propriété OnOpenDocument. Si cette propriété est nulle, aucune action d'ouverture n'est définie pour ce document.

Application du chiffrement et des signatures numériques

Le chiffrement et les signatures numériques couvrent deux aspects complémentaires de la sécurisation des PDF que vous créez. Le chiffrement contrôle qui peut ouvrir un document et quelles actions il peut effectuer, tandis que les signatures prouvent qui a créé ou approuvé le fichier et confirment qu'il n'a pas été modifié.

La protection par mot de passe vous permet de définir des règles d'accès dès la création. Vous pouvez attribuer un mot de passe d'ouverture pour restreindre la consultation et un mot de passe propriétaire pour définir des autorisations telles que l'impression, la copie, la modification ou le remplissage de formulaires. Le chiffrement par certificat offre une protection renforcée et spécifique au destinataire, et s'avère particulièrement efficace pour la distribution de PDF confidentiels à plusieurs personnes sans utiliser de mot de passe partagé. Pour plus de détails, consultez l'article sur le chiffrement des PDF par mot de passe et certificat.

Les signatures numériques ajoutent authenticité et intégrité au moment de la création. Docotic.Pdf peut signer des PDF à l'aide de certificats provenant de fichiers, du Microsoft Store, de jetons matériels, de modules de sécurité matériels (HSM) ou de services de clés cloud. Vous pouvez inclure des horodatages et des données de validation à long terme afin que les signatures restent vérifiables longtemps après la production du document. Les flux de signature externes, notamment PKCS#11 et les services de gestion de clés cloud (KMS), sont également pris en charge.

Définition des métadonnées PDF

Les métadonnées PDF sont des informations descriptives intégrées à un document, telles que le titre, l'auteur, le sujet, les mots-clés, la date de création et d'autres champs similaires. Elles permettent aux logiciels, aux moteurs de recherche et aux systèmes de gestion documentaire de comprendre le contenu d'un fichier sans avoir à l'ouvrir.

Un document PDF peut contenir des métadonnées dans deux systèmes coexistants :

• Métadonnées XMP
• Dictionnaire d'informations du document (dictionnaire Info)

XMP est le format plus riche, structuré et normalisé pour l'intégration de métadonnées descriptives. Le dictionnaire Info est simple et largement pris en charge, mais limité ; il est déconseillé dans la norme PDF 2.0 (ISO 32000-2) au profit des métadonnées XMP. Docotic.Pdf peut lire et écrire dans les deux systèmes et propose une méthode d'assistance pour les synchroniser.

Docotic.Pdf met à jour automatiquement certaines métadonnées avant l'enregistrement d'un fichier PDF. Par exemple, la bibliothèque définit par défaut les valeurs du Producteur et du Créateur. Utilisez les options d'enregistrement pour modifier ce comportement et conserver les valeurs de métadonnées définies explicitement.

Métadonnées XMP

Utilisez la propriété PdfDocument.Metadata pour accéder aux métadonnées XMP d'un PDF et les modifier. Cette propriété vous permet de gérer des schémas courants tels que XMP Core, Dublin Core et le schéma PDF, ainsi que vos propres métadonnées personnalisées.

using var pdf = new PdfDocument();
var xmp = pdf.Metadata;

xmp.Pdf.Creator = new XmpString("Second-line authoring terminal");
xmp.Pdf.Title = new XmpString("Quarterly Report");

var creators = new XmpArray(XmpArrayType.Ordered);
creators.Values.Add(new XmpString("Second-line authoring terminal"));
creators.Values.Add(new XmpString("Assistive authoring terminal"));
xmp.DublinCore.Creators = creators;

var descriptions = new XmpArray(XmpArrayType.Alternative);
descriptions.Values.Add(new XmpLanguageAlternative("x-default", "Quarterly Report"));
descriptions.Values.Add(new XmpLanguageAlternative("fr", "Rapport trimestriel"));
descriptions.Values.Add(new XmpLanguageAlternative("de", "Quartalsbericht"));
xmp.DublinCore.Descriptions = descriptions;

var author1 = new XmpString("First Author");
author1.Qualifiers.Add("role", "main author");

var author2 = new XmpString("Second Author");
author2.Qualifiers.Add("role", "co-author");

var authors = new XmpArray(XmpArrayType.Unordered);
authors.Values.Add(author1);
authors.Values.Add(author2);
xmp.Custom.Properties.Add("authors", authors);

pdf.Save("with-xmp-metadata.pdf");

XMP prend en charge les tableaux, les structures et les valeurs typées, ce qui le rend idéal pour les métadonnées riches. Le code ci-dessus montre également comment stocker les propriétés spécifiques à l'application dans le schéma XMP personnalisé.

Dictionnaire d'informations sur les documents

Le dictionnaire Info stocke principalement des chaînes de caractères. Compact et largement compatible, il présente toutefois des limitations. Utilisez le dictionnaire Info pour assurer la compatibilité avec les outils plus anciens et privilégiez XMP dans les autres cas.

Synchronisation des métadonnées

Il est recommandé de synchroniser les deux systèmes de métadonnées afin d'éviter les incohérences susceptibles de perturber les lecteurs et les outils automatisés.

Utilisez PdfDocument.SyncMetadata pour aligner les valeurs XMP et Info afin que les champs correspondants correspondent. Cette méthode complète les propriétés Info manquantes à partir de XMP et, de même, renseigne les champs XMP manquants à partir de Info. Définissez preferXmp: true si XMP est votre source principale, ou false si le dictionnaire Info doit être prioritaire.

pdf.SyncMetadata(preferXmp: true);

Consultez la section Remarques de la documentation SyncMetadata pour obtenir des informations détaillées sur les propriétés que la méthode synchronise.

Configuration des étiquettes de page et des préférences du visualiseur

Un PDF nouvellement créé peut bénéficier d'une numérotation de pages explicite, de préférences d'affichage optimisées et d'une mise en page choisie pour présenter plus efficacement son contenu. Ces paramètres influencent la première impression du lecteur et sa navigation dans le fichier.

Étiquettes de page

Les étiquettes de page sont des métadonnées qui indiquent aux visionneuses de PDF quelle étiquette afficher pour chaque page. Utilisez-les lorsque la numérotation visible doit différer de l'index physique des pages. Par exemple, si vous souhaitez utiliser « i, ii, iii » pour les pages liminaires et « 1, 2, 3 » pour le corps du texte de votre PDF.

Ce code C# montre comment numéroter les pages d'un PDF : les trois premières pages sont en chiffres romains minuscules, et les suivantes en chiffres arabes à partir de 1.

using var pdf = new PdfDocument();

for (int i = 0; i < 8; i++)
    pdf.AddPage();

pdf.PageLabels.AddRange(0, 2, PdfPageNumberingStyle.LowercaseRoman);
pdf.PageLabels.AddRange(3, PdfPageNumberingStyle.DecimalArabic);

pdf.Save("with-page-labels.pdf");

Préférences du visualiseur PDF

Les préférences d'affichage des PDF sont des recommandations intégrées au document qui indiquent comment il doit être présenté. Par exemple, vous pouvez spécifier que le visualiseur doit masquer les barres d'outils, centrer la fenêtre ou l'adapter à la page. Ces préférences complètent la mise en page et les paramètres d'ouverture.

Voici comment modifier les préférences d'affichage des PDF avec Docotic.Pdf :

using var pdf = new PdfDocument();

pdf.ViewerPreferences.DisplayTitle = false;
pdf.ViewerPreferences.FitWindow = true;
pdf.ViewerPreferences.HideToolBar = true;
pdf.ViewerPreferences.HideMenuBar = true;
pdf.ViewerPreferences.HideWindowUI = true;
pdf.ViewerPreferences.CenterWindow = true;

pdf.Save("with-viewer-prefs.pdf");

Veuillez noter que, selon leur configuration, Adobe Acrobat et d'autres visionneuses peuvent ignorer ces préférences.

Mise en page et mode page

La mise en page détermine l'agencement des pages à l'ouverture du document : page par page, en une seule colonne ou sur deux pages. Le mode d'affichage contrôle les panneaux d'interface visibles à l'ouverture : signets/plans, pièces jointes, vignettes ou aucun.

Voici comment spécifier que le PDF créé doit s'afficher sur deux pages, page de gauche en premier, avec le panneau des vignettes visible à l'ouverture :

using var pdf = new PdfDocument();

for (int i = 0; i < 7; i++)
{
    var page = i > 0 ? pdf.AddPage() : pdf.Pages[0];
    page.Canvas.FontSize = 36;
    page.Canvas.DrawString(100, 100, $"Page {i + 1}");
}

pdf.PageLayout = PdfPageLayout.TwoPageLeft;
pdf.PageMode = PdfPageMode.UseThumbs;

pdf.Save("with-layout-and-mode.pdf");

Enregistrement des PDF

Docotic.Pdf peut générer différents fichiers PDF ou flux à partir d'un même document créé ou modifié. Ces sorties peuvent être conformes à différentes versions du format PDF, avoir une longueur en octets variable et nécessiter des quantités de mémoire différentes pour leur génération.

La manière dont la bibliothèque génère les octets d'un PDF dépend des options d'enregistrement. Si vous ne spécifiez pas explicitement d'options d'enregistrement, les méthodes Save, SignAndSave et TimestampAndSave d'un objet PdfDocument utilisent les paramètres par défaut. Ces paramètres par défaut sont soigneusement sélectionnés et conviennent à la plupart des cas, mais vous pouvez les ajuster.

Consultez la documentation de la classe PdfSaveOptions pour obtenir des informations détaillées sur les options disponibles et leurs valeurs par défaut. Les sections ci-dessous mettent en lumière certaines des options les plus importantes et fournissent des recommandations pratiques.

PDF version

Docotic.Pdf utilise par défaut les flux d'objets pour une meilleure compression des fichiers produits. De ce fait, la bibliothèque crée par défaut des fichiers et des flux PDF 1.5.

Pour visualiser les documents produits, il faut Adobe Reader 6 (sorti en 2003) ou une version ultérieure. Cela ne pose généralement pas de problème, sauf si vous devez assurer la compatibilité avec d'anciens outils, des visionneuses plus anciennes ou des appareils embarqués qui n'acceptent que les anciennes versions de PDF.

Voici comment enregistrer un fichier au format PDF antérieur :

using var pdf = new PdfDocument();

var options = new PdfSaveOptions
{
    Version = PdfVersion.Pdf14,
    UseObjectStreams = false,
};
pdf.Save("version-1.4.pdf", options);

Pour enregistrer au format PDF 1.4, les flux d'objets doivent également être désactivés. La bibliothèque n'utilisera pas une version antérieure si le document contient des fonctionnalités introduites dans des versions ultérieures.

Réduction de la taille des fichiers

Plusieurs options d'enregistrement, lorsqu'elles sont activées, permettent à Docotic.Pdf de générer des fichiers plus petits (en octets) : RemoveUnusedObjects, OptimizeIndirectObjects, WriteWithoutFormatting et UseObjectStreams.

Voici comment générer des PDF sans objets non référencés ni espaces superflus, avec des données regroupées de manière optimale dans des flux d'objets :

using var pdf = new PdfDocument();

var options = new PdfSaveOptions
{
    UseObjectStreams = true,
    RemoveUnusedObjects = true,
    OptimizeIndirectObjects = true,
    WriteWithoutFormatting = true,
};
pdf.Save("optimized.pdf", options);

Ces options sont plus efficaces lorsque le PDF est entièrement réécrit. Lors d'une sauvegarde incrémentale, elles ne s'appliquent qu'à la nouvelle révision et ne permettent pas de nettoyer ni d'optimiser les parties précédentes du fichier.

Mises à jour incrémentales

Docotic.Pdf permet la mise à jour incrémentale des fichiers PDF. Lorsque l'option WriteIncrementally est activée (true), la bibliothèque ajoute les modifications au fichier existant au lieu de le réécrire. Les références croisées et les données d'objet précédentes sont conservées. Ces données ajoutées constituent une mise à jour incrémentale, et la mise à jour actuelle, combinée à toutes les mises à jour précédentes, forme une nouvelle révision du fichier.

Les mises à jour incrémentales ne sont pas possibles pour les documents nouvellement créés, car il n'existe aucune révision précédente. La bibliothèque ignore cette option pour les nouveaux documents et les écrit en mode non incrémental.

Lorsque des mises à jour incrémentales sont nécessaires

Lors de l'ajout d'une nouvelle signature numérique à un document déjà signé, il est impératif d'enregistrer le fichier de manière incrémentielle. Il en va de même lors de la mise à jour d'un fichier précédemment signé avec de nouvelles annotations ou données de formulaire. Dans ces cas, la réécriture complète du fichier invaliderait les signatures existantes.

Par ailleurs, il est préférable d'effectuer une sauvegarde complète (non incrémentielle) avant d'appliquer la première signature numérique, afin que la version de référence signée soit un fichier propre et entièrement réécrit. La signature d'un document présentant des problèmes de structure dans les versions précédentes peut entraîner des problèmes de validation de signature inattendus.

L'ajout incrémentiel est également requis dans les flux de travail qui doivent conserver un historique des révisions traçable ou imposer un stockage des documents en mode ajout uniquement.

Avantages de l'utilisation des mises à jour incrémentales

Les mises à jour incrémentales permettent l'apposition de plusieurs signatures sur un même fichier et autorisent un nombre limité de modifications après signature, comme le remplissage de champs de formulaire, sans invalider les signatures existantes.

Cette approche offre également une sauvegarde plus rapide pour les modifications mineures, car seules les données modifiées sont enregistrées. Elle préserve aussi l'historique des révisions du document, essentiel pour les audits et autres processus de conformité.

Problèmes et pièges à éviter

Les mises à jour incrémentales ne peuvent pas appliquer de compression globale ni supprimer les objets obsolètes dans l'ensemble du fichier, car elles n'ajoutent que les objets modifiés. Par conséquent, elles produisent généralement des fichiers plus volumineux et moins optimisés qu'une réécriture complète.

La taille du fichier augmente à chaque révision, même en l'absence d'objets inutilisés, car toutes les révisions précédentes restent intégrées au fichier et continuent d'occuper de l'espace.

Les informations sensibles ou erronées des révisions antérieures restent récupérables, et les problèmes de format PDF ou les défauts structurels existants dans les révisions précédentes ne sont pas corrigés par l'ajout de nouvelles données.

Enfin, certains visualiseurs et outils de traitement ont des difficultés avec les PDF multi-révisions. Avant d'opter pour les mises à jour incrémentales, assurez-vous que tous les logiciels qui utilisent vos documents peuvent gérer les fichiers à révisions multiples.

Test de sortie PDF

Les tests PDF automatisés protègent les versions contre les régressions de contenu et de mise en page en comparant les PDF générés avec des PDF de référence stockés dans votre référentiel ou votre espace de stockage d'artefacts. Ces références vous aident à détecter les modifications accidentelles de texte, de polices, d'images ou de mise en page et réduisent le besoin d'assurance qualité manuelle à chaque compilation.

Pour des résultats optimaux, combinez les vérifications structurelles, l'extraction de texte et les comparaisons visuelles.

Comparaison rapide des approches

Comparaison de la structure des documents

Utilisez PdfDocument.DocumentsAreEqual pour comparer les graphes d'objets PDF, la version du PDF et le système de sécurité des documents (DSS), tout en ignorant les propriétés du document dépendant du temps. Cette méthode ignore également les métadonnées, les identifiants de fin de document et les autres propriétés générées automatiquement.

Elle est idéale pour les flux de travail de test de documents PDF qui doivent garantir qu'aucun objet inattendu n'a été ajouté ou supprimé. DocumentsAreEqual prend en charge les surcharges de type fichier et flux et peut comparer des PDF chiffrés.

Un exemple complet illustrant cette technique est disponible dans les exemples Docotic.Pdf. Outre l'utilisation de la méthode dans des applications .NET classiques, cet exemple montre également comment utiliser DocumentsAreEqual dans des applications AOT natives.

Vérification des PDF via du texte extrait

Extrayez le texte de l'intégralité du document en une seule fois ou page par page, puis comparez les chaînes de caractères. Vous pouvez affiner l'extraction grâce aux options dédiées, par exemple en excluant le rectangle contenant le pied de page. Pour faciliter la comparaison, vous pouvez segmenter le texte extrait en lignes ou en mots.

Pour les vérifications structurées, commencez par extraire le texte en conservant la position, la police et d'autres informations détaillées sur chaque segment, mot ou caractère. Comparez ensuite chaque élément extrait avec l'élément de référence correspondant.

Détection des différences visuelles

Commencez par convertir les pages PDF en images et comparez chaque image à l'image de référence. Utilisez des bibliothèques spécialisées comme ImageSharp.Compare ou Magick.NET pour détecter les différences entre les images.

Privilégiez une comparaison stricte pixel par pixel : chaque pixel correspondant des deux images doit être identique. Si vos exigences tolèrent de légères variations de rendu, vous pouvez ajuster la logique de comparaison pour accepter de petites différences, mais une égalité exacte des pixels offre les résultats les plus fiables.

Vous pouvez utiliser le hachage comme pré-vérification rapide pour déterminer si deux images sont probablement identiques sans effectuer une comparaison pixel par pixel complète. Calculez un hachage SHA-256 pour chaque image convertie ; si les hachages correspondent, les images sont presque certainement identiques. Si les hachages diffèrent, effectuez alors une comparaison pixel par pixel complète.

Conclusion

Docotic.Pdf offre une suite d'outils complète et multicouche pour la création et la manipulation de PDF en .NET. Les développeurs peuvent choisir entre un contrôle de bas niveau avec l'API Core, la génération de documents de haut niveau avec l'API Layout, ou la conversion HTML vers PDF pour les flux de travail déjà construits autour des technologies web.

La bibliothèque prend également en charge les PDF basés sur des images, la génération par modèles et un large éventail de fonctionnalités interactives telles que les annotations, les liens, les signets, les actions JavaScript et les actions d'ouverture.

Pour garantir la fiabilité, Docotic.Pdf inclut des méthodes permettant de tester la sortie PDF afin que les modifications apportées à votre application n'entraînent pas de régressions ou de différences inattendues.