iText 7.1 - Migration guide for .NET

Tags: migration guideiText 7.1Release.NET

Migration Guide for .NET

Introduction

This is a short migration guide to help you or your developers switch from 7.0.x to 7.1.0. This guide will broadly cover the breaks in the API. Please consult the breaking changes on the iText website for the full and detailed list of changes. All listing below are non-exhaustive and mainly cover the most important changes that you need to do or you need to take into account when moving to 7.1.0.

1. Updating the version using NuGet

Update the following dependencies in your project files and packages.config:

  • Change the version of the iText-core from 7.0.x to 7.1.0.

  • Change the version of the iText add-on modules from 1.x.y to 2.0.0.

2.License keys and Licensed users

Together with 7.1.0, we are releasing v3.0.0 of our LicenseKey library. If you wish to use 7.1 under a commercial license, you'll need to use this version of the LicenseKey library. If you have been using v2.0, the only thing you'll have to change in your code is the dependency version of this library. You might also need to update your license-files as well.

3. Accessibility changes

  • In order to create a PDF/UA document, you need to explicitly call #AddUAXmpMetadata for WriterProperties, otherwise PDF document won't be marked (and therefore recognized) as such.

  • The SetRole() method on several layout elements has been moved to GetAccessibilityProperties().setRole().

  • SetRole() now takes a java string as argument. Standard role constants have found a home in iText.Kernel.Pdf.Tagging.StandardRoles

4. Moved packages, classes, fields and method

The following things have been moved from their old location to a new location.

Core

  • The SetRole() method on several layout elements has been moved to GetAccessibilityProperties().SetRole().

  • Constants from iText.IO.Font.FontConstants has moved to iText.IO.Font.Constants package. Standard PDF font names moved to iText.IO.Font.Constants.StandardFonts.

  • iText.IO.Font.FontConstants#notdef has moved to iText.IO.Font.FontEncoding#NOTDEF.

  • All constants in iText.IO.Font.FontNames have moved to FontMacStyleFlags, FontStretches and FontWeights.

  • The fields initialDocumentId and modifiedDocumentId and their accessors in iText.Kernel.Pdf.PdfDocument have been moved to WriterProperties.

  • Several methods in the abstract class iText.Kernel.Pdf.Annot.PdfAnnotation have been moved to the specific annotation where they make sense (e.g. it's no longer possible to attempt to set borders on a pop-up annotation).

  • Several methods in the abstract class iText.Kernel.Pdf.Annot.PdfMarkupAnnotation have been moved to the specific annotation where they make sense (e.g. it's no longer possible to attempt to set borders on a highlight annotation).

  • The emptyArea field and its accessors in iText.Layout.Layout.LayoutArea have been moved to RootLayoutArea.

  • The class iText.Forms.PdfSigFieldLockDictionary has been replaced by iText.Forms.PdfSigFieldLock.

Add-ons

pdfHTML

  • All jsoup classes and packages have moved from Org.Jsoup to iText.Html2pdf.Jsoup.

  • Some constants in in iText.Html2pdf.Css.CssConstants have moved to iText.Html2pdf.Html.AttributeConstants.

5. Removed packages, classes, fields and methods

The following things have been removed from iText in 7.1.0.

Core

  • Most constants in iText.IO.Font.FontConstants have been removed. The rest was deprecated.

  • Some methods in iText.IO.Font.PdfFont have been removed.

  • Due to changes in Counter logic, the classes in iText.Kernel.Log that dealt with counter logic have been removed.

  • To fix inconsistencies, DRAW_MODE fields in iText.Kernel.Pdf.IsoKey have been removed.

  • MakeIndirect and CopyTo methods belonging to classes that inherited from "PdfObject* have been removed.

  • Several methods and classes in iText.Kernel.Pdf.Tagging have been removed during tagging improvements.

  • Several methods in iText.Kernel that should not have been in use or were deprecated have been removed.

  • The height and width properties in iText.Layout.ElementPropertyContainer now only work with UnitValue, all methods that used float have been removed.

  • iText.Layout.Element.Cell#add(String) has been removed, use a BlockElement such as Paragraph instead.

  • A cleanup in iText.Layout has removed obsolete methods related to old rendering code.

6. Changed packages, classes, methods and fields

Core

  • iText.IO.Font several methods changed name or argument lists to fix inconsistencies and bugs.

  • iText.Kernel.Font.PdfFont the method ContainsGlyph(char) has been removed, use containsGlyph(int) instead.

  • iText.Kernel has had several methods change their return type to fix inconsistencies.

  • MakeIndirect() and CopyTo() methods belonging to classes that inherited from PdfObject have been removed, use PdfObject#copyTo() and PdfObject#makeIndirect() instead.

  • Return type of method iText.Kernel.Pdf.PdfPage#removePage(int) has been changed to void due to change in functionality.

  • Classes in iText.Kernel.Pdf.Annot now return their own type instead of the supertype for layout-methods (e.g. SetBorderStyle).

  • Changes in iText.Kernel.Pdf.Canvas.Parser.Data for unifying IEventData properties.

  • Methods in iText.Kernel.Pdf.Colorspace.PdfShading that return an array now will all return a PdfArray.

  • Major changes in return types, argument lists, interface inheritance (and more) in iText.Kernel.Pdf.Tagging and iText.Kernel.Pdf.Tagutils to allow the improvements for tagged pdf.

  • Return type changes in iText.Layout to fix inconsistencies.

  • iText.Forms.Fields.PdfFormField, inconsistency fixes.

  • iText.Signatures.PdfSigner, inconsistency fixes.

Change in counters logic

Previously counters had GetCounter() method and were in a way responsible for creating and filtering themselfs based on class there were used in. Now ICounterFactory responsible for creating and filtering counters and the actual class that process read and write event now extends from ICounter.

  • CounterManager deals with registration of counters instead of CounterFactory (to avoid confusion with ICounterFactory interface).

  • For simple cases use SimpleCounterFactory.

  • NoOpCounter was removed since there is no point in registering counter that does nothing.

  • You'll have to unregister its ICounterFactory implementation to disable a counter.

  • Since now there could be multiple counters registered, classes extended from PdfDocument should override GetCounters() method instead of GetCounter().

7. Visibility changes

Core

  • iText.IO.Font several classed and methods that should not have been used externally have been decreased in visibility from public to protected/private and from protected to internal.

  • The constructors for iText.Kernel.Pdf.PdfOutline have had their visibility reduced to internal. To create them, use PdfDocument#GetOutlines() instead.

  • In iText.Kernel.Pdf.Annot, the visibility of the constructors for the specific annotations have been made protected. To create such annotations, use PdfAnnotation#MakeAnnotation() instead.

  • iText.Kernel.Pdf.Colorspace.PdfShading: several methods changed from public to protected.

  • iText.Layout.Renderer: decrease in visibility for fields and methods not intended for public use.