.Net Core migration guide

The pdfEngine SDK v12 includes the new callas .Net Core language binding that replaces the existing callas .Net Framework language binding. It is available for multiple platforms (Windows, Linux, MacOS).

This migration guide is intended to support customers who are using existing applications developed with the previous, now obsolete callas .Net Framework.

The callas .Net Core language binding is not compatible with the callas .Net Framework language binding.

We use the term .Net Core when we actually mean .Net Standard. The reason is that the distinction between .Net Standard and .Net Framework often led to confusion.

callas .Net Framework language binding

The callas .Net Framework language binding assembly is still available inside the var/legacy subdirectory of the Engine SDK. However it is no longer maintained and has become a legacy interface.

Assembly

  • pdfEngineDotNet.dll

For existing .Net Framework applications the var/legacy/pdfEngineDotNet.dll assembly needs to be copied into the top level directory.

The following sample programs have been removed:

  • pdfaPilotDotNetSample.exe

  • pdfaPilotDotNetSampleThreadSafe.exe

  • pdfToolboxDotNetSample.exe

  • pdfToolboxDotNetSampleThreadSafe.exe

  • sample-DotNet  (the directory containing the sample source code)

callas .Net Core language binding

Assembly

  • EngineDotNetCore.dll
  • EngineDotNetCore.deps.json
  • EngineDotNetCore.xml

This assembly (and its companion files) reside either in the top level directory (on Windows and MacOS) or in the lib subfolder (on Linux).

The following sample programs have been added:

  • sample-DotNetCore/pdfToolboxSampleDotNetCore

  • sample-DotNetCore/pdfaPilotSampleDotNetCore

  • sample-DotNetCore/src (the directory containing the sample source code)

In addition there is a sample-DotNetCore/Readme.txt containing further Usage and Build Instructions.

Main differences

Namespace

The namespace has been changed from CallasSoftware.PDFEngine to CallasSoftware.PDFEngineCore.

Naming conventions

The PTB_ prefix has been removed from all API functions, Structures and Enum Types. In addition some API functions have been renamed, e.g. PTB_LanguageEnum has been renamed to EnumerateLanguages.

In general the new API functions try to follow a Verb<Something> paradigm.

Callbacks

API Functions with callbacks no longer have a corresponding userData parameter. All user Data needs to be passed using Lambdas.

Migration Example

As an example the former PTB_ListLanguages API call is used to demonstrate how it can be migrated to the new EnumerateLanguages API call.

.Net Framework 

        public static Boolean listLangCB (TStringID idLang, IntPtr userData) {
            Console.WriteLine ("Lang: " + getString (idLang));
            return true;
        }


        private static CError.PTB_EError doEnumerateLanguages () {
            CLib.PTB_LanguageCB_Net cbLang = new CLib.PTB_LanguageCB_Net (listLangCB);
            CLib.PTB_LanguageEnum (cbLang, IntPtr.Zero);
            return CError.PTB_EError.PTB_eerrNone;
        }
Click to copy

.Net Core 

        EError DoEnumerateLanguages()
        {
            LanguageCB cb = (StringID id) =>
            {
                Console.WriteLine("Lang: " + GetString(id));
                return true;
            };
            EnumerateLanguages(cb);
            return EError.None;
        }
Click to copy

IDE users

The callas .Net Core language binding is no longer compatible with Visual Studio 2017. At least Visual Studio 2019 (or higher) is required for development with Visual Studio.

Another possible alternative is to use the open source Visual Studio Code IDE.

Summary

.Net Core is the new recommended API (actually it is a .Net Standard API).

Since the .Net Framework language binding assembly is still included in the installation package, there are two alternative upgrade paths for existing .Net framework applications to use pdfEngine SDK v12:

  • migrate to the new .Net Core API (recommended)
  • continue using the legacy .Net Framework API