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

Traduit par Bit Miracle. Article original de Vitaliy Shibaev

Mis à jour le 29 juin 2026

Cet article décrit différentes façons de créer des documents PDF dans .NET à l’aide de la bibliothèque Docotic.Pdf. Il s’agit d’une bibliothèque .NET C# pure et hautes performances, sans dépendances externes, pour créer, modifier, convertir et traiter des documents PDF.

Dans les sections suivantes, je présente les principales approches pour créer des PDF avec Docotic.Pdf :

• Utilisation du contrôle de bas niveau du Core API sur le texte, les graphiques et les éléments internes du PDF. Cette option convient le mieux aux mises en page personnalisées, aux documents riches en graphiques et aux fonctionnalités avancées.
• Utilisation du Layout API 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 lorsque vous voulez des documents structurés sans calculer manuellement les positions.
• Conversion HTML vers PDF avec prise en charge de SVG et d’autres formats web. Cette approche est particulièrement utile lorsque votre solution produit 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 qui démarre avec des images matricielles.
• Fusion ou division de PDF. C’est un bon choix pour assembler des rapports, traiter des envois utilisateurs, combiner des documents liés et restructurer de grands PDF.
• Création de PDF à partir de modèles. Cette approche fonctionne bien lorsqu’un formatage cohérent est requis pour des documents générés en série, comme des reçus, des formulaires fiscaux, des contrats de travail et d’autres types de documents répétitifs.

Les autres sujets abordés dans le guide incluent :

• Fonctionnalités interactives telles que les liens et les actions JavaScript
• Approches pour tester la sortie PDF afin de garantir les résultats attendus

Création de PDF avec le Core API

Le Core API est la base de la création de PDF dans Docotic.Pdf. Il vous donne un contrôle complet et de bas niveau sur le placement du texte, des images et des graphiques vectoriels sur un canvas PDF via son Canvas API. Cette API de dessin est un sous-ensemble du Core API et fournit les méthodes et propriétés utilisées pour ajouter du contenu aux pages et à d’autres objets avec des canvases. Au-delà du rendu, le Core API prend également en charge les annotations, les champs de formulaire, les calques, les signets et d’autres fonctionnalités PDF.

Voici du code C# qui crée un PDF simple en utilisant trois opérations fondamentales : dessiner du texte, placer une image et rendre des graphiques vectoriels sur un canvas de page.

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 de ce que le Core API peut faire. Pour les sujets avancés, consultez l’article détaillé sur la création de PDF avec le Core API. L’article couvre la mesure du texte, le travail avec les espaces colorimétriques, l’application du clipping, le remplissage de zones avec des motifs, la gestion de la transparence et d’autres შესაძლებლités.

Génération de PDF avec le Layout API

Le Layout API est un moteur de création de documents de haut niveau qui offre le moyen le plus simple et le plus efficace de générer des PDF complexes et riches en contenu.

Lorsque vous utilisez l’API, vous composez des PDF à partir d’éléments structurels tels que des pages, des conteneurs, des spans de texte, des images, des tableaux, des liens, des en-têtes, des pieds de page, et plus encore. Au lieu de calculer les coordonnées ou de gérer manuellement la pagination, vous décrivez la structure du document et laissez le moteur de mise en page s’occuper du reste.

Cet exemple illustre comment créer un PDF en utilisant le Layout API, en s’appuyant sur une mise en page déclarative plutôt que sur 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 à utiliser le Layout API lors de la génération de PDF dans des applications .NET.

Conversion de contenu web avec le HTML to PDF API

Docotic.Pdf, associé à son extension gratuite HtmlToPdf, fournit un moteur HTML vers PDF moderne, de haute qualité et basé sur Chrome. Vous pouvez transformer du HTML moderne et d’autres contenus web, comme des images SVG ou WebP, en documents PDF de haute qualité à l’aide de l’API fournie par l’extension.

Le HTML to PDF API peut créer des PDF à partir de pages HTML complètes ou de fragments HTML. Vous pouvez convertir du contenu à partir 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.

Voici un exemple montrant comment produire un PDF à partir d’un modèle HTML :

