Resolving Namespace Conflicts in Syncfusion® PDF Packages

24 Jul 20263 minutes to read

Conflict Scenario

Namespace conflicts in .NET projects can occur when combining different Syncfusion PDF-related packages that target multiple platforms. For example, including the following package pairs in the same project:

  • Syncfusion.Pdf.Net.Core (cross-platform)
  • Syncfusion.PdfViewer.Windows or Syncfusion.PdfViewer.WPF (platform-specific viewers)

These conflicts usually arise because multiple Syncfusion packages share the same namespaces or types, leading to ambiguity.

Typical Error Message

When conflicting packages are used together, you may encounter a compiler error similar to the following:

The type 'PdfDocument' exists in both 'Syncfusion.Pdf.Base, Version=28.1462.35.0, Culture=neutral, PublicKeyToken=3d67ed1f87d44c89' and 'Syncfusion.Pdf.Portable, Version=28.1.35.0, Culture=neutral, PublicKeyToken=3d67ed1f87d44c89'

Resolution Strategy

To resolve this issue, follow the steps below.

1. Use the Package Compatibility Matrix

Ensure that your project uses the correct Syncfusion PDF package based on your application type. The following matrix provides a recommended approach for selecting the appropriate packages.

Application Type Required Packages Avoid
Windows Desktop Apps Syncfusion.Pdf.WinForms + Syncfusion.PdfViewer.Windows or Syncfusion.PdfViewer.WPF Syncfusion.Pdf.Net.Core
Headless Services Syncfusion.Pdf.Net.Core Syncfusion.Pdf.WinForms, Syncfusion.PdfViewer.Windows, Syncfusion.PdfViewer.WPF
ASP.NET Core / Blazor Syncfusion.Pdf.Net.Core + Syncfusion.PdfViewer.AspNet.Core Syncfusion.Pdf.WinForms, Syncfusion.PdfViewer.Windows, Syncfusion.PdfViewer.WPF

By following this matrix, you can ensure that platform-specific and cross-platform packages do not conflict.

2. Configure Package References in Your Project File

Use the following examples to correctly reference Syncfusion packages in your .csproj file.

Windows Forms Application (WinForms)

<!-- Windows Forms Application -->
<ItemGroup>
  <PackageReference Include="Syncfusion.Pdf.WinForms" Version="24.1.34" />
  <PackageReference Include="Syncfusion.PdfViewer.Windows" Version="24.1.34" />
</ItemGroup>

.NET 8 Web API (Headless Service)

<!-- .NET 8 Web API -->
<ItemGroup>
  <PackageReference Include="Syncfusion.Pdf.Net.Core" Version="24.1.34" />
</ItemGroup>

These configurations ensure that your application uses only the packages relevant to the target platform, preventing namespace conflicts.

3. Migrate an Existing Project

If your project already contains conflicting packages, follow these steps to resolve the issue.

Remove Conflicting Packages

Remove any conflicting packages from your project. For example:

dotnet remove package Syncfusion.Pdf.Net.Core
dotnet remove package Syncfusion.Pdf.WinForms

Install Platform-Appropriate Packages

Install the packages required for your specific platform. Ensure that only the required package(s) for your target platform are included.

Update All Syncfusion Dependencies to the Same Version

Make sure that every Syncfusion package referenced in your project is at the same version to maintain compatibility.

Verification Checklist

After resolving the conflict, verify the following to ensure your project is correctly configured:

  • A single PDF package family is referenced in dependencies (for example, either Syncfusion.Pdf.Net.Core or Syncfusion.Pdf.WinForms—not both).
  • No mixed versions of Syncfusion packages are referenced.
  • Namespace consistency is maintained—ensure that all PDF-related namespaces come from Syncfusion.Pdf.