1. Introduction The ExpertPDF HTML to PDF Converter for .NET 2.0 and .NET 3.5 consists in a .NET library that can be used directly in any .NET application (ASP.NET, Windows Forms, Console, Web Services, Windows Services, etc) and an ASP.NET 2.0 server control built as wrapper of the library to help you benefit from the design time capabilities of the Microsoft Visual Studio 2005 or 2008.
The converter does not require any installation and it does not use any printer driver to perform conversion. It's just an assembly that you can directly link with your .NET application. Full HTML / CSS is supported and the main goal of the converter is to preserve unchanged the original aspect of the converted HTML page.
It can be used as general purpose tool for converting web pages and HTML code to PDF or as part of our Reporting Toolkit for .NET to easily create PDF reports directly from ASP.NET pages. If you think that the converted ASP.NET page can contain your preferred server controls like charts, barcodes, data bound control like data grids and repeaters you can realize how powerful this tool can be.
The converter API offers methods to convert a web page from a specified URL to PDF or a specified HTML string. Additionally you can convert web pages and HTML code to images in any format supported by .NET 2.0 and .NET 3.5 framework (BMP, JPEG, PNG, GIF, etc).
If you want to get started immediately without reading the next sections of this document this is something perfectly possible. First you have to add a reference to the converter library assembly ephtmltopdf.dll in your .NET or ASP.NET project. Then you have to add the following two lines of code in your application. The first one will import the converter namespace and the second one will call the converter to render the web page from the specified url as an array of bytes representing the resulted PDF document:
1: using ExpertPdf.HtmlToPdf; 2: byte[] pdfBytes = new PdfConverter().GetPdfFromUrlBytes(url);
Further you can save the PDF document bytes into a file on disk or you can send the bytes as a response to the client browser. We provide full sample applications, both in C# and VB.NET to exemplify both situations.
The code above will produce a PDF document based on the default settings of the library which is enough for the most of the situations. However, the converter library offers a large number of parameters that you can set to customize the conversion process. You can add headers and footers with text and images to the resulted PDF document, specify page orientation, page size, compression level of the resulted PDF document, encrypt the resulted document and set user and owner password, set the permissions for printing 2. Installation The ExpertPDF HTML to PDF Converter for .NET 2.0 and .NET 3.5 is delivered as a zip archive and it doesn't require an installer. You have to unzip the archive in a folder on the disk. Below is a brief description of the content of the archive.
2.1 Bin Folder
Bin folder contains the .NET 2.0 and .NET 3.5 assembly you can use in your applications.
ephtmltopdf.dll - is the HTML to PDF converter library that you can link in any .NET application, either Windows Forms or ASP.NET.
2.2 Documentation
HtmlToPdf.chm - contains the HTML to PDF converter library API referenceManual.pdf - contains this document
2.3 Samples
WebSample - is a ASP.NET 2.0 application written in C# and VB.NET language which shows you how to convert web pages to PDF. The application uses the HTML to PDF Converter library and shows you how to set various conversion parameters like the headers and footers, page size, page orientation, compression level, etc. This application runs live on our website homepage.
WinSample - is a Windows Forms application written in C# language which shows you how to convert web pages and HTML code to PDF and images. The application uses the HTML to PDF Converter library and shows you how to set various conversion parameters like the headers and footers, page size, page orientation, compression level, etc. 3. Requirements and Recommendations The recommended hardware and software resources for successfully running the ExpertPDF HTML to PDF converter for .NET are listed below. Basically this is the environment we used for testing the product. Operating System: Windows XP, Windows 2003 Server, Windows Vista, Windows 2000Hardware Architecture: 32-bit, 64-bitFree RAM: 1GBMicrosoft .NET Framework 2.0 or .NET 3.5Full trust level when used in ASP.NET applications 4. Converter API The converter API is fully documented in the Doc/HtmlToPdfConvertLib.chm . In order to use the converter library you have include the ExpertPdf.HtmlToPdf namespace in your application. The main classes in this namespace is the PdfConverter class and the ImgConverter class which expose the methods you can use to render a PDF document or an image from a URL or a HTML string. Below is a brief description of the main classes and properties of the converter. 4.1 PdfConverter Class This class defines a set of methods to render a PDF document from a URL or from a HTML string. The conversion result can be a stream of bytes as byte[] object or a file on the disk. The PDF bytes can be further saved in a disk file or can be send a HTTP response to the client browser.
4.1.1 PdfConverter Render Methods The method below retrieves the PDF bytes from a URL. The URL must be anonymously accessible from the computer running your application otherwise a 'Get web page content cancelled or invalid URL supplied' exception is thrown by the converter. The best way to debug this type of exception is to load the URL in the Internet Explorer browser running on the same machine with your application and see if the page is correctly loaded. public byte[] GetPdfFromUrlBytes ( string url )
To convert a HTML string to PDF you can use one of the following methods below. The first method simply renders the HTML string as a PDF document. The second one accepts an additional parameter urlBase which is the full URL of the page from where you have retrieved the HTML string. The urlBase parameter is a hint for the converter which is used to determine the full URL of the images and other external files like CSS and JavaScript referenced in the HTML string by a relative URL. If you don't set this parameter the images referenced by relative URLS won't appear in the document and the styles from external CSS files won't be applied to the rendered document.
public byte[] GetPdfBytesFromHtmlString (string htmlString)public byte[] GetPdfBytesFromHtmlString (string htmlString,string urlBase)
The correspondent methods you can use to render the PDF document in disk file are listed below. These methods internally use the methods above to get the bytes array and then they simply save the bytes in the specified file on disk.
public void SavePdfFromUrlToFile (string url, string outFile)public void SavePdfFromHtmlStringToFile (string htmlString, string outFile)public void SavePdfFromHtmlStringToFile (string htmlString, string outFile, string urlBase)
In the full API reference document you'll notice some other similar methods for converting a HTML stream to PDF or a HTML file to file but they are derived from the methods described above and in the most of the cases you won't need them. 4.1.2 PdfConverter Configuration Properties The conversion process and the aspect of the generated PDF document can be configured in many ways. You can set the PDF document page size (A4, A3, etc), orientation (Portrait or Landscape), compression level, encryption and passwords, document info (author, title, subject, etc), add headers and footers with page numbering, etc. The main properties of the converter are listed below. To set the license key you received after purchase and unlock the product you can use the LicenseKey property. If this property is not set with any value the converter will enter in demo mode. public string LicenseKey { get; set; }
The PageWidth and PageHeight properties allow you to set the width and height of the virtual browser windows. The web page content is rendered based on the virtual browser width specified as an integer value in pixels. Setting these properties has the same effect as the effect produced when resizing a web page in a browser window to the specified dimensions.
The default value of the PageWidth property is 1024 pixels. The default value of the PageHeight property is 0 pixels which mean the height will be automatically determined. These values are producing good results in most of the cases but there are also some situations when you'll have to change these properties. You can also choose to let the converter auto determine both the width and height of the virtual browser by setting both PageWidth and Page Height properties to 0.
public int PageWidth { get; set; }public int PageHeight { get; set; } The PdfDocumentOptions property allows you to change the aspect and properties of the rendered PDF document like setting the margins, add header and footer, embed true type fonts, generate a document with selectable texts and images or a document with an embedded image, enable or disable live links, pdf page size and page orientation, compression level, show or hide the headers and footers.
This property exposes an object of PdfDocumentOptions type which is automatically created in the PdfConverter constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfDocumentOptions object.
The main properties of the PdfDocumentOptions class are described in a later section. public PdfDocumentOptions PdfDocumentOptions { get; }
The PdfSecurityOptions class property allows you to change the permissions of the rendered PDF document like allow or disallow printing, editing, etc and also to set user and owner passwords.
This property exposes an object of PdfSecurityOptions type which is automatically created in the PdfConverter constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfDocumentOptions object.
The main properties of the PdfDocumentOptions class are described in a later section. public PdfSecurityOptions PdfSecurityOptions { get; }
The PdfDocumentInfo property allows you to set the rendered PDF description like title, author, subject, keywords, etc.
The main properties of the PdfDocumentOptions class are described in a later section. public PdfDocumentInfo PdfDocumentInfo { get; }
The PdfHeaderOptions and PdfFooterOptions properties allow you to customize the aspect of the headers and footers added to the rendered PDF document. Note that the header and footer are visible in the resulted PDF document only if the corresponding ShowHeader and ShowFooter properties from the PdfDocumentOptions property are true.
These properties expose objects of PdfHeaderOptions type and PdfFooterOptions type which are automatically created in the PdfConverter constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfHeaderOptions and PdfFooterOptions object.
The main properties of the PdfHeadersOptions and PdfFooterOptions classes are described in a later section.
public PdfHeaderOptions PdfHeaderOptions { get; }public PdfFooterOptions PdfFooterOptions { get; } 4.2 ImgConverter Class This class defines a set of methods to render an image from a URL or from a HTML string. The conversion result can be a stream of bytes as byte[] object or a file on the disk. The image bytes can be further saved in a disk file or can be send a HTTP response to the client browser.
4.2.1 ImgConverter Render Methods The method below retrieves the image bytes from a URL. There is also a similar method which produces a System.Drawing.Image object from a specified URL. The second parameter allows you to specify the format of the resulted image as a value from the System.Drawing.Imaging.ImageFormat enumeration.
The URL must be anonymously accessible from the computer running your application otherwise a 'Get web page content cancelled or invalid URL supplied' exception is thrown by the converter. The best way to debug this type of exception is to load the URL in the Internet Explorer browser running on the same machine with your application and see if the page is correctly loaded.
public byte[] GetImageFromUrlBytes (string url,ImageFormat format)public Image GetImageFromUrl (string url,ImageFormat format)
To convert a HTML string to image you can use one of the following methods below. The first method simply renders the HTML string as an Image object or as a byte[]. The second one accepts an additional parameter urlBase which is the full URL of the page from where you have retrieved the HTML string. The urlBase parameter is a hint for the converter which is used to determine the full URL of the images and other external files like CSS and JavaScript referenced in the HTML string by a relative URL. If you don't set this parameter the images referenced by relative URLS won't appear in the document and the styles from external CSS files won't be applied to the rendered image.
You can notice there are similar methods producing a System.Drawing.Image object instead of a byte[].
public Image GetImageFromHtmlString (string htmlString,ImageFormat format)public Image GetImageFromHtmlString (string htmlString,ImageFormat format,string urlBase)public byte[] GetImageBytesFromHtmlString (string htmlString,ImageFormat format)public byte[] GetImageBytesFromHtmlString (string htmlString,ImageFormat format,string urlBase)
The correspondent methods you can use to render the image in disk file are listed below. These methods internally use the methods above to get the bytes array and then they simply save the bytes in the specified file on disk.
public void SaveImageFromUrlToFile (string url, ImageFormat format, string outFile)public void SaveImageFromHtmlStringToFile (string htmlString, ImageFormat format, string outFile)public void SaveImageFromHtmlStringToFile (string htmlString, ImageFormat format, string outFile, string urlBase)
In the full API reference document you'll notice some other similar methods for converting a HTML stream to image or a HTML file to image file but they are derived from the methods described above and in the most of the cases you won't need them. 4.1.2 ImgConverter Configuration Properties The conversion process and the aspect of the generated image can be configured with the configuration properties below. To set the license key you received after purchase and unlock the product you can use the LicenseKey property. If this property is not set with any value the converter will enter in demo mode. public string LicenseKey { get; set; }
public int PageWidth { get; set; }public int PageHeight { get; set; } 5. Features In this section will be described the main features of the converter and code samples for each feature 5.1 Headers and Footers In order to show or hide the header or footer on the rendered document you have to set the ShowHeader and ShowFooter properties of the PdfDocumentOptions property of the PdfConverter class. For example, to add both footer and header to the generated document you can use the following code:
PdfConverter pdfConverter = new PdfConverter();pdfConverter.PdfDocumentOptions.ShowHeader = true;pdfConverter.PdfDocumentOptions.ShowFooter = true;
The aspect of the header and footer can be controlled with the PdfHeaderOptions and PdfFooterOptions properties of the PdfConverter object.
For the header you can set a title and a subtitle, add an image in a specified position and draw a horizontal line under the header, change the text font and size, change the background color of the header. Below you can see a sample code to set the header options:
pdfConverter.PdfHeaderOptions.HeaderBackColor = Color.WhiteSmoke; pdfConverter.PdfHeaderOptions.HeaderHeight = 50; pdfConverter.PdfHeaderOptions.HeaderText = "Title"; pdfConverter.PdfHeaderOptions.HeaderTextColor = Color.Black; pdfConverter.PdfHeaderOptions.HeaderTextFontType = PdfFontType.Helvetica; pdfConverter.PdfHeaderOptions.HeaderTextFontSize = 18; pdfConverter.PdfHeaderOptions.HeaderTextYLocation = 5; pdfConverter.PdfHeaderOptions.HeaderSubtitleText = "Subtitle"; pdfConverter.PdfHeaderOptions.HeaderSubtitleTextColor = Color.Black; pdfConverter.PdfHeaderOptions.HeaderSubtitleTextFontType = PdfFontType.Helvetica; pdfConverter.PdfHeaderOptions.HeaderSubtitleTextFontSize = 12; pdfConverter.PdfHeaderOptions.HeaderTitleSubtitleYSpacing = 7; pdfConverter.PdfHeaderOptions.HeaderImageLocation = new PointF(0, 0); pdfConverter.PdfHeaderOptions.HeaderImage = Image.FromFile(logoImageFullPath); pdfConverter.PdfHeaderOptions.DrawHeaderLine = true;
The dimensions are specified in points and a point is 1/72 inches. The A4 page size in points is 595x842. At a screen resolution of 96 dpi, an A4 PDF page has 794 pixels in width and 1123 pixels in height. For the footer you can set the text, to show or not the page numbering, the text that appears before the page number, the font text and color, the footer background color and to draw or not a line above the footer. Below you can see a sample code to set the footer options:
pdfConverter.PdfFooterOptions.FooterText = "Footer text"; pdfConverter.PdfFooterOptions.FooterBackColor = Color.WhiteSmoke; pdfConverter.PdfFooterOptions.FooterHeight = 40; pdfConverter.PdfFooterOptions.FooterTextColor = Color.Black; pdfConverter.PdfFooterOptions.FooterTextFontType = PdfFontType.HelveticaOblique; pdfConverter.PdfFooterOptions.FooterTextFontSize = 8; pdfConverter.PdfFooterOptions.DrawFooterLine = true; pdfConverter.PdfFooterOptions.PageNumberText = "Page"; pdfConverter.PdfFooterOptions.PageNumberTextColor = Color.Black; pdfConverter.PdfFooterOptions.PageNumberTextFontType = PdfFontType.HelveticaBold; pdfConverter.PdfFooterOptions.PageNumberTextFontSize = 10; pdfConverter.PdfFooterOptions.ShowPageNumber = true;
The dimensions are specified in points and a point is 1/72 inches. The A4 page size in points is 595x842. At a screen resolution of 96 dpi, an A4 PDF page has 794 pixels in width and 1123 pixels in height. Starting with v2.5, ExpertPdf HtmlToPdf Converter offers full support for html in headers and footers. Please see below some sample code:
PdfConverter pdfConverter = new PdfConverter(); // show header and footer in the rendered PDF pdfConverter.PdfDocumentOptions.ShowHeader = true; pdfConverter.PdfDocumentOptions.ShowFooter = true; // set the header height in points pdfConverter.PdfHeaderOptions.HeaderHeight = 60; // set the header HTML area pdfConverter.PdfHeaderOptions.HtmlToPdfArea = new HtmlToPdfArea(Path.Combine (Application.StartupPath, @"..\..\HeaderAndFooterHtml.htm")); // set the footer height in points pdfConverter.PdfFooterOptions.FooterHeight = 50; //write the page number pdfConverter.PdfFooterOptions.TextArea = new TextArea(0, 30, "This is page &p; of &P; ", new Font(new FontFamily("Times New Roman"), 10, GraphicsUnit.Point)); pdfConverter.PdfFooterOptions.TextArea.TextAlign = HorizontalTextAlign.Right; // set the footer HTML area pdfConverter.PdfFooterOptions.HtmlToPdfArea = new HtmlToPdfArea(Path.Combine (Application.StartupPath,@"..\..\HeaderAndFooterHtml.htm")); //pdfConverter.PdfFooterOptions.HtmlToPdfArea = new HtmlToPdfArea(http://www.google.com); string outFilePath = Path.Combine(Application.StartupPath, "Result.pdf"); pdfConverter.SavePdfFromUrlToFile(textBoxURL1.Text, outFilePath); 5.2 Security Options With the security options you have the possibility to allow or disallow printing, editing, copying, filling form fields, set a user password and an owner password. When you set a user password the PDF document is encrypted and that password will be asked by the PDF viewer in order to open the PDF document. When you set the owner password that password will be required when someone wants to change the PDF permissions. Below you can see a sample code which you can use to set the security options of the generated
pdfConverter.PdfSecurityOptions.CanCopyContent = true; pdfConverter.PdfSecurityOptions.CanEditContent = true; pdfConverter.PdfSecurityOptions.CanFillFormFields = true; pdfConverter.PdfSecurityOptions.CanPrint = true; pdfConverter.PdfSecurityOptions.CanEditAnnotations = true; pdfConverter.PdfSecurityOptions.CanAssembleDocument = true; pdfConverter.PdfSecurityOptions.KeySize = EncryptionKeySize.EncryptKey128Bit; pdfConverter.PdfSecurityOptions.UserPassword = "expertpdf"; pdfConverter.PdfSecurityOptions.OwnerPassword = "";
5.3 Document Description You can set the document description like author, title, subject, keyword using the PdfDocumentInfo property.
pdfConverter.PdfDocumentInfo.AuthorName = "ExpertPDF"; pdfConverter.PdfDocumentInfo.Title = "PDF Document Info"; pdfConverter.PdfDocumentInfo.Subject = "HTML to PDF Converter"; pdfConverter.PdfDocumentInfo.Keywords = "HTML, PDF, Converter"; pdfConverter.PdfDocumentInfo.CreatedDate = DateTime.Now; 5.4 Automatic and Custom Page Breaks, Keep Together The converter supports the following CSS styles to control the page breaks: page-break-before:always, page-break-after:always and page-break-inside:avoid. For example, with the page-break-after:always style applied to a HTML element (image, text, etc) you instruct the converter to insert a page break right after that element is rendered.
By default the converter always tries to avoid breaking the text between PDF pages. You can disable this behavior using the PdfConverter.AvoidTextBreak property. Also you can enable the converter to avoid breaking the images between PDF pages using the PdfConverter.AvoidImageBreak . By default this property is false.
An advanced and very useful feature when creating PDF reports is the Keep Together feature which can be implemented with the page-break-inside:avoid style. This instructs the converter to avoid breaking the content of a group of HTML elements you want to keep together on the same page. If you think you can apply this style to a table, a table row or a div element you can easily understand the utility of this feature.
Below is an example of using the page-break-inside:avoid style. The table contains a large number of rows, each row containing an image in the left and a text in the right and we don't want a row to span on two pages. <table> <tr style="page-break-inside : avoid"> <td> <img width="100" height="100" src="img1.jpg"> </td> <td> My text 1 </td> </tr> <tr style="page-break-inside : avoid"> <td> <img width="100" height="100" src="img2.jpg"> </td> <td> My text 2 </td> </tr></table> 5.5 Live HTTP Links The converter can convert any HTTP link from the HTML document into a link in the PDF document. This works on links containing text, image or any other combination supported by the HTML code. This is the default behavior of the converter. If you don't want to get active links in the generated PDF document you can set PdfConverter.PdfDocumentOptions.LiveUrlsEnabled = false. 5.6 Merge Capabilities The HTML to PDF Converter provides you with the possibility to append a PDF file or a list of PDF files to the conversion result. This possibility is available with the AppendPDFFile and AppendPDFFIleArray properties from PdfDocumentOptions class. The properties must be set before calling the PDF render method. There also available similar properties to append PDF streams instead of files. The prototypes of these properties are:
public string AppendPDFFile { get; set; }public string[] AppendPDFFileArray { get; set; }public Stream AppendPDFStream { get; set; }public Stream[] AppendPDFStreamArray { get; set; } 5.7 Enable/Disable Client Scripts and ActiveX from HTML Page The JavaScript code and ActiveX controls are disabled by default in the converted page during conversion. If you have JavaScript code that modifies the web page on the client you can instruct the converter to execute that JavaScript code. You can activate scripts both when rendering an image or a PDF document. The properties from PdfConverter class which allow you to activate the scripts when converting to PDF file are:
public bool ScriptsEnabled { get; set; }public bool ScriptsEnabledInImage { get; set; } 5.8 Server Authentication The converter offers support for any type of server authentication. For example the converter can handle IIS authentication types like Integrated Windows Authentication and Basic Authentication. The authentication is disabled by default. To enable authentication you have to set the AuthenticationOptions property of the PdfConverter object. Below you can find sample code for setting the username and password for authentication when converting HTML to PDF: pdfConverter.AuthenticationOptions.Username = username; pdfConverter.AuthenticationOptions.Password = password; The properties of ImgConverter class which allow you to handle the authentication when converting HTML to images are:
public string AuthenticationPassword { get; set; }public string AuthenticationUsername { get; set; }
5.9 Custom PDF Page Size The converter can produce PDF documents with pages of any size. The page size is controlled by the PdfConverter.PdfDocumentOptions.PdfPageSize property of type PdfPageSize. You can set this property to standard values like A4, A3, etc or to Custom. In this case the PDF page size will be given by the PdfConverter.PdfDocumentOptions.CustomPdfPageSize property. Below is a sample code for setting the converter to produce PDF pages with the width of 200 points and height of 300 points. A point is 1/72 inch. pdfConverter.PdfDocumentOptions.CustomPdfPageSize = new SizeF(200,300); By default the custom size is set to a width of 595 and a height of 842 points which is the size of the A4 portrait page. When the page orientation is set to landscape the width and height values are inverted. 5.10 Bookmarks The converter can produce bookmarks in the generated PDF document for a list of specified HTML tags. The bookmarking is controlled by the pdfConverter.PdfBookmarkOptions property and is enabled only when a list of HTML tag names is specified by the pdfConverter.PdfBookmarkOptions.TagNames property. For example, to enable bookmarking of the H1 and H2 tags you can use the following line of C# code:
pdfConverter.PdfBookmarkOptions.TagNames = new string[] { "H1", "H2" }; The tags to be bookmarked can be further filtered by CSS class name using the pdfConverter.PdfBookmarkOptions.ClassNameFilter property. For example, to filter only the H1 and H2 tags having the CSS class bookmark, the following line of C# can be added to the previous one:
pdfConverter.PdfBookmarkOptions.ClassNameFilter = "bookmark"; The ClassNameFilter property is case sensitive and the string value set for this property must textually match the class attribute of the HTML tag to be bookmarked. 6. Licensing A unique license key string is generated for each purchase. In order to unlock the HTML to PDF Converter product you have to set the LicenseKey property of the PdfConverter class (when converting to PDF) or of the ImgConverter class (when converting to image) with the license key string you have received after the product purchase.
The license key contains the information about the purchased product like the product version and license type and is uniquely associated with an order ID. More details about the license types and pricing can be found on the pricing page of our website.
Other Links: