How to Configure Proxy Servers for PDF Rendering in C#

Minimal Workflow (3 Steps)

1. Install IronPDF via NuGet: Install-Package IronPdf
2. Pass the proxy string as the third parameter to RenderHtmlAsPdf()
3. Format: http(s)://host:port or http(s)://user:pass@host:port for authenticated proxies

How Do You Pass a Proxy to RenderHtmlAsPdf?

The Proxy parameter is an optional string on four method signatures:

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

' Instance methods
Function RenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Proxy As String = Nothing) As PdfDocument
End Function

Function RenderHtmlAsPdf(Html As String, Optional BaseUrl As Uri = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

' Static methods
Shared Function StaticRenderHtmlAsPdf(Html As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

Shared Function StaticRenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

When this parameter is null (the default), IronPDF's Chromium engine connects directly to external resources — stylesheets, images, fonts, and JavaScript files referenced in your HTML. When you provide a proxy string, all HTTP/HTTPS requests from the rendering engine route through that proxy.

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.corp.local:8443"
);

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.corp.local:8443"
);

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Direct connection (default — no proxy)
Dim pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>")

' Through an unauthenticated proxy
Dim pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath:=Nothing,
    proxy:="http://squid.internal:3128"
)

' Using the Uri overload
Dim pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl:=New Uri("https://assets.example.com/"),
    proxy:="https://proxy.corp.local:8443"
)

The proxy string supports both http:// and https:// schemes. Use https:// when the proxy itself requires TLS encryption for the connection between your application and the proxy server. The scheme here refers to the proxy connection, not the final resource — an http:// proxy can still fetch https:// resources via CONNECT tunneling.

The static method variants accept the same proxy parameter, which is useful for one-off renders in console applications or unit tests:

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.local:8080"
);

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.local:8080"
);

' Static render with proxy — no renderer instance needed
Dim pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options:=Nothing,
    proxy:="http://proxy.corp.local:8080"
)

Important: There is no ProxyAddress property on ChromePdfRenderOptions. Do not look for it there. The proxy is strictly a method parameter on RenderHtmlAsPdf and StaticRenderHtmlAsPdf overloads.

How Do You Authenticate with a Corporate Proxy?

Most enterprise proxies require credentials. You embed them directly in the proxy URL using the http(s)://username:password@host:port format:

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

Dim proxyWithAuth As String = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: "C:\templates\assets\",
    proxy:=proxyWithAuth
)
pdf.SaveAs("report.pdf")

URL-encode special characters in passwords. If your password contains @, #, :, /, or other reserved URI characters, they must be percent-encoded. Common encodings:

Use Uri.EscapeDataString() to encode the password programmatically:

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";

Imports System

Dim rawPassword As String = "P@ssw0rd!"
Dim encoded As String = Uri.EscapeDataString(rawPassword) ' "P%40ssw0rd%21"
Dim proxy As String = $"http://svc-account:{encoded}@proxy.corp.local:8080"

Do not confuse proxy authentication with web page authentication. The ChromeHttpLoginCredentials.NetworkUsername and NetworkPassword properties authenticate against the web page being rendered (NTLM/Negotiate with a website), not against a proxy server. For proxy auth, the credentials go in the proxy URL string as shown above.

How Do You Render URLs Behind a Proxy?

RenderUrlAsPdf() does not accept a proxy parameter. This is a deliberate API design choice — RenderUrlAsPdf navigates Chromium to a URL, and the proxy configuration for that navigation is handled differently than for resource loading during HTML rendering.

The recommended workaround: fetch the HTML yourself using HttpClient configured with a WebProxy, then pass the HTML string to RenderHtmlAsPdf() with the proxy parameter (so that referenced assets — images, CSS, fonts — also route through the proxy).

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.corp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.corp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

Imports IronPdf
Imports System.Net
Imports System.Net.Http

' Step 1: Configure HttpClient with the corporate proxy
Dim proxy As New WebProxy("http://proxy.corp.local:8080") With {
    .Credentials = New NetworkCredential("svc-account", "P@ssw0rd!")
}

Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using httpClient As New HttpClient(handler)
    ' Step 2: Fetch the HTML from the target URL
    Dim targetUrl As String = "https://dashboard.internal.corp/quarterly-report"
    Dim html As String = Await httpClient.GetStringAsync(targetUrl)

    ' Step 3: Render the fetched HTML, with the proxy for asset loading
    Dim renderer As New ChromePdfRenderer()

    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
        html,
        baseUrlOrPath:=targetUrl,  ' Resolves relative asset paths against the original URL
        proxy:="http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using

The baseUrlOrPath parameter is set to the original target URL so that relative paths in the fetched HTML (<img src="/images/logo.png">, <link href="/css/styles.css">) resolve correctly. The proxy parameter ensures those asset requests route through the proxy during rendering.

This pattern also works with pages behind authentication — configure the HttpClient with the appropriate cookies or headers before fetching, then pass the authenticated HTML to IronPDF. The HTTP request header how-to covers header configuration for authenticated requests.

If the page relies on JavaScript for rendering (SPAs, React dashboards, Angular apps), the fetched HTML will only contain the initial shell — client-side rendering will not execute during the HttpClient fetch. For those cases, you have two options: set system-level HTTP_PROXY/HTTPS_PROXY environment variables (covered in the next section) so that RenderUrlAsPdf() routes through the proxy at the OS level, or use a headless browser to fetch the fully-rendered HTML before passing it to RenderHtmlAsPdf().

How Do You Configure Proxy in Docker Containers?

In containerized environments, you may prefer system-level proxy configuration over per-method parameters. IronPDF's Chromium engine respects the standard HTTP_PROXY and HTTPS_PROXY environment variables that Linux containers use for outbound traffic routing.

Set these in your Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# System-level proxy for all outbound HTTP/HTTPS traffic
ENV HTTP_PROXY=http://proxy.corp.local:8080
ENV HTTPS_PROXY=http://proxy.corp.local:8080
ENV NO_PROXY=localhost,127.0.0.1,.internal.corp

# Install IronPDF dependencies (fonts, etc.)
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libc6-dev \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

With these environment variables set, you can call RenderHtmlAsPdf() without the proxy parameter — Chromium picks up the system-level configuration automatically:

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

' No proxy parameter needed — Chromium uses HTTP_PROXY env var
Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)

NO_PROXY is important for internal resources. Without it, requests to internal services (like a local CSS server or image CDN running inside your Kubernetes cluster) would unnecessarily route through the proxy. Comma-separate the hostnames and domains that should bypass the proxy.

If you need both system-level proxy for general traffic and a different proxy for specific renders, the method parameter takes precedence over the environment variable. This gives you per-render control when needed.

For Kubernetes deployments, inject proxy configuration via ConfigMaps or environment variables in the pod spec rather than hardcoding them in the Dockerfile. This makes the same container image work across environments with different proxy configurations:

# Kubernetes pod spec
spec:
  containers:
    - name: pdf-generator
      image: myregistry/pdf-service:latest
      env:
        - name: HTTP_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: http-proxy
        - name: HTTPS_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: https-proxy
        - name: NO_PROXY
          value: "localhost,127.0.0.1,.internal.corp"

# Kubernetes pod spec
spec:
  containers:
    - name: pdf-generator
      image: myregistry/pdf-service:latest
      env:
        - name: HTTP_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: http-proxy
        - name: HTTPS_PROXY
          valueFrom:
            configMapKeyRef:
              name: proxy-config
              key: https-proxy
        - name: NO_PROXY
          value: "localhost,127.0.0.1,.internal.corp"

When both the environment variable and the method parameter are present, the method parameter takes precedence. This gives you a layered configuration model: set the default proxy at the infrastructure level, and override it per-render when specific requests need a different route.

How Do You Handle Proxy in CI/CD Pipelines?

CI/CD runners in corporate networks frequently sit behind proxies. Pass the proxy URL as a build variable or secret — never hardcode credentials in source control.

