Create and write PDF files in C# and VB.NET

Creating a PDF file from HTML

The simplest approach is to create a PDF from an existing HTML file. GemBox.Pdf uses pixel-perfect rendering with the same quality of result that you would get from a web browser.

To convert HTML to PDF, install the GemBox.Pdf library first. Then you need to install either the GemBox.Pdf.Html.Windows or GemBox.Pdf.Html.Linux NuGet library, depending on your platform. In Visual Studio, run one of the following commands in the NuGet Package Manager Console:

Install-Package GemBox.Pdf.Html.Windows
Install-Package GemBox.Pdf.Html.Linux

After that you can convert an HTML file to PDF using the HtmlConverter class:

var document = await HtmlConverter.ConvertFileToPdfAsync("%#Invoice.html%");
document.Save("Invoice.pdf");

Dim document = Await HtmlConverter.ConvertFileToPdfAsync("%#InputFileName%")
document.Save("Invoice.pdf")

Alternatively, you can generate a PDF from a URL or a HTML string.

document = await HtmlConverter.ConvertUrlToPdfAsync("https://www.gemboxsoftware.com");
document = await HtmlConverter.ConvertHtmlToPdfAsync("<h1>html</h1>");

document = Await HtmlConverter.ConvertUrlToPdfAsync("https://www.gemboxsoftware.com")
document = Await HtmlConverter.ConvertHtmlToPdfAsync("<h1>html</h1>")

To learn more about HTML to PDF conversion, see the HTML to PDF example.

Create a PDF with the API

Using the API of GemBox.Pdf gives you the most flexibility and control over the creation process. For this approach, you only have to have the GemBox.Pdf library installed.

The PDF document is represented by a PdfDocument class that contains a collection of PdfPage objects. The following code shows how to create a PDF document with a single empty page.

using (var document = new PdfDocument())
{
    var page = document.Pages.Add();
}

Using document As New PdfDocument()
    Dim page = document.Pages.Add()
End Using

You can save this empty document to a file with the PdfDocument.Save method.

document.Save("file.pdf");

document.Save("file.pdf")

Adding content to a page

The PDF format uses fixed layout, where every element has an exact position on a page and is independent of other elements. The text doesn’t automatically reflow and all line breaks are explicitly specified. This is different compared to reflowable (flow) layout of Word documents or HTML, where the position of an element adapts to the output device and the surrounding elements.

Imagine adding content to the page as drawing on a canvas. You need to know the precise coordinates of where you want the content to be shown. Similarly to drawing on canvas, additional content can be put on top of the existing content, but it will not move it.

The following code shows how to draw an image over the whole page:

var image = PdfImage.Load("FragonardReader.jpg");
var location = new PdfPoint(0, 0);
var size = new PdfSize(page.Size.Width, page.Size.Height);
page.Content.DrawImage(image, location, size);

Dim image = PdfImage.Load("FragonardReader.jpg")
Dim location As New PdfPoint(0, 0)
Dim size As New PdfSize(page.Size.Width, page.Size.Height)
page.Content.DrawImage(image, location, size)

Positioning elements inside a PDF

PDF uses a 2D Cartesian coordinate system with the origin (0, 0) at the bottom-left corner of a page. This is different from the top-left coordinate system used by HTML or UI frameworks. When placing the content on a page, the bottom-left corner of its bounding box is used for positioning.

To place a text 200 points from the left edge and 100 points from the bottom edge, you must first create a text instance:

using var formattedText = new PdfFormattedText();
formattedText.FontSize = 24;
formattedText.Append("GemBox.Pdf");

Using formattedText As New PdfFormattedText()
    formattedText.FontSize = 24
    formattedText.Append("GemBox.Pdf")
End Using

...and then draw it at a specified location:

page.Content.DrawText(formattedText, new PdfPoint(200, 100));

page.Content.DrawText(formattedText, New PdfPoint(200, 100))

To position the text relative to the top-left corner of the page, adjust the Y coordinate:

var topLeftCoordinates = new PdfPoint(200, 100);

var bottomLeftCoordinates = new PdfPoint(
    topLeftCoordinates.X, 
    page.Size.Height - topLeftCoordinates.Y - formattedText.Height);

page.Content.DrawText(formattedText, bottomLeftCoordinates);

Dim topLeftCoordinates As New PdfPoint(200, 100)

Dim bottomLeftCoordinates As New PdfPoint(
    topLeftCoordinates.X,
    page.Size.Height - topLeftCoordinates.Y - formattedText.Height
)

page.Content.DrawText(formattedText, bottomLeftCoordinates)

You can learn more about writing text in PDFs in our text writing example.

Adding elements to a page inside a PDF

You already saw how images and texts can be added to a page but GemBox.Pdf enables you to add various other elements to a page as well. Elements that can be added to a page include, but are not limited to:

• Text
• Images
• Shapes
• Hyperlinks
• Forms
• Charts
• Barcodes
• Watermarks
• Headers and Footers

You can find more information about each element in its dedicated article.

Transformations

When drawing the content, you can apply transformations to modify how the content will be displayed. Common transformation scenarios are scaling, rotating, or translating. Transformations are implemented via the PdfMatrix class that represents affine transformation matrix.

Even though transformations may sound scary at first, the API of GemBox.Pdf simplifies the process of creating the most common transformations with easy to use methods.

First, you start with PdfMatrix.Identity which represents no transformation:

var transform = PdfMatrix.Identity;

Dim transform = PdfMatrix.Identity

