이 페이지에는 자동 번역된 텍스트가 포함될 수 있습니다.

C# 및 VB.NET에서 HTML을 PDF로 변환

Bit Miracle에서 번역했습니다. Sergey Bobrovsky의 원본 기사

2026년 7월 2일에 업데이트됨

이미 HTML 형식의 콘텐츠를 만드는 데 상당한 시간과 비용을 투자했다면, 해당 HTML에서 PDF를 생성하고 싶을 수 있습니다. 이 방식은 중복 작업을 피하려는 모든 사람에게 자연스러운 선택입니다.

이 문서는 Docotic.Pdf와 무료 HtmlToPdf 추가 기능을 함께 사용하여 .NET에서 HTML을 PDF로 변환하는 방법을 자세히 설명합니다.

Docotic.Pdf가 적합한 선택인 이유, 추가 기능 설치 방법, 변환이 내부적으로 어떻게 동작하는지에 대한 정보는 HTML to PDF API 개요 페이지를 참조하세요.

HTML을 PDF로 변환

간단한 HTML을 PDF로 변환하는 C# 예제

먼저 추가 기능을 설치합니다.

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

HTML to PDF API를 사용하면 C# 변환 코드는 다음과 같이 작성할 수 있습니다:

static async Task ConvertUrlToPdfAsync(string urlString, string pdfFileName)
{
    using var converter = await HtmlConverter.CreateAsync();
    using var pdf = await converter.CreatePdfAsync(new Uri(urlString));
    pdf.Save(pdfFileName);
}

매우 간단합니다. PDF 문서를 생성하는 데 두 번의 호출만 필요합니다.

이 코드는 변환기 인스턴스를 만들고 이를 사용해 HTML에서 PDF를 생성합니다. PDF를 편집하거나 디지털 서명으로 서명할 수 있습니다. 간단하게 하기 위해 예제 코드는 문서를 그대로 저장합니다.

보시다시피 API는 비동기이며 동기 메서드는 전혀 제공하지 않습니다.

동기 코드에서 async API 사용하기

동기 코드에서 API를 호출해야 하는 경우가 있습니다. 예를 들어 콘솔 애플리케이션이 이전 버전의 C#을 사용하고 async Main이 없는 경우입니다. 걱정하지 마세요. 애플리케이션에서 여전히 추가 기능을 사용할 수 있습니다.

다음 코드는 일반적인 동기 메서드에서 URL을 PDF로 변환하는 방법을 보여줍니다:

Task.Run(async () =>
{
    using var converter = await HtmlConverter.CreateAsync();
    var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
    using var pdf = await converter.CreatePdfAsync(uri);
    pdf.Save("output.pdf");
}).GetAwaiter().GetResult();

VB.NET 애플리케이션은 유사한 코드를 사용합니다. 다음은 동기 VB.NET 코드에서 HTML을 PDF로 변환하는 방법을 보여주는 예제입니다.

Task.Run(
    Async Function()
        Using converter = Await HtmlConverter.CreateAsync()
            Dim uri = New Uri("https://bitmiracle.com/pdf-library/html-pdf/")
            Using pdf = Await converter.CreatePdfAsync(uri)
                pdf.Save("output.pdf")
            End Using
        End Using
    End Function
).GetAwaiter().GetResult()

일반적으로 비동기 메서드를 동기적으로 호출하는 것은 권장되지 않으므로, 다른 선택지가 없을 때만 래퍼를 사용하세요.

샘플 코드

콘솔, Windows Forms 및 WPF 애플리케이션용 샘플 코드를 제공합니다. GitHub 저장소에서 전체 테스트 프로젝트를 다운로드하세요:

또한 HTML to PDF 샘플 그룹도 있습니다. 각 샘플은 C# 및 VB.NET 버전으로 제공됩니다.

HTML 문자열 또는 파일을 사용해 C# 및 VB.NET에서 PDF 만들기

