TuesPechkin Not Working in .NET Core: Migration Guide

Developers attempting to use TuesPechkin in .NET Core projects encounter a series of errors that cannot be resolved through configuration changes. The library was designed for .NET Framework and relies on native interop patterns that do not translate to .NET Core or .NET 5+. Combined with the fact that its underlying dependency, wkhtmltopdf, was archived in January 2023 with unpatched security vulnerabilities, TuesPechkin represents a dead end for modern .NET development.

This article documents the specific errors developers encounter, explains why these issues cannot be fixed, and provides a migration path to IronPDF for teams that need HTML-to-PDF conversion in .NET Core environments.

The Problem

TuesPechkin is a .NET wrapper for wkhtmltopdf, the open-source command-line tool that converts HTML to PDF using the Qt WebKit rendering engine. The library gained popularity in the .NET Framework era because it provided an object-oriented API over wkhtmltopdf's native binaries.

The fundamental issue is that TuesPechkin targets .NET Framework 2.0 and was never updated to support .NET Core or .NET 5+. The library's NuGet package explicitly states compatibility with ".NET 2.0 and up," referring exclusively to .NET Framework versions. When developers attempt to use TuesPechkin in .NET Core projects, they encounter immediate failures at runtime.

The library depends on native Windows DLLs (wkhtmltox.dll) that must be deployed alongside the application. This deployment model relies on .NET Framework's assembly loading behavior, which differs significantly from .NET Core's runtime host. The result is a series of exceptions that cannot be resolved without fundamentally rewriting the library.

Error Messages and Symptoms

Developers commonly encounter these exceptions when attempting to use TuesPechkin in .NET Core:

System.DllNotFoundException: Unable to load DLL 'wkhtmltox.dll': The specified
module could not be found. (Exception from HRESULT: 0x8007007E)

This error occurs even when the DLL exists in the expected location because .NET Core's native library loading mechanism differs from .NET Framework's.

System.BadImageFormatException: Could not load file or assembly
'TuesPechkin.Wkhtmltox.Win32' or one of its dependencies. An attempt was made
to load a program with an incorrect format.

This error indicates a 32-bit versus 64-bit mismatch. TuesPechkin provides separate packages for Win32 and Win64, and selecting the wrong one for your process architecture causes this failure. In .NET Core, the default is typically 64-bit, which conflicts with many existing TuesPechkin deployments.

System.TypeLoadException: Could not load type 'TuesPechkin.TempFolderDeployment'
from assembly 'TuesPechkin, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'

This error appears when the library cannot initialize its deployment infrastructure, often because the underlying file system operations or assembly loading patterns do not work correctly in the .NET Core runtime.

Who Is Affected

The .NET Core compatibility issues affect several categories of developers:

Migration projects are the largest affected group. Organizations upgrading legacy ASP.NET applications to ASP.NET Core discover that TuesPechkin, which worked in their .NET Framework application, fails completely after migration. The library cannot be updated to work with .NET Core because its architecture depends on .NET Framework-specific behaviors.

Docker and container deployments fail because TuesPechkin requires the Visual C++ 2013 runtime and specific Windows system libraries. While .NET Core applications can run on Windows containers, the additional dependencies complicate deployment and defeat much of the containerization benefit.

Linux and macOS development is completely blocked. TuesPechkin only supports Windows because wkhtmltopdf's Windows binaries are embedded in the NuGet packages. Developers working on non-Windows systems cannot even run tests locally.

Azure App Service deployments face particular challenges. Microsoft's documentation notes that Azure Websites do not support wkhtmltopdf, meaning applications using TuesPechkin cannot be deployed to Azure's PaaS offering without significant architectural changes.

Evidence from the Developer Community

The TuesPechkin GitHub repository shows a pattern of unresolved compatibility issues spanning several years.

Timeline

Date	Event	Source
2016-03-15	DllNotFoundException issue reported	GitHub Issue #57{:rel="nofollow"}
2016-08-22	32/64-bit AnyCPU package requested	GitHub Issue #87{:rel="nofollow"}
2017-04-12	Production environment DLL loading failures	GitHub Issue #153{:rel="nofollow"}
2018-01-15	Application pool conflicts documented	GitHub Issue #143{:rel="nofollow"}
2023-01-02	wkhtmltopdf repository archived	GitHub{:rel="nofollow"}