GitHub Actions:

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.CORP_PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.CORP_PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

Azure DevOps:

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

Jenkins (Declarative Pipeline):

environment {
    HTTP_PROXY  = credentials('corp-proxy-url')
    HTTPS_PROXY = credentials('corp-proxy-url')
}

In all three cases, Chromium reads the environment variables automatically. If you prefer explicit control, read the proxy URL from the environment and pass it as the method parameter:

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

Option Strict On
Option Infer On

Dim proxy As String = Environment.GetEnvironmentVariable("HTTPS_PROXY")
Dim pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath:=Nothing, proxy:=proxy)

How Do You Troubleshoot Proxy Issues?

Timeout errors: Corporate proxies add latency. Increase the render timeout from the 60-second default:

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

This is the ChromePdfRenderOptions.Timeout property — it controls how long Chromium waits for page load and resource fetching combined. If your proxy adds 5–10 seconds of latency per request, and the page loads 20+ external resources, 60 seconds may not be enough.

SSL interception (MITM proxies): Many corporate proxies decrypt and re-encrypt HTTPS traffic using a corporate root CA certificate. Chromium rejects these connections because it does not trust the corporate CA by default. Two solutions:

1. Install the corporate CA certificate in the container or host's trusted root store. On Linux: copy the .crt to /usr/local/share/ca-certificates/ and run update-ca-certificates.
2. In development only, you can disable certificate validation — but never do this in production. The safer approach is always to install the proper certificate.

NTLM authentication: The inline user:pass@host format supports Basic and Digest proxy authentication. NTLM (common in Windows-centric enterprises) is not supported through the proxy URL string. The workaround is to run a local NTLM-to-Basic forwarding proxy like CNTLM on the host or as a sidecar container. Configure CNTLM with your NTLM credentials, then point IronPDF at http://localhost:3128 (CNTLM's default port).

Blank PDF or missing assets: If the PDF renders but images/CSS are missing, your HTML references resources that the proxy blocks or that require a different proxy path. Verify that the baseUrlOrPath parameter resolves correctly through the proxy, and check the proxy's access logs for 403 or 407 responses.

Proxy bypass for local assets: If your HTML references a mix of local assets (bundled images, inline CSS) and remote resources (CDN fonts, external scripts), the proxy only needs to handle the remote requests. Set baseUrlOrPath to a local directory for file-system assets, and let the proxy handle only the network requests. This avoids routing local file reads through the proxy unnecessarily.

Diagnosing connectivity: To verify your proxy string is correct before using it with IronPDF, test it with a simple HttpClient request first:

var proxy = new WebProxy("http://proxy.corp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

var proxy = new WebProxy("http://proxy.corp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

Imports System
Imports System.Net
Imports System.Net.Http

Dim proxy As New WebProxy("http://proxy.corp.local:8080")
Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using client As New HttpClient(handler)
    Dim response = Await client.GetAsync("https://httpbin.org/ip")
    Console.WriteLine(Await response.Content.ReadAsStringAsync())
    ' Should return the proxy's external IP, not your machine's IP
End Using

If this succeeds but IronPDF still fails, the issue is likely SSL interception or a protocol mismatch between your proxy and Chromium's CONNECT tunneling. Check whether the proxy supports HTTP CONNECT for HTTPS resources — some proxies require explicit configuration to allow tunneling.

Next Steps

Proxy support in IronPDF is a method parameter on RenderHtmlAsPdf() — pass the proxy string, and the Chromium engine routes all HTTP traffic through it. For RenderUrlAsPdf() scenarios, fetch the HTML with HttpClient and a WebProxy first. For containers and CI/CD, system-level HTTP_PROXY/HTTPS_PROXY environment variables give you infrastructure-level control without code changes.

Explore the logins and authentication how-to for web page authentication (distinct from proxy auth), the HTTP request header guide for custom headers, and the rendering options reference for timeout and performance tuning.

View licensing options starting at $749. The ChromePdfRenderer API reference documents every method overload and the ChromePdfRenderOptions reference covers all configurable properties.