API를 사용하면 HTML 문자열을 PDF로 쉽게 변환할 수 있습니다. 문자열에는 완전한 HTML 문서 또는 일부 조각만 포함될 수 있습니다. 변환기가 HTML 코드로부터 PDF를 생성해 줍니다.

using var converter = await HtmlConverter.CreateAsync();

var html = "<body><br><br><br><h1>Hello, World</h1></body>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

HTML에는 이미지, 스크립트, CSS 파일에 대한 상대 참조가 포함될 수 있습니다. 이러한 코드를 올바르게 변환하려면 HTML의 모든 상대 링크에 대해 기본 URL을 지정해야 합니다. 변환 옵션을 사용해 기본 URL을 지정하는 방법은 다음과 같습니다:

using var converter = await HtmlConverter.CreateAsync();

var incompleteHtml = "<img src=\"/images/team.svg\"></img>";

var options = new HtmlConversionOptions();
options.Load.BaseUri = new Uri("https://bitmiracle.com/");

using var pdf = await converter.CreatePdfFromStringAsync(incompleteHtml, options);
pdf.Save("output.pdf");

GitHub 저장소에는 전체 테스트 프로젝트가 포함되어 있습니다.

HTML 파일을 변환하는 것은 URL을 변환하는 것과 거의 같습니다. URL 대신 경로를 받는 CreatePdfAsync 오버로드를 사용하면 됩니다. HTML 파일을 C# 또는 VB.NET 코드에서 PDF로 변환할 때도 기본 URL과 기타 옵션을 지원합니다.

var sampleHtmlPath = @"C:\path\to\sample.html";
using var pdf = await converter.CreatePdfAsync(sampleHtmlPath);
pdf.Save("output.pdf");

API를 사용해 SVG 이미지를 PDF로 변환할 수도 있습니다.

사용자 지정 페이지 크기, 여백, 배율 사용

레이아웃이 넓은 웹 페이지를 처리할 때는 출력 PDF 크기를 늘리거나 콘텐츠를 축소해 PDF 페이지에 맞출 수 있습니다. 축소된 콘텐츠의 배치를 더 잘 맞추려면 여백을 설정할 수도 있습니다.

잘 조정된 PDF는 읽기 경험을 향상시킵니다. 독자가 콘텐츠를 제대로 보기 위해 확대하거나 축소할 필요가 없기 때문입니다. HTML 문서가 글꼴 크기가 작아 읽기 어렵다면 콘텐츠를 확대할 수 있습니다.

기본적으로 API는 페이지 크기가 A4와 같은 PDF를 생성합니다. 여백과 확대/축소는 없습니다. 변환 옵션을 사용해 이러한 설정을 변경할 수 있습니다.

HTML에서 PDF를 생성할 때 배율과 여백을 설정하는 방법

using var converter = await HtmlConverter.CreateAsync();

var html = "<html><head><style>body { background-color: coral; margin-top: 100px;}</style></head>" +
"<body><h1>Did you notice the margins and the scale?</h1></body></html>";

var options = new HtmlConversionOptions();
options.Page.MarginLeft = 10;
options.Page.MarginTop = 20;
options.Page.MarginRight = 30;
options.Page.MarginBottom = 40;
options.Page.Scale = 1.5;

using var pdf = await converter.CreatePdfFromStringAsync(html, options);
pdf.Save("output.pdf");

Docotic.Pdf 샘플 저장소에는 전체 프로젝트가 포함되어 있습니다.

헤더 및 푸터 템플릿 지정

HTML to PDF API는 생성된 페이지에 반복 가능한 푸터 / 헤더 블록을 추가할 수 있습니다. 변환기는 페이지 옵션에 지정된 HTML 템플릿으로 블록을 생성합니다. 템플릿 내부의 이미지는 인라인 스타일과 Data URI를 사용하는 것을 권장합니다.

변환기는 페이지 여백 내부에 헤더와 푸터를 배치합니다. 기본 페이지 여백이 작기 때문에 헤더와 푸터의 내용이 보이지 않을 수 있습니다. 상단 및 하단 여백을 명시적으로 지정하는 것을 권장합니다. 크기는 각각 헤더와 푸터의 크기와 일치해야 합니다.

