Skip to main content

.NET technical notes

Learn about specifics of the .NET interface of the Pdftools SDK.

tip

For the full API reference for the Pdftools SDK, see the .NET API reference.

IDisposable objects​

Objects that must be closed explicitly (for example, PdfTools.Pdf.Document, PdfTools.Image.Document, PdfTools.Crypto.Providers.Provider, or subclasses) implement the IDisposable interface. Instead of calling Dispose() directly, use the using statement:

using (Document document = ...)
{
 ...
} 
// document.Dispose() is called implicitly here

Error handling​

Errors are reported using exceptions. Where applicable, the SDK maps errors to corresponding native exception classes, such as System.ArgumentException, System.InvalidOperationException, System.NotSupportedException, or System.IO.IOException. The remaining errors are modeled using exception classes that inherit from a base class PdfToolsException.

Streams​

The native stream interface System.IO.Stream is used.

Lists and iterables​

The API uses different concepts for returning collections of elements depending on the context:

  • Lists (System.Collections.Generic.IList<T>) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible.
  • Iterables (System.Collection.Generic.IEnumerable<T>) are used when elements are retrieved on demand. They don’t allow random access, but only allow iterating through the elements.

Maps​

Maps implement the native dictionary interface System.Collections.Generic.IDictionary<K, V>.

Namespace​

The Pdftools SDK uses the namespace PdfTools.

note

We recommend using a custom, company-specific namespace for your code. Using the PdfTools namespace like the SDK can lead to problems with ambiguous class names, especially when you use multiple Pdftools SDKs in the same project.