Wie konfiguriere ich Proxy-Server für das PDF-Rendering in C

Minimal Workflow (3 Schritte)

1. Installieren Sie IronPDF über NuGet: Install-Package IronPdf
2. Übergeben Sie den Proxy-String als dritten Parameter an RenderHtmlAsPdf
3. Format: http(s)://host:port oder http(s)://user:pass@host:port für authentifizierte Proxys

Wie übergibt man einen Proxy an RenderHtmlAsPdf?

Der Proxy-Parameter ist ein optionaler string bei vier Methodensignaturen:

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

Wenn dieser Parameter null (der Standard) ist, verbindet sich die Chromium-Engine von IronPDF direkt mit externen Ressourcen — Stylesheets, Bilder, Schriftarten und JavaScript-Dateien, die in Ihrem HTML referenziert werden. Wenn Sie einen Proxy-String angeben, werden alle HTTP/HTTPS-Anfragen der Rendering-Engine über diesen Proxy geleitet.

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

Der Proxy-String unterstützt sowohl http:// als auch https://-Schemata. Verwenden Sie https://, wenn der Proxy selbst TLS-Verschlüsselung für die Verbindung zwischen Ihrer Anwendung und dem Proxy-Server erfordert. Das Schema bezieht sich hier auf die Proxy-Verbindung, nicht auf die endgültige Ressource — ein http://-Proxy kann trotzdem über CONNECT-Tunneling https://-Ressourcen abrufen.

Die Varianten mit statischer Methode akzeptieren denselben Proxy-Parameter, was für einmalige Renderings in Konsolenanwendungen oder Unittests nützlich ist:

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

Wichtig: Es gibt keine Proxy-Eigenschaft auf ChromePdfRenderOptions. Suchen Sie dort nicht danach. Der Proxy ist strikt ein Methodenparameter bei RenderHtmlAsPdf und FromHtml-Überladungen.

Wie authentifizieren Sie sich bei einem Unternehmensproxy?

Die meisten Unternehmens-Proxys erfordern Anmeldedaten. Sie betten sie direkt in die Proxy-URL ein, indem Sie das http(s)://username:password@host:port-Format verwenden:

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

URL-encodieren Sie Sonderzeichen in Passwörtern. Wenn Ihr Passwort @, #, :, / oder andere reservierte URI-Zeichen enthält, müssen sie prozent-kodiert werden. Häufige Kodierungen:

Verwenden Sie Uri.EscapeDataString(), um das Passwort programmgesteuert zu kodieren:

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"

Verwechseln Sie nicht die Proxy-Authentifizierung mit der Webseiten-Authentifizierung. Die ChromeHttpLoginCredentials.NetworkUsername- und NetworkPassword-Eigenschaften authentifizieren sich gegen die Webseite, die gerendert wird (NTLM/Negotiate mit einer Webseite), nicht gegen einen Proxy-Server. Für die Proxy-Authentifizierung gehen die Anmeldedaten in die Proxy-URL-Zeichenfolge, wie oben gezeigt.

Meine Lieblingsbibliothek dieser Art ist IronPDF. Es ermöglicht eine schnelle und effiziente Bearbeitung von PDF-Dateien. Es verfügt auch über viele wertvolle Funktionen, wie das Exportieren in das PDF/A-Format und das digitale Signieren von PDF-Dokumenten.

Milan Jovanovic

Microsoft MVP

Fallstudie ansehen

IronOCR bedeutet, dass wir jährlich 40.000 $ durch manuelle Verarbeitung einsparen können, während die Produktivität gesteigert wird und Ressourcen für wichtige Aufgaben freigesetzt werden. Ich würde es sehr empfehlen.

Brent Matzelle

Technischer Leiter, OPYN

Fallstudie ansehen

Die Iron Suite spielt eine entscheidende Rolle in unseren Operationen. Diese Werkzeuge erhöhen die Effizienz im gesamten Unternehmen, einschließlich der Erstellung von Grundrissen und der Verbesserung des Bestandsmanagements.

David Jones

Leitender Software-Ingenieur, Agorus Build

Fallstudie ansehen

Wie Verarbeiten Sie URLs hinter einem Proxy?

RenderUrlToPdf akzeptiert keinen Proxy-Parameter. Dies ist eine bewusste API-Design-Entscheidung — NavigateUrl navigiert Chromium zu einer URL, und die Proxy-Konfiguration für diese Navigation wird anders gehandhabt als beim Ressourcenladen während des HTML-Renderings.

Der empfohlene Workaround: Holen Sie das HTML selbst mit HttpClient, das mit einem HttpProxy konfiguriert ist, und übergeben Sie dann den HTML-String an RenderHtmlAsPdf mit dem Proxy-Parameter (so dass referenzierte Assets — Bilder, CSS, Schriftarten — auch über den Proxy geleitet werden).

: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

Der baseUrlOrPath-Parameter ist auf die ursprüngliche Ziel-URL eingestellt, so dass relative Pfade im abgerufenen HTML (<img src="/images/logo.png">, <link href="/css/styles.css">) korrekt aufgelöst werden. Der proxy-Parameter stellt sicher, dass diese Asset-Anfragen während des Renderings über den Proxy geleitet werden.

Dieses Muster funktioniert auch mit Seiten hinter Authentifizierung — konfigurieren Sie die HttpClient mit den geeigneten Cookies oder Headern, bevor Sie holen, und übergeben Sie dann das authentifizierte HTML an IronPDF. Das HTTP-Anfrage-Header How-to behandelt die Header-Konfiguration für authentifizierte Anfragen.

Wenn die Seite auf JavaScript für das Rendering angewiesen ist (SPAs, React-Dashboards, Angular-Apps), enthält das abgerufene HTML nur die anfängliche Hülle — die clientseitige Rendering wird während der HttpClient-Abholung nicht ausgeführt. Für diese Fälle haben Sie zwei Optionen: Setzen Sie systemweite HTTPS_PROXY-Umgebungsvariablen (im nächsten Abschnitt behandelt), so dass RenderUrlAsPdf() auf Betriebssystemebene über den Proxy geleitet wird, oder verwenden Sie einen headless Browser, um das vollständig gerenderte HTML abzurufen, bevor Sie es an RenderHtmlAsPdf() übergeben.

Wie Konfigurieren Sie einen Proxy in Docker-Containern?

In containerisierten Umgebungen bevorzugen Sie möglicherweise eine systemweite Proxy-Konfiguration gegenüber einem pro-Methode-Parameter. Die Chromium-Engine von IronPDF respektiert die Standard-HTTP_PROXY und HTTPS_PROXY-Umgebungsvariablen, die Linux-Container für die ausgehende Verkehrsführung verwenden.

Setzen Sie diese in Ihrer 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"]

Mit diesen Umgebungsvariablen können Sie RenderHtmlAsPdf ohne den Proxy-Parameter aufrufen — Chromium übernimmt die systemweite Konfiguration automatisch:

: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() ist wichtig für interne Ressourcen. Ohne es würden Anfragen an interne Dienste (wie einen lokalen CSS-Server oder ein Bild-CDN, das innerhalb Ihres Kubernetes-Clusters läuft) unnötigerweise durch den Proxy geleitet. Trennen Sie die Hosts und Domains, die den Proxy umgehen sollen, mit einem Komma.

Wenn Sie sowohl einen systemweiten Proxy für allgemeinen Traffic als auch einen anderen Proxy für spezifische Darstellungen benötigen, hat der Methodenparameter Vorrang vor der Umgebungvariable. Dies gibt Ihnen die Kontrolle pro-Darstellung, wenn erforderlich.

Wie Verarbeiten Sie Proxys in CI/CD-Pipelines?

CI/CD-Runner in Unternehmensnetzwerken sitzen häufig hinter Proxys. Übergaben Sie die Proxy-URL als Build-Variable oder Geheimnis — nie Anmeldedaten im Quellcode hartkodieren.

GitHub-Aktionen:

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 (Deklarative Pipeline):

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

In allen drei Fällen liest Chromium automatisch die Umgebungvariablen. Wenn Sie eine explizite Kontrolle bevorzugen, lesen Sie die Proxy-URL aus der Umgebung und übergeben sie als Methodenparameter:

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

Wie Beheben Sie Proxy-Probleme?

Timeout-Fehler: Unternehmensproxies erhöhen die Latenz. Erhöhen Sie den Darstellungs-Timeout von dem Standardwert von 60 Sekunden:

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

Dies ist die RenderTimeout-Eigenschaft — sie steuert, wie lange Chromium auf das Laden der Seite und das Abrufen von Ressourcen im Kombinierten wartet. Wenn Ihr Proxy 5–10 Sekunden Latenz pro Anfrage hinzufügt und die Seite über 20 externe Ressourcen lädt, reichen 60 Sekunden möglicherweise nicht aus.

SSL-Abfangschnitte (MITM-Proxies): Viele Unternehmensproxies entschlüsseln und verschlüsseln HTTPS-Verkehr mittels eines Unternehmens-Root-CA-Zertifikats. Chromium lehnt diese Verbindungen ab, da es die Unternehmens-CA standardmäßig nicht vertraut. Zwei Lösungen:

1. Installieren Sie das Unternehmens-CA-Zertifikat im Container oder im Trusted Root Store des Hosts. Unter Linux: Kopieren Sie die .crt nach /usr/local/share/ca-certificates/ und führen Sie update-ca-certificates aus.
2. Nur in der Entwicklung, können Sie die Zertifikatsvalidierung deaktivieren — aber niemals in Produktion. Der sicherere Ansatz ist immer, das richtige Zertifikat zu installieren.

NTLM-Authentifizierung: Das Inline-user:pass@host-Format unterstützt Basic und Digest Proxy-Authentifizierung. NTLM (häufig in Windows-zentrierten Unternehmen) wird nicht durch die Proxy-URL-Zeichenfolge unterstützt. Die Umgehungsmöglichkeit ist, einen lokalen NTLM-zu-Basic-Forwarding-Proxy wie CNTLM auf dem Host oder als sidecar-container auszuführen. Konfigurieren Sie CNTLM mit Ihren NTLM-Anmeldedaten und richten Sie IronPDF auf http://localhost:3128 (den Standardport von CNTLM) aus.

Leere PDF oder fehlende Ressourcen: Wenn das PDF dargestellt wird, aber Bilder/CSS fehlen, verweist Ihr HTML auf Ressourcen, die der Proxy blockiert oder die einen anderen Proxy-Pfad erfordern. Stellen Sie sicher, dass der baseUrlOrPath-Parameter korrekt über den Proxy aufgelöst wird, und überprüfen Sie die Zugriffsprotokolle des Proxys auf 403- oder 407-Antworten.

Proxy-Umgehung für lokale Assets: Wenn Ihr HTML eine Mischung aus lokalen Assets (gebündelte Bilder, Inline-CSS) und remote Ressourcen (CDN-Schriften, externe Skripte) referenziert, muss der Proxy nur die Remote-Anfragen verarbeiten. Setzen Sie baseUrlOrPath auf ein lokales Verzeichnis für Dateisystem-Assets und lassen Sie den Proxy nur die Netzwerkabfragen verwalten. Dies vermeidet, dass lokale Dateizugriffe unnötigerweise durch den Proxy geleitet werden.

Konnektivität diagnostizieren: Um zu überprüfen, ob Ihr Proxy-String korrekt ist, bevor Sie ihn mit IronPDF nutzen, testen Sie ihn zuerst mit einer einfachen HttpClient-Anfrage:

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

Wenn dies Erfolg hat, IronPDF jedoch weiterhin fehlschlägt, liegt das Problem wahrscheinlich an SSL-Abfangschnitte oder einem Protokollfehlanpassung zwischen Ihrem Proxy und Chromiums CONNECT-Tunneling. Überprüfen Sie, ob der Proxy HTTP CONNECT für HTTPS-Ressourcen unterstützt — einige Proxies erfordern eine explizite Konfiguration, um Tunneling zu erlauben.

Nächste Schritte