Comment configurer des serveurs proxy pour le rendu de PDF en C

Processus de travail minimal (3 étapes)

1. Installez IronPDF via NuGet : Install-Package IronPdf
2. Transmettez la chaîne de proxy en tant que troisième paramètre à RenderHtmlAsPdf
3. Format : http(s)://host:port ou http(s)://user:pass@host:port pour les proxys authentifiés

Comment passer un proxy à RenderHtmlAsPdf ?

Le paramètre Proxy est un string facultatif sur quatre signatures de méthode :

// 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

Lorsque ce paramètre est défini sur null (valeur par défaut), le moteur Chromium d'IronPDF se connecte directement aux ressources externes — feuilles de style, images, polices et fichiers JavaScript référencés dans votre code HTML. Lorsque vous fournissez une chaîne de proxy, toutes les requêtes HTTP/HTTPS provenant du moteur de rendu transitent par ce 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.co/rp.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.co/rp.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.co/rp.local:8443"
)

La chaîne de proxy prend en charge les schémas http:// et https://. Utilisez https:// lorsque le proxy lui-même nécessite un chiffrement TLS pour la connexion entre votre application et le serveur proxy. Le schéma fait ici référence à la connexion proxy, et non à la ressource finale — un proxy http:// peut toujours récupérer des ressources https:// via un tunneling CONNECT.

Les variantes de la méthode statique acceptent le même paramètre proxy, ce qui est utile pour les rendus ponctuels dans les applications console ou les tests unitaires :

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.co/rp.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.co/rp.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.co/rp.local:8080"
)

Important : il n'y a pas de propriété Proxy sur ChromePdfRenderOptions. Ne le cherchez pas là-bas. Le proxy est strictement un paramètre de méthode sur les surcharges RenderHtmlAsPdf et FromHtml.

Comment s'authentifier avec un proxy d'entreprise ?

La plupart des proxys Enterprise nécessitent des identifiants. Vous les intégrez directement dans l'URL du proxy en utilisant le format http(s)://username:password@host:port :

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.co/rp.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.co/rp.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.co/rp.local:8080"

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

Encodez les caractères spéciaux des mots de passe en URL. Si votre mot de passe contient @, #, :, / ou d'autres caractères URI réservés, ceux-ci doivent être encodés en pourcentage. Encodages courants :

Utilisez Uri.EscapeDataString() pour encoder le mot de passe par programmation :

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

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.co/rp.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.co/rp.local:8080"

Ne confondez pas l'authentification par proxy avec l'authentification sur une page web. Les propriétés ChromeHttpLoginCredentials.Net/workUsername et NetworkPassword s'authentifient auprès de la page web en cours de rendu (NTLM/Negotiate avec un site web), et non auprès d'un serveur proxy. Pour l'authentification par proxy, les identifiants doivent être intégrés à la chaîne d'URL du proxy, comme indiqué ci-dessus.

Comment rendre les URL derrière un proxy ?

RenderUrlToPdf n'accepte pas de paramètre proxy. Il s'agit d'un choix de conception délibéré de l'API — NavigateUrl navigue dans Chromium vers une URL, et la configuration du proxy pour cette navigation est gérée différemment de celle pour le chargement des ressources lors du rendu HTML.

Solution recommandée : récupérez vous-même le code HTML à l'aide de HttpClient configuré avec un HttpProxy, puis transmettez la chaîne HTML à RenderHtmlAsPdf avec le paramètre proxy (afin que les ressources référencées — images, CSS, polices — transitent également par le proxy).

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

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.co/rp.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.co/rp/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.co/rp.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.co/rp.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.co/rp/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.co/rp.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.co/rp.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.co/rp/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.co/rp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using

Le paramètre baseUrlOrPath est défini sur l'URL cible d'origine afin que les chemins relatifs dans le code HTML récupéré (<img src="/images/logo.png">, <link href="/css/styles.css">) soient résolus correctement. Le paramètre proxy garantit que ces requêtes de ressources transitent par le proxy lors du rendu.

Ce modèle fonctionne également avec les pages protégées par une authentification : configurez HttpClient avec les cookies ou les en-têtes appropriés avant la récupération, puis transmettez le code HTML authentifié à IronPDF. Le guide pratique sur les en-têtes de requêtes HTTP couvre la configuration des en-têtes pour les requêtes authentifiées.

Si la page s'appuie sur JavaScript pour son rendu (SPAs, tableaux de bord React, applications Angular), le code HTML récupéré ne contiendra que la structure initiale — le rendu côté client ne s'exécutera pas lors de la récupération HttpClient. Dans ces cas, vous disposez de deux options : définir des variables d'environnement au niveau du système HTTPS_PROXY au niveau du système (abordées dans la section suivante) afin que RenderUrlAsPdf() passe par le proxy au niveau du système d'exploitation, ou d'utiliser un navigateur sans interface graphique pour récupérer le code HTML entièrement rendu avant de le transmettre à RenderHtmlAsPdf().

Comment configurer un proxy dans des conteneurs Docker ?

Dans les environnements conteneurisés, vous préférerez peut-être une configuration de proxy au niveau du système plutôt que des paramètres par méthode. Le moteur Chromium d'IronPDF respecte les variables d'environnement standard HTTP_PROXY et HTTPS_PROXY que les conteneurs Linux utilisent pour le routage du trafic sortant.

