Cette page peut contenir du texte traduit automatiquement.
Convertir HTML en PDF en C# et VB.NET
Si vous avez déjà investi beaucoup de temps et d’argent dans la création de contenu au format HTML, vous souhaiterez peut-être créer des PDF à partir de ce HTML. Cette approche est un choix naturel pour toute personne qui veut éviter le travail en double.
Cet article est un guide détaillé sur la conversion de HTML en PDF dans .NET à l’aide de Docotic.Pdf avec son module complémentaire HtmlToPdf gratuit.
Pour savoir pourquoi Docotic.Pdf est le bon choix, comment installer le module complémentaire et comment la conversion fonctionne en interne, consultez la page Vue d’ensemble de l’API HTML en PDF.
Conversion simple de HTML en PDF en C#
Commencez par installer le module complémentaire.
Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf
À l’aide de l’API HTML en PDF, le code de conversion en C# peut ressembler à ceci :
static async Task ConvertUrlToPdfAsync(string urlString, string pdfFileName)
{
using var converter = await HtmlConverter.CreateAsync();
using var pdf = await converter.CreatePdfAsync(new Uri(urlString));
pdf.Save(pdfFileName);
}
C’est assez simple. Deux appels suffisent pour produire un document PDF.
Le code crée une instance du convertisseur et l’utilise pour générer un PDF à partir du HTML. Vous pouvez modifier le document PDF ou le signer avec une signature numérique. Pour simplifier, l’exemple enregistre le document tel quel.
Comme vous pouvez le constater, l’API est asynchrone et ne fournit aucune méthode synchrone.
Utilisation de l’API async dans du code synchrone
Il existe des cas où vous devez appeler l’API à partir d’un code synchrone. Par exemple, lorsque votre application console utilise une ancienne version de C# et que vous ne disposez pas de async Main. Pas d’inquiétude, vous pouvez quand même utiliser le module complémentaire dans votre application.
Le code suivant montre comment convertir une URL en PDF dans une méthode synchrone classique :
Task.Run(async () =>
{
using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("output.pdf");
}).GetAwaiter().GetResult();
Les applications VB.NET utilisent un code similaire. Voici un extrait qui montre comment convertir du HTML en PDF dans du code VB.NET synchrone.
Task.Run(
Async Function()
Using converter = Await HtmlConverter.CreateAsync()
Dim uri = New Uri("https://bitmiracle.com/pdf-library/html-pdf/")
Using pdf = Await converter.CreatePdfAsync(uri)
pdf.Save("output.pdf")
End Using
End Using
End Function
).GetAwaiter().GetResult()
Veuillez noter qu’en général, il n’est pas recommandé d’appeler des méthodes async de manière synchrone ; utilisez donc l’enveloppe uniquement lorsque vous n’avez pas d’autre choix.
Exemples de code
Nous fournissons des exemples de code pour des applications console, Windows Forms et WPF. Téléchargez les projets de test complets depuis notre dépôt GitHub :
Il existe aussi le groupe d’exemples HTML en PDF. Chaque exemple est disponible en version C# et VB.NET.
Créer un PDF à partir d’une chaîne HTML ou d’un fichier en C# et VB.NET
Il est facile de convertir une chaîne HTML en PDF avec l’API. La chaîne peut contenir un document HTML complet ou simplement un fragment. Le convertisseur créera pour vous un PDF à partir du code HTML.
using var converter = await HtmlConverter.CreateAsync();
var html = "<body><br><br><br><h1>Hello, World</h1></body>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");
Le HTML peut contenir des références relatives vers des images, des scripts et des fichiers CSS. Pour convertir correctement ce code, vous devez spécifier une URL de base pour tous les liens relatifs dans le HTML. Voici comment spécifier une URL de base à l’aide des options de conversion :
using var converter = await HtmlConverter.CreateAsync();
var incompleteHtml = "<img src=\"/images/team.svg\"></img>";
var options = new HtmlConversionOptions();
options.Load.BaseUri = new Uri("https://bitmiracle.com/");
using var pdf = await converter.CreatePdfFromStringAsync(incompleteHtml, options);
pdf.Save("output.pdf");
Notre dépôt GitHub contient le projet de test complet.
La conversion d’un fichier HTML est presque identique à celle d’une URL. Utilisez simplement la surcharge CreatePdfAsync qui accepte un chemin au lieu d’une URL. L’URL de base et les autres options sont également prises en charge lors de la conversion d’un fichier HTML en PDF dans du code C# ou VB.NET.
var sampleHtmlPath = @"C:\path\to\sample.html";
using var pdf = await converter.CreatePdfAsync(sampleHtmlPath);
pdf.Save("output.pdf");
Vous pouvez aussi convertir des images SVG en PDF à l’aide de l’API.
Utiliser une taille de page, des marges et une échelle personnalisées
Lorsqu’il s’agit de pages web avec des mises en page larges, vous pouvez soit augmenter la taille du PDF de sortie, soit réduire le contenu pour l’adapter à la page PDF. Pour mieux positionner le contenu mis à l’échelle, vous pouvez aussi définir des marges.
Un PDF correctement mis à l’échelle offre une meilleure expérience de lecture, car les lecteurs n’auront pas besoin de zoomer ou dézoomer pour afficher correctement le contenu. Si le document HTML est difficile à lire à cause d’une taille de police trop petite, vous pouvez augmenter l’échelle du contenu.
Par défaut, l’API produit des PDF au format A4. Il n’y a ni marges ni agrandissement. À l’aide des options de conversion, vous pouvez modifier ces paramètres.
Voici comment définir le facteur d’échelle et les marges lors de la génération d’un PDF à partir de HTML
using var converter = await HtmlConverter.CreateAsync();
var html = "<html><head><style>body { background-color: coral; margin-top: 100px;}</style></head>" +
"<body><h1>Did you notice the margins and the scale?</h1></body></html>";
var options = new HtmlConversionOptions();
options.Page.MarginLeft = 10;
options.Page.MarginTop = 20;
options.Page.MarginRight = 30;
options.Page.MarginBottom = 40;
options.Page.Scale = 1.5;
using var pdf = await converter.CreatePdfFromStringAsync(html, options);
pdf.Save("output.pdf");
Le dépôt d’exemples de Docotic.Pdf contient le projet complet.
Spécifier des modèles d’en-tête et de pied de page
L’API HTML en PDF peut ajouter des blocs récurrents de pied de page / en-tête sur les pages générées. Le convertisseur crée ces blocs à partir des modèles HTML indiqués dans les options de page. Nous recommandons d’utiliser des styles en ligne et des URI de données pour les images à l’intérieur des modèles.
Le convertisseur place les en-têtes et les pieds de page à l’intérieur des marges de page. Comme les marges par défaut sont faibles, le contenu de l’en-tête et du pied de page peut ne pas être visible. Nous recommandons de définir explicitement les marges supérieure et inférieure. La taille doit correspondre respectivement à celle de l’en-tête et du pied de page.
Voici comment modifier HTML en PDF et ajouter un en-tête et un pied de page
using var converter = await HtmlConverter.CreateAsync();
var options = new HtmlConversionOptions();
options.Page.HeaderTemplate = File.ReadAllText("header-template.html");
options.Page.MarginTop = 50;
options.Page.FooterTemplate = File.ReadAllText("footer-template.html");
options.Page.MarginBottom = 50;
var url = new Uri("https://www.iana.org/numbers");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Les modèles utilisent du code HTML classique avec prise en charge de quelques variables. Ces variables sont date, title, url, pageNumber et totalPages. Les modèles d’en-tête et les modèles de pied de page prennent en charge le même ensemble de variables.
Le projet de test complet et le code du modèle se trouvent dans le dépôt d’exemples de Docotic.Pdf. L’exemple de code montre comment utiliser les variables et les URI de données dans les modèles.
Conversion HTML en PDF protégée par mot de passe en C#
Certaines pages web nécessitent une authentification pour y accéder. Lorsque vous accédez à une URL sécurisée qui requiert une authentification HTTP, le navigateur vous demande de fournir un nom d’utilisateur et un mot de passe.
À l’aide des options de conversion, vous pouvez indiquer à l’API de fournir des identifiants pour les pages web qui nécessitent une connexion.
Ce code C# montre comment convertir du HTML protégé par mot de passe en PDF
using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://httpbin.org/basic-auth/foo/bar");
var options = new HtmlConversionOptions();
options.Authentication.SetCredentials("foo", "bar");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Retrouvez l’exemple fonctionnel complet dans le dépôt d’exemples.
C’est également simple si la page a besoin de certains cookies pour fonctionner correctement. Ajoutez simplement ces cookies aux options. Voici comment :
var options = new HtmlConversionOptions();
options.Cookies.Add(new Cookie("sessionID", "my-session-ID"));
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Différer le début de la conversion
Par défaut, la conversion commence immédiatement après le chargement. Retarder la conversion de HTML en PDF peut être utile si la page continue de se mettre à jour pendant un certain temps après le chargement. C’est souvent le cas avec du contenu dynamique généré par JavaScript ou des appels AJAX.
Le test Acid 3 est un exemple parfait de page qui bénéficie d’un délai avant la conversion. Ce test exécute un certain nombre de vérifications pour évaluer la capacité d’un navigateur à rendre correctement des pages web complexes. Ces vérifications prennent du temps. Essayez de modifier le temps d’attente dans le code suivant pour voir son effet sur les résultats de conversion.
var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);
using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://acid3.acidtests.org/");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Le code ci-dessus montre comment convertir HTML en PDF avec délai. Même si ce temps supplémentaire aide à obtenir de meilleurs résultats, notez que l’ajout de délais peut affecter les performances. Des délais insuffisants peuvent nuire à la qualité de la conversion. Une autre approche consiste à utiliser un script qui s’exécute jusqu’à ce que la page soit prête.
Vous pouvez obtenir le projet de test complet dans le dépôt d’exemples de Docotic.Pdf.
Exécuter JavaScript avant la conversion
Le module complémentaire fournit un moyen d’exécuter du code JS avant la conversion. Le code peut générer ou modifier dynamiquement le contenu HTML. Par exemple, il peut basculer des éléments ou déclencher le chargement de contenu dynamique.
Le code suivant montre comment retarder la conversion de HTML en PDF jusqu’à la fin de JavaScript.
using var converter = await HtmlConverter.CreateAsync();
var options = new HtmlConversionOptions();
var js = @"document.body.style.backgroundColor = 'green';";
options.Start.SetStartAfterScriptRun(js);
var url = new Uri("https://google.com");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
L’extrait ci-dessus utilise un code très simple uniquement pour illustrer l’approche. Pour un exemple plus concret, consultez l’application d’exemple correspondante dans notre dépôt GitHub. L’application montre comment gérer une page qui charge dynamiquement son contenu. Le code JavaScript de l’application fait défiler la page jusqu’à ce qu’il n’y ait plus de nouveau contenu. Ensuite, la conversion en PDF a lieu.
Convertir HTML en PDF dans .NET en ignorant les erreurs SSL
Lors de l’envoi de requêtes sécurisées pour charger du HTML, le module complémentaire vérifie si le certificat SSL qui authentifie l’identité d’un site web et permet une connexion chiffrée est valide et approuvé.
Par défaut, le module complémentaire lève une exception si le convertisseur HTML en PDF ne fait pas confiance au certificat, quelle qu’en soit la raison. Cela se produit généralement à cause d’un certificat auto-signé, révoqué ou expiré.
Si vous comprenez le risque d’accepter un certificat non fiable, vous pouvez demander au module complémentaire d’ignorer les vérifications à l’aide des options du moteur.
var engineOptions = new HtmlEngineOptions
{
IgnoreSslErrors = true
};
using var converter = await HtmlConverter.CreateAsync(engineOptions);
var url = new Uri("https://self-signed.badssl.com/");
using var pdf = await converter.CreatePdfAsync(url);
pdf.Save("output.pdf");
Pour le code complet, rendez-vous dans le dépôt d’exemples de Docotic.Pdf.
Superposer du HTML sur un PDF existant
Il existe des cas où vous souhaitez utiliser un PDF existant comme arrière-plan pour le résultat de la conversion. Par exemple, lorsque vous avez l’image d’un formulaire et que vous voulez placer quelque chose sur les zones vides de cette image. Le résultat ressemblera à un formulaire rempli. Cela est possible avec Docotic.Pdf et le module complémentaire.
Ce processus consiste à créer un nouveau PDF à partir du HTML (le contenu de superposition), puis à le fusionner avec le PDF existant. Le document final inclura à la fois le contenu d’origine et la nouvelle superposition. Voici le code qui illustre ce processus.
using var converter = await HtmlConverter.CreateAsync();
var options = new HtmlConversionOptions();
options.Page.SetSizeInches(4.13, 5.83);
string htmlCode =
"<div style=\"position: absolute; top: 270px; right: 100px;\">" +
"I would like to put this here</div>";
using var htmlPdf = await converter.CreatePdfFromStringAsync(htmlCode, options);
using var pdf = new PdfDocument("pdf-to-merge-with.pdf");
var xObj = pdf.CreateXObject(htmlPdf.Pages[0]);
pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("output.pdf");
Il est important de spécifier une taille de page pour la superposition. En général, la taille doit être égale à celle de la page sur laquelle vous souhaitez superposer le contenu. Vous devez ensuite produire le nouveau PDF avec le contenu de superposition. Notez que l’arrière-plan est transparent par défaut. Vous pouvez modifier l’arrière-plan en exécutant un script avant la conversion si nécessaire.
Le code ci-dessus :
- crée un document PDF avec une page transparente à partir du HTML
- ouvre un PDF existant
- crée un XObject à partir de la première page du document converti dans le document existant
- dessine le XObject au-dessus de la première page PDF du document existant
Le projet de test complet avec un exemple de PDF source se trouve dans le dépôt d’exemples de Docotic.Pdf.