Documents de construction

Bien entendu, vous devez générer un document PDF avec vos données. Mais assez souvent, vous souhaitez également chiffrer le fichier PDF avec des mots de passe. Et vous souhaitez généralement ajouter des métadonnées PDF au fichier de sortie.

Continuez à lire pour savoir comment demander au générateur de crypter les fichiers PDF. Comment spécifier l'auteur du document et les mots-clés.

Cet article fait partie d'une série sur l'API Layout pour la génération de PDF. Si vous débutez avec l'API, lisez d'abord la partie Mise en route avec l'API Layout.

Create & Generate

Le point d'entrée de l'API Layout est la classe PdfDocumentBuilder. Vous commencez par créer une instance de la classe avec la méthode Create. Pour générer un PDF, vous appelez la méthode Generate de la classe.

Generate peut enregistrer la sortie dans un fichier ou un flux. L'une ou l'autre version de la méthode nécessite un délégué de type Action<Document> comme deuxième paramètre. Dans le délégué, vous décrivez le document que vous souhaitez obtenir. La bibliothèque générera un PDF basé sur la description.

Chiffrement

Pour crypter le PDF de sortie, appelez la méthode Encryption avant la méthode Generate.

Vous devrez créer et fournir un gestionnaire de chiffrement. Pour crypter un PDF avec des mots de passe, utilisez un gestionnaire de type PdfStandardEncryptionHandler.

PdfDocumentBuilder.Create()
    .Encryption(new PdfStandardEncryptionHandler("owner", "user"))
    .Generate("encrypted-with-password.pdf", doc => doc.Pages(_ => { }));

Vous pouvez également crypter des PDF avec des certificats. Consultez l'article Crypter les documents PDF. Il contient des informations détaillées sur les gestionnaires de chiffrement et les autorisations PDF.

Métadonnées du fichier PDF

Dans certains flux de travail, il est très important de spécifier les mots-clés PDF appropriés et l'auteur du PDF dans le PDF de sortie. L’API Layout fournit un moyen simple pour cela. Appelez la méthode Info avant la méthode Generate et fournissez les valeurs de métadonnées dans le délégué.

PdfDocumentBuilder.Create()
    .Info(info =>
    {
        info.Author = $"{Environment.UserName}";
        info.Title = "Generate encrypted PDF with custom metadata";
        info.Keywords = "Metadata keywords encryption";
    })
    .Generate("metadata.pdf", doc => doc.Pages(_ => { }));

Possibilités

Pour un même contenu, la bibliothèque peut créer des fichiers PDF avec une structure interne différente. Ces options affecteront le PDF de sortie.

Version

Utilisez la méthode Version pour définir la version minimale du format PDF pour le PDF de sortie.

PdfDocumentBuilder.Create()
    .Version(PdfVersion.Pdf17)
    .Generate("version.pdf", doc => doc.Pages(_ => { }));

Veuillez noter que la bibliothèque peut créer un PDF avec une version plus grande que celle spécifiée. Cela se produit lorsque le contenu du document nécessite une version plus récente. En d’autres termes : lorsque le document utilise des fonctionnalités non disponibles dans la version spécifiée de la norme PDF.

Flux d'objets

Par défaut, la bibliothèque utilise des flux d'objets dans les PDF générés. Cela permet de produire des fichiers plus petits et mieux compressés.

Vous pouvez demander à l'API de créer des fichiers PDF sans flux d'objets à l'aide de la méthode ObjectStreams.

PdfDocumentBuilder.Create()
    .ObjectStreams(false)
    .Generate("no-object-streams.pdf", doc => doc.Pages(_ => { }));

Je vous suggère de continuer à utiliser les flux d'objets, sauf s'il existe certaines exigences réglementaires. Ou lorsque d'autres parties de votre flux de travail ne peuvent pas traiter des documents avec des flux d'objets.

Fournisseur de flux

La bibliothèque utilise des flux comme stockage intermédiaire. Lors de la génération d'un PDF, il le fait pour les images et autres objets volumineux. La bibliothèque obtient des flux via le fournisseur de flux. Il y en a toujours un associé à l'instance PdfDocumentBuilder actuelle.

La bibliothèque utilise PdfMixedStorageStreamProvider par défaut. Cette implémentation de fournisseur de flux fournit des flux qui conservent les données en mémoire. Ces flux vident leur contenu dans des fichiers temporaires lorsqu'il y a trop de données. Cela permet de réduire la consommation de mémoire et d’éviter la fragmentation LOH.

Vous pouvez utiliser votre propre implémentation de l'interface IPdfStreamProvider lors de la génération de fichiers PDF. Une des raisons de ce changement pourrait être une opération de disque lente et/ou coûteuse. Les environnements cloud peuvent correspondre à cette description.

Ce code montre comment générer un PDF entièrement en mémoire, sans fichiers temporaires. Veuillez noter que cela nécessitera beaucoup plus de mémoire qu'avec les options par défaut.

using (var memoryOnlyProvider = new PdfMemoryStreamProvider())
{
    PdfDocumentBuilder.Create()
        .StreamProvider(memoryOnlyProvider)
        .Generate("created-without-temp-files.pdf", doc => doc.Pages(_ => { }));
}

La bibliothèque appelle finalement Dispose pour chaque flux qu'elle reçoit via le fournisseur de flux. Vous devez disposer vous-mêmes de l’instance du fournisseur de flux.