public static async Task HelloHtmlTemplate()
{
    static string GetUserName()
    {
        // Remplacez par une logique réelle : saisie de formulaire, appel d’API, configuration, 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 présentation détaillée HTML vers PDF.

Création de PDF à partir d’images

Docotic.Pdf fournit un moyen flexible et convivial pour les développeurs 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 le Core API.

Lorsque le format PDF le permet, Docotic.Pdf intègre les octets de l’image tels quels, en évitant 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.

En outre, les formats SVG et WebP sont pris en charge via le HTML to PDF API. Lorsque vous devez placer des images à côté d’étiquettes ou de descriptions, le Layout API vous aide à organiser et aligner les éléments avec un minimum d’effort.

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 sur chaque page.

L’exemple ci-dessous charge des images depuis des fichiers et dessine chacune d’elles sur sa propre page. Chaque image est redimensionnée pour s’adapter à la page et centrée pour obtenir une mise en page propre et cohérente.

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 au lieu de CreateImage si certaines images peuvent contenir plusieurs pages.

Le code suivant montre comment convertir un TIFF en PDF, et il fonctionne aussi bien pour les images à une seule page 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 approche pour convertir un GIF en PDF. Elle s’applique aussi à d’autres formats d’image, bien qu’elle soit plus élaborée que nécessaire pour les formats qui ne contiennent qu’une seule image.

Fusion et division de PDF

En tant que bibliothèque .NET complète, Docotic.Pdf peut créer de nouveaux PDF en fusionnant, extrayant et réorganisant des pages de documents existants.

Lorsque vous fusionnez des PDF, la bibliothèque n’ajoute pas seulement des pages d’un autre document, elle ajoute aussi les calques, les signets, les étiquettes de page, le JavaScript partagé, les destinations (cibles de lien) et les fichiers intégrés. Pour plus de détails et pour savoir comment réduire la taille des PDF combiné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 portfolio PDF au lieu d’ajouter les documents les uns à la suite des autres. Une autre option consiste à fusionner d’abord les PDF, puis à appliquer une nouvelle signature numérique au document combiné.

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 d’autres données associées. Pour des exemples pratiques, reportez-vous à l’article sur la division de PDF dans .NET. Il explique aussi comment extraire ou supprimer des pages.

Travail avec des modèles PDF

Les modèles PDF sont des fichiers PDF préconçus qui servent de structure de base pour créer de nouveaux documents. Ils sont utiles lorsque vous devez produire des PDF avec une mise en page cohérente tout en fournissant des données différentes. Si vous souhaitez séparer la conception visuelle des données elles-mêmes, les modèles PDF sont également un bon choix.

Les modèles peuvent être des PDF basés sur des formulaires ou des PDF statiques sans formulaires. Les deux types servent le même objectif. En outre, les modèles basés sur des formulaires incluent des éléments interactifs qui, s’ils ne sont pas aplatis, peuvent collecter 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 pris en charge de formulaire PDF interactif. Pour générer un PDF à partir d’un tel modèle, vous devez généralement :

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

Voici du code C# qui trouve un champ de texte de remplacement 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 emplacements réservés, vous pouvez importer des données FDF au lieu de remplir chaque champ individuellement. Vous pouvez aussi 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 dessinerez directement les noms et autres données sur le canvas de la page. Les modèles PDF statiques contiennent généralement des emplacements réservés visuels fixes, tels que du texte, des images ou des zones vides. Pour produire un PDF à partir du modèle, vous devrez remplir ces zones vides et remplacer les textes et images de remplacement par programme.

Zones vides

Utilisez le Canvas API 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 fonctionne bien. Vous devez connaître les coordonnées et la taille des zones, et pour positionner correctement le texte, vous devrez peut-être d’abord le mesurer, puis l’aligner en conséquence.

Le travail avec du texte de longueur variable ou sur plusieurs lignes est plus délicat, mais reste réalisable. En combinant DrawText, DrawString et les méthodes de mesure du texte, vous pouvez effectuer le retour à la ligne et positionner les lignes selon les besoins. Si votre modèle contient plus que quelques zones de ce type, envisagez une autre approche, comme la génération de PDF avec le Layout API.

Texte de remplacement

Docotic.Pdf fournit également des méthodes pour rechercher et remplacer du texte. Cependant, l’utilisation de la recherche de texte comme mécanisme de modélisation n’est généralement pas plus simple que le travail avec des zones vides de remplacement. Avant d’insérer un nouveau contenu, vous devez localiser le fragment de texte exact et le supprimer proprement.

Images de remplacement

Les modèles statiques peuvent inclure des images de remplacement pour les avatars d’utilisateur ou les photos de produits. Pour trouver une image de remplacement, énumérez la collection d’images dessinées sur chaque page. Pour chaque image dessinée, vous pouvez obtenir sa taille visible et sa position. Pour remplacer l’image de remplacement, 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’emplacements réservés faciles à remplacer

Pour les modèles statiques, il est utile de concevoir la mise en page avec des zones prévisibles et bien définies pour le texte et les images. Laissez suffisamment d’espace autour des zones qui contiendront du contenu de longueur variable, et utilisez des images de remplacement neutres correspondant aux rapports d’aspect que vous prévoyez d’insérer plus tard.

Si votre modèle utilise du texte de remplacement que vous prévoyez de remplacer, vous pouvez simplifier le flux de travail en utilisant des zones de texte plutôt que du texte brut. Ajoutez au modèle une zone de texte en lecture seule, sans bordure, et placez-y le texte de remplacement. Lors de la génération du PDF final, ouvrez le modèle, localisez la zone de texte par son nom et attribuez directement la nouvelle valeur avec box.Text = "new text";. Aplatissez ensuite 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 document dynamique et facile à parcourir, enrichi d’annotations et de balisage. Les actions et JavaScript permettent l’automatisation directement dans le PDF.

Annotations

Les annotations sont des objets attachés à une page qui représentent des commentaires, des surlignages, des pièces jointes et d’autres widgets interactifs. Elles sont visibles dans le contenu de la page et prennent en charge les flux de travail de relecture et la collaboration.

L’exemple C# suivant montre comment ajouter des annotations de texte, également appelées notes autocollantes, à 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 des 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");

Liens

Les normes PDF définissent plusieurs types de liens PDF. 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 à une page ou à une destination nommée à l’intérieur du même PDF. Ils sont utiles pour les renvois et la navigation interne.

Voici du code C# qui crée un lien de la première page vers la page dont l’index est égal à 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");

Le Layout API fournit une autre façon de créer des liens internes qui ne nécessite pas de positionnement absolu.

Les liens externes, également appelés actions URI, ouvrent une URL web. Vous pouvez ajouter un hyperlien à une page PDF en utilisant la méthode PdfPage.AddHyperlink. Sinon, l’approche est la même que pour les liens internes.

Signets

Les signets, également appelés outlines, sont des raccourcis ou des liens spéciaux qui aident les lecteurs à accéder rapidement à des sections ou des pages spécifiques. Lorsque le lecteur clique sur un signet, l’application de lecture saute à la partie désignée du document.

Les outlines apparaissent dans le panneau des signets du lecteur et fournissent une arborescence de navigation hiérarchique similaire à une table des matières dans un livre, mais interactive. Les outlines PDF peuvent inclure des signets principaux et des signets imbriqués, ce qui facilite la structuration de grands documents.

L’exemple suivant montre comment créer des signets dans des 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 de la table des matières que vous pourriez trouver imprimée sur les pages d’un livre physique ou affichée dans un PDF. Vous pouvez créer une table des matières par programme en mesurant les titres et en écrivant des entrées avec les numéros de page.

Pour voir une autre approche de création d’une table des matières en utilisant le Layout API, consultez le code correspondant dans notre dépôt d’exemples.

Scripting PDF

Les actions JavaScript font partie des fonctionnalités interactives les plus puissantes. Le JavaScript PDF est un sous-ensemble de JavaScript qui expose les API du document et du lecteur. 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 incorporer du code JavaScript dans un PDF. Le code peut valider les saisies de formulaire, calculer des valeurs, afficher ou masquer des champs, ou effectuer des interactions avec le lecteur.

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 aident à réduire la duplication et à simplifier la maintenance.

Le code ci-dessous définit un script partagé qui affiche un message d’alerte dans le lecteur PDF, puis montre comment déclencher ce script en l’affectant à 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 construire des actions JavaScript de n’importe quelle complexité. La référence de l’API JavaScript d’Adobe fournit de nombreuses méthodes que vous pouvez utiliser. Gardez à l’esprit que les lecteurs non Adobe ne prennent généralement en charge qu’un sous-ensemble de l’API.

Actions d’ouverture

Une action d’ouverture est une action que le lecteur PDF exécute lorsque le document est ouvert. Les utilisations courantes incluent l’ouverture sur une page spécifique, l’exécution d’une routine d’initialisation JavaScript ou la définition de préférences du lecteur. Il n’existe aucune restriction sur le type d’action d’ouverture.

L’exemple suivant montre comment créer une action d’ouverture GoTo. Le code ajoute du texte à la deuxième page et définit une action d’ouverture qui fait automatiquement naviguer le lecteur vers cette page lorsque le PDF est ouvert.

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 lecteurs n’exécutent pas les actions d’ouverture JavaScript. Certains les ignorent ou demandent d’abord à l’utilisateur. Certains lecteurs bloquent complètement les actions d’ouverture.

Pour vérifier si un PDF contient une action d’ouverture, chargez-le dans un PdfDocument et inspectez la propriété OnOpenDocument. Si la propriété est null, le document ne définit aucune action d’ouverture.

Application du chiffrement et des signatures numériques

Le chiffrement et les signatures numériques traitent deux aspects complémentaires de la sécurisation des PDF que vous créez. Le chiffrement contrôle qui peut ouvrir un document et ce qu’il peut en faire, 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 pendant 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 fournit une protection plus forte, spécifique au destinataire, et fonctionne bien lorsque vous distribuez des PDF confidentiels à plusieurs personnes sans dépendre d’un mot de passe partagé. Pour plus de détails, consultez l’article sur le chiffrement des PDF avec des mots de passe et des certificats.

Les signatures numériques ajoutent l’authenticité et l’intégrité au moment de la création. Docotic.Pdf peut signer des PDF à l’aide de certificats provenant de fichiers, du magasin Windows, de jetons matériels, de 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, y compris PKCS#11 et le KMS cloud, sont également pris en charge.

Définition des métadonnées PDF

Les métadonnées PDF sont des informations descriptives intégrées dans un document, comme le titre, l’auteur, le sujet, les mots-clés, les dates de création et des champs similaires. Elles aident les logiciels, les moteurs de recherche et les systèmes de gestion documentaire à comprendre le contenu d’un fichier sans 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 (Info dictionary)

XMP est le format plus riche, structuré et normalisé pour intégrer des métadonnées descriptives. Le dictionnaire Info est simple et largement pris en charge, mais limité, et il est obsolète dans la norme PDF 2.0 (ISO 32000‑2) au profit des métadonnées XMP. Docotic.Pdf peut lire et écrire les deux systèmes et fournit une méthode d’assistance pour les maintenir synchronisés.

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

Métadonnées XMP

Utilisez la propriété PdfDocument.Metadata pour accéder aux métadonnées XMP d’un PDF et les modifier. Via cette propriété, vous pouvez travailler avec des schémas bien connus tels que XMP Core, Dublin Core et le schéma PDF, ainsi que gérer 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 en fait un bon choix pour des métadonnées riches. Le code ci-dessus montre aussi comment stocker des propriétés spécifiques à l’application dans le schéma XMP personnalisé.

Dictionnaire d’informations du document

Le dictionnaire Info stocke principalement des valeurs de type chaîne de texte. Il est compact et largement pris en charge, mais limité. Utilisez le dictionnaire Info pour assurer la compatibilité avec les anciens outils, et privilégiez XMP dans les autres cas.

Synchronisation des métadonnées

Il est recommandé de conserver les deux systèmes de métadonnées synchronisés afin d’éviter des 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. La méthode remplit les propriétés Info manquantes à partir de XMP et, de la même manière, renseigne les champs XMP manquants à partir de Info. Définissez preferXmp: true lorsque XMP est votre source de vérité, ou false lorsque le dictionnaire Info doit être prioritaire.

pdf.SyncMetadata(preferXmp: true);

Consultez la section Remarks de la documentation SyncMetadata pour obtenir des informations détaillées sur les propriétés synchronisées par la méthode.

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

Un PDF nouvellement créé peut bénéficier d’une numérotation explicite des pages, de préférences du lecteur ajustées avec précision et d’une disposition de page choisie pour présenter le contenu du document plus efficacement. Ces paramètres influencent la manière dont les lecteurs voient et parcourent le fichier au premier affichage.

Étiquettes de page

Les étiquettes de page sont des métadonnées qui indiquent aux lecteurs PDF l’étiquette à afficher pour chaque page. Utilisez-les lorsque la numérotation visible doit différer de l’index physique de la page. Par exemple, lorsque vous voulez i, ii, iii pour les pages liminaires et 1, 2, 3 pour le corps principal de votre PDF.

Ce code C# montre comment étiqueter les pages PDF avec des chiffres romains minuscules pour les trois premières pages et une numérotation arabe à partir de 1 pour les suivantes.

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 lecteur PDF

Les préférences du lecteur PDF sont des recommandations intégrées dans le document qui indiquent comment un lecteur doit l’afficher. Par exemple, vous pouvez spécifier que le lecteur doit masquer les barres d’outils, centrer la fenêtre ou adapter la fenêtre à la page. Les préférences du lecteur complètent la disposition de page et les paramètres d’action d’ouverture.

Voici comment modifier les préférences d’affichage 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 lecteurs peuvent ignorer ces préférences.

Disposition de page et mode de page

La disposition de page détermine comment les pages sont organisées à l’ouverture du document : une page à la fois, en continu sur une colonne ou en doubles pages. Le mode de page contrôle les panneaux d’interface visibles à l’ouverture : signets/outlines, pièces jointes, miniatures ou aucun.

Voici comment spécifier que le PDF créé doit s’afficher en double page, page de gauche en premier, avec le panneau des miniatures 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 produire différents fichiers ou flux PDF à partir du même document que vous avez créé ou modifié. Ces sorties peuvent respecter différentes versions du format PDF, varier en longueur d’octets et nécessiter des quantités de mémoire différentes pour être générées.

La manière dont la bibliothèque produit les octets d’un PDF dépend des options d’enregistrement. Lorsque 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 valeurs par défaut sont soigneusement choisies et conviennent bien à la plupart des scénarios, mais vous devrez parfois les ajuster.

Reportez-vous à 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 évidence certaines des options les plus importantes et fournissent des recommandations pratiques.

Version PDF

Docotic.Pdf utilise par défaut des flux d’objets pour obtenir une meilleure compression des fichiers qu’il produit. En conséquence, la bibliothèque crée par défaut des fichiers et flux PDF 1.5.

PDF 1.5 nécessite Adobe Reader 6 (publié en 2003) ou une version plus récente pour afficher les documents produits. Cela ne pose généralement pas de problème, sauf si vous devez prendre en charge des outils hérités, des lecteurs plus anciens ou des appareils intégrés qui n’acceptent que des versions PDF plus anciennes.

Voici comment enregistrer avec une version de fichier PDF plus ancienne :

using var pdf = new PdfDocument();

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

Pour enregistrer avec la version PDF 1.4, les flux d’objets doivent également être désactivés. La bibliothèque n’utilisera pas une version plus ancienne si le document contient des fonctionnalités introduites dans des versions ultérieures.

Réduction de la taille du fichier

Plusieurs options d’enregistrement, lorsqu’elles sont définies sur true, amènent Docotic.Pdf à produire des fichiers plus petits (en octets) : RemoveUnusedObjects, OptimizeIndirectObjects, WriteWithoutFormatting et UseObjectStreams.

Voici comment produire des PDF sans objets non référencés ni espaces blancs supplémentaires, avec des données compactées 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 les plus efficaces lorsque le PDF est entièrement réécrit. Lors d’une sauvegarde incrémentielle, elles ne s’appliquent qu’à la révision nouvellement ajoutée et ne peuvent pas nettoyer ni optimiser les parties antérieures du fichier.

Mises à jour incrémentales

Docotic.Pdf peut mettre à jour les PDF de façon incrémentale. Lorsque WriteIncrementally est true, la bibliothèque ajoute les modifications au fichier existant au lieu de le réécrire. Les données de référence croisée et d’objets précédentes restent intactes. Les données ajoutées sont appelées une mise à jour incrémentale, et la mise à jour actuelle avec toutes les mises à jour précédentes constitue 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 à laquelle ajouter des données. La bibliothèque ignore cette option pour les nouveaux documents et les écrit en mode non incrémental.

Quand les mises à jour incrémentales sont requises

Lors de l’ajout d’une nouvelle signature numérique à un document qui contient déjà des signatures, vous devez enregistrer le fichier de manière incrémentale. Il en va de même lors de la mise à jour d’un fichier déjà signé avec de nouvelles annotations ou de nouvelles données de formulaire. Réécrire l’intégralité du fichier dans ces cas invaliderait les signatures existantes.

En même temps, il est préférable d’effectuer une sauvegarde non incrémentale (complète) avant d’appliquer la première signature numérique, afin que la base signée soit un fichier propre, entièrement réécrit. Signer un document qui contient des problèmes structurels dans des révisions antérieures peut entraîner des problèmes inattendus de validation de signature.

Les ajouts incrémentaux sont également requis dans les flux de travail qui doivent conserver un historique de révisions vérifiable ou imposer un stockage de documents en ajout uniquement.

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

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

Cette approche offre en outre des enregistrements plus rapides pour les petites modifications, car seules les données modifiées sont écrites. Elle préserve également l’historique des révisions du document, ce qui est essentiel pour l’audit et d’autres flux de travail soumis à des exigences de conformité.

Problèmes et pièges à éviter

Les mises à jour incrémentales ne peuvent pas appliquer une compression globale ni supprimer les objets obsolètes sur l’ensemble du fichier, car elles n’ajoutent que les objets modifiés. En conséquence, 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 lorsqu’aucun objet inutilisé n’est présent, 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 incorrectes des révisions antérieures restent récupérables, et les problèmes de format PDF ou les défauts structurels présents dans les révisions précédentes ne sont pas corrigés par l’ajout de nouvelles données.

Enfin, certains lecteurs et outils de traitement ont des difficultés avec les PDF multi-révisions. Avant de vous appuyer sur les mises à jour incrémentales, assurez-vous que tous les consommateurs de vos documents peuvent gérer des fichiers comportant plusieurs révisions.

Test de la sortie PDF

Les tests automatisés de PDF 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 dépôt ou votre stockage d’artefacts. Les références vous aident à détecter les changements accidentels dans le texte, les polices, les images ou la mise en page et réduisent le besoin de contrôle qualité manuel à chaque build.

Combinez les vérifications structurelles, l’extraction de texte et les comparaisons visuelles pour obtenir les résultats les plus fiables.

Comparaison rapide des approches

Comparaison de la structure du document

Utilisez PdfDocument.DocumentsAreEqual pour comparer les graphes d’objets PDF, la version PDF et le magasin de sécurité du document (DSS), tout en ignorant les propriétés du document dépendantes du temps. La méthode ignore également les métadonnées du document, les IDs du trailer et d’autres propriétés générées automatiquement.

Cette méthode est idéale pour les flux de test de documents PDF qui doivent garantir qu’aucun objet inattendu n’a été ajouté ou supprimé. DocumentsAreEqual prend en charge les surcharges pour fichiers et flux et peut comparer des PDF chiffrés.

Un exemple complet démontrant cette technique est disponible dans les exemples Docotic.Pdf. En plus de montrer comment utiliser la méthode dans des applications .NET classiques, l’exemple montre aussi comment utiliser DocumentsAreEqual dans Native AOT applications.

Vérification des PDF via le texte extrait

Extrayez le texte de l’ensemble du document en une seule fois ou de pages individuelles l’une après l’autre, puis comparez les chaînes. Vous pouvez utiliser les options d’extraction de texte pour affiner le processus, par exemple en excluant le rectangle du pied de page. Pour faciliter la comparaison, vous pouvez découper le texte extrait en lignes ou en mots.

Pour les vérifications structurées, commencez par extraire le texte avec la position, la police et d’autres informations détaillées sur chaque bloc, 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 rendre des pages PDF en images et comparez chaque image avec l’image de référence correspondante. Utilisez des bibliothèques spécialisées comme ImageSharp.Compare ou Magick.NET pour détecter les différences dans les images.

Privilégiez une comparaison stricte pixel par pixel afin que chaque pixel correspondant dans les deux images doive correspondre. Si vos exigences autorisent de მცირე variations de rendu, vous pouvez ajuster la logique de comparaison pour tolérer de petites différences, mais l’égalité exacte pixel par pixel offre les résultats les plus fiables.

Envisagez d’utiliser le hachage comme pré-vérification rapide pour déterminer si deux images sont probablement identiques sans effectuer une comparaison complète pixel par pixel. Calculez un hachage SHA‑256 pour chaque image rendue, et si les hachages correspondent, les images sont presque certainement identiques. Si les hachages diffèrent, lancez alors la comparaison complète pixel par pixel.

Conclusion

Docotic.Pdf fournit une boîte à outils complète et à plusieurs niveaux pour créer et manipuler des PDF dans .NET. Les développeurs peuvent choisir entre un contrôle de bas niveau avec le Core API, une génération de documents de haut niveau avec le Layout API, ou une 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 à partir de modèles et un riche ensemble 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 de test de la sortie PDF afin que les modifications dans votre application n’introduisent pas de régressions ni de différences inattendues.