C# PDF generation quick start guide

Read about how to generate PDF files like reports, invoices and receipts in your .NET projects. Using C# or VB.NET, create PDF documents easily by composing structural elements. The elements include headers, footers, containers, tables, paragraphs, images, and the like. The API automatically breaks content into pages.

Some other methods of generating PDF files described in the Create PDF documents in C# and VB.NET article.

We offer the layout API as a free add-on for Docotic.Pdf library. Both the library and Layout add-on are available on NuGet and from our site. Get the library, the add-on, and a free time-limited license key on the Download C# .NET PDF library page.

Installation

Install the BitMiracle.Docotic.Pdf.Layout package from NuGet. This is the easiest and most convenient way to install Layout add-on.

As an alternative, you can download the ZIP with the library binaries on our site. To use Layout API, add references to the following DLLs from the ZIP package:

• BitMiracle.Docotic.Pdf.dll
• Layout add-on/BitMiracle.Docotic.Pdf.Layout.dll

The approach

The entry point is the PdfDocumentBuilder class. To start generating a PDF, you call the Generate method of the class. The method requires a delegate of the Action<Document> type as one of its parameters. The library expects you to layout document contents in the delegate.

PdfDocumentBuilder.Create().Generate("output.pdf", (Document doc) =>
{
    // build document contents here
});

Given a Document object, the delegate should define layout. The complete layout consists of smaller building blocks. Pages, headers and footers, containers, text blocks are examples of such blocks.

Many method calls are chained together. The order of calls in a chain is important. Here is an example that shows how to set up pages content in a few chained calls.

PdfDocumentBuilder.Create()
    .Generate("output.pdf", doc => doc.Pages(pages =>
    {
        pages.Content().Padding(24).AlignCenter().Text("Some text");
    }));

Intellisense will help you with discovering the API. Try the API yourself. I hope you find it easy to use.

Hello, world!

Let's develop a simple application that shows common building blocks in action. The app will use the approach mentioned above.

I put the complete application code in our Docotic.Pdf sample code repository. The code for this step is in the HelloWorld class of the example app.

public void CreatePdf()
{
    PdfDocumentBuilder.Create().Generate("hello.pdf", doc => doc.Pages(page =>
    {
        page.Content().Text("Hello, world!");
    }));
}

Not much code, but what is happening here?

Long explanation for the short code

The code creates an instance of the document builder, asks the builder to generate hello.pdf. The builder delegates the job of document content layout to my code.

In the code of the delegate, I ask the document to build some pages. Now the document delegates the job of laying out the content of the pages to my code.

In the delegate for the pages, I access the layout container for the primary content of the pages. I do this by calling the Content method. The chained call to the Text adds the famous text span to the content of the pages.

Now it is time for the builder to generate the document with some pages according to the provided layout. The builder creates the exact number of pages required to contain the data I added into the layout container for the primary content. One page is enough in this case? Okay.

Prepare for future updates

I am going to add some more features to the code. To make it more convenient to develop the app further, I changed the code like this:

public void CreatePdf()
{
    PdfDocumentBuilder.Create().Generate("hello.pdf", BuildDocument);
}

static void BuildDocument(Document doc)
{
    doc.Pages(BuildPages);
}

static void BuildPages(PageLayout pages)
{
    pages.Content().Text("Hello, world!");
}

It might look unnecessary, but splitting the code into methods at least makes it more readable.

The sample code for this step is in the HelloWorld2 class of the example app.

Related resources

Please check the following articles for more information about documents, pages and containers.

• Building documents
• How to layout pages
• Containers and their content

Fonts and colors

The default font is good, but I will show how to use another one. The main idea is to create a text style using a font. Then, if needed, apply some optional properties to the style and, finally, use the style on a text span.

You can use a font from the collection of fonts installed in the operating system or load a font from a file or a stream.

I recommend overriding the pre-defined styles by setting up typography for the document. But that is not required and you can use text styles directly.

The sample code for this step is in the HelloWorld3 class of the example app. Below are the parts that changed from the previous step.

static void BuildDocument(Document doc)
{
    doc.Typography(t =>
    {
        t.Document = doc.TextStyleWithFont(SystemFont.Family("Calibri"));
    });
    doc.Pages(BuildPages);
}

static void BuildPages(PageLayout pages)
{
    pages.Size(PdfPaperSize.A6);
    pages.Margin(10);

    BuildTextContent(pages.Content());
}

static void BuildTextContent(LayoutContainer content)
{
    var colorAccented = new PdfRgbColor(56, 194, 10);
    var styleAccented = TextStyle.Parent.FontColor(colorAccented);

    content.Text(t =>
    {
        t.Span("Hello, ").Style(styleAccented);
        t.Span("world!").Style(styleAccented.Underline());
    });
}