Then you can modify the transformation instance to layer multiple transformations. For example, the following code shows how to modify the transformation that will translate (move) the content, rotate it by 30 degrees, and scale it vertically by 200%:

transform.Translate(200, 100);
transform.Rotate(30);
transform.Scale(1, 2);

transform.Translate(200, 100)
transform.Rotate(30)
transform.Scale(1, 2)

You can then apply the transformation when drawing the content on a page:

page.Content.DrawText(formattedText, transform);

page.Content.DrawText(formattedText, transform)

Transformations are at the heart of PDF’s layouting. Every element on a page has a transformation. The positioning specified in the Positioning section is just a sugarcoat for translation transformation.

Content grouping

In its simplest form you can view the content of a page as a list of elements. However, elements in more complex PDF files form a tree structure. Multiple elements can be grouped together in the PdfContentGroup. Transformations applied to a group affect all its child elements. The positioning of elements inside a group is relative to the position of the group.

The following code illustrates how to create a simple group:

var greenSquare = page.Content.Elements.AddPath().AddRectangle(new PdfPoint(50, 50), new PdfSize(50, 50));
greenSquare.Format.Fill.IsApplied = true;
greenSquare.Format.Fill.Color = PdfColors.Green;

var group = page.Content.Elements.AddGroup();
group.Transform = PdfMatrix.CreateTranslation(150, 50);

var yellowSquare = group.Elements.AddPath().AddRectangle(new PdfPoint(0, 0), new PdfSize(50, 50));
yellowSquare.Format.Fill.IsApplied = true;
yellowSquare.Format.Fill.Color = PdfColors.Yellow;

var blueSquare = group.Elements.AddPath().AddRectangle(new PdfPoint(100, 0), new PdfSize(50, 50));
blueSquare.Format.Fill.IsApplied = true;
blueSquare.Format.Fill.Color = PdfColors.Blue;

Dim greenSquare = page.Content.Elements.AddPath().AddRectangle(New PdfPoint(50, 50), New PdfSize(50, 50))
greenSquare.Format.Fill.IsApplied = True
greenSquare.Format.Fill.Color = PdfColors.Green

Dim group = page.Content.Elements.AddGroup()
group.Transform = PdfMatrix.CreateTranslation(150, 50)

Dim yellowSquare = group.Elements.AddPath().AddRectangle(New PdfPoint(0, 0), New PdfSize(50, 50))
yellowSquare.Format.Fill.IsApplied = True
yellowSquare.Format.Fill.Color = PdfColors.Yellow

Dim blueSquare = group.Elements.AddPath().AddRectangle(New PdfPoint(100, 0), New PdfSize(50, 50))
blueSquare.Format.Fill.IsApplied = True
blueSquare.Format.Fill.Color = PdfColors.Blue

The tree structure of the page obtained via the PdfPage.Content.Elements property will look like this:

• greenRectangle - coordinates (50, 50)
• rectangleGroup - coordinates (150, 50)
  • yellowRectangle - coordinates relative to rectangleGroup (0, 0)
  • blueRectangle - coordinates relative to rectangleGroup (100, 0)

Additional features

GemBox.Pdf offers many other features for creating PDF files, including:

• Encrypting and digitally signing PDF files.
• Setting document properties and viewer preferences.
• Formatting (fill, stroke, and clip) the content.
• Creating bookmarks (outlines).
• Using custom fonts.

Working with low-level PDF structure

GemBox.Pdf provides a high-level API that enables you to create PDF files without understanding the complexity of the PDF file format. However, there are scenarios where you might need to dive deep into the specifics of the PDF file format and work with low-level objects. To gain deeper insight into PDF file structure and to understand how to work with low-level PDF objects in GemBox.Pdf, you can read this guide.

Combination of HTML to PDF conversion and GemBox.Pdf API

The combination of both approaches can give you the right balance between simplicity and flexibility. You can create an HTML file that will serve as a template and use GemBox.Pdf API to fill it with dynamic data.

The following example shows how to load an HTML document, add a watermark, and save it to PDF:

// Load HTML
var document = await HtmlConverter.ConvertFileToPdfAsync("%#Invoice.html%");

var page = document.Pages[0];

// Create formatted text
using var formattedText = new PdfFormattedText();
formattedText.FontSize = 130;
formattedText.Color = PdfColors.Red;
formattedText.FontWeight = PdfFontWeight.Bold;
formattedText.Opacity = 0.5;
formattedText.Append("PAID");

// Draw it in the center of the page
var location = new PdfPoint(
    (page.Size.Width - formattedText.Width) / 2,
    (page.Size.Height - formattedText.Height) / 2
);
page.Content.DrawText(formattedText, location);

// Save to PDF
document.Save("InvoiceWithWatermark.pdf");

' Load HTML
Dim document = Await HtmlConverter.ConvertFileToPdfAsync("%#Invoice.html%")

Dim page = document.Pages(0)

    'Create formatted text
    Using formattedText As New PdfFormattedText()
    formattedText.FontSize = 130
    formattedText.Color = PdfColors.Red
    formattedText.FontWeight = PdfFontWeight.Bold
    formattedText.Opacity = 0.5
    formattedText.Append("PAID")

    ' Draw it in the center of the page
    Dim location As New PdfPoint(
        (page.Size.Width - formattedText.Width) / 2, 
        (page.Size.Height - formattedText.Height) / 2
    )
    page.Content.DrawText(formattedText, location)
End Using

' Save to PDF
document.Save("InvoiceWithWatermark.pdf")