ImageGear .NET v25.1 - Updated
Getting Started with ImageGear PDF
User Guide > How to Work with... > PDF > Getting Started with ImageGear PDF

This section provides information about the following:

PDF Samples and Tutorials

Our suite of PDF samples will help you get started using ImageGear's PDF capabilities.

This section also provides step-by-step PDF tutorials, which show you how to create a new ImageGear project using the PDF component:

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:

 
Copy Code
using ImageGear.Formats.PDF;

PDF Dependencies

You can use our NuGet packages to ensure you have met all required dependencies or run the Deployment Packaging Wizard (DPW) specifying the exact dependencies needed.

NuGet Packages

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.

Deployment Packaging Wizard

  1. To ensure that you have all the required library files, please run the Deployment Packaging Wizard located at …\Accusoft\ImageGear.NET v24\Licensing\Deployment \DPW.exe or navigate to Start menu >All Programs > Accusoft > ImageGear .NET v24 > Deployment Kit > Deployment Packaging Wizard. For more information, see Deployment Packaging Wizard, if needed.
  2. Please ensure that your Visual Studio build environment is set properly. This can be checked or changed by the following:
    1. From the project properties:
      • On the Build tab, check/change the Platform target property to the appropriate x86/x64. At the top, also make sure the Platform property is set to the same.
      • On the Build tab, in the Output section, make sure Output path property is pointing to the same location as your dlls, i.e., bin\RunTime\NET\
      • On the Debug tab, check/change the Platform property to the correct platform.
    2. Select Build from the pull down menus, and click Configuration Manager…
      • Check/change the Active solution platform property to the correct x86/x64 platform.
      • Click Close.
  3. You will also need to have the Microsoft Visual C++ CRT 10.0 (x86) installed.
    For more information, see Distributing PDF and PS Fonts and Libraries with an Application.
  4. You can also pass in the direct location of the PDF resource files as a parameter of the CreatePDFFormat method. For a modified code example, please see the following:
     
    Copy Code
    ImGearFileFormats.Filters.Add(ImGearPDF.CreatePDFFormat(@"C:\Users\Public\Documents\Accusoft\ImageGear.NET v24\Bin"));
    
    ImGearPDF.Initialize(@"C:\Users\Public\Documents\Accusoft\ImageGear.NET v24\Bin");
  5. For a WEB application, you can pass the location of PDF binaries and resources directly in the web.config file of the application:
     
    Copy Code
    <appSettings>
      ......
      <add key="igPdfResources" value="C:\Users\Public\Documents\Accusoft\ImageGear.NET v24\Bin" />
      <add key="igBinaries" value="C:\Users\Public\Documents\Accusoft\ImageGear.NET v24\Bin" />
    </appSettings>

    For more information about working with the web.config file, see Using the ASP.NET Web.Config Editor Application for Configuring Your Web Application.

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:

Example - "using" statement:

C#
Copy Code
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 - Explicit call to Dispose():

C#
Copy Code
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#
Copy Code
// 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 ImGearPDEContainerImGearPDEForm, and ImGearPDEGroup do not have such a method.

Here is sample code to illustrate this:

C#
Copy Code
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 .NET 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 .NET. 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.