Community Reports

The GitHub repository contains numerous unresolved issues describing the same fundamental problems:

"I'm getting 'Unable to load DLL wkhtmltox.dll' on my server but it works fine on my local machine. Both are Windows, same files, same everything."
— Multiple developers, GitHub Issues

The pattern repeats across environments. Developers report that the library works in development but fails in production, works with IIS Express but fails with full IIS, or works with one application pool configuration but fails with another.

"After updating to version 2.0.0+, Factory.Create() no longer works. The library now expects a path to the DLL using StaticDeployment."
— Developer report, GitHub Issue #57

Breaking changes between versions compound the compatibility problems. Developers who upgrade to fix one issue often introduce new failures.

Root Cause Analysis

.NET Framework Dependency

TuesPechkin was built for .NET Framework 2.0, which has fundamentally different assembly loading and native interop mechanisms compared to .NET Core. The library uses P/Invoke to call into native wkhtmltox.dll, but the way it locates and loads this DLL relies on .NET Framework's probing behavior.

In .NET Core, native library loading follows different rules. The runtime does not automatically probe the same locations, and the deployment model for native dependencies changed significantly. TuesPechkin's EmbeddedDeployment classes, which extract DLLs to temporary folders at runtime, do not account for these differences.

32-bit vs 64-bit Architecture

The library ships separate NuGet packages for Win32 and Win64:

• TuesPechkin.Wkhtmltox.Win32
• TuesPechkin.Wkhtmltox.Win64

Developers must choose the correct package for their target architecture. In .NET Framework, where 32-bit was common, Win32 was often the default choice. In .NET Core, 64-bit is standard, requiring developers to switch packages. An AnyCPU package was requested by the community but never officially implemented in the main repository.

The architecture mismatch causes BadImageFormatException because loading a 32-bit DLL into a 64-bit process (or vice versa) is not possible at the operating system level.

Visual C++ Runtime Dependency

TuesPechkin requires the Visual C++ 2013 Redistributable to be installed on the target machine. This requirement is not enforced by NuGet and often surprises developers when their application works in development (where Visual Studio installs the runtime) but fails in production or containerized environments.

Abandoned Underlying Library

The wkhtmltopdf project, which TuesPechkin wraps, was archived on January 2, 2023. The repository is now read-only, meaning no updates or security patches will be released. This affects TuesPechkin directly because:

1. Any bugs in wkhtmltopdf cannot be fixed
2. Security vulnerabilities in wkhtmltopdf remain unpatched
3. The Qt WebKit rendering engine that wkhtmltopdf uses is itself deprecated and unmaintained
4. Modern HTML5, CSS3, and JavaScript features are poorly supported or broken

Security Vulnerabilities

Using TuesPechkin means inheriting wkhtmltopdf's unpatched security vulnerabilities. Several critical issues remain unfixed:

CVE-2022-35583: Server-Side Request Forgery (CVSS 9.8 Critical)

wkhtmltopdf 0.12.6 is vulnerable to SSRF attacks. An attacker can inject an iframe tag with a malicious source URL, causing the server to make requests to internal network resources. This can lead to:

• Access to internal services and metadata endpoints
• Credential theft from cloud provider metadata services
• Data exfiltration from internal databases

The vulnerability affects any application that renders user-controlled HTML content.

CVE-2020-21365: Directory Traversal

Directory traversal in wkhtmltopdf through 0.12.5 allows remote attackers to read local files via crafted HTML. An attacker can use this to:

• Read sensitive configuration files
• Access application source code
• Steal credentials stored on the filesystem

Local File Inclusion

The wkhtmltopdf project explicitly states that the tool "should not be used for untrusted HTML content." When used improperly, it introduces high-risk vulnerabilities for both SSRF and Local File Inclusion attacks.

Since wkhtmltopdf is archived, these vulnerabilities will never be patched. Organizations using TuesPechkin in production are exposed to known, exploitable security issues.

