Click or drag to resize

Getting Started with ExpertPdf PDF Merger Library for .NET

ExpertPdf PDF Merge Library for .NET combines PDF documents and images into one PDF document. It can be used in any type of .NET application: console and Windows Forms applications, Windows services, ASP.NET and ASP.NET Core web applications.

The library is one assembly, epmergepdf.dll. The main class is PDFMerge: you append documents, images and empty pages to it in the order they must appear, then save the merged document.

Features
  • Merge PDF documents from files, streams and byte arrays: the whole document, the pages from a start page to the end, or a range of pages.

  • Merge password protected documents, opened with their user or owner password.

  • Add images - BMP, GIF, JPEG, PNG, TIFF files or a System.Drawing.Image created in code - and empty pages, each on a new page.

  • Insert a document, a range of pages, an image or an empty page at any position, and change the order of the merged pages.

  • Add a bookmark for each merged document (titled from its file name or document title), with the bookmarks of the document nested under it; or leave the bookmarks out.

  • Save the merged pages as a booklet: two pages on each landscape sheet, in saddle stitch order, for single or double-sided printing.

  • Choose the page size and orientation of the pages the library creates, and the compression level of the merged document.

  • Set the document information: title, subject, author, keywords, creation date.

  • Protect the merged document: user and owner passwords, print, copy, edit, form fill and assemble permissions, RC4 or AES encryption with 40, 128 or 256 bit keys.

  • Save the merged document as PDF/A-1b, PDF/A-2b, PDF/A-3b, PDF/A-3u or PDF/X-1a.

  • Save to a file, a stream or a byte array.

Requirements
  • .NET Framework 4.0 or later. The download also has a build for .NET Framework 2.0 - 3.5 applications.

  • .NET Core 2.0 or later and .NET 5 to .NET 11, through the .NET Standard 2.0 build in the NuGet package.

  • Windows 10, Windows 11, Windows Server 2016 or later, 32-bit or 64-bit.

Installation using the NuGet package

