Jak skonfigurować serwery proxy do renderowania plików PDF w języku C

Minimalny przebieg pracy (3 kroki)

1. Zainstaluj IronPDF za pomocą NuGet: Install-Package IronPdf
2. Przekaż ciąg proxy jako trzeci parametr do RenderHtmlAsPdf
3. Format: http(s)://host:port lub http(s)://user:pass@host:port dla uwierzytelnionych serwerów proxy

Jak przekazać proxy do RenderHtmlAsPdf?

Parametr Proxy jest opcjonalny string w czterech sygnaturach metod:

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

Gdy ten parametr ma wartość null (domyślnie), silnik Chromium IronPDF łączy się bezpośrednio z zasobami zewnętrznymi — arkuszami stylów, obrazami, czcionkami i plikami JavaScript, do których odwołuje się kod HTML. Po podaniu ciągu proxy wszystkie żądania HTTP/HTTPS z silnika renderującego są kierowane przez ten serwer 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"
)

Ciąg proxy obsługuje zarówno schematy http://, jak i https://. Użyj https://, gdy sam serwer proxy wymaga szyfrowania TLS dla połączenia między aplikacją a serwerem proxy. Schemat ten odnosi się do połączenia proxy, a nie do ostatecznego zasobu — proxy http:// nadal może pobierać zasoby https:// poprzez tunelowanie CONNECT.

Warianty metod statycznych akceptują ten sam parametr proxy, co jest przydatne w przypadku jednorazowego renderowania w aplikacjach konsolowych lub testach jednostkowych:

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

Ważne: W ChromePdfRenderOptions nie ma właściwości Proxy. Nie szukaj tego tam. Proxy jest wyłącznie parametrem metody w przeciążeniach RenderHtmlAsPdf i FromHtml.

Jak uwierzytelnić się za pomocą firmowego serwera proxy?

Większość serwerów proxy dla Enterprise wymaga podania danych uwierzytelniających. Wstawia się je bezpośrednio w adresie URL proxy, używając formatu 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")

Zakoduj znaki specjalne w hasłach za pomocą kodowania URL. Jeśli Twoje hasło zawiera @, #, :, / lub inne zarezerwowane znaki URI, muszą one zostać zakodowane za pomocą znaków procentowych. Typowe kodowania:

Użyj Uri.EscapeDataString(), aby zakodować hasło programowo:

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"

Nie należy mylić uwierzytelniania przez serwer proxy z uwierzytelnianiem na stronie internetowej. Właściwości ChromeHttpLoginCredentials.Net/workUsername i NetworkPassword uwierzytelniają użytkownika względem renderowanej strony internetowej (NTLM/Negotiate z witryną), a nie względem serwera proxy. W przypadku uwierzytelniania przez proxy dane uwierzytelniające należy umieścić w ciągu adresu URL proxy, jak pokazano powyżej.

Jak renderować adresy URL za serwerem proxy?

RenderUrlToPdf nie akceptuje parametru proxy. Jest to świadomy wybór projektowy API — NavigateUrl przekierowuje Chromium do adresu URL, a konfiguracja proxy dla tego przekierowania jest obsługiwana inaczej niż w przypadku ładowania zasobów podczas renderowania HTML.

Zalecane obejście: pobierz kod HTML samodzielnie, używając HttpClient skonfigurowanego z HttpProxy, a następnie przekaż ciąg HTML do RenderHtmlAsPdf z parametrem proxy (tak, aby odwołane zasoby — obrazy, CSS, czcionki — również przechodziły przez 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

Parametr baseUrlOrPath jest ustawiony na oryginalny docelowy adres URL, aby ścieżki względne w pobranym kodzie HTML (<img src="/images/logo.png">, <link href="/css/styles.css">) były poprawnie rozpoznawane. Parametr proxy zapewnia, że żądania dotyczące zasobów są kierowane przez serwer proxy podczas renderowania.

Ten wzorzec działa również w przypadku stron wymagających uwierzytelnienia — przed pobraniem danych należy skonfigurować HttpClient z odpowiednimi plikami cookie lub nagłówkami, a następnie przekazać uwierzytelniony kod HTML do IronPDF. Poradnik dotyczący nagłówków żądań HTTP obejmuje konfigurację nagłówków dla żądań uwierzytelnionych.

Jeśli strona wykorzystuje JavaScript do renderowania (SPA, pulpity nawigacyjne React, aplikacje Angular), pobrany kod HTML będzie zawierał jedynie początkową strukturę — renderowanie po stronie klienta nie zostanie wykonane podczas pobierania HttpClient. W takich przypadkach masz dwie opcje: ustawić zmienne środowiskowe na poziomie systemu HTTPS_PROXY na poziomie systemu (omówione w następnej sekcji), tak aby RenderUrlAsPdf() kierował ruch przez serwer proxy na poziomie systemu operacyjnego, lub użyć przeglądarki bezinterfejsowej do pobrania w pełni wyrenderowanego kodu HTML przed przekazaniem go do RenderHtmlAsPdf().

Jak skonfigurować serwer proxy w kontenerach Docker?

W środowiskach kontenerowych można preferować konfigurację proxy na poziomie systemu zamiast parametrów poszczególnych metod. Silnik Chromium firmy IronPDF obsługuje standardowe zmienne środowiskowe HTTP_PROXY i HTTPS_PROXY, których kontenery Linux używają do routingu ruchu wychodzącego.

Ustaw te opcje w pliku 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"]

Po ustawieniu tych zmiennych środowiskowych można wywołać RenderHtmlAsPdf bez parametru proxy — Chromium automatycznie pobiera konfigurację na poziomie systemu:

// 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() jest ważny dla zasobów wewnętrznych. W przeciwnym razie żądania kierowane do usług wewnętrznych (takich jak lokalny serwer CSS lub CDN obrazów działający w klastrze Kubernetes) byłyby niepotrzebnie kierowane przez serwer proxy. Nazwy hostów i domen, które powinny ominąć serwer proxy, należy oddzielić przecinkami.

Jeśli potrzebujesz zarówno proxy na poziomie systemu dla ogólnego ruchu, jak i innego proxy dla konkretnych renderowań, parametr metody ma pierwszeństwo przed zmienną środowiskową. Daje to kontrolę nad renderowaniem w razie potrzeby.

Jak radzisz sobie z proxy w potokach CI/CD?

Programy CI/CD w sieciach korporacyjnych często działają za serwerami proxy. Przekaż adres URL serwera proxy jako zmienną kompilacji lub sekret — nigdy nie zapisuj danych uwierzytelniających na stałe w systemie kontroli wersji.

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 (deklaratywny potok):

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

We wszystkich trzech przypadkach Chromium automatycznie odczytuje zmienne środowiskowe. Jeśli wolisz mieć pełną kontrolę, odczytaj adres URL serwera proxy ze środowiska i przekaż go jako parametr metody:

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)

