16. Jun 2025
Lesedauer 4 Min.
Ratzfatz umgewandelt
PDF aus HTML erzeugen
Mit dem NuGet-Paket SimpleHtmlToPdf erstellen Sie PDF-Dateien jetzt noch einfacher.
dotnetpro
Zur Erzeugung von PDF-Dateien in einer C#-Anwendung gibt es einige bekannte kommerzielle Varianten. Zu nennen wären IronPdf [1] und Aspose.PDF [2], aber auch Open-Source-Projekte wie DinkToPdf [3]. Zu Letzterem existiert nun eine verbesserte und vereinfachte Variante – SimpleHtmlToPdf [4].
Gemeinsame Grundlage für mehrere NuGet-Pakete
Sowohl DinkToPdf als auch SimpleHtmlToPdf basieren auf wkhtmltopdf [5], einer Bibliothek, die in C++ geschrieben wurde. Dieses Befehlszeilentool nutzt die Qt-Bibliothek (insbesondere Qt WebKit), um HTML-Seiten zu rendern und in PDF-Dateien umzuwandeln. Da Qt ebenfalls in C++ entwickelt ist, war die Wahl dieser Sprache für die Entwicklung von wkhtmltopdf naheliegend.wkhtmltopdf selbst ist ein Open-Source-Befehlszeilenwerkzeug (LGPLv3), das HTML-Code in eine PDF-Datei umwandelt. Da Webentwickler mit HTML-Code vertraut sind, wird es ihnen leichtfallen, SimpleHtmlToPdf für die Erstellung von PDF-Dateien zu verwenden.DinkToPdf
Das erste NuGet-Paket, das einen Wrapper für wkhtmltopdf enthielt und es so ermöglichte, diese Bibliothek in C#-Anwendungen zu verwenden, war DinkToPdf. Dieses Paket hatte jedoch den Nachteil, dass die benötigten DLL-Dateien der wkhtmltopdf-Bibliothek manuell nachzuinstallieren waren. Dazu musste man die DLL-Dateien herunterladen und dem Projekt hinzufügen sowie einen eigenen AssemblyLoadContext schreiben, damit die DLL-Dateien eingebunden werden können. Fehlten die DLL-Dateien, kam es zu einem Laufzeitfehler (siehe Bild 1). Dies musste in manchen Konstellationen beim Veröffentlichen einer Webseite beachtet werden.
Laufzeitfehler beim Fehlen der benötigten DLL-Dateien aus der wkhtmltopdf-Bibliothek (Bild 1)
Autor
Die Installation und die Verwendung von DinkToPdf wurden bereits in einem dotnetpro-Artikel beschrieben [6].
SimpleHtmlToPdf
Einen Schritt weiter geht nun das NuGet-Paket SimpleHtmlToPdf. Dieses ist ein leichtgewichtiger Wrapper für die wkhtmltopdf-Bibliothek und beinhaltet die DLL-Dateien der wkhtmltopdf-Bibliothek bereits, was bedeutet, dass diese nicht manuell nachinstalliert werden müssen.Verwendung von SimpleHtmlToPdf
Hier eine kurze Beschreibung, wie man SimpleHtmlToPdf in ein Projekt einbindet und damit eine PDF-Datei erstellt.Zunächst installieren wir das NuGet-Paket über die Paket-Manager-Konsole:
dotnet add package
SimpleHtmlToPdf
Danach registrieren wir den neuen Service in der Datei Program.cs:
builder.Services.AddSimpleHtmlToPdf();
Nun stehen uns die Funktionen von SimpleHtmlToPdf über Dependency-Injection überall zur Verfügung; dazu verwenden wir das Interface IConverter. Listing 1 zeigt an einem einfachen Beispiel die nötigen Schritte.
Listing 1: Ein einfaches SimpleHtmlToPdf-Anwendungsbeispiel
public class ReportController(IConverter converter) :
Controller
{
private readonly IConverter _converter = converter;
public IActionResult GetReport()
{
// Parameter für die PDF-Datei
var pdfDoc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4Plus,
},
Objects = {
new ObjectSettings()
{
// HtmlContent erhält den HTML-Code, der in
// eine PDF-Datei konvertiert werden soll
HtmlContent = GetHtmlCodeForReport(),
WebSettings = { DefaultEncoding = "utf-8" },
},
}
};
// Konvertiert HTML-Code in eine PDF-Datei in
// Form von byte[]
byte[] pdfFile = _converter.Convert(pdfDoc);
return File(pdfFile, "application/pdf");
}
private static string GetHtmlCodeForReport()
{
var reportHtml = "<html><body>........</body>
</html>";
return reportHtml;
}
}
Zunächst binden wir mit Dependency-Injection den Service von SimpleHtmlToPdf in unseren Controller ein. In der Action GetReport() erstellen wir ein neues Objekt vom Typ HtmlToPdfDocument. Unter GlobalSettings können wir verschiedene Einstellungen für das PDF-Dokument festlegen, etwa Farbe oder Schwarz/Weiß, Ausrichtung, Ränder, Papiergröße und anderes mehr. Unter ObjectSettings übergeben wie den HTML-Code, der als PDF-Datei dargestellt werden soll. Die Erstellung des HTML-Codes haben wir in die Methode GetHtmlCodeForReport() ausgelagert. Hier kann auch eigener CSS-Code mitgegeben werden, und es existieren Einstellungen für Fußzeile, Paginierung und anderes. Schließlich erstellt die Methode converter.Convert(pdfDoc) eine PDF-Datei und gibt diese als Byte-Array zurück. In unserem Beispiel zeigen wir die PDF-Datei direkt im Browser an; alternativ könnte man die PDF-Datei auch in einer Datenbank speichern oder als Anhang mit einer E-Mail versenden.Wie gesagt: Dies ist nur ein einfaches Beispiel. In der Realität würde man beispielsweise die Erstellung eines Objekts vom Typ HtmlToPdfDocument in eine statische Klasse auslagern und in der Action nur noch den HTML-Code an die Variable HtmlContent übergeben.
Umstellung von DinkToPdf auf SimpleHtmlToPdf
Wer bereits mit DinkToPdf gearbeitet hat, dem fällt auf, dass die Syntax der Methodenaufrufe in SimpleHtmlToPdf sehr ähnlich ist. Und in der Tat bezieht sich der Entwickler von SimpleHtmlToPdf explizit auf die Bibliothek von DinkToPdf, die den initialen Code bereitgestellt hat [7]. Das bringt für uns den Vorteil einer einfachen Umstellung von DinkToPdf auf SimpleHtmlToPdf. Die Schritte dazu sind folgende:- NuGet-Paket DinkToPdf deinstallieren.
- NuGet-Paket SimpleHtmlToPdf installieren.
- In der Datei Program.cs Einträge von DinkToPdf entfernen und SimpleHtmlToPdf als Service hinzufügen.
- Nicht mehr benötigte DLL-Dateien von wkhtmltopdf und den eigenen AssemblyLoadContext löschen.
Fazit
Entwickler, die in ihren Webanwendungen PDF-Dateien erstellen möchten, sollten SimpleHtmlToPdf eine Chance geben. Wer bereits DinkToPdf in seinen Projekten verwendet hat, kann eine Umstellung auf SimpleHtmlToPdf in Betracht ziehen und auf diese Weise seinen Code verschlanken.Fussnoten
- IronPdf,
- Aspose.PDF, https://docs.aspose.com/pdf/net/
- DinkToPdf, https://github.com/rdvojmoc/DinkToPdf
- SimpleHtmlToPdf,
- wkhtmltopdf, https://wkhtmltopdf.org
- Christian Kiefer, Aus HTML mach PDF, dotnetpro 7/2024, Seite 136 ff.,
- SimpleHtmlToPdf, Acknowledgments,
- Beispielprojekt „Create PDF-files on websites“ auf GitHub,
