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

C# 및 VB.NET을 사용하여 HTML을 PDF로 변환

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

2026년 1월 22일에 업데이트됨

이미 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는 비동기 방식으로 작동하며 동기식 메서드는 전혀 제공하지 않습니다.

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

때로는 동기 코드에서 API를 호출해야 하는 경우가 있습니다. 예를 들어 콘솔 애플리케이션이 이전 버전의 C#을 사용하고 비동기 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을 PDF로 변환하는 샘플 모음도 있습니다. 각 샘플은 C# 및 VB.NET 버전으로 제공됩니다.

C# 및 VB.NET을 사용하여 HTML 문자열 또는 파일로 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 파일을 PDF로 변환하는 것은 URL을 변환하는 것과 거의 동일합니다. URL 대신 경로를 인수로 받는 CreatePdfAsync 오버로드 함수를 사용하면 됩니다. C# 또는 VB.NET 코드에서 HTML 파일을 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 템플릿에서 블록을 생성합니다. 템플릿 내 이미지에는 인라인 스타일과 데이터 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 샘플 저장소에 있습니다. 샘플 코드는 템플릿에서 변수와 데이터 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를 사용하면 변환 전에 JavaScript 코드를 실행할 수 있습니다. 이 코드는 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 파일을 엽니다.
변환된 PDF 파일의 첫 번째 페이지를 기존 문서에 XObject로 생성합니다.
기존 문서의 첫 번째 PDF 페이지 위에 XObject를 그립니다.

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