Skip to main content
Version: 1.3

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.

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. Initialize the library by passing the license key.
  5. Choose your goals. Depending on your goals, the tasks to be performed vary:
  6. Optional: Set color profiles and install fonts.

Request a license key​

Without a valid license key the output files are watermarked. Use a valid license key to remove the watermark. Get in touch with the Pdftools sales team through the Contact page to get a full license.

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.

Without a valid license key the output files are watermarked. To remove the watermark, request 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.

Initialize the SDK​

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

tip

Without a valid license key the output files are watermarked. Use a valid license key to remove the watermark. Get in touch with the Pdftools sales team through the Contact page to get a full license.

static void Main(string[] args)
{
    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.

note

For trial licenses, if the Pdftools SDK can not connect to the Pdftools Licensing Service, an exception is thrown. See Pdftools SDK license management documentation for more information.

Optional: 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:

Optional: 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.

Special Directories​

Special directories are used by the Pdftools SDK during file processing. For optimal performance, the application should have write access to these directories.

Temporary files directory​

The directory of temporary files is used for data specific to one instance of a program. The data is not shared between different invocations and is deleted after the program is terminated. 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 must be writable by the application. Otherwise, caches cannot be created or updated leading to significantly decreased performance.

If the user has a profile:

%LOCAL_APPDATA%\PDF Tools AG\Caches

If the user has no profile:

<TempDirectory>\PDF Tools AG\Caches