This section provides information about the following:
Note: In order to use the ImageGear PDF component on Linux, you will need to specify the location from which native binaries will be loaded, otherwise ImageGear PDF will fail to initialize. You can do this by setting the LD_LIBRARY_PATH
variable to the location of native binaries before your application runs. If you linked ImageGear to your project using nuget, these binaries will likely be located at $(OutDir)/runtimes/linux-x64/native
.
ImageGear.Formats.PDF Namespace
The ImageGear.Formats.PDF namespace allows you to load, save, and process native PDF and PostScript documents. It also allows rasterization of PDF and PostScript documents, by converting them to bitmaps, and provides you with the ability to extract text from loaded PDF and PostScript documents.
The ImageGear.Formats.PDF namespace provides full multi-page read and write support for the entire document as well as a specified set of pages. You can detect, read, write, append, insert, replace, swap, and delete a specified page in the PDF document as well as to edit its content.
To enable the ImageGear.Formats.PDF Namespace in your project, specify the following directive:
C#
using ImageGear.Formats.PDF;
PDF Dependencies
The PDF component depends on the Core component. You can use our NuGet packages to ensure you have met all required dependencies. NuGet packages make it easy to add, remove, and update libraries and tools in Visual Studio projects that use the .NET Framework. See NuGet Packages for more information.
PDF Object Lifetime
Many PDF objects are disposable. This means that the Dispose()
method must be called, either explicitly or via a using
statement, when the newly created PDF object is no longer needed.
Disposable PDF objects:
ImGearPDFDocument
- derived from Disposable ImGearDocument
ImGearPDFPage
ImGearPDFObject
- base class for many PDF objects, such as ImGearPDEContent
, ImGearPDFLayer
, ImGearPDFWordFinder
, etc.
Example with using
:
C#
using (Stream stream = new FileStream(fileName, FileMode.Open, FileAccess.Read))
{
// Load new document
using (ImGearPDFDocument document = ImGearFileFormats.LoadDocument(stream, FIRST_PAGE, ALL_PAGES) as ImGearPDFDocument)
{
// Clone page
using (ImGearPDFPage page = document.Pages[0].Clone() as ImGearPDFPage)
{
// Get page content
using (ImGearPDEContent content = page.GetContent())
{
// Do something.
page.ReleaseContent();
}
}
}
}
Example with explicit call to Dispose()
:
C#
using (Stream stream = new FileStream(fileName, FileMode.Open, FileAccess.Read))
{
// Load new document
ImGearPDFDocument document = ImGearFileFormats.LoadDocument(stream, FIRST_PAGE, ALL_PAGES) as ImGearPDFDocument;
// Clone page
ImGearPDFPage page = document.Pages[0].Clone() as ImGearPDFPage;
// Get page content
ImGearPDEContent content = page.GetContent();
// Do something
page.ReleaseContent();
content.Dispose();
page.Dispose();
document.Dispose();
}
Note that the Dispose()
method should not be called for the PDF page when the page is obtained from a PDF page array by index because there is no newly created instance of ImGearPDFPage
in this case.
C#
// Dispose() is not needed for page
ImGearPDFPage page = document.Pages[0] as ImGearPDFPage;
All PDF objects, such as ImGearPDEColorspace
, ImGearPDFPage
, and ImGearPDEContent
, are based on underlying low-level PDF objects, which are not controlled by .NET resource manager and garbage collector. Due to complex dependencies between these objects, it is not possible to wrap these objects with a fully-automated .NET lifecycle management. For example, disposing an ImGearPDFPage
object whose content was obtained with the GetContent
method and was not released with ReleaseContent
can lead to an internal PDF exception.
Failure to dispose of PDF Documents and Pages can cause significant memory issues in the running application and lingering issues, in the form of abandoned temp files, after the application has terminated.
Also, an ImGearPDEContent
object obtained from ImGearPDFPage
should be released using the ImGearPDFPage.ReleaseContent()
method in all cases.
An ImGearPDEContent
object obtained from a Container, Group, or Form does not need to be released, so ImGearPDEContainer
, ImGearPDEForm
, and ImGearPDEGroup
do not have such a method.
Here is sample code to illustrate this:
C#
public void IterateElements(ImGearDocument imageDocument)
{
ImGearPDFDocument pdfDocument = (ImGearPDFDocument)imageDocument;
for (int index = 0; index < pdfDocument.Pages.Count; index++)
{
try
{
ImGearPage page = pdfDocument.Pages[index];
// content should be disposed
ImGearPDEContent content = ((ImGearPDFPage)page).GetContent();
for (int elementIndex = 0; elementIndex < content.ElementCount; elementIndex++)
{
ImGearPDEElement element = content.GetElement(elementIndex);
if (!TryLoadElement(element))
{
throw new Exception();
}
element.Dispose();
}
// ReleaseContent should be called for a page
((ImGearPDFPage)page).ReleaseContent();
// dispose content
content.Dispose();
}
catch (Exception ex)
{
MessageBox.Show("Error”);
}
}
// ImGearPDFDocument object should be disposed too. We’ve left it to caller.
}
Working with PS Files
The ImageGear.Formats.PDF
namespace loads PostScript files by converting them to PDF first and applying a set of default conversion settings. To adjust the results of that conversion, ImageGear PDF namespace implements JobOptionsFile PostScript filter control parameter that can be pointed to one of the .joboptions files distributed with the product. A .joboptions file contains settings that control the conversion from PostScript or EPS to PDF performed on-the-fly for rendering PostScript and EPS in ImageGear. If you encounter any problems with PostScript or EPS rendering or conversion to PDF, such as color or layout differences, you can use the provided "Bin\Resource\PS\Settings\Standard.joboptions" by setting the value of JobOptionsFile PostScript filter control parameter to the full path of the location of that file.