HTML을 PDF로 변경하고 헤더와 푸터를 추가하는 방법

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
options.Page.HeaderTemplate = File.ReadAllText("header-template.html");
options.Page.MarginTop = 50;

options.Page.FooterTemplate = File.ReadAllText("footer-template.html");
options.Page.MarginBottom = 50;

var url = new Uri("https://www.iana.org/numbers");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");

템플릿은 몇 가지 변수를 지원하는 일반 HTML 코드를 사용합니다. 이러한 변수는 date, title, url, pageNumber, totalPages입니다. 헤더 템플릿과 푸터 템플릿 모두 동일한 변수 집합을 지원합니다.

전체 테스트 프로젝트 및 템플릿 코드는 Docotic.Pdf 샘플 저장소에 있습니다. 샘플 코드는 템플릿에서 변수와 Data URI를 사용하는 방법을 보여줍니다.

암호로 보호된 HTML을 PDF로 변환하는 C# 예제

일부 웹 페이지는 접근하려면 인증이 필요합니다. HTTP 인증이 필요한 보안 URL에 접근하면 브라우저가 사용자 이름과 암호를 입력하라고 요청합니다.

변환 옵션을 사용하면 로그인이 필요한 웹 페이지에 대한 자격 증명을 API에 제공하도록 지시할 수 있습니다.

다음 C# 코드는 암호로 보호된 HTML을 PDF로 변환하는 방법을 보여줍니다

using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://httpbin.org/basic-auth/foo/bar");

var options = new HtmlConversionOptions();
options.Authentication.SetCredentials("foo", "bar");

using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");

샘플 저장소에서 전체 동작 예제를 확인하세요.

페이지가 제대로 동작하려면 쿠키를 설정해야 하는 경우에도 쉽게 처리할 수 있습니다. 해당 쿠키를 옵션에 추가하기만 하면 됩니다. 방법은 다음과 같습니다:

var options = new HtmlConversionOptions();
options.Cookies.Add(new Cookie("sessionID", "my-session-ID"));

using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");

변환 시작 지연

기본적으로 변환은 로딩이 끝난 직후 시작됩니다. HTML을 PDF로 변환하기 전에 지연을 두면 페이지가 로드된 후 일정 시간 동안 계속 업데이트되는 경우에 유용합니다. JavaScript 또는 AJAX 호출로 생성되는 동적 콘텐츠를 다룰 때 흔히 그렇습니다.

Acid 3 테스트는 변환 전에 지연을 두면 도움이 되는 페이지의 대표적인 예입니다. 이 테스트는 브라우저가 복잡한 웹 페이지를 올바르게 렌더링하는 능력을 평가하기 위해 여러 검사를 실행합니다. 이러한 검사는 시간이 걸립니다. 다음 코드에서 대기 시간을 변경해 변환 결과에 어떤 영향을 주는지 확인해 보세요.

var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);

using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://acid3.acidtests.org/");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");

위 코드는 지연을 두고 HTML을 PDF로 변환하는 방법을 보여줍니다. 추가 시간은 더 나은 결과를 얻는 데 도움이 되지만, 지연을 추가하면 성능에 영향을 줄 수 있습니다. 지연이 부족하면 변환 품질이 저하될 수 있습니다. 지연을 사용하는 대신 스크립트를 사용해 페이지가 준비될 때까지 실행하는 방법도 있습니다.

Docotic.Pdf 샘플 저장소에서 전체 테스트 프로젝트를 받을 수 있습니다.

변환 전에 JavaScript 실행

추가 기능 API는 변환 전에 JS 코드를 실행하는 방법을 제공합니다. 코드는 HTML 콘텐츠를 동적으로 생성하거나 수정할 수 있습니다. 예를 들어 요소를 전환하거나 동적 콘텐츠 로딩을 발생시킬 수 있습니다.

다음 코드는 JavaScript가 완료될 때까지 HTML을 PDF로 변환을 지연하는 방법을 보여줍니다.

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
var js = @"document.body.style.backgroundColor = 'green';";
options.Start.SetStartAfterScriptRun(js);

var url = new Uri("https://google.com");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");

위 예제는 접근 방식을 설명하기 위해 매우 단순한 코드를 사용합니다. 더 실제적인 예제는 GitHub 저장소의 해당 샘플 앱을 확인하세요. 이 앱은 콘텐츠를 동적으로 로드하는 페이지를 처리하는 방법을 보여줍니다. 앱의 JavaScript 코드는 더 이상 새 콘텐츠가 없을 때까지 페이지를 스크롤합니다. 그 후 PDF로 변환이 수행됩니다.

SSL 오류를 무시하고 .NET에서 HTML을 PDF로 변환

HTML을 로드하기 위해 보안 요청을 보낼 때, 추가 기능은 웹사이트의 신원을 인증하고 암호화된 연결을 가능하게 하는 SSL 인증서가 유효하고 신뢰할 수 있는지 확인합니다.

기본적으로 HTML을 PDF로 변환하는 변환기가 어떤 이유로든 인증서를 신뢰하지 않으면 추가 기능은 예외를 발생시킵니다. 일반적으로 자체 서명, 폐기 또는 만료된 인증서 때문에 발생합니다.

신뢰할 수 없는 인증서를 수락하는 위험을 이해한다면, 엔진 옵션을 사용해 추가 기능이 검사를 건너뛰도록 설정할 수 있습니다.

var engineOptions = new HtmlEngineOptions
{
    IgnoreSslErrors = true
};
using var converter = await HtmlConverter.CreateAsync(engineOptions);

var url = new Uri("https://self-signed.badssl.com/");
using var pdf = await converter.CreatePdfAsync(url);
pdf.Save("output.pdf");

전체 코드는 Docotic.Pdf 샘플 저장소에서 확인하세요.

기존 PDF 위에 HTML 오버레이하기

변환 결과의 배경으로 기존 PDF를 사용하고 싶을 때가 있습니다. 예를 들어 양식 그림이 있고 그 그림의 빈 영역 위에 무언가를 넣고 싶은 경우입니다. 결과는 채워진 양식처럼 보이게 됩니다. Docotic.Pdf와 추가 기능을 사용하면 가능합니다.

이 과정은 HTML(오버레이 콘텐츠)로 새 PDF를 만든 다음 기존 PDF와 병합하는 방식으로 이루어집니다. 최종 문서에는 원본 콘텐츠와 새 오버레이가 모두 포함됩니다. 아래는 이 과정을 보여주는 코드입니다.

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
options.Page.SetSizeInches(4.13, 5.83);

string htmlCode =
    "<div style=\"position: absolute; top: 270px; right: 100px;\">" +
    "I would like to put this here</div>";
using var htmlPdf = await converter.CreatePdfFromStringAsync(htmlCode, options);

using var pdf = new PdfDocument("pdf-to-merge-with.pdf");
var xObj = pdf.CreateXObject(htmlPdf.Pages[0]);

pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("output.pdf");

오버레이에는 페이지 크기를 지정하는 것이 중요합니다. 일반적으로 크기는 오버레이하려는 페이지의 크기와 같아야 합니다. 그런 다음 오버레이 콘텐츠가 포함된 새 PDF를 생성해야 합니다. 기본적으로 배경은 투명합니다. 필요하다면 변환 전에 스크립트를 실행하여 배경을 변경할 수 있습니다.

위 코드는 다음을 수행합니다:

HTML에서 투명한 페이지가 있는 PDF 문서를 생성합니다
기존 PDF를 엽니다
변환된 문서의 첫 페이지에서 기존 문서용 XObject를 생성합니다
기존 문서의 첫 번째 PDF 페이지 위에 XObject를 그립니다

예제 소스 PDF가 포함된 전체 테스트 프로젝트는 Docotic.Pdf 샘플 저장소에 있습니다.