Skip to main content
Version: 1.2

Getting started with the Pdftools SDK

This guide walks you through the steps necessary to integrate the Pdftools SDK into your project. By the end, you’ll be able to create a PDF document.

tip

Get in touch with the Pdftools sales team through the Contact page to get a license key.

Steps to use the Pdftools SDK:

  1. Request a license key.
  2. Create a new project.
  3. Add the Pdftools SDK to your project. Depending on the language, there are two ways you can get the SDK:
  4. Set color profiles and install fonts, as appropriate.
  5. Initialize the library by passing the license key.
  6. Decide on your goal. Depending on your goal, the tasks to be performed vary:

Request a license key​

You can download your license key from your My PDF Tools Portal account or get an evaluation license key.

Install the Pdftools SDK​

The Pdftools SDK can be installed in different ways according to the operating system and programming language used:

NuGet package

NuGet is a package manager that facilitates the integration of libraries for the software development in .NET. The NuGet package for the Pdftools SDK contains all the libraries needed, managed and native, for all supported operating systems.

Install the package

Download the NuGet package directly from https://www.nuget.org/. In Microsoft Visual Studio, this is the default location for downloading packages.

The package contains .NET libraries with version .NET Standard 2.0, and native libraries for Windows, macOS, and Linux. The required native libraries are loaded automatically. All project platforms are supported, including AnyCPU.

To use the SDK, download a license key from the Pdftools website and use it as described in Initialize the SDK.

note

This NuGet package is only supported on a subset of the operating systems supported by .NET Core.

Directory for temporary files​

This directory for temporary files is used for data specific to one instance of a program. The data is not shared between different invocations and deleted after termination of the program. The directory is determined as follows. The product checks for the existence of environment variables in the following order and uses the first path found:

  1. The path specified by the %TMP% environment variable.
  2. The path specified by the %TEMP% environment variable.
  3. The path specified by the %USERPROFILE% environment variable.
  4. The Windows directory.

Cache directory​

The cache directory is used for data that is persisted and shared between different invocations of a program. The actual caches are created in subdirectories. The content of this directory can safely be deleted to clean all caches. This directory should be writable by the application, otherwise caches cannot be created or updated and performance degrades significantly.

If the user has a profile:

%LOCAL_APPDATA%\PDF Tools AG\Caches

If the user has no profile:

<TempDirectory>\PDF Tools AG\Caches

Font directories​

For font directories by operating system, see Install fonts.

Set color profiles​

If no color profiles are available, default profiles for both RGB and CMYK are generated on the fly by the Pdftools SDK. If no particular color profiles are set, default profiles are used. By default, the SDK uses the color profile "sRGB Color Space Profile.icm" for device RGB colors, and "USWebCoatedSWOP.icc" for device CMYK. It searches for these profiles in the specified directories:

  1. %SystemRoot%\System32\spool\drivers\color
  2. directory Icc, which must be a direct sub-directory of where the PdfToolsSdkAPI.dll resides.

Most systems have pre-installed color profiles. For example, on Windows at %SystemRoot%\sys- tem32\spool\drivers\color\.

You can download color profiles from the links provided in the bin\Icc\ directory or from these websites:

Install fonts​

Some Pdftools SDK features require fonts to be installed locally.

If you use these SDK features, then you must have fonts installed:

  • PDF to PDF/A conversion
  • PDF to image conversion

For example, the PDF/A standard requires all fonts to be embedded in the PDF file. This guarantees that the textual content of a conforming file will match, on a glyph by glyph basis, the appearance of the file originally created. If non-embedded fonts are used in the original PDF when converting to PDF/A, the fonts must be embedded during conversion. To embed fonts, a matching font has to be found in the font directories.

PDF documents may contain both embedded and non-embedded fonts. When rendering non-embedded fonts when converting to image from PDF, the best result can be achieved if the font is available on the system. Therefore, it is important to make sure the font directories contain all fonts required.

Font directories​

The location of the font directories depends on the operating system.

Font directories are traversed recursively in the order specified. If two fonts with the same name are found, the latter takes precedence, i.e. user fonts always take precedence over system fonts.

Installing fonts in Windows

When a font is installed, it is installed by default only for a particular user. It is important to either install fonts for all users or make sure the Pdf Tools SDK is run under that user and the user profile is loaded.

The font directories for Windows are:

  1. %SystemRoot%\Fonts
  2. User fonts listed in the registry key \HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Fonts. This includes user specific fonts from C:\Users\<user>\AppData\Local\Microsoft\Windows\Fonts and app specific fonts from C:\Program Files\WindowsApps
  3. Fonts directory, which must be a direct subdirectory of where PdfToolsSdkAPI.dll resides.

The directories are transversed recursively in this order.

Font cache​

A cache of all fonts in all font directories is created. If fonts are added or removed from the font directories, the cache is updated automatically.

To achieve optimal performance, make sure that the cache directory is writable for the Pdftools SDK. Otherwise, the font cache cannot be updated and the font directories have to be scanned on each program startup.

The font cache is created in the subdirectory <CacheDirectory>/Installed Fonts of the cache directory.

Initialize the SDK​

You initialize the library with the initialize method of the sdk class, passing the license key as a string.

tip

Sign up for a trial license to get a license key.

namespace PdfToolsValidateSimple
{
    class Program
    {
        /***$Usage$***/

        static void Main(string[] args)
        {
            /***$CheckArguments$***/

            try
            {
                // Set and check license key. If the license key is not valid, an exception is thrown.
                Sdk.Initialize("$LicenseKey$");

If the license key is missing, an exception is thrown. If a license key is provided but is incorrect as either the format is incorrect or it is not a valid key, a corrupt file or license exception is thrown, respectively.