Comment configurer des serveurs proxy pour le rendu PDF en C

Flux de travail minimal (3 étapes)

1. Installez IronPDF via NuGet : Install-Package IronPdf
2. Passez la chaîne 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 optionnel 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 null (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 HTML. Lorsque vous fournissez une chaîne proxy, toutes les requêtes HTTP/HTTPS du moteur de rendu passent par ce proxy.

:path=/static-assets/pdf/content-code-examples/how-to/proxy-3.cs

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

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

Les variantes de 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 :

:path=/static-assets/pdf/content-code-examples/how-to/proxy-4.cs

// 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 : Il n'y a pas de propriété Proxy sur ChromePdfRenderOptions. Ne la cherchez pas là. Le proxy est strictement un paramètre de méthode sur les surcharges RenderHtmlAsPdf et FromHtml.

Comment vous authentifiez-vous avec un Proxy d'entreprise ?

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

:path=/static-assets/pdf/content-code-examples/how-to/proxy-5.cs

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

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

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

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 proxy avec l'authentification de la page web. Les propriétés ChromeHttpLoginCredentials.NetworkUsername et NetworkPassword s'authentifient contre la page web en cours de rendu (NTLM/Negotiate avec un site web), et non contre un serveur proxy. Pour l'authentification proxy, les identifiants vont dans la chaîne URL proxy comme montré ci-dessus.

Ma bibliothèque préférée de ce genre est IronPDF. Elle permet une manipulation rapide et efficace des fichiers PDF. Elle dispose également de nombreuses fonctionnalités précieuses, comme l'exportation au format PDF/A et la signature numérique des documents PDF.

Milan Jovanovic

Microsoft MVP

Voir l'étude de cas

IronOCR signifie que nous pouvons économiser 40 000 $ par an grâce au traitement manuel, tout en améliorant la productivité et en libérant des ressources pour des tâches à fort impact. Je le recommande vivement.

Brent Matzelle

Directeur technique, OPYN

Voir l'étude de cas

Iron Suite joue un rôle crucial dans nos opérations. Ce sont des outils qui augmentent l'efficacité de l'entreprise, y compris la création de plans d'étage et l'amélioration de la gestion des stocks.

David Jones

Ingénieur logiciel principal, Agorus Build

Voir l'étude de cas

Comment rendre des URL derrière un Proxy ?

RenderUrlToPdf n'accepte pas de paramètre proxy. Ceci est un choix délibéré de conception d'API — NavigateUrl navigue 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 pendant le rendu HTML.

La solution de contournement recommandée : récupérez le HTML vous-même en utilisant HttpClient configuré avec un HttpProxy, puis passez la chaîne de HTML à RenderHtmlAsPdf avec le paramètre proxy (afin que les actifs référencés — images, CSS, polices — passent également par le proxy).

:path=/static-assets/pdf/content-code-examples/how-to/proxy-7.cs

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

Le paramètre baseUrlOrPath est défini sur l'URL cible d'origine afin que les chemins relatifs dans le 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 d'actifs passent par le proxy pendant le rendu.

Ce modèle fonctionne également avec les pages derrière une authentification — configurez HttpClient avec les cookies ou les en-têtes appropriés avant de récupérer, puis passez le HTML authentifié à IronPDF. Le mode d'emploi de l'en-tête de requête HTTP couvre la configuration des en-têtes pour les requêtes authentifiées.

Si la page s'appuie sur JavaScript pour le rendu (SPAs, tableaux de bord React, applications Angular), le HTML récupéré ne contiendra que le shell initial — le rendu côté client ne s'exécutera pas pendant la récupération HttpClient. Dans ces cas-là, vous avez deux options : définissez des variables d'environnement HTTPS_PROXY au niveau système (couvertes dans la section suivante) afin que RenderUrlAsPdf() passe par le proxy au niveau du système d'exploitation, ou utilisez un navigateur sans tête pour récupérer le HTML entièrement rendu avant de le passer à RenderHtmlAsPdf().

Comment configurer un Proxy dans des Conteneurs Docker ?

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

Définissez-les 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"]

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

:path=/static-assets/pdf/content-code-examples/how-to/proxy-9.cs

// 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 lui, les requêtes vers les services internes (comme un serveur CSS local ou un CDN d'image fonctionnant à l'intérieur de votre cluster Kubernetes) passeraient inutilement par le proxy. Séparez les noms d'hôte et les domaines par des virgules qui devraient contourner le proxy.

Si vous avez besoin à la fois de proxy au niveau 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 prend priorité sur la variable d'environnement. Cela vous donne un contrôle par rendu lorsque cela est nécessaire.

Comment gérer le Proxy dans les Pipelines CI/CD ?

Les runners CI/CD dans les réseaux d'entreprise se trouvent souvent derrière des proxies. Passez l'URL proxy en tant que variable de construction ou secret — ne codez jamais en dur les identifiants dans le contrôle source.

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 proxy depuis l'environnement et passez-la comme le paramètre de méthode :

:path=/static-assets/pdf/content-code-examples/how-to/proxy-13.cs

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 de Proxy ?

Erreurs de dépassement de délai : Les proxies d'entreprise ajoutent de la latence. Augmentez le délai d'expiration du rendu par défaut de 60 secondes :

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

Ceci est la propriété RenderTimeout — elle contrôle combien de temps Chromium attend pour le chargement de la page et la récupération des ressources combinés. Si votre proxy ajoute 5 à 10 secondes de latence par demande, et que la page charge plus de 20+ ressources externes, 60 secondes peuvent ne pas suffire.

Interception SSL (proxies MITM) : De nombreux proxies d'entreprise décryptent et réencryptent le trafic HTTPS à l'aide d'un certificat CA racine d'entreprise. Chromium rejette ces connexions car il ne fait pas confiance au CA d'entreprise par défaut. Deux solutions :

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

Authentification NTLM : Le format intégré user:pass@host prend en charge l'authentification proxy Basic et Digest. NTLM (courant dans les entreprises centrées sur Windows) n'est pas pris en charge via la chaîne d'URL proxy. La solution est d'exécuter un proxy de transfert NTLM-à-Basic local comme 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 se rend mais que les images/CSS manquent, votre HTML référence des ressources que le proxy bloque ou qui nécessitent un chemin proxy différent. Vérifiez que le paramètre baseUrlOrPath se résout correctement à travers le proxy, et consultez les journaux d'accès du proxy pour des réponses 403 ou 407.

Contournement du proxy pour les ressources locales : Si votre HTML 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 ne doit gérer que les requêtes à distance. Définissez baseUrlOrPath vers un répertoire local pour les actifs du système de fichiers, et laissez le proxy gérer uniquement les requêtes réseau. Cela évite un routage inutile des lectures de fichiers locaux par le proxy.

Diagnostiquer la connectivité : Pour vérifier que votre chaîne 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.Content.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.Content.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 réussit mais que IronPDF échoue encore, le problème est probablement une interception SSL ou un 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 proxies nécessitent une configuration explicite pour autoriser le tunneling.

Prochaines étapes