Définissez ces paramètres dans votre Dockerfile :

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

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

# 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"]

Une fois ces variables d'environnement définies, vous pouvez appeler RenderHtmlAsPdf sans le paramètre proxy — Chromium récupère automatiquement la configuration au niveau du système :

// 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)

RenderHtmlAsPdf() est important pour les ressources internes. Sans cela, les requêtes adressées aux services internes (tels qu'un serveur CSS local ou un CDN d'images fonctionnant au sein de votre cluster Kubernetes) passeraient inutilement par le proxy. Séparez par des virgules les noms d'hôte et les domaines qui doivent contourner le proxy.

Si vous avez besoin à la fois d'un proxy au niveau du système pour le trafic général et d'un proxy différent pour des rendus spécifiques, le paramètre de méthode a priorité sur la variable d'environnement. Cela vous permet de contrôler le rendu au cas par cas lorsque cela est nécessaire.

Comment gérez-vous les proxys dans les pipelines CI/CD ?

Les runners CI/CD dans les réseaux d'entreprise sont souvent placés derrière des proxys. Transmettez l'URL du proxy sous forme de variable de build ou de secret — ne codez jamais en dur les identifiants dans le contrôle de version.

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 (pipeline déclaratif) :

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

Dans les trois cas, Chromium lit automatiquement les variables d'environnement. Si vous préférez un contrôle explicite, lisez l'URL du proxy à partir de l'environnement et transmettez-la en tant que paramètre de la méthode :

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



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

Comment résoudre les problèmes liés aux proxys ?

Erreurs de délai d'expiration : les proxys d'entreprise ajoutent de la latence. Augmentez le délai d'expiration du rendu par rapport à la valeur par défaut de 60 secondes :

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

Il s'agit de la propriété RenderTimeout — elle contrôle la durée pendant laquelle Chromium attend le chargement de la page et la récupération des ressources combinés. Si votre proxy ajoute 5 à 10 secondes de latence par requête et que la page charge plus de 20 ressources externes, 60 secondes pourraient ne pas suffire.

Interception SSL (proxys MITM) : de nombreux proxys d'entreprise déchiffrent et rechiffrent le trafic HTTPS à l'aide d'un certificat CA racine d'entreprise. Chromium rejette ces connexions car il ne fait pas confiance à l'autorité de certification d'entreprise par défaut. Deux solutions :

1. Installez le certificat CA de l'entreprise dans le magasin racine de confiance du conteneur ou de l'hôte. Sous Linux : copiez le contenu de .crt vers /usr/local/share/ca-certificates/ et exécutez update-ca-certificates.
2. En phase de développement uniquement, vous pouvez désactiver la validation des certificats — mais ne le faites jamais en production. L'approche la plus sûre consiste toujours à installer le certificat approprié.

Authentification NTLM : le format en ligne user:pass@host prend en charge l'authentification proxy Basic et Digest. Le protocole NTLM (couramment utilisé dans les entreprises centrées sur Windows) n'est pas pris en charge via la chaîne d'URL du proxy. La solution consiste à exécuter un proxy de redirection NTLM vers Basic local, tel que CNTLM, sur l'hôte ou en tant que conteneur sidecar. Configurez CNTLM avec vos identifiants NTLM, puis pointez IronPDF vers http://localhost:3128 (le port par défaut de CNTLM).

PDF vide ou ressources manquantes : si le PDF s'affiche mais que les images/CSS sont manquantes, votre code HTML fait référence à des ressources que le proxy bloque ou qui nécessitent un chemin de proxy différent. Vérifiez que le paramètre baseUrlOrPath est correctement résolu via le proxy, et consultez les journaux d'accès du proxy pour détecter d'éventuelles réponses 403 ou 407.

Contournement du proxy pour les ressources locales : si votre code HTML fait référence à un mélange de ressources locales (images intégrées, CSS en ligne) et de ressources distantes (polices CDN, scripts externes), le proxy n'a besoin de traiter que les requêtes distantes. Définissez baseUrlOrPath sur un répertoire local pour les ressources du système de fichiers, et laissez le proxy gérer uniquement les requêtes réseau. Cela évite de faire passer inutilement les lectures de fichiers locaux par le proxy.

Diagnostic de la connectivité : pour vérifier que votre chaîne de proxy est correcte avant de l'utiliser avec IronPDF, testez-la d'abord avec une simple requête HttpClient :

var proxy = new WebProxy("http://proxy.co/rp.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.Co/ntent.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

var proxy = new WebProxy("http://proxy.co/rp.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.Co/ntent.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

Imports System.Net.Http
Imports System.Net

Dim proxy As New WebProxy("http://proxy.co/rp.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

Si cela fonctionne mais qu'IronPDF échoue toujours, le problème provient probablement d'une interception SSL ou d'une incompatibilité de protocole entre votre proxy et le tunneling CONNECT de Chromium. Vérifiez si le proxy prend en charge HTTP CONNECT pour les ressources HTTPS — certains proxys nécessitent une configuration explicite pour autoriser le tunneling.

Prochaines étapes