Attempted Workarounds

Developers have attempted various workarounds to make TuesPechkin function in .NET Core environments. None provide a complete solution.

Workaround 1: Manual DLL Deployment

Approach: Copy wkhtmltox.dll directly to the application's output directory and use StaticDeployment.

// Attempt to specify DLL location manually
var path = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "wkhtmltox.dll");
var deployment = new StaticDeployment(path);
var converter = new ThreadSafeConverter(new RemotingToolset<PdfToolset>(deployment));

Limitations:

• Still fails in .NET Core due to different native library loading
• Requires managing 32-bit and 64-bit DLLs manually
• Does not resolve the Visual C++ runtime dependency
• Does not work in containerized environments without additional configuration

Workaround 2: Custom AnyCPU Deployment

Approach: Create a custom deployment class that detects architecture at runtime.

// Community workaround for architecture detection
public class WinAnyCPUEmbeddedDeployment : IDeployment
{
    public string Path
    {
        get
        {
            if (IntPtr.Size == 8)
                return Win64EmbeddedDeployment.Path;
            else
                return Win32EmbeddedDeployment.Path;
        }
    }
}

Limitations:

• Only addresses the 32/64-bit issue, not .NET Core compatibility
• Adds complexity to deployment
• Does not resolve underlying runtime differences

Workaround 3: Running in Separate Process

Approach: Spawn wkhtmltopdf as a separate command-line process rather than using TuesPechkin's managed wrapper.

Limitations:

• Loses the object-oriented API that made TuesPechkin attractive
• Requires wkhtmltopdf to be installed separately
• Introduces process management complexity
• Still carries all of wkhtmltopdf's security vulnerabilities

A Different Approach: IronPDF

For .NET Core applications requiring HTML-to-PDF conversion, IronPDF provides a maintained alternative that works natively across .NET Framework, .NET Core, and .NET 5+.

Why IronPDF Avoids These Issues

IronPDF uses an embedded Chromium rendering engine rather than wrapping wkhtmltopdf. This architectural difference eliminates the problems TuesPechkin developers encounter:

Native .NET Core support: IronPDF is built as a .NET Standard 2.0 library, meaning it runs on .NET Framework 4.6.2+, .NET Core 2.0+, and .NET 5/6/7/8+ without compatibility issues.

No external dependencies: The Chromium engine is embedded within the NuGet package. There is no need to install Visual C++ runtimes, wkhtmltopdf, or other system dependencies.

Cross-platform operation: IronPDF runs on Windows, Linux, and macOS. Docker deployments work without special configuration.

Active maintenance: IronPDF receives regular updates with bug fixes, security patches, and new features. The underlying Chromium engine is updated to support modern web standards.

Modern web standards: Chromium provides full support for HTML5, CSS3 (including Flexbox and Grid), JavaScript, and web fonts. Content renders exactly as it would in Google Chrome.

Code Example

The following example demonstrates converting HTML to PDF in .NET Core, the exact scenario where TuesPechkin fails:

using IronPdf;

public class HtmlToPdfService
{
    public byte[] ConvertHtmlToPdf(string htmlContent)
    {
        // ChromePdfRenderer uses embedded Chromium - no external dependencies
        var renderer = new ChromePdfRenderer();

        // Configure rendering options
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.MarginLeft = 20;
        renderer.RenderingOptions.MarginRight = 20;

        // Enable JavaScript for dynamic content
        renderer.RenderingOptions.EnableJavaScript = true;

        // Wait for any async JavaScript to complete
        renderer.RenderingOptions.WaitFor.RenderDelay(200);

        // Render HTML string to PDF
        // This works identically on Windows, Linux, and macOS
        var pdf = renderer.RenderHtmlAsPdf(htmlContent);

        // Return PDF as byte array for web responses
        return pdf.BinaryData;
    }
}

This code runs without modification on any .NET Core or .NET 5+ application, regardless of operating system or deployment environment.

Comparison: TuesPechkin vs IronPDF

The following comparison shows the equivalent operations in both libraries:

TuesPechkin (does not work in .NET Core):