As you can see, I have updated the code for the BuildDocument and the BuildPages. I also added a new method named BuildTextContent.

In the BuildDocument, I create a text style from the system font named "Calibri". Then I set this text style as the default text style for the document.

The BuildPages method now contains code for setting size and margin for all pages. Also, the method calls the BuildTextContent, passing the container for the primary content of the pages as the parameter.

The way I construct the primary content is different now. I use two text spans and apply different text styles to each span. In effect, both spans use the accent color, but the second span also has an underline.

The code produces a PDF with the custom text font and color. If your result contains a trial message warning, please get a free time-limited license on the Docotic.Pdf library page.

Header and footer

Many real-world PDF documents like reports or invoices contain header and footer. Let me show how to add header and footer to a PDF.

The sample code for this step is in the HelloWorld4 class of the example app. Below are the parts that changed from the previous step.

static void BuildPages(PageLayout pages)
{
    pages.Size(PdfPaperSize.A6);
    pages.Margin(10);

    BuildPagesHeader(pages.Header());
    BuildPagesFooter(pages.Footer());

    BuildTextContent(pages.Content());
}

static void BuildPagesHeader(LayoutContainer header)
{
    header.TextStyle(TextStyle.Parent.FontSize(8))
        .AlignRight()
        .Text(t =>
        {
            t.Line($"Created by: {Environment.UserName}");
            t.Line($"Date: {DateTime.Now}");
        });
}

static void BuildPagesFooter(LayoutContainer footer)
{
    footer.Height(20)
        .Background(new PdfGrayColor(95))
        .AlignCenter()
        .Text(t => t.CurrentPageNumber());
}

I changed the BuildPages method to call the BuildPagesHeader with the header container as the parameter. The method also calls the BuildPagesFooter passing the footer container to it.

The resulting PDF with header and footer definitely looks more like a professional PDF document.

The BuildPagesHeader method sets a smaller font size for the text. I use two lines for the header contents: one with the name of the current user and the second with the current date. The text is right-aligned.

Please note that I do not specify any explicit size for the header. It will occupy the entire page width minus the left and the right margins. The height will depend on the text lines height.

The footer is similar, except that it has its height specified explicitly. And there is a background color applied to it. The interesting part is that to put the current page number in the PDF footer, I can just use the CurrentPageNumber method. All calculations happen inside the library.

Images

As they say, you can save a lot of words by using one picture. In a quote or receipt, you will probably use a logo of your company or some other important image. For this example code, I will use just a nice-looking one.

The file is on our site, for you to see how the resulting PDF with the beautiful image looks like.

To use an image, you would need to add it to the document first. The library can read the image from a file or a stream. I changed the BuildDocument method to show how to add an image to the document.

The sample code for this step is in the HelloWorld5 class of the example app. Below are the parts that changed from the previous step.

static void BuildDocument(Document doc)
{
    doc.Typography(t =>
    {
        t.Document = doc.TextStyleWithFont(SystemFont.Family("Calibri"));
    });

    var imageFile = new FileInfo("red-flowers-at-butterfly-world.jpg");
    var image = doc.Image(imageFile);

    doc.Pages(pages => {
        BuildPages(pages);

        pages.Content().Column(c =>
        {
            BuildTextContent(c.Item());
            BuildImageContent(c.Item(), image);
        });
    });
}

static void BuildPages(PageLayout pages)
{
    pages.Size(PdfPaperSize.A6);
    pages.Margin(10);

    BuildPagesHeader(pages.Header());
    BuildPagesFooter(pages.Footer());
}

static void BuildImageContent(LayoutContainer content, Image image)
{
    content.AlignCenter()
        .PaddingVertical(20)
        .Image(image);
}

As you can see, there are more changes in the BuildDocument method. Before, the code used the Text method to set some text as the primary content for pages. This still happens in the BuildTextContent method. But now I also want an image in the content.

To have both the text and the image in the primary content of the pages, I need a container. I use the Column container to add the text and the image vertically one after another. The Item method of the column container provides a sub-container. I use one call to the Item method to get a container for the text and another call to get a container for the image.

As you can see, I didn't change the BuildTextContent a bit. But, of course, I had to remove a call to the BuildTextContent from the BuildPages method.

The BuildImageContent does an important job in three lines. It adds the image with some padding at the top and at the bottom. And it also centers the image on the page.

We have more information about the Column container and images in the following articles.

• Containers and their content
• Compound containers

Lists

What is a list? Let's think of it as a group of numbered items written one below the other. This idea suggests a way to implement a list.

The sample code for this step is in the HelloWorld6 class of the example app. Below are the parts that changed from the previous step.

static void BuildDocument(Document doc)
{
    ....

    doc.Pages(pages => {
        BuildPages(pages);

        pages.Content().Column(c =>
        {
            BuildTextContent(c.Item());
            BuildImageContent(c.Item(), image);
            BuildListContent(c.Item());
        });
    });
}

static void BuildListContent(LayoutContainer content)
{
    var dayNames = DateTimeFormatInfo.InvariantInfo.DayNames;
    var dayNamesSpain = DateTimeFormatInfo.GetInstance(new CultureInfo("es-ES")).DayNames;

    content.Column(column =>
    {
        for (int i = 0; i < dayNames.Length; i++)
        {
            column.Item().Row(row =>
            {
                row.Spacing(5);
                row.AutoItem().Text($"{i + 1}.");
                row.RelativeItem().Text(t => {
                    t.Line(dayNames[i]);
                    t.Line($"In Spain they call it {dayNamesSpain[i]}");
                });
            });
        }
    });
}

The only change in the BuildDocument is the new method call. I added the call to the BuildListContent after the BuildImageContent call.

The BuildListContent creates the list as a column of rows. In each row, there are two items. The first (left) one is for the item number. Another (right) one is for the item text. The code explicitly sets the spacing between the items in the row.

To arrange items, the Row container needs to know beforehand or calculate the size of each item. I use the AutoItem and the RelativeItem methods in this example. As the result, the row container will calculate the width required to contain the first item. Then the container will use the remaining available width for the second item.

After adding the list, the contents of the resulting PDF no longer fit one page. Layout API automatically adds the second page and puts the list on it. You can see that API repeated the header and footer on the new page in the PDF document with multiple pages.

We have more information about lists in the Compound containers article.

Tables

Many PDF documents contain tables. There is no surprise here because tables enhance clarity and organization of data. Let me show how to create a table in PDF using Layout API.

The sample code for this step is in the HelloWorld7 class of the example app. Below are the parts that changed from the previous step.

static void BuildDocument(Document doc)
{
    ....

    doc.Pages(pages => {
        BuildPages(pages);

        pages.Content().Column(c =>
        {
            BuildTextContent(c.Item());
            BuildImageContent(c.Item(), image);
            BuildListContent(c.Item());
            BuildTableContent(c.Item());
        });
    });
}

static void BuildTableContent(LayoutContainer content)
{
    var color = new PdfGrayColor(75);

    content.PaddingTop(20).Table(t =>
    {
        t.Columns(c =>
        {
            c.RelativeColumn(4);
            c.RelativeColumn(1);
            c.RelativeColumn(4);
        });

        t.Header(h =>
        {
            h.Cell().Background(color).Text("Month in 2024");
            h.Cell().Background(color).Text("Days");
            h.Cell().Background(color).Text("First Day");
        });

        for (int i = 0; i < 12; i++)
        {
            var stats = GetMonthStats(2024, i);

            t.Cell().Text(stats.Item1);
            t.Cell().Text(stats.Item2);
            t.Cell().Text(stats.Item3);
        }
    });
}

static (string, string, string) GetMonthStats(int year, int monthIndex)
{
    return (
        DateTimeFormatInfo.InvariantInfo.MonthNames[monthIndex],
        DateTime.DaysInMonth(year, monthIndex + 1).ToString(),
        new DateTime(year, monthIndex + 1, 1).DayOfWeek.ToString()
    );
}

The call to the BuildTableContent is the only change in the BuildDocument.

In the BuildTableContent, I create a simple table. The table displays trivial information about months in the year 2024. For a start, I define three columns with relative widths. The left- and the rightmost columns will be 4 times wider than the column in the middle.

The code also defines the header for the table. It does so by adding header cells and specifying text and background color for each cell. When the table does not fit onto one page, the header gets repeated on each page occupied by the table. You can see this in the resulting PDF document with table. In the document, the table starts on the second page and continues on the third one.

I am using the simple loop to make up rows. The code in the loop starts by retrieving the information about each month. Then it adds three cells making up a row of information.

The Table container article explains all the Table container features in greater detail.

Sample code

Above, I presented some of the more popular features of PDF generation in C#. I suggest you continue discovering the API by reading the following article. Also try the sample code from Docotic.Pdf.Samples repository on GitHub. The sample code for Layout API is in the Layout folder of the repository.

You can use the sample code as a code playground. This way you can try some ideas without starting from scratch each time.

The same sample code is in the Samples folder of the ZIP package. There are two solution files. The SamplesCSharp is for sample projects that use C# language. And the SamplesVB.NET is for the VB.NET versions.