Class IronPdfConnectionConfiguration

Configures the connection to IronPdfEngine for distributed/remote PDF processing. Use static factory methods for common configurations.

IronPdfEngine can run locally, in Docker, or on remote servers for scalable PDF generation across distributed architectures.

Example - Configuration scenarios:

// Docker container (common for microservices):
IronPdf.Setting.Connection = IronPdfConnectionConfiguration.Docker;
// Remote server with custom port:
IronPdf.Setting.Connection = IronPdfConnectionConfiguration.RemoteServer(
"https://pdf-server.mycompany.com:8080");
// .NET Framework with custom channel:
IronPdf.Setting.Connection = IronPdfConnectionConfiguration.NetFrameworkChannel(
"192.168.1.100:33350");
// Custom gRPC channel with metadata:
var channel = GrpcChannel.ForAddress("https://secure-server.com");
var metadata = new Metadata { { "Authorization", "Bearer token123" } };
IronPdf.Setting.Connection = IronPdfConnectionConfiguration.WithCustomChannel(
channel, metadata);

Inheritance

System.Object

IronPdfConnectionConfiguration

Namespace: IronPdf.GrpcLayer

Assembly: IronPdf.dll

Syntax

public class IronPdfConnectionConfiguration : Object

Remarks

Static Factory Methods:

• Docker - Pre-configured for Docker networking
• Executable - Local executable (default)
• RemoteServer(String, Metadata) - Remote HTTPS connection
• WithCustomChannel(ChannelBase, Metadata) - Advanced custom channel

Related Resources:

• IronPdfEngine Docker Guide
• Linux/Docker Deployment

Constructors

IronPdfConnectionConfiguration()

Declaration

public IronPdfConnectionConfiguration()

Properties

AllowUntrustedServerCertificate

Whether a RemoteServer connection accepts an IronPdfEngine TLS certificate that fails validation, for example a self-signed or expired certificate, or one issued for another host name.

Example - Validate the engine's certificate now (recommended):

var config = IronPdfConnectionConfiguration.RemoteServer("https://pdf-engine.mycompany.com");
config.AllowUntrustedServerCertificate = false;
Installation.ConnectToIronPdfHost(config);

Declaration

public Nullable<bool> AllowUntrustedServerCertificate { get; set; }

Property Value

Type	Description
System.Nullable<System.Boolean>

Remarks

• null (default): the certificate is accepted, as in earlier releases, and a warning is written once when it fails validation. A future release will change this default to reject such certificates.
• false: the certificate must pass the operating system's validation, otherwise the connection fails.
• true: any certificate is accepted, without a warning. Anyone between the application and the engine can then read or change the traffic, including documents and the license key. Prefer ServerCertificateValidationCallback to trust one specific self-signed certificate.

Ignored when ServerCertificateValidationCallback is set, for http:// addresses and for the other connection types.

ConnectionType

The nature of the client-to-host connection (e.g. executable, Docker, remote, etc.)

Declaration

public IronPdfConnectionType ConnectionType { get; set; }

Property Value

Type	Description
IronPdfConnectionType

CustomChannel

Custom gRPC Channel Grpc.Core.ChannelBase You can create a channel by either create a new Grpc.Core.Channel object (on .NET 6 and later IronPdf no longer brings the Grpc.Core package, so add a direct reference to it) or using Grpc.Net.Client.GrpcChannel.ForAddress(System.String) or else to custom your own gRPC channel

Declaration

public ChannelBase CustomChannel { get; set; }

Property Value

Type	Description
Grpc.Core.ChannelBase

Remarks

Setting CustomChannel will cause any configuration in this object (IronPdfConnectionConfiguration) to be ignored, except for Metadata

Docker

Default configuration for connecting to IronPdfEngine docker host service with a docker network service name ironpdfengine

Declaration

public static IronPdfConnectionConfiguration Docker { get; }

Property Value

Type	Description
IronPdfConnectionConfiguration

Executable

Default configuration for connecting to IronPdfEngine local service executable

Declaration

public static IronPdfConnectionConfiguration Executable { get; }

Property Value

Type	Description
IronPdfConnectionConfiguration

Host

Hostname or IP address

Declaration

public string Host { get; set; }

Property Value

Type	Description
System.String

LicenseKey

License key

Declaration

public string LicenseKey { get; set; }

Property Value

Type	Description
System.String

Metadata

