Diese Seite kann automatisch übersetzten Text enthalten.
HTML in PDF konvertieren in C# und VB.NET
Wenn Sie bereits viel Zeit und Geld in die Erstellung von HTML-Inhalten investiert haben, möchten Sie daraus vielleicht PDFs generieren. Dieser Ansatz ist ideal für alle, die doppelte Arbeit vermeiden möchten.
Dieser Artikel bietet eine detaillierte Anleitung zur Konvertierung von HTML in PDF in .NET mithilfe von Docotic.Pdf und dem kostenlosen Add-on HtmlToPdf.
Informationen darüber, warum Docotic.Pdf die richtige Wahl ist, wie Sie das Add-on installieren und wie die Konvertierung intern funktioniert, finden Sie auf der Seite HTML-zu-PDF-API-Übersicht.
Einfache HTML-zu-PDF-Konvertierung mit C#
Installieren Sie zuerst das Add-on.
Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf
Mithilfe der HTML-zu-PDF-API kann der C#-Konvertierungscode wie folgt aussehen:
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);
}
Es ist recht einfach. Nur zwei Aufrufe sind nötig, um ein PDF-Dokument zu erstellen.
Der Code erzeugt eine Instanz des Konverters und generiert damit ein PDF aus HTML. Sie können das PDF-Dokument bearbeiten oder digital signieren. Der Beispielcode speichert das Dokument unverändert.
Wie Sie sehen, ist die API asynchron und bietet keine synchronen Methoden.
Verwendung der asynchronen API in synchronem Code
Es gibt Fälle, in denen Sie die API aus synchronem Code aufrufen müssen. Dies ist beispielsweise
der Fall, wenn Ihre Konsolenanwendung eine ältere C#-Version verwendet und Sie keine asynchrone
Main-Methode haben. Keine Sorge, Sie können das Add-on trotzdem in Ihrer Anwendung verwenden.
Der folgende Code zeigt, wie Sie eine URL in einer regulären synchronen Methode in ein PDF konvertieren:
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();
VB.NET-Anwendungen verwenden einen ähnlichen Code. Hier ist ein Codebeispiel, das zeigt, wie man HTML in synchronem VB.NET-Code in PDF konvertiert.
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()
Bitte beachten Sie, dass es generell nicht empfehlenswert ist, asynchrone Methoden synchron aufzurufen. Verwenden Sie den Wrapper daher nur, wenn es keine andere Möglichkeit gibt.
Beispielcode
Wir stellen Beispielcode für Konsolen-, Windows Forms- und WPF-Anwendungen bereit. Laden Sie vollständige Testprojekte aus unserem GitHub-Repository herunter:
Es gibt außerdem die Beispielgruppe HTML zu PDF. Jedes Beispiel ist in einer C#- und einer VB.NET-Version verfügbar.
Erstellen Sie in C# und VB.NET eine PDF-Datei aus einer HTML-Zeichenfolge oder -Datei
Mit der API lässt sich ein HTML-String ganz einfach in eine PDF-Datei konvertieren. Der String kann ein vollständiges HTML-Dokument oder nur einen Ausschnitt davon enthalten. Der Konverter erstellt daraus automatisch eine PDF-Datei.
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");
HTML kann relative Verweise auf Bilder, Skripte und CSS-Dateien enthalten. Um solchen Code korrekt zu konvertieren, müssen Sie für alle relativen Links im HTML eine Basis-URL angeben. So legen Sie eine Basis-URL mithilfe der Konvertierungsoptionen fest:
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");
Unser GitHub-Repository enthält das vollständige Testprojekt.
Das Konvertieren einer HTML-Datei ist fast identisch mit dem Konvertieren einer URL. Verwenden Sie einfach die Überladung von CreatePdfAsync, die einen Pfad anstelle einer URL akzeptiert. Die Basis-URL und weitere Optionen werden auch bei der Konvertierung einer HTML-Datei in PDF in C#- oder VB.NET-Code unterstützt.
var sampleHtmlPath = @"C:\path\to\sample.html";
using var pdf = await converter.CreatePdfAsync(sampleHtmlPath);
pdf.Save("output.pdf");
Sie können SVG-Bilder auch mit Hilfe der API in PDF konvertieren using the API.
Benutzerdefinierte Seitengröße, Ränder und Skalierung verwenden
Bei Webseiten mit breitem Layout können Sie entweder die Größe der Ausgabedatei (PDF) erhöhen oder den Inhalt verkleinern, um ihn an die PDF-Seite anzupassen. Um den skalierten Inhalt besser zu positionieren, können Sie außerdem Ränder festlegen.
Eine optimal skalierte PDF-Datei bietet ein besseres Leseerlebnis, da die Leser nicht zoomen müssen, um den Inhalt korrekt zu sehen. Ist das HTML-Dokument aufgrund einer kleinen Schriftgröße schwer lesbar, können Sie den Inhalt vergrößern.
Standardmäßig erzeugt die API PDFs im A4-Format. Es gibt keine Ränder und keine Vergrößerung. Mithilfe der Konvertierungsoptionen können Sie diese Einstellungen ändern.
Informationen zum Festlegen von Skalierungsfaktor und Rändern beim Generieren von PDFs aus HTML finden Sie hier
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");
Das Docotic.Pdf-Beispielrepository enthält das komplette Projekt.
Kopf- und Fußzeilenvorlagen festlegen
Die HTML-zu-PDF-API kann wiederholbare Kopf- und Fußzeilenblöcke auf generierten Seiten hinzufügen. Der Konverter erstellt diese Blöcke anhand der in den Seitenoptionen angegebenen HTML-Vorlagen. Wir empfehlen, Inline-Styles und Data-URIs für Bilder innerhalb der Vorlagen zu verwenden.
Der Konverter platziert Kopf- und Fußzeilen innerhalb der Seitenränder. Da die Standardseitenränder klein sind, ist der Inhalt von Kopf- und Fußzeile möglicherweise nicht sichtbar. Wir empfehlen daher, die oberen und unteren Ränder explizit anzugeben. Die Größe sollte jeweils der Größe von Kopf- und Fußzeile entsprechen.
Informationen zum Konvertieren von HTML in PDF und zum Hinzufügen von Kopf- und Fußzeilen finden Sie hier
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");
Die Vorlagen verwenden regulären HTML-Code mit Unterstützung für einige Variablen. Diese Variablen
sind date, title, url, pageNumber und totalPages. Sowohl die
Header-Vorlagen als auch die
Footer-Vorlagen unterstützen
denselben Satz an Variablen.
Das vollständige Testprojekt und der Vorlagencode befinden sich im Docotic.Pdf-Beispielrepository. Der Beispielcode zeigt, wie Variablen und Daten-URIs in den Vorlagen verwendet werden.
Passwortgeschützte HTML-zu-PDF-Konvertierung mit C#
Für den Zugriff auf einige Webseiten ist eine Authentifizierung erforderlich. Beim Aufruf einer sicheren URL, die eine HTTP-Authentifizierung erfordert, werden Sie vom Browser zur Eingabe von Benutzername und Passwort aufgefordert.
Mithilfe der Konvertierungsoptionen können Sie die API anweisen, Anmeldeinformationen für Webseiten bereitzustellen, die eine Anmeldung erfordern.
Der folgende C#-Code zeigt, wie passwortgeschütztes HTML in PDF konvertiert wird
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");
Das vollständige, lauffähige Beispiel finden Sie im Beispiel-Repository.
Falls die Seite Cookies benötigt, um korrekt zu funktionieren, ist die Vorgehensweise ebenfalls einfach. Fügen Sie diese Cookies einfach in den Optionen hinzu. So geht's:
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");
Verzögerter Konvertierungsstart
Standardmäßig startet die Konvertierung unmittelbar nach dem Laden der Seite. Eine verzögerte HTML-zu-PDF-Konvertierung kann sinnvoll sein, wenn die Seite nach dem Laden noch eine Weile aktualisiert wird. Dies ist häufig der Fall bei dynamischen Inhalten, die durch JavaScript oder AJAX-Aufrufe generiert werden.
Der Acid-3-Test ist ein perfektes Beispiel für eine Seite, die von einer Verzögerung vor der Konvertierung profitiert. Der Test führt eine Reihe von Prüfungen durch, um die Fähigkeit eines Browsers zur korrekten Darstellung komplexer Webseiten zu bewerten. Diese Prüfungen benötigen Zeit. Ändern Sie die Wartezeit im folgenden Code, um zu sehen, wie sich dies auf die Konvertierungsergebnisse auswirkt.
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");
Der obige Code zeigt, wie man HTML mit Verzögerung in PDF konvertiert. Die zusätzliche Zeit trägt zwar zu besseren Ergebnissen bei, jedoch kann sie die Performance beeinträchtigen. Unzureichende Verzögerungen können die Konvertierungsqualität negativ beeinflussen. Alternativ zur Verzögerung kann ein Skript verwendet werden, das so lange ausgeführt wird, bis die Seite vollständig geladen ist.
Das vollständige Testprojekt finden Sie im Docotic.Pdf-Beispielrepository.
Führe JavaScript vor der Konvertierung aus
Die Add-on-API ermöglicht es, JavaScript-Code vor der Konvertierung auszuführen. Dieser Code kann den HTML-Inhalt dynamisch generieren oder modifizieren. Beispielsweise kann er Elemente ein- und ausblenden oder das dynamische Laden von Inhalten ermöglichen.
Der folgende Code zeigt, wie die HTML-zu-PDF-Konvertierung verzögert wird, bis der JavaScript-Code abgeschlossen ist.
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");
Der obige Codeausschnitt dient lediglich der Veranschaulichung des Ansatzes. Ein praxisnäheres Beispiel finden Sie in der zugehörigen Beispiel-App in unserem GitHub-Repository. Die App zeigt, wie man mit Seiten umgeht, deren Inhalte dynamisch geladen werden. Der JavaScript-Code in der App scrollt die Seite, bis keine neuen Inhalte mehr vorhanden sind. Anschließend erfolgt die Konvertierung in PDF.
HTML in PDF in .NET konvertieren und SSL-Fehler ignorieren
Beim Senden sicherer Anfragen zum Laden von HTML prüft das Add-on, ob das SSL-Zertifikat, das die Identität einer Website authentifiziert und eine verschlüsselte Verbindung ermöglicht, gültig und vertrauenswürdig ist.
Standardmäßig löst das Add-on eine Ausnahme aus, wenn der HTML-zu-PDF-Konverter dem Zertifikat aus irgendeinem Grund nicht vertraut. Dies geschieht üblicherweise aufgrund eines selbstsignierten, widerrufenen oder abgelaufenen Zertifikats.
Wenn Sie sich des Risikos bewusst sind, ein nicht vertrauenswürdiges Zertifikat zu akzeptieren, können Sie das Add-on anweisen, die Prüfungen mithilfe der Engine-Optionen zu umgehen.
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");
Den vollständigen Code finden Sie im Docotic.Pdf-Beispiel-Repository.
HTML-Overlay auf ein bestehendes PDF
Es gibt Fälle, in denen Sie ein bestehendes PDF als Hintergrund für das Konvertierungsergebnis verwenden möchten. Beispielsweise, wenn Sie ein Bild eines Formulars haben und leere Bereiche darin mit Inhalten überdecken möchten. Das Ergebnis sieht dann aus wie ein ausgefülltes Formular. Mit Docotic.Pdf und dem entsprechenden Add-on ist dies möglich.
Dabei wird aus dem HTML-Code (dem Overlay-Inhalt) ein neues PDF erstellt und anschließend mit dem bestehenden PDF zusammengeführt. Das endgültige Dokument enthält sowohl den ursprünglichen Inhalt als auch das neue Overlay. Der folgende Code veranschaulicht den Vorgang.
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");
Es ist wichtig, eine Seitengröße für die Überlagerung anzugeben. Diese sollte üblicherweise der Größe der zu überlagernden Seite entsprechen. Anschließend muss das neue PDF mit dem Überlagerungsinhalt erstellt werden. Bitte beachten Sie, dass der Hintergrund standardmäßig transparent ist. Sie können den Hintergrund bei Bedarf ändern, indem Sie vor der Konvertierung ein Skript ausführen.
Der obige Code:
- erstellt ein PDF-Dokument mit einer transparenten Seite aus dem HTML-Code
- öffnet ein bestehendes PDF
- erstellt ein XObject aus der ersten Seite des konvertierten Dokuments im bestehenden Dokument
- zeichnet das XObject über die erste PDF-Seite des bestehenden Dokuments
Das vollständige Testprojekt mit einer Beispiel-Quell-PDF finden Sie im Docotic.Pdf-Beispiel-Repository.