Upgrading .NET and .NET Framework Applications from APDFL 18 to APDFL 21

Overview

Upgrading Adobe PDF Library (APDFL) to v21 primarily involves updating your runtime, NuGet references, and deployment files. The assembly name `Datalogics.PDFL.dll` and namespace `Datalogics.PDFL` remain the same, and applications using recent v18 packages can generally keep their existing APDFL calls.

APDFL v21 uses Adobe's v21 core and includes improvements to PDF processing, fonts, and document conversion. For more information, refer to the APDFL v21 Release Notes.

Before You Begin

Identify which .NET interface your application uses:

For .NET, update both development and deployment environments. Where practical, verify your application on .NET 10 with its existing APDFL v18 package before changing APDFL. See the [.NET Supported Environments](https://dev.datalogics.com/adobe-pdf-library-21/dot-net/supported-environments).

Confirm that the selected package contains native libraries for your runtime identifier and architecture. Availability can differ between License-Managed and non-License-Managed distributions, particularly for 32-bit Windows and Intel macOS.

Update the Application

1. Select the Correct NuGet Packages

Keep the same licensing model when upgrading. Package IDs containing `.LM.` identify License-Managed packages; packages without `.LM.` are the non-License-Managed equivalents. Do not reference both in one application.

Public v21 NuGet packages are License-Managed. Obtain non-License-Managed packages through your Datalogics distribution channel. If you previously installed the managed interface from an older SDK installer, move to NuGet distribution.

Replace the v18 package reference with an explicit v21 version. A reference such as `18.*` will stay within v18. For example, a non-License-Managed .NET project using package 21.0.1 contains:

```xml
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Adobe.PDF.Library.NET" Version="21.0.1" />
</ItemGroup>
```

Use the package version approved for your deployment; 21.0.1 is an example, not a requirement to use that patch. NuGet version numbers differ from APDFL product release labels.

2. Review Companion Packages

Update Forms Extension references when used. Let NuGet resolve the required resource and shared-library dependencies, and review any versions pinned directly or through central package management.

For example, APDFL .NET 21.0.1 requires Resources 1.1.x and SharedLibs 21.x. Supporting packages have their own version numbers, so do not assign every dependency the same version as the main package.

3. Check .NET Framework Binding Settings

For .NET Framework applications, inspect `app.config` or `web.config` for `bindingRedirect` and `codeBase` entries referencing the old assembly version. Update them for the assembly actually installed by the selected package. The assembly version is not the NuGet package version.

For projects using `packages.config`, also check project `HintPath` entries for old package directories.

4. Replace the Deployment Files

Clean the build output, restore packages, and rebuild. Deploy the managed assembly, native libraries, plug-ins, and resources produced by the updated build together.

Review custom copy scripts and installer manifests for `DL180` filenames; v21 uses `DL210` equivalents. Avoid collecting dependencies from only one package directory, because native components can move between packages.

Verify the Upgrade

Run representative documents and compare the results. Rendering, font matching, and color conversion can change even when the application compiles successfully.

If initialization fails, inspect the innermost exception, native dependencies, architecture, resource paths, and license configuration. License-Managed applications retain the existing licensing API, but license-file or server compatibility should be confirmed for the target release.

When skipping older v18 patches, also review intervening API changes. Earlier `DigestCategory` values such as `Sha3_256` and `Shake128` are absent from the compared v21 package and may require source changes.

How to Get Additional Help

Contact Datalogics Tech Support 

Fetch the answers quickly using our AI assistant Scout, available for any language. Scout also opens access to our MCP server, connecting APDFL with your favorite AI tools for faster and easier coding.