// TuesPechkin approach - fails in .NET Core
var document = new HtmlToPdfDocument
{
    GlobalSettings = {
        ProduceOutline = true,
        DocumentTitle = "My Document",
        PaperSize = PaperKind.A4
    },
    Objects = {
        new ObjectSettings { HtmlText = htmlContent }
    }
};

// This line throws DllNotFoundException in .NET Core
byte[] result = converter.Convert(document);

IronPDF (works in .NET Core):

// IronPDF approach - works in .NET Core
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
renderer.RenderingOptions.Title = "My Document";

var pdf = renderer.RenderHtmlAsPdf(htmlContent);
byte[] result = pdf.BinaryData;

API Reference

For complete documentation on the methods used:

• ChromePdfRenderer Class
• HTML to PDF Tutorial
• .NET Core Deployment Guide

Migration Considerations

Licensing

TuesPechkin is open source under the MIT license. IronPDF is commercial software with per-developer licensing. A free trial is available for evaluation, and the Lite license covers single-developer teams.

API Differences

The migration from TuesPechkin to IronPDF requires code changes, but the patterns are similar:

TuesPechkin	IronPDF
HtmlToPdfDocument	ChromePdfRenderer
ObjectSettings.HtmlText	RenderHtmlAsPdf(html)
ObjectSettings.PageUrl	RenderUrlAsPdf(url)
GlobalSettings.PaperSize	RenderingOptions.PaperSize
converter.Convert(doc)	renderer.RenderHtmlAsPdf(html)

Most migrations can be completed by replacing the PDF generation calls without modifying the HTML content or application logic.

What You Gain

• Platform independence: Run on Windows, Linux, macOS, Docker, Azure App Service
• .NET Core compatibility: No DllNotFoundException or BadImageFormatException
• Modern rendering: Full HTML5, CSS3, JavaScript support
• Security updates: Active maintenance and vulnerability patches
• No external dependencies: Everything included in the NuGet package

What to Consider

• Commercial licensing: Unlike TuesPechkin's MIT license, IronPDF requires a paid license for production use
• Package size: IronPDF's NuGet package is larger due to the embedded Chromium engine
• Memory usage: Chromium-based rendering uses more memory than wkhtmltopdf for simple documents

Conclusion

TuesPechkin cannot be made to work reliably in .NET Core because its architecture depends on .NET Framework-specific behaviors that do not exist in the .NET Core runtime. Combined with the abandonment of the underlying wkhtmltopdf project and its unpatched security vulnerabilities, TuesPechkin should not be used for new development and existing implementations should be migrated.

IronPDF provides a straightforward migration path for teams that need HTML-to-PDF conversion in modern .NET applications. The library's cross-platform support and native .NET Core compatibility eliminate the errors that make TuesPechkin unusable in current development environments.

---

Jacob Mellor is CTO at Iron Software. He originally built IronPDF and continues to lead the company's technical direction with over 25 years of commercial software experience.

---

References

1. TuesPechkin GitHub Repository{:rel="nofollow"} - Official repository showing .NET Framework 2.0 targeting
2. TuesPechkin NuGet Package{:rel="nofollow"} - Package compatibility information
3. GitHub Issue #57 - DllNotFoundException{:rel="nofollow"} - DLL loading failures
4. GitHub Issue #65 - Unable to load DLL{:rel="nofollow"} - Production deployment failures
5. GitHub Issue #87 - AnyCPU Package Request{:rel="nofollow"} - 32/64-bit compatibility requests
6. GitHub Issue #153 - Production Environment Failures{:rel="nofollow"} - Environment-specific errors
7. wkhtmltopdf Repository (Archived){:rel="nofollow"} - Archived January 2023
8. CVE-2022-35583 - SSRF Vulnerability{:rel="nofollow"} - Critical security vulnerability
9. CVE-2020-21365 - Directory Traversal{:rel="nofollow"} - File disclosure vulnerability
10. wkhtmltopdf Security Advisory{:rel="nofollow"} - SSRF and LFI risks

For comprehensive IronPDF documentation including tutorials, API reference, and deployment guides, visit ironpdf.com.