Use IronPDF with in-Engine Mode

Difference between Native & Engine

IronPDF has some performance-intensive functions that you may choose to run remotely. While IronPDF does not require IronPdfEngine to run, setting up IronPdfEngine as a remote service is an optional way to avoid platform-specific Chrome compatibility issues on older operating systems and mobile environments.

Get started with IronPDF

Start using IronPDF in your project today with a free trial.

First Step:
green arrow pointer


How using Engine changes the way you code with IronPDF

When using the Engine configuration, we recommend installing IronPdf.Slim instead of the full IronPdf package from NuGet, as the Engine manages all the extra bulk included in the Native package.

Install-Package IronPdf.Slim

After installing IronPdf.Slim, configure the connection settings by pointing IronPDF to your IronPdfEngine instance. Add the following code at the startup of your application (or before calling any IronPDF method):

Extra Line of Configuration Code to add to your C# code

Assuming that IronPdfEngine runs remotely at 123.456.7.8:33350:

// Establish a connection with the remote IronPdfEngine
// Remember to replace the IP address and port with your actual server details
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
);

// Additional code for your application
// Establish a connection with the remote IronPdfEngine
// Remember to replace the IP address and port with your actual server details
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
);

// Additional code for your application
' Establish a connection with the remote IronPdfEngine
' Remember to replace the IP address and port with your actual server details
Installation.ConnectToIronPdfHost(IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350"))

' Additional code for your application
$vbLabelText   $csharpLabel

How does IronPdfEngine Work?

IronPdfEngine is a containerized server designed to manage various IronPDF operations, including creating, writing, editing, and reading PDFs, all using the gRPC protocol. Built as a self-contained C# .NET application, IronPdfEngine operates independently, eliminating the need for the .NET runtime during execution. We handle the gRPC connection for you so you can focus on the coding!

Other clarifications for IronPdfEngine

IronPdf .NET does not require IronPdfEngine to run. IronPdfEngine is just an optional way to use IronPdf. By default, IronPdf for .NET will not use IronPdfEngine.

Please noteEach version of IronPdf for .NET requires a specific version of IronPdfEngine. Cross-version support is not available. For IronPdf for .NET, the required version of IronPdfEngine will always match. For example, IronPdf 2024.2.2 will use IronPdfEngine 2024.2.2

IronPdf .NET with Remote IronPdfEngine

The IronPdf.slim NuGet package is the only package needed to use IronPdf for .NET with Remote IronPdfEngine.

Please noteIf you are using IronPdf or IronPdf.Linux, you may use IronPdf.slim instead to reduce your application size.

Assuming that IronPdfEngine runs remotely at 123.456.7.8:33350.

Install IronPdf using NuGet:

Install-Package IronPdf.Slim

After installing IronPdf.slim, you just need to tell IronPdf where IronPdfEngine is (please make sure that address is accessible, not blocked by firewall). Use the IronPdfConnectionConfiguration class to configure the connection settings. Add the below code to the initial stage of your application (or just before calling any IronPdf method).

// Connect to the remote IronPdfEngine
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
);
// Connect to the remote IronPdfEngine
Installation.ConnectToIronPdfHost(
    IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350")
);
' Connect to the remote IronPdfEngine
Installation.ConnectToIronPdfHost(IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer("123.456.7.8:33350"))
$vbLabelText   $csharpLabel

Simple as that! After this, your application will be connected to the Remote IronPdfEngine!


IronPdfEngine Limitations

  • Currently, IronPdfEngine does not support horizontal scaling yet (load balancing with multiple instances) because we store the processing PDF file binaries inside the server memory and use PdfDocumentId for communicating between server and client. This also minimizes bandwidth usage and increases the processing speed.
  • To run IronPdfEngine Docker remotely, you need to ensure that the IronPdfEngine port is reachable.
  • IronPdfEngine Docker running on Linux x64 (Debian) using official ubuntu:22.04 based images may produce PDF output that is slightly different from what you would get running IronPdf locally due to different OS behavior.
  • Since IronPdfEngine Docker is Linux-based, it requires Linux Containers daemon (select Switch to Linux Containers if you are using Windows).
  • IronPdfEngine binaries are not cross-platform, so we build them for each platform specifically.
  • Cross-version support is not available.

Frequently Asked Questions

How can I set up IronPdfEngine for remote PDF generation?

To set up IronPdfEngine for remote PDF generation, install the `IronPdf.Slim` package from NuGet and configure the connection settings using the `IronPdfConnectionConfiguration` class. This setup allows you to connect your application to the IronPdfEngine instance remotely.

What are the main benefits of using IronPdfEngine with my application?

Using IronPdfEngine with your application allows for remote execution of PDF tasks, helping avoid platform-specific compatibility issues, especially on older systems and mobile platforms. It also eliminates the need for the .NET runtime during execution.

Why might I choose to use IronPdfEngine instead of the native PDF library?

You might choose IronPdfEngine to run performance-intensive PDF functions remotely, reducing compatibility issues with different operating systems and improving performance by leveraging a Chrome-identical renderer for HTML to PDF conversion.

Is horizontal scaling supported in IronPdfEngine?

No, IronPdfEngine currently does not support horizontal scaling, which means it cannot be load-balanced across multiple instances due to the way PDF file binaries are handled in server memory.

Can IronPdfEngine run on different operating systems?

IronPdfEngine is designed to run on Linux systems using Docker containers. However, the binaries are platform-specific, so you need to ensure you are using the correct version for your operating system.

What should I do if my PDF outputs are different when using IronPdfEngine?

PDF outputs may vary slightly due to different operating system behaviors. To minimize differences, ensure you are using the correct Docker image and check for any OS-specific settings that might affect rendering.

How do I ensure my application is using the correct version of IronPdfEngine?

To ensure compatibility, each version of IronPDF requires a matching version of IronPdfEngine. Make sure to update both components simultaneously to avoid cross-version issues.

What are the limitations when using IronPdfEngine on Windows?

When using IronPdfEngine on Windows, you need Linux Containers for Docker and must ensure the server port is reachable. The binaries are platform-specific, and switching to Linux Containers is required.

How do I configure IronPDF to connect to a remote IronPdfEngine server?

To configure IronPDF for a remote server, use Installation.ConnectToIronPdfHost with the IronPdf.GrpcLayer.IronPdfConnectionConfiguration.RemoteServer method, specifying the server's IP and port details.

What package should I use to minimize the application size when using IronPdfEngine?

You should use the `IronPdf.Slim` package from NuGet, as it includes only the necessary components for running IronPDF with IronPdfEngine, thereby reducing the application size.

Chaknith Bin
Software Engineer
Chaknith works on IronXL and IronBarcode. He has deep expertise in C# and .NET, helping improve the software and support customers. His insights from user interactions contribute to better products, documentation, and overall experience.