Chapter 1: Introduction


1.1 What is AspPDF.NET?

AspPDF.NET is a managed-code .NET component for generating, opening and modifying documents in Portable Document Format (PDF). With AspPDF.NET, your application can automatically create customer invoices, generate secure financial reports, produce encrypted and digitally signed documents, automate form fill-out process, send password-protected email with file attachments, convert HTML pages to PDF, and much more.

1.2 Feature Summary

  • Ability to generate and read PDF documents from any application supporting COM.
  • Easy, intuitive object model.
  • Resultant PDFs can be saved to disk, memory, or an HTTP stream.
  • Support for external TrueType/OpenType fonts.
  • Optimized font embedding.
  • Multi-language support, special handling of Hebrew and Arabic alphabets, support for Arabic ligatures.
  • Support for a subset of HTML tags to facilitate formatted text rendering.
  • Word wrapping, text alignment to the left, right and center, full justification.
  • Image embedding, support for GIF, JPEG, BMP, PNG and TIFF formats.
  • Support for image masking, image transparency.
  • Document encryption with 40-bit, 128-bit and 256-bit keys (RC2 and AES).
  • X.509 certificate-based digital signing of new and existing documents.
  • Support for HTML-style tabular representation of information for easy report generation.
  • Modification of existing PDF documents, page adding and removal.
  • Page extraction.
  • PDF stamping.
  • Source documents can be read from disk as well as memory/database.
  • Document stitching.
  • Raw text content extraction for search and indexing purposes.
  • Support for interactive features such as actions, annotations, outlines.
  • Support for interactive form fields such as checkboxes, text boxes, and pushbuttons.
  • Form fill-in.
  • Drawing of all major types of barcodes.
  • HTML to PDF conversion.
  • PDF to Image conversion.
  • Automatic printing.
  • Image extraction.
  • Drawing this document's pages on other documents.
  • Support for all major types of color spaces and transformation functions.
  • Support for Adobe XFA forms.
  • Support for PDF transparency model.
  • Support for patterns and shadings.
  • PDF/A-1b and PDF/A-3 compliance.
  • Image replacement.

1.3 System Requirements

Windows NT • 2000 • XP • 2003 • Vista • 2008 • 7 • 2012 • 8 • 2016 • 2019 • 2022
Microsoft .NET Framework 2.0 or higher.

Microsoft .NET Core 2.0 or higher with any platform to which .NET Core is ported, including Windows and Linux.

1.4 Installation Instructions

The AspPDF.NET component consists of a single assembly, Persits.PDF.dll, which needs to be placed in the /Bin subdirectory of your .NET application, or the Global Assembly Cache. This DLL does not need to be registered on the server with regsvr32.

You also need to put the registration key in the .config file of your application. Registration keys and the expiration mechanism used by AspPDF.NET are described below.

Under .NET Core on Windows and Linux, your Project file must include the following entries:

   <Reference Include="AspPDF.NET">

   <PackageReference Include="System.Configuration.ConfigurationManager" Version="4.6"/>

It is strongly recommended that NTFS permissions be adjusted on the \Samples directory and all subdirectories to avoid an "Access is denied" or other errors when running the code samples. Using Windows Explorer, right-click on the directory c:\Program Files\Persits Software\AspPDF.NET\Samples, select the Security tab and give the "Everyone" account full control over this folder. Click "Advanced..." and make sure the checkbox "Reset permissions on all child objects..." is checked, as follows:

1.5 Expiration Mechanism

AspPDF.NET requires a registration key even for evaluation purposes. A free 30-day evaluation key is sent to the evaluator via email. Request your key at the Download page. Once a copy of the product is purchased, a permanent registration key is sent to the customer.

Registration keys used by AspPDF.NET are 76-character strings containing symbols from the Base64 character set. Each key has the issue and expiration date information embedded into it securely. A typical AspPDF.NET registration key looks as follows:


Note: The AspPDF and AspPDF.NET keys are not compatible with each other. Do not attempt to use your existing AspPDF key with AspPDF.NET, or vice versa.

Once a key is obtained, it should be placed in the appSettings section of your application's .config file, as follows:

      <add key="AspPDF_RegKey" value="GYlbc3g5Th3Y30WwhEkqReuk03hT/1hsJt...3zNJ5kD9"/>

Alternatively, the registration key can be specified in your code via the RegKey property of the top-level PdfManager object, as follows:

PdfManager objPDF = new PdfManager();
objPDF.RegKey = "GYlbc3g5Th3Y30WwhEkqReuk03hT/1hsJtbZkwLx51ZpX7CCQz3vZ4kEqj0HzVgRE9NC3zNJ5kD9";

The current expiration date of the key can be retrieved via the Expires property, as follows:

PdfManager objPDF = new PdfManager();
Response.Write( objPDF.Expires );

If the Expires property returns 9/9/9999 it means a permanent registration key is being used. This property throws an exception if the key cannot be found, or is invalid.

Under .NET Core on Windows and Linux, there are no .config files. Therefore, the only way to specify the registration key is via the .RegKey property of the PdfManager object:

objPDF.RegKey = "GYlbc3g5Th3Y30WwhEk........VgRE9NC3zNJ5kD9";

1.6 Quick Start

This chapter would not be complete without a Hello World application. The following C# and VB.NET code samples are fairly self-explanatory. A format introduction to AspPDF.NET's object model will be provided in the next chapter.

<%@ Page Language="C#" debug="true" %>

<%@ Import Namespace="Persits.PDF" %>

<script runat="server" language="c#">

void Page_Load(Object Source, EventArgs E)
  // create instance of the PDF manager
  PdfManager objPDF = new PdfManager();

  // Create new document
  PdfDocument objDoc = objPDF.CreateDocument();

  // Add a page to document
  PdfPage objPage = objDoc.Pages.Add();

  // Obtain font
  PdfFont objFont = objDoc.Fonts["Helvetica"];

  // Draw text
  objPage.Canvas.DrawText("Hello World!", "x=100; y=400; size=50", objFont);

  // Save to HTTP stream for instant viewing by user
  objDoc.SaveHttp( "filename=test.pdf");

<%@ Page Language="vb" debug="true" %>

<%@ Import Namespace="Persits.PDF" %>

<script runat="server" language="vb">

Sub Page_Load(Source As Object, E As EventArgs)
  ' create instance of the PDF manager
  Dim objPDF As PdfManager= New PdfManager()

  ' Create new document
  Dim objDoc As PdfDocument = objPDF.CreateDocument()

  ' Add a page to document
  Dim objPage As PdfPage = objDoc.Pages.Add()

  ' Obtain font
  Dim objFont As PdfFont = objDoc.Fonts("Helvetica")

  ' Draw text
  objPage.Canvas.DrawText("Hello World!", "x=100; y=400; size=50", objFont)

  ' Save to HTTP stream for instant viewing by user
  objDoc.SaveHttp( "filename=test.pdf")
End Sub


Click the links below to run this code sample: