Diese Seite kann automatisch übersetzten Text enthalten.
HTML in C# und VB.NET in PDF konvertieren
Wenn Sie bereits erheblich Zeit und Geld in die Erstellung von Inhalten in HTML-Form investiert haben, möchten Sie daraus möglicherweise PDFs erstellen. Dieser Ansatz ist eine naheliegende Wahl für alle, die doppelte Arbeit vermeiden möchten.
Dieser Artikel ist ein ausführlicher Leitfaden zur Konvertierung von HTML in PDF in .NET mit Docotic.Pdf zusammen mit dem kostenlosen HtmlToPdf-Add-on.
Informationen dazu, warum Docotic.Pdf die richtige Wahl ist, wie Sie das Add-on installieren und wie die Konvertierung intern funktioniert, finden Sie auf der Seite Überblick über die HTML-zu-PDF-API.
Einfache HTML-zu-PDF-Konvertierung in C#
Installieren Sie zunächst das Add-on.
Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf
Mit der HTML-zu-PDF-API kann der C#-Konvertierungscode so 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);
}
Das ist recht einfach. Für die Erstellung eines PDF-Dokuments sind nur zwei Aufrufe erforderlich.
Der Code erstellt eine Instanz des Konverters und verwendet sie, um aus HTML ein PDF zu generieren. Sie können das PDF-Dokument bearbeiten oder es mit einer digitalen Signatur signieren. Der Einfachheit halber speichert der Beispielcode das Dokument unverändert.
Wie Sie sehen, ist die API asynchron und stellt überhaupt keine synchronen Methoden bereit.
Verwendung der asynchronen API in synchronem Code
Es gibt Fälle, in denen Sie die API aus synchronem Code aufrufen müssen. Wenn Ihre Konsolenanwendung beispielsweise eine ältere C#-Version verwendet und Sie kein async Main haben. Keine Sorge, Sie können das Add-on trotzdem in Ihrer App verwenden.
Der folgende Code zeigt, wie man eine URL in einer regulären synchronen Methode in PDF konvertiert:
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 ähnlichen Code. Hier ist ein Ausschnitt, der 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 im Allgemeinen nicht empfohlen wird, asynchrone Methoden synchron aufzurufen. Verwenden Sie den Wrapper daher nur, wenn Sie keine andere Wahl haben.
Beispielcode
Wir stellen Beispielcode für Konsolen-, Windows Forms- und WPF-Anwendungen bereit. Laden Sie die vollständigen Testprojekte aus unserem GitHub-Repository herunter:
Es gibt auch die HTML-zu-PDF-Gruppe von Beispielen. Jedes Beispiel liegt in einer C#- und einer VB.NET-Version vor.
Eine PDF-Datei mit einem HTML-String oder einer Datei in C# und VB.NET erstellen
Mit der API ist es einfach, einen HTML-String in PDF zu konvertieren. Der String kann ein vollständiges HTML-Dokument oder nur ein Fragment enthalten. Der Konverter erstellt für Sie ein PDF aus dem HTML-Code.
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 eine Basis-URL für alle relativen Links im HTML angeben. So legen Sie eine Basis-URL mit den 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.
Die Konvertierung einer HTML-Datei ist fast dasselbe wie die Konvertierung einer URL. Verwenden Sie einfach die CreatePdfAsync-Überladung, die statt einer URL einen Pfad akzeptiert. Die Basis-URL und weitere Optionen werden auch unterstützt, wenn Sie in C#- oder VB.NET-Code eine HTML-Datei in PDF konvertieren.
var sampleHtmlPath = @"C:\path\to\sample.html";
using var pdf = await converter.CreatePdfAsync(sampleHtmlPath);
pdf.Save("output.pdf");
Sie können mit der API auch SVG-Bilder in PDF konvertieren.
Benutzerdefinierte Seitengröße, Ränder und Skalierung verwenden
Bei Webseiten mit breiten Layouts können Sie entweder die Ausgabe-PDF-Größe erhöhen oder den Inhalt verkleinern, damit er auf die PDF-Seite passt. Um den skalierten Inhalt besser zu positionieren, können Sie außerdem Ränder festlegen.
Ein gut skaliertes PDF bietet ein besseres Leseerlebnis, da Leser nicht hinein- oder herauszoomen müssen, um den Inhalt korrekt anzuzeigen. Wenn das HTML-Dokument wegen einer kleinen Schriftgröße schwer lesbar ist, können Sie den Inhalt vergrößern.
Standardmäßig erzeugt die API PDFs mit einer Seitengröße gleich A4. Es gibt keine Ränder und keine Vergrößerung. Mit den Konvertierungsoptionen können Sie diese Einstellungen ändern.
So legen Sie Skalierungsfaktor und Ränder fest, wenn PDF aus HTML generiert wird
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-Beispiel-Repository enthält das vollständige Projekt.
Kopf- und Fußzeilenvorlagen angeben
Die HTML-zu-PDF-API kann wiederholbare Fuß-/Kopfzeilenblöcke auf generierten Seiten hinzufügen. Der Konverter erstellt die Blöcke aus den in den Seitenoptionen angegebenen HTML-Vorlagen. Wir empfehlen, in den Vorlagen Inline-Styles und Data-URIs für Bilder zu verwenden.
Der Konverter platziert Kopf- und Fußzeilen innerhalb der Seitenränder. Da die Standard-Seitenränder klein sind, sind Inhalte der Kopf- und Fußzeile möglicherweise nicht sichtbar. Wir empfehlen, obere und untere Ränder explizit anzugeben. Die Größe sollte jeweils der Größe von Kopf- und Fußzeile entsprechen.
So ändern Sie HTML zu PDF und fügen Kopf- und Fußzeilen hinzu
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 Kopfzeilenvorlagen als auch die Fußzeilenvorlagen unterstützen denselben Variablensatz.
Das vollständige Testprojekt und Vorlagencode befindet sich im Docotic.Pdf-Beispiel-Repository. Der Beispielcode zeigt, wie die Variablen und Data-URIs in den Vorlagen verwendet werden.
Passwortgeschützte HTML-zu-PDF-Konvertierung in C#
Manche Webseiten erfordern eine Authentifizierung, um darauf zugreifen zu können. Wenn Sie eine sichere URL aufrufen, die HTTP-Authentifizierung erfordert, fordert der Browser Sie auf, Benutzername und Passwort anzugeben.
Mit den Konvertierungsoptionen können Sie die API anweisen, Anmeldeinformationen für Webseiten bereitzustellen, die eine Anmeldung erfordern.
Dieser C#-Code zeigt, wie man passwortgeschütztes HTML in PDF konvertiert
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ändig lauffähige Beispiel finden Sie im Beispiel-Repository.
Es ist auch einfach, wenn die Seite für die korrekte Funktion einige gesetzte Cookies benötigt. Fügen Sie diese Cookies einfach zu 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");
Start der Konvertierung verzögern
Standardmäßig beginnt die Konvertierung unmittelbar nach dem Laden. Das Verzögern der HTML-zu-PDF-Konvertierung kann nützlich sein, wenn die Seite nach dem Laden noch eine Weile aktualisiert wird. Das ist oft der Fall bei dynamischem Inhalt, der durch JavaScript oder AJAX-Aufrufe erzeugt wird.
Der Acid-3-Test ist ein perfektes Beispiel für eine Seite, bei der eine Verzögerung vor der Konvertierung hilfreich wäre. Der Test führt mehrere Prüfungen aus, um die Fähigkeit eines Browsers zu bewerten, komplexe Webseiten korrekt darzustellen. Diese Prüfungen dauern Zeit. Ändern Sie die Wartezeit im folgenden Code, um zu sehen, wie sich das 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 hilft zwar, bessere Ergebnisse zu erzielen, aber beachten Sie bitte, dass Verzögerungen die Leistung beeinflussen können. Zu geringe Verzögerungen können die Qualität der Konvertierung negativ beeinflussen. Eine Alternative zur Verwendung einer Verzögerung ist die Verwendung eines Skripts, das ausgeführt wird, bis die Seite bereit ist.
Sie erhalten das vollständige Testprojekt im Docotic.Pdf-Beispiel-Repository.
JavaScript vor der Konvertierung ausführen
Die Add-on-API bietet eine Möglichkeit, vor der Konvertierung JS-Code auszuführen. Der Code kann HTML-Inhalte dynamisch erzeugen oder ändern. Er kann beispielsweise Elemente umschalten oder das Laden dynamischer Inhalte auslösen.
Der folgende Code zeigt, wie man die HTML-zu-PDF-Konvertierung verzögert, bis JavaScript beendet 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 Ausschnitt verwendet sehr einfachen Code, um den Ansatz zu verdeutlichen. Ein realistischeres Beispiel finden Sie in der entsprechenden Beispiel-App in unserem GitHub-Repository. Die App zeigt, wie man mit einer Seite umgeht, die ihren Inhalt dynamisch lädt. Der JavaScript-Code in der App scrollt die Seite, bis kein neuer Inhalt mehr vorhanden ist. Danach erfolgt die Konvertierung in PDF.
HTML in .NET unter Ignorieren von SSL-Fehlern in PDF konvertieren
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. Das liegt meist an einem selbst signierten, widerrufenen oder abgelaufenen Zertifikat.
Wenn Sie das Risiko der Annahme eines nicht vertrauenswürdigen Zertifikats verstehen, können Sie dem Add-on über die Engine-Optionen anweisen, die Prüfungen 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 über ein vorhandenes PDF legen
Es gibt Fälle, in denen Sie ein vorhandenes PDF als Hintergrund für das Konvertierungsergebnis verwenden möchten. Zum Beispiel, wenn Sie ein Bild eines Formulars haben und etwas über leere Bereiche in diesem Bild legen möchten. Das Ergebnis sieht dann wie ein ausgefülltes Formular aus. Mit Docotic.Pdf und dem Add-on ist das möglich.
Bei diesem Vorgang wird aus dem HTML (dem Overlay-Inhalt) ein neues PDF erstellt und dann mit dem vorhandenen PDF zusammengeführt. Das endgültige Dokument enthält sowohl den ursprünglichen Inhalt als auch das neue Overlay. Hier ist der Code, der den Ablauf veranschaulicht.
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, für das Overlay eine Seitengröße anzugeben. In der Regel sollte die Größe der Seite entsprechen, die Sie überlagern möchten. Dann müssen Sie das neue PDF mit dem Overlay-Inhalt erzeugen. 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 aus dem HTML ein PDF-Dokument mit einer transparenten Seite
- öffnet ein vorhandenes PDF
- erstellt ein XObject aus der ersten Seite des konvertierten Dokuments im vorhandenen Dokument
- zeichnet das XObject über die erste PDF-Seite des vorhandenen Dokuments
Das vollständige Testprojekt mit einem Beispiel-Quelldokument PDF befindet sich im Docotic.Pdf-Beispiel-Repository.