Jak skonfigurować serwery proxy do renderowania PDF w 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 uwierzytelnianych proxy

Jak przesłać proxy do RenderHtmlAsPdf?

Parametr Proxy jest opcjonalnym string w czterech sygnaturach metody:

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

Kiedy ten parametr jest null (domyślnie), silnik Chromium IronPDF łączy się bezpośrednio z zasobami zewnętrznymi - arkuszami stylów, obrazami, czcionkami i plikami JavaScript odwoływanymi w twoim HTML. Gdy podasz ciąg proxy, wszystkie żądania HTTP/HTTPS z silnika renderującego są kierowane przez to 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"
)

Łańcuch proxy obsługuje oba schematy http:// i https://. Użyj https://, gdy proxy wymaga szyfrowania TLS dla połączenia między twoją aplikacją a serwerem proxy. Schemat tutaj odnosi się do połączenia proxy, a nie do końcowego zasobu — proxy http:// może wciąż pobierać zasoby https:// przez tunelowanie CONNECT.

Statyczne warianty metody akceptują ten sam parametr proxy, co jest przydatne dla renderów jednorazowych w aplikacjach konsolowych lub testach jednostkowych:

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

Ważne: Nie ma własności Proxy na ChromePdfRenderOptions. Nie szukaj tego tam. Proxy jest ściśle parametrem metody na 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. Osadz je bezpośrednio w URL-u proxy używając formatu 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")

Zakoduj URL-owo specjalne znaki w hasłach. Jeśli twoje hasło zawiera @, #, :, / lub inne zastrzeżone znaki URI, muszą być zakodowane procente. Typowe kodowania:

Użyj Uri.EscapeDataString() do programowego zakodowania hasła:

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"

Nie myl uwierzytelniania proxy z uwierzytelnianiem strony internetowej. ChromeHttpLoginCredentials.NetworkUsername i właściwości NetworkPassword uwierzytelniają się wobec strony internetowej, która jest renderowana (NTLM/Negotiate z witryną), a nie wobec serwera proxy. W przypadku uwierzytelniania proxy dane uwierzytelniające należy umieścić w ciągu adresu URL proxy, jak pokazano powyżej.

Moją ulubioną biblioteką tego typu jest IronPDF. Umożliwia ona szybkie i efektywne manipulowanie plikami PDF. Posiada także wiele cennych funkcji, takich jak eksport do formatu PDF/A i cyfrowe podpisywanie dokumentów PDF.

Milan Jovanovic

Microsoft MVP

Zobacz studium przypadku

IronOCR pozwala nam oszczędzić 40 000 USD rocznie na ręcznym przetwarzaniu, jednocześnie zwiększając produktywność i uwalniając zasoby do zadań o wysokim wpływie. Gorąco polecam.

Brent Matzelle

Dyrektor technologiczny, OPYN

Zobacz studium przypadku

IronSuite odgrywa kluczową rolę w naszej działalności. Są to narzędzia zwiększające wydajność w całej firmie, w tym tworzenie planów pięter i poprawa zarządzania zapasami.

David Jones

Główny inżynier oprogramowania, Agorus Build

Zobacz studium przypadku

Jak renderować adresy URL za serwerem proxy?

RenderUrlToPdf nie akceptuje parametru proxy. To jest zamierzony wybór projektu API — NavigateUrl nawigując Chromium do URL-a, a konfiguracja proxy dla tej nawigacji jest obsługiwana inaczej niż dla ładowania zasobów podczas renderowania HTML.

Polecane obejscie: pobierz HTML sam za pomocą HttpClient skonfigurowanego z HttpProxy, następnie przekaż ciąg HTML do RenderHtmlAsPdf z parametrem proxy (aby zasoby referencyjne — obrazy, CSS, czcionki — również przeszły przez 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

Parametr baseUrlOrPath jest ustawiony na oryginalny URL docelowy, tak aby względne ścieżki w pobranym HTML-u (<img src="/images/logo.png">, <link href="/css/styles.css">) rozwiązały się poprawnie. Parametr proxy zapewnia, że te żądania zasobów przechodzą przez proxy podczas renderowania.

Ten wzorzec również działa z stronami zabezpieczonymi uwierzytelnieniem — skonfiguruj HttpClient z odpowiednimi ciastkami lub nagłówkami przed pobraniem, następnie przekaż uwierzytelniony HTML do IronPDF. Poradnik dotyczący nagłówków żądań HTTP obejmuje konfigurację nagłówków dla żądań uwierzytelnionych.

Jeśli strona opiera się na JavaScripcie dla renderowania (SPA, panele kontrolne w React, aplikacje w Angular), pobrany HTML będzie zawierał tylko początkową powłokę — renderowanie po stronie klienta nie wykona się podczas pobierania HttpClient. Dla tych przypadków masz dwie opcje: ustaw zmienne środowiskowe poziomu systemu HTTPS_PROXY (omówione w następnej sekcji), aby RenderUrlAsPdf() przeszedł przez proxy na poziomie systemu operacyjnego, lub użyj przeglądarki bezgłowej do pobrania w pełni renderowanego HTML-a 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 IronPDF respektuje standardowe zmienne środowiskowe HTTP_PROXY i HTTPS_PROXY, które kontenery Linux używają do kierowania ruchu zewnetrznego.

Ustaw to 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.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"]

Z tymi ustawionymi zmiennymi środowiskowymi, możesz wywołać RenderHtmlAsPdf bez parametru proxy — Chromium automatycznie przechwytuje konfigurację na poziomie systemu:

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

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

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

Błędy przekroczenia limitu czasu: korporacyjne serwery proxy powodują 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

To jest właśćiwość RenderTimeout — kontroluje, jak długo Chromium czeka na załadowanie strony i pobranie zasobów. 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 proxy korporacyjnych 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. Na Linux: skopiuj .crt do /usr/local/share/ca-certificates/ i uruchom update-ca-certificates.
2. Tylko w środowisku programistycznym 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 inline user:pass@host obsługuje uwierzytelnianie proxy Basic i Digest. NTLM (powszechnie stosowany w Enterprise korzystającym z systemu Windows) nie jest obsługiwany przez ciąg adresu URL serwera proxy. Rozwiązaniem jest uruchomienie lokalnego proxy przekierowującego z NTLM do Basic, takiego jak CNTLM, na hoście lub jako kontener typu sidecar. Skonfiguruj CNTLM ze swoimi poświadczeniami NTLM, 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, 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 rozwiązuje się poprawnie przez proxy i sprawdź dzienniki dostępu 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 (obrazy w pakiecie, wbudowany CSS), jak i zasobów zdalnych (czcionki z CDN, skrypty zewnętrzne), proxy musi obsługiwać tylko żądania zdalne. Ustaw baseUrlOrPath na lokalny katalog dla zasobów systemu plików, a proxy pozwól obsługiwać tylko żądania sieciowe. Pozwala to uniknąć niepotrzebnego kierowania odczytu plików lokalnych przez serwer proxy.

Diagnozowanie połączenia: Aby sprawdzić, czy twój ciąg proxy jest poprawny przed użyciem go z IronPDF, przetestuj go najpierw z prostym zapytaniem HttpClient:

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

Jeśli to zadziała, ale IronPDF nadal nie działa, problemem jest prawdopodobnie przechwytywanie SSL lub niezgodność protokołów między Twoim 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