Custom Grpc.Core.Metadata that will be sent with each gRPC request.

Declaration

public Metadata Metadata { get; set; }

Property Value

Type	Description
Grpc.Core.Metadata

Port

Host port

Declaration

public int Port { get; set; }

Property Value

Type	Description
System.Int32

ServerCertificateValidationCallback

Custom validation of the IronPdfEngine TLS certificate for a RemoteServer connection. Return true to accept the certificate. When set, it takes precedence over AllowUntrustedServerCertificate.

Example - Trust one self-signed certificate by its SHA-256 hash:

var config = IronPdfConnectionConfiguration.RemoteServer("https://pdf-engine.internal");
config.ServerCertificateValidationCallback = (request, certificate, chain, errors) =>
{
    if (errors == SslPolicyErrors.None) return true;
    if (certificate == null) return false;
    // SHA-256 of the certificate as uppercase hex without separators (the colons that
    // openssl x509 -fingerprint -sha256 prints removed). Works on .NET Framework and .NET.
    using (var sha256 = SHA256.Create())
        return BitConverter.ToString(sha256.ComputeHash(certificate.RawData)).Replace("-", "") == "3A1F...C9";
};
Installation.ConnectToIronPdfHost(config);

Declaration

public Func<HttpRequestMessage, X509Certificate2, X509Chain, SslPolicyErrors, bool> ServerCertificateValidationCallback { get; set; }

Property Value

Type	Description
System.Func<System.Net.Http.HttpRequestMessage, System.Security.Cryptography.X509Certificates.X509Certificate2, System.Security.Cryptography.X509Certificates.X509Chain, System.Net.Security.SslPolicyErrors, System.Boolean>

Remarks

Used only for https:// addresses of RemoteServer.

Methods

NetFrameworkChannel(String, Metadata)

For .Net Framework project. Creates a plaintext (insecure) gRPC channel to the given address. Using this custom gRPC Channel Grpc.Core.ChannelBase for .Net Framework project.
Since gRPC work differently in .Net Framework project. If this not working, please try remove http:// or https:// prefix in the address. Or try to create your own Grpc.Core.ChannelBase object and use WithCustomChannel(ChannelBase, Metadata)
On .NET 6 and later the channel is created with Grpc.Net.Client, so the Grpc.Core package is not required. The address uses the Grpc.Core target forms: host:port, [ipv6]:port, dns:///host:port, ipv4:address:port or ipv6:[address]:port; the port defaults to 443 as it did in Grpc.Core. An http:// or https:// address is also accepted on .NET 6 and later.

Declaration

public static IronPdfConnectionConfiguration NetFrameworkChannel(string address, Metadata metadata = null)

Parameters

Type	Name	Description
System.String	address	Example: 123.456.7.8:80
Grpc.Core.Metadata	metadata

Returns

Type	Description
IronPdfConnectionConfiguration

Exceptions

Type	Condition
System.ArgumentException	On .NET 6 and later, when the address is not one of the forms above (for example a unix socket or a list of several addresses).

RemoteServer(String, Metadata)

Custom configuration for connecting to IronPdfEngine remote server

Declaration

public static IronPdfConnectionConfiguration RemoteServer(string address, Metadata metadata = null)

Parameters

Type	Name	Description
System.String	address	Example: https://grpc.myironpdfengine.com
Grpc.Core.Metadata	metadata

Returns

Type	Description
IronPdfConnectionConfiguration

Remarks

For an https:// address, how the engine's TLS certificate is validated is set by AllowUntrustedServerCertificate and ServerCertificateValidationCallback.

WithCustomChannel(ChannelBase, Metadata)

Using your custom gRPC Channel Grpc.Core.ChannelBase
You can create a channel by either create a new Grpc.Core.Channel object (on .NET 6 and later IronPdf no longer brings the Grpc.Core package, so add a direct reference to it) or using Grpc.Net.Client.GrpcChannel.ForAddress(System.String) or else to custom your own gRPC channel

Declaration

public static IronPdfConnectionConfiguration WithCustomChannel(ChannelBase customChannel, Metadata metadata = null)

Parameters

Type	Name	Description
Grpc.Core.ChannelBase	customChannel	Custom gRPC Channel Grpc.Core.ChannelBase
Grpc.Core.Metadata	metadata

Returns

Type	Description
IronPdfConnectionConfiguration

See Also

IronPdfConnectionType