BCL easyPDF SDK
easyPDF SDK Usermanual
PDF Creator Programming API  |  Download Free Trial  |  Contact Us to Purchase

Native .NET PDFConverter API

Usage

The native .NET API is very similar to the COM API, with only a few distinct differences. .NET Framework 3.5 or above is required.

First, you need to add using BCL.easyPDF.PDFConverter; to your code. Then you need to add reference to the appropriate .NET DLL.

If you are targeting .NET 4.x, you need to add a reference to the BCL.easyPDF.PDFConverter.dll assembly, which is under C:\Program Files\Common Files\BCL Technologies\easyPDF 8.

If you are targeting .NET 3.5, you need to add a reference to the BCL.easyPDF.PDFConverter-NET35.dll assembly, which is under C:\Program Files\Common Files\BCL Technologies\easyPDF 8.

If you are targeting .NET Core, you need to add a reference to the BCL.easyPDF.PDFConverter.NetCore.dll assembly, which is under C:\Program Files\Common Files\BCL Technologies\easyPDF 8.

Currently there are no differences between the .NET 3.5 and 4.x APIs, other than the target version. They both implement the same features, classes, methods and properties. It is strongly recommended to use the .NET 4.x or the .NET Core version, unless your app must target .NET 3.5.

COM exceptions were replaced by the new PDFConverterException.

The PDFConverter class is inherited from IDisposable, which means it really needs to be deterministically disposed. Relying on the garbage collector is not recommended, because each PDFConverter object launches a separate worker process. Even though these worker processes are sleeping while not executing a function, they are still in the memory, and only really quit when the PDFConverter object is disposed.

The PDFConverter object should be treated as if it were an expensive resource, such as a file, mutex, or a database connection. If you would like to know what really is inside PDFConverter, it is just a named pipe. However, the worker process is programmed to only quit when the pipe is closed.

If the customer's application crashes, the system automatically closes all pipes belonging to the process, which means all related worker processes automatically quit as well.

The minimal C# sample code looks like this:
(Note: all Native .NET sample code and declarations have a light yellow background color)

using(PDFConverter converter = new PDFConverter())
{
   converter.PDF2Image.Convert(@"c:\test\input.pdf", @"c:\test\output.jpg");
}

The key here is the using keyword, which gives PDFConverter a deterministic behavior.

An alternative solution, especially if you are catching exceptions, is the try/finally idiom:

PDFConverter converter = new PDFConverter();
try
{
   converter.PDF2Image.Convert(@"c:\temp\input.pdf", @"c:\temp\output.jpg");
}
catch(PDFConverterException ex)
{
   Console.WriteLine(ex.Message);
}
finally
{
   converter.Dispose();
}

The key here is the finally block, which calls Dispose().

PDFConverter's constructor is designed to never throw exceptions. That's because it does not launch a worker process and does not create a named pipe, it merely initializes a few variables to their default values. In other words, creating a PDFConverter object is extremely lightweight, like creating a Color object.

However, as soon as you do anything else, even getting a property, it instantly launches a worker process.

Notification Events

Notification events in the native .NET API are slightly different than in the COM object. Here is an example that catches OnPageStart, which is called before printing each page:

using(PDFConverter converter = new PDFConverter())
{
   converter.PDFConverterMonitor.OnPageStart += new PDFConverterMonitor.OnPageStartEventHandler(OnPageStart);
   converter.PDF2Image.Convert(@"c:\temp\input.pdf", @"c:\temp\output.jpg");
}

You would then create your own handler method as follows:

cnvMonitorResponse OnPageStart(int pageNumber, int pageCount, string fileName)
{
   Console.WriteLine(pageNumber);
   return cnvMonitorResponse.CNV_MON_CONTINUE_CONVERSION;
}

What's different here from COM is that event handlers return cnvMonitorResponse, instead of int.

Launch Timeout

Launching the worker process and connecting the named pipe should happen very fast, in milliseconds. However, under an abnormally heavy load, the computer may not have enough cycles to perform this task in a timely fashion.

The Native .NET API has an internal timeout built-in. The default value is 1 minute. This is because a server may momentarily slow down so much that it is not responding for seconds, but it usually recovers after a while.

The default timeout value can be changed via the LaunchTimeout member (in milliseconds). This must be performed immediately after the creation of the PDFConverter object.

using(PDFConverter converter = new PDFConverter())
{
   converter.LaunchTimeout = 30000; // 30 seconds
   converter.PDF2Image.Convert(@"c:\temp\input.pdf", @"c:\temp\output.jpg");
}

Upon timeout an exception is thrown, and the SDK cannot be used. Another attempt may be made later.