Using HtmlToPdfSession

Overview

HtmlToPdfSession is a new addition to EO.Pdf Html to PDF converter. It can be used to establish a "session" with the web server and visit multiple pages through out the session. The typical usage of the HtmlToPdfSession object is to use it to log into a website, then convert a page that can only be accessed after log in.

Typical Usage

The following code demonstrates the typical usage of the HtmlToPdfSession object:

using (HtmlToPdfSession session = HtmlToPdfSession.Create())
{
    //Load the log in page
    session.LoadUrl("Login.html");
    
    //Fill the user name and password field with a valid user name
    //and password. Here "username" and "password" are the name of
    //the two form fields for user to enter their user name and 
    //password
    session.Fill("username", valid_username);
    session.Fill("password", valid_password);
    
    //Submit the log in page. Here "login" the name of the submit
    //button in the page. You can think this method as simulating
    //a "click" on that button. This session is logged in after
    //the Submit method returns
    session.Submit("login");
    
    //Now we are logged in, load the "MyProfile.html" page, which
    //can only be accessed after log in
    session.LoadUrl("MyProfile.html");
    
    //Render this page as PDF
    session.RenderAsPDF("MyProfile.pdf");
}

Key points of interests in the above code:

  • Always use "using" keyword to create a HtmlToPdfSession object to ensure its release. HtmlToPdfSession object is a rather expensive object, so you should create it, use it and release it. Do not hold it. In fact if you hold a HtmlToPdfSession object for long time without using it, the object will be automatically released and if you try to use it again later, an exception will be thrown;
  • Use LoadUrl to load a page. This is similar to user types in an address and then presses enter to load a page in a browser. If the page creates any cookies, the cookies will be preserved in the HtmlToPdfSession object;
  • Use Fill to fill one or more form fields. This has the same effects as if the user typed into these fields. In order to fill the form field, you must find the correct form field name first. Note this is different than the form field's id. To find a form field's name, you can use a browser to load the page, then view the page's HTML source code to locate the corresponding HTML input element. For example, you may see such HTML in the page:

    HTML
    Enter your user name:
    <input type="text" name="TextBox1" id="TextBox1" />

    In this case the name of the user name field is "TextBox1".

    In most cases the name and the id of a form field are different. For example, it's typical to see such code for an ASP.NET page:

    HTML
    Enter your user name:
    <input type="text" name="ctl00$TextBox1" id="ctl00_TextBox1" />

    In this case you should pass "ctl00$TextBox1", not "ctl00_TextBox1" to the Fill function.

  • Call Submit to submit a page after you have filled the form fields. In order to submit a page, you must provide the name of the "submit button", which is usually a button or an image element (see above notes about the Fill function for more details about form field names). Calling Submit with the name of the "submit button" is similar to user clicking that button;

Once you fill in the credentials and submit the page, the HtmlToPdfSession object is "logged in". After that you can load any protected pages, then call HtmlToPdfSession.RenderAsPDF to render the page as PDF.

Getting Session Cookies

You can call HtmlToPdfSession.GetCookies to get all the cookies the HtmlToPdfSession object currently has. Once you have the cookies, you can save them and use them later (assuming they haven't expired when you use them), or pass the returned cookie collection to HtmlToPdfOptions.Cookies so that you can use HtmlToPdf.ConvertUrl to convert other pages. The following code demonstrated how to do that:

//Simulate a log in and get the authentication cookies
CookieCoolection cookies;
using (HtmlToPdfSession session = HtmlToPdfSession.Create())
{
    ...code to log the session in....
    
    //Get the cookies
    cookies = session.GetCookies();
}

//Create an HtmlToPdfOptions object and set it to
//use these cookies
HtmlToPdfOptions options = new HtmlToPdfOptions();
options.Cookies = cookies;

//Convert one page that requires authentication. Note the
//last argument "options"
HtmlToPdf.ConvertUrl("MyProfile.html", "profile.pdf", options);

//Convert another page that requires authentication
HtmlToPdf.ConvertUrl("OrderHistory.html", "orderhistory.pdf", options);