Jak rozwiązywać problemy związane z serwerem proxy?

Błędy przekroczenia limitu czasu: korporacyjne serwery proxy zwiększają opóźnienia. Zwiększ limit czasu renderowania z domyślnych 60 sekund:

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

Jest to właściwość RenderTimeout — kontroluje ona, jak długo Chromium czeka na załadowanie strony i pobranie zasobów łącznie. Jeśli Twój serwer proxy powoduje opóźnienie rzędu 5–10 sekund na żądanie, a strona ładuje ponad 20 zasobów zewnętrznych, 60 sekund może nie wystarczyć.

Przechwytywanie SSL (proxy MITM): Wiele korporacyjnych serwerów proxy odszyfrowuje i ponownie szyfruje ruch HTTPS przy użyciu korporacyjnego certyfikatu głównego urzędu certyfikacji. Chromium odrzuca te połączenia, ponieważ domyślnie nie ufa korporacyjnemu certyfikatowi CA. Dwa rozwiązania:

1. Zainstaluj certyfikat CA firmy w zaufanym magazynie głównym kontenera lub hosta. W systemie Linux: skopiuj .crt do /usr/local/share/ca-certificates/ i uruchom update-ca-certificates.
2. Tylko w środowisku deweloperskim można wyłączyć weryfikację certyfikatów — ale nigdy nie należy tego robić w środowisku produkcyjnym. Bezpieczniejszym rozwiązaniem jest zawsze zainstalowanie odpowiedniego certyfikatu.

Uwierzytelnianie NTLM: Format wbudowany user:pass@host obsługuje uwierzytelnianie proxy typu Basic i Digest. NTLM (powszechnie stosowany w Enterprise) nie jest obsługiwany przez ciąg adresu URL serwera proxy. Rozwiązaniem jest uruchomienie lokalnego proxy przekierowującego z NTLM na Basic, takiego jak CNTLM, na hoście lub jako kontener typu sidecar. Skonfiguruj CNTLM przy użyciu swoich poświadczeń NTLM, a następnie skieruj IronPDF na http://localhost:3128 (domyślny port CNTLM).

Pusty plik PDF lub brakujące zasoby: Jeśli plik PDF wyświetla się, ale brakuje obrazów/CSS, Twój kod HTML odwołuje się do zasobów, które są blokowane przez serwer proxy lub wymagają innej ścieżki proxy. Sprawdź, czy parametr baseUrlOrPath jest poprawnie rozpoznawany przez serwer proxy, i sprawdź logi dostępu serwera proxy pod kątem odpowiedzi 403 lub 407.

Omijanie proxy dla zasobów lokalnych: Jeśli kod HTML odwołuje się zarówno do zasobów lokalnych (pakiety obrazów, wbudowane arkusze CSS), jak i zasobów zdalnych (czcionki z sieci CDN, skrypty zewnętrzne), serwer proxy musi obsługiwać wyłącznie żądania zdalne. Ustaw baseUrlOrPath na lokalny katalog dla zasobów systemu plików i pozwól, aby proxy obsługiwało tylko żądania sieciowe. Pozwala to uniknąć niepotrzebnego kierowania odczytu plików lokalnych przez serwer proxy.

Diagnozowanie łączności: Aby sprawdzić, czy ciąg proxy jest poprawny przed użyciem go w IronPDF, przetestuj go najpierw za pomocą prostego żądania 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

Jeśli to zadziała, ale IronPDF nadal nie działa, problemem jest prawdopodobnie przechwytywanie SSL lub niezgodność protokołów między serwerem proxy a tunelowaniem CONNECT w Chromium. Sprawdź, czy serwer proxy obsługuje protokół HTTP CONNECT dla zasobów HTTPS — niektóre serwery proxy wymagają wyraźnej konfiguracji, aby umożliwić tunelowanie.

Kolejne kroki