The easiest way to install the library is the ExpertPdf.MergePdf package (https://www.nuget.org/packages/ExpertPdf.MergePdf/). In Visual Studio open the NuGet Package Manager and install the package, or run:

dotnet add package ExpertPdf.MergePdf

The package works for .NET Framework and for .NET Core / .NET 5 to .NET 11 projects. It is for AnyCPU and x86 applications. ExpertPdf.MergePdf.x64 (https://www.nuget.org/packages/ExpertPdf.MergePdf.x64/) is the x64 optimized build, for applications that target the x64 platform and run in a 64-bit process.

Installation using the downloaded assemblies

The download contains:

  • Bin\.NET_4.0\epmergepdf.dll - the library for .NET Framework 4.0 and later

  • Bin\epmergepdf.dll - the library for .NET Framework 2.0 - 3.5

  • Samples - samples for .NET Framework 4.6.2, in C# and VB.NET

  • Samples_NET_10 - the same samples for .NET 10 and .NET 11, using the NuGet package

Add a reference to the epmergepdf.dll for your framework to your project.

Getting started

Create a PDFMerge, append the documents and images, and save the result with SaveMergedPDFToFile(String):

using ExpertPdf.MergePdf;

PDFMerge pdfMerge = new PDFMerge();
// pdfMerge.LicenseKey = "your license key";

pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf");
pdfMerge.AppendImageFile(@"C:\Documents\chart.png");    // on a new page
pdfMerge.AppendEmptyPage();
pdfMerge.AppendPDFFile(@"C:\Documents\invoice.pdf");

pdfMerge.SaveMergedPDFToFile(@"C:\Documents\merged.pdf");

The options of the merged document are given to the constructor in a PdfDocumentOptions object. The page size and orientation (A4 and portrait by default) are used for the pages the library creates - images and empty pages; the pages of the appended PDF documents keep their own size.

PdfDocumentOptions options = new PdfDocumentOptions();
options.PdfPageSize = PdfPageSize.Letter;
options.PdfPageOrientation = PDFPageOrientation.Landscape;
options.PdfCompressionLevel = PDFCompressionLevel.Best;

PDFMerge pdfMerge = new PDFMerge(options);
Page ranges, streams and memory

Each Append method has versions that take only some pages of the source document: from a zero based start index to the end, or a number of pages from the start index (a negative number of pages also means "to the end"). Documents can come from a file (AppendPDFFile(String, Int32, Int32)), a stream (AppendPDFStream(Stream, Int32, Int32)) or a byte array (AppendPDFBytes(Byte, Int32, Int32)), for example a document just created in memory by another ExpertPdf library. A stream must stay open until the merged document is saved.

PDFMerge pdfMerge = new PDFMerge();

// the first two pages of the report
pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf", 0, 2);
// a whole document from memory
pdfMerge.AppendPDFBytes(File.ReadAllBytes(@"C:\Documents\invoice.pdf"));
// the report from its fifth page to the end
pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf", 4);
// an image created in code
using (Image chart = Image.FromFile(@"C:\Documents\chart.png"))
{
    pdfMerge.AppendImageObject(chart);

    Console.WriteLine("Pages: " + pdfMerge.GetCurrentPageCount());

    // the merged document in memory, for example to send it in a web response
    byte[] mergedBytes = pdfMerge.RenderMergedPDFDocument();
}

GetPageCount(String) is a fast way to get the page count of a document before you merge it.

Document information, security and protected sources

DocumentInfo sets the title, subject, author and keywords of the merged document, and SecurityOptions protects it. The user password opens the document with the permissions you set; the owner password opens it with all the rights. When only a user password is set, it is also the owner password.

PDFMerge pdfMerge = new PDFMerge();

pdfMerge.DocumentInfo.Title = "Report with invoice";
pdfMerge.DocumentInfo.AuthorName = "Sample Company";
pdfMerge.DocumentInfo.Keywords = "report, invoice";

pdfMerge.SecurityOptions.UserPassword = "user";
pdfMerge.SecurityOptions.OwnerPassword = "owner";
pdfMerge.SecurityOptions.KeySize = EncryptionKeySize.EncryptKey256Bit;
pdfMerge.SecurityOptions.CanCopyContent = false;
pdfMerge.SecurityOptions.CanEditContent = false;

// a protected source document is opened with its user or owner password (-1 = all the pages)
pdfMerge.AppendPDFFile(@"C:\Documents\protected.pdf", "password", 0, -1);
pdfMerge.AppendPDFFile(@"C:\Documents\invoice.pdf");

using (FileStream output = File.Create(@"C:\Documents\secured.pdf"))
{
    pdfMerge.SaveMergedPDFToStream(output);
}
Insert and reorder pages

The Insert methods add a document, a range of pages, an image or an empty page at a zero based position in the merged document: 0 inserts before the first page, GetCurrentPageCount at the end. They take the same arguments as the Append methods, after the position: InsertPDFFile(Int32, String), InsertPDFStream(Int32, Stream, String, Int32, Int32), InsertPDFBytes(Int32, Byte, Int32, Int32), InsertImageFile(Int32, String) and InsertEmptyPage(Int32). ReorderPages(Int32) changes the order of the pages merged so far: the new order lists, for each position, the current index of the page that goes there, and contains every page once. The bookmarks keep opening the same pages and are listed in the order of the pages.

PDFMerge pdfMerge = new PDFMerge();

pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf");          // 6 pages
pdfMerge.InsertPDFFile(1, @"C:\Documents\invoice.pdf");      // after the first page
pdfMerge.InsertEmptyPage(0);                                 // in front

// reverse the order of the 8 pages
pdfMerge.ReorderPages(new int[] { 7, 6, 5, 4, 3, 2, 1, 0 });

pdfMerge.SaveMergedPDFToFile(@"C:\Documents\merged.pdf");
Bookmarks

By default the merged document keeps the bookmarks of the merged documents. With AddDocumentBookmarks set to true, each merged document - and each image appended from a file - gets a bookmark that opens its first page, and its own bookmarks are nested under it. TitleSource takes the title from the file name or from the document title (a document from a stream or memory without a title is "Document N"), and SetBookmarkTitle(String) sets the title of the document added last. KeepSourceBookmarks set to false leaves the bookmarks of the merged documents out.

PDFMerge pdfMerge = new PDFMerge();
pdfMerge.BookmarkOptions.AddDocumentBookmarks = true;
pdfMerge.BookmarkOptions.TitleSource = BookmarkTitleSource.DocumentTitle;

pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf");
pdfMerge.AppendPDFFile(@"C:\Documents\invoice.pdf");
pdfMerge.SetBookmarkTitle("Invoice");

pdfMerge.SaveMergedPDFToFile(@"C:\Documents\merged.pdf");
Booklets

With Enabled set to true the merged pages are saved two by two on landscape sheets of PageSize (A4 sheets, so A5 pages, by default), in the order that gives a booklet when the printed sheets are folded in the middle. Each page is scaled to fit its half of the sheet. The page count is completed to a multiple of 4 with empty halves at the end. With TwoSided the sheets are ordered for double-sided printing (for 8 pages: 8|1, 2|7, 6|3, 4|5; flip on the short edge); otherwise each sheet holds a page and its counterpart from the end, in reading order (1|8, 2|7, 3|6, 4|5). A booklet has no bookmarks; the document information, security and PDF standard apply to it as usual.

PDFMerge pdfMerge = new PDFMerge();
pdfMerge.BookletOptions.Enabled = true;
pdfMerge.BookletOptions.PageSize = PdfPageSize.A4;
pdfMerge.BookletOptions.TwoSided = true;

pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf");
pdfMerge.SaveMergedPDFToFile(@"C:\Documents\booklet.pdf");
PDF/A and PDF/X

Set PdfStandardSubset to save the merged document as PDF/A-1b, PDF/A-2b, PDF/A-3b or PDF/A-3u for long term archiving, or as PDF/X-1a for graphics exchange. The source documents are imported as they are: for a conformant result they must be suitable for the standard - for example, their fonts must be embedded for PDF/A. The PDF/A standards do not allow encryption: do not set passwords for a PDF/A document.

PdfDocumentOptions options = new PdfDocumentOptions();
options.PdfStandardSubset = PdfStandardSubset.Pdf_A_2b;

PDFMerge pdfMerge = new PDFMerge(options);
pdfMerge.DocumentInfo.Title = "Archived report";
pdfMerge.AppendPDFFile(@"C:\Documents\report.pdf");
pdfMerge.AppendPDFFile(@"C:\Documents\invoice.pdf");
pdfMerge.SaveMergedPDFToFile(@"C:\Documents\archive.pdf");
Samples

The Samples (.NET Framework 4.6.2) and Samples_NET_10 (.NET 10 and .NET 11) folders have the same samples, in C# and VB.NET:

  • MergePdfCommandLine - a command line tool that merges PDF files, images and empty pages, with options for the page size, orientation, compression, PDF standard, title, passwords, a bookmark per document and booklets.

  • MergePdfFeatures - page ranges, documents from memory and streams, an image created in code, document information and security, password protected sources, PDF/A-2b, inserting and reordering pages, a bookmark per document, a booklet.

  • WinForms_MergePdfDemo - a Windows Forms application that merges page ranges of two documents, with a title and an open password.

They work on the documents and the image that come with them and need no arguments.

PDF Merge command line tool

The MergePdfCommandLine sample is also a ready to use tool. The syntax is:

MergePdfCommandLine {/pdf:file | /image:file | /emptypage}+ [/out:file]
    [/pagesize:A4|Letter|...] [/orientation:Portrait|Landscape]
    [/compression:NoCompression|BestSpeed|BelowNormal|Normal|AboveNormal|Best]
    [/standard:Full|Pdf_A_1b|Pdf_A_2b|Pdf_A_3b|Pdf_A_3u|Pdf_X_1a]
    [/title:text] [/userpswd:password] [/ownerpswd:password]
    [/bookmarks] [/booklet | /booklet:twosided]

The documents, images and empty pages are merged in the order you give them. /bookmarks adds a bookmark for each document, named after the file; /booklet saves a booklet on landscape sheets of the page size. Quote the paths that contain spaces. Example:

MergePdfCommandLine /pdf:"C:\My Documents\Report.pdf" /emptypage /image:chart.png /standard:Pdf_A_2b /out:Merged.pdf
What's new in version 10
  • PDF/A-1b, PDF/A-2b, PDF/A-3b, PDF/A-3u and PDF/X-1a output: PdfStandardSubset.

  • AppendPDFBytes(Byte) and its overloads: merge documents from memory, with page ranges and passwords.

  • Insert documents, page ranges, images and empty pages at a position, and reorder the merged pages: the Insert methods and ReorderPages(Int32).

  • A bookmark for each merged document, with its own bookmarks nested under it: BookmarkOptions.

  • Booklets, for single or double-sided printing: BookletOptions.

  • Version 10 is part of the ExpertPdf 22.0 release and needs a version 10 license key.

  • New samples for .NET Framework 4.6.2, .NET 10 and .NET 11, in C# and VB.NET.

Licensing

A license key is emailed to you when you purchase the product. Set it with the LicenseKey property before you save the merged document. Without a license key the library adds an evaluation notice to the pages of the merged document.