PDFSharp 가이드: MigraDoc 및 PdfSharpCore를 사용하여 PDF 파일 만들기

PDFsharp는 C# 코드를 사용하여 PDF 문서를 생성하고 편집할 수 있는 오픈 소스 .NET 라이브러리입니다. 페이지에 텍스트, 선, 이미지를 그리고 저장(Save) 메서드를 호출하면 PDF 파일이 생성됩니다. 브라우저 엔진이나 네이티브 바이너리가 필요하지 않습니다. 이 프로젝트는 2005년에 시작되었으며, 오늘날 .NET 백엔드에서 생성되는 많은 청구서, 보고서, 증명서 등이 여전히 PDFsharp를 거쳐 처리되고 있습니다.

이 글은 서버에서 PDF 파일을 필요로 하는 개발자들을 위해 작성되었습니다. PDFsharp와 MigraDoc의 연동 방식, 설치해야 할 빌드, 처음으로 제대로 작동하는 파일, Linux 환경에서의 폰트 문제, 최근 라이선스 변경 사항, 그리고 다른 도구를 선택해야 하는 시점까지 다룹니다.

PDFsharp는 무엇이며 어떤 기능을 제공하나요?

PDFsharp 라이브러리 뒤에는 empira Software GmbH라는 작은 독일 회사가 있는데, 이 회사는 거의 20년 동안 PDFsharp를 유지해 왔습니다. 대부분의 시간은 XGraphics라는 한 클래스에 할애됩니다. System.Drawing.Graphics를 사용하여 WinForms에서 그림을 그려본 경험이 있다면 10분 안에 익숙해질 것입니다. 글꼴, 브러시, x, y 좌표를 사용하면 됩니다.

개봉 시 구성품은 다음과 같습니다:

• 텍스트, 벡터 도형, 선, 이미지를 사용하여 처음부터 PDF 문서를 만드세요.
• 기존 PDF 파일을 열고 스탬프, 워터마크 또는 페이지 번호와 같은 콘텐츠를 페이지에 추가할 수 있습니다.
• 한 파일의 페이지를 다른 파일로 가져와 문서를 병합하거나 분할할 수 있습니다.
• 글꼴을 포함시키거나 부분집합으로 만들어 모든 기기에서 파일이 동일하게 보이도록 합니다.
• 책갈피, 링크, 그리고 제목, 저자, 키워드와 같은 문서 메타데이터를 추가하세요.
• 암호와 권한 플래그를 사용하여 파일을 보호하세요
• (6.2 릴리스 버전부터) 문서를 디지털 방식으로 서명할 수 있습니다.

배포는 지루합니다. 칭찬의 의미입니다. 모든 것이 관리형 코드이기 때문에 운영 담당자는 새벽 2시에 헤드리스 크롬을 설치하거나 고스트스크립트 DLL을 찾아 헤맬 필요가 없습니다. NuGet 패키지 하나만 참조하고 푸시하면 끝입니다.

자, 이제 함정이 있습니다. 캔버스만 제공될 뿐, 그 이상은 아무것도 없습니다. 긴 단락이 하단 여백에 닿나요? 당신 책임입니다. 표가 1페이지를 넘어가나요? MigraDoc을 사용하지 않는 한, 이 또한 당신 책임입니다.

PDFsharp와 MigraDoc: 어떤 레이어가 필요할까요?

같은 공급업체, 같은 출시 일정이지만, 하는 일은 완전히 다릅니다. MigraDoc Foundation은 PDFsharp보다 한 단계 위에 있습니다. 문자열의 위치를 지정하는 대신 섹션, 단락, 표, 머리글, 바닥글, 스타일, 그리고 가끔 차트까지 모두 입력하면 MigraDoc Foundation이 모든 요소의 위치를 알아서 처리합니다. 그러면 PDF 파일이 생성됩니다. 또는 모든 파일을 Word에서 열어야 한다고 고집하는 동료를 위해 RTF 형식으로도 제공됩니다.

제가 쓰는 약어는 이렇습니다. PDFsharp는 "이 텍스트를 x=40, y=120에 넣어라"이고, MigraDoc는 "여기 30개의 행과 반복되는 헤더가 있으니 페이지는 알아서 배치해라"입니다.

실제 프로젝트에서는 두 가지 방식이 모두 사용되는 경우가 많습니다. 본문 텍스트는 MigraDoc을 통해, 표지는 손으로 직접 그리거나 특정 업체에서 제공하는 PDF 파일에 도장을 찍는 방식은 하위 레이어를 통해 구현됩니다. 어쨌든 MigraDoc 패키지가 PDFsharp를 종속성으로 포함시키기 때문에 설치를 피할 수는 없습니다.

PDFsharp 빌드 설명: 코어 빌드, GDI+ 및 WPF

새로운 프로그램은 보통 NuGet 패키지 목록에서 다음 순서로 밀려나는 경우가 많습니다. PDFsharp 6은 세 가지 빌드로 제공되며, 각 빌드에는 MigraDoc 버전이 함께 제공됩니다.

현재 패키지는 .NET 8, 9, 10과 .NET Standard 2.0 및 .NET Framework 4.6.2를 대상으로 합니다. 따라서 오래된 WinForms 도구부터 최신 ASP.NET Core API에 이르기까지 현재 개발 중인 거의 모든 것을 지원합니다.

콘솔 앱, 웹 API, Docker, Azure Functions 등 Linux 기반 앱이라면 코어 빌드를 사용하세요. GDI+나 WPF는 시스템 글꼴을 사용하거나 네이티브 컨트롤에서 미리 보기를 표시하려는 Windows 데스크톱 앱에만 적합합니다. Stack Overflow에서 어떤 사람이 콘솔 앱에 WPF 버전이 필요한지 물어본 적이 있는데, 필요 없다고 답했습니다.

Visual Studio에서 NuGet을 사용하여 PDFsharp를 설치하는 방법

아직도 윈폼 시대 포럼 게시글에서 ZIP 파일을 다운로드하고 DLL 파일을 찾아 직접 참조를 추가하라는 내용을 볼 수 있을 겁니다. 그런 글은 무시하세요. PDFsharp는 NuGet을 통해 설치하세요. 패키지 관리자가 버전을 자동으로 관리해주기 때문에 따로 신경 쓸 필요가 없습니다.

1. Visual Studio에서 솔루션을 열고 솔루션 탐색기에서 프로젝트를 마우스 오른쪽 버튼으로 클릭합니다.
2. [NuGet 패키지 관리]를 선택하고 [찾아보기] 탭으로 전환한 다음 "PDFsharp"를 검색하세요.
3. 문서 레이아웃 기능도 필요한 경우 PDFsharp (Core 빌드) 또는 PDFsharp-MigraDoc을 선택하십시오. 게시자가 empira Software GmbH인지 확인하십시오.
4. 설치를 클릭하고 라이선스 메시지를 수락하세요.
5. 패키지가 올바르게 복원되었는지 확인하려면 프로젝트를 한 번 빌드하십시오.

터미널 이용자는 클릭을 건너뛸 수 있습니다.

bash dotnet add package PDFsharp dotnet add package PDFsharp-MigraDoc

패키지 관리자 콘솔에서도 마찬가지로 Install-Package PDFsharp 명령어를 사용하면 됩니다. 그리고 빌드 버전을 혼합해서 사용하지 마세요. 한 프로젝트에서 PDFsharp를 참조하는 반면, 옆 프로젝트에서는 PDFsharp-GDI를 참조하는 바람에 타입 충돌이 발생해서 팀이 오후 내내 고생한 적이 있습니다.

PDFsharp를 사용하여 C 언어로 첫 번째 PDF 문서를 만드세요

아래는 한 페이지짜리 PDF 파일을 생성하는 가장 간단한 프로그램입니다. 이 프로그램은 글꼴 해결 프로그램이 설정되어 있으면(다음 섹션 참조) 모든 운영 체제의 코어 빌드에서 실행됩니다.

```csharp
PdfSharp.Drawing을 사용합니다.
PdfSharp.Pdf를 사용합니다.

PDFsharp 6.5 이상 버전에서는 처음 사용하기 전에 라이선스를 선택해야 합니다.
PdfSharpLicense.SetAgplLicense();

var document = new PdfDocument();
document.Info.Title = "안녕하세요 PDFsharp";

PdfPage 페이지 = document.AddPage();
XGraphics gfx = XGraphics.FromPdfPage(page);

var font = new XFont("Arial", 20, XFontStyleEx.Bold);
gfx.DrawString("안녕하세요, PDFsharp!", 글꼴, XBrushes.Black,
새로운 XRect(0, 0, page.Width.Point, page.Height.Point),
XStringFormats.Center);

document.Save("hello.pdf");
```

모든 PDFsharp 프로그램은 문서, 페이지, XGraphics, 그리기, 저장 순서로 진행됩니다. 단위는 포인트(1/72인치)이며 원점은 왼쪽 상단에 있습니다. 6.2.x 버전에서는 라이선스 관련 줄을 삭제하세요. 해당 API는 6.5.0 버전부터 추가되었습니다.

MigraDoc 버전은 다음과 같습니다.

```csharp
MigraDoc.DocumentObjectModel을 사용합니다.
MigraDoc.Rendering을 사용합니다.

var doc = new Document();
섹션 섹션 = doc.AddSection();
section.AddParagraph("안녕하세요, MigraDoc님!");

var renderer = new PdfDocumentRenderer { Document = doc };
renderer.RenderDocument();
renderer.PdfDocument.Save("hello-migradoc.pdf");
```

좌표는 어디에도 없습니다. 단락 500개를 넣으면 페이지 수가 얼마가 되든 상관없이 페이지 매김 코드를 전혀 작성할 필요가 없습니다.

PDFsharp 코어 빌드의 글꼴: 해결사 문제

주변에 물어보면 글꼴 문제가 가장 많이 언급될 겁니다. GDI+ 및 WPF 빌드는 Windows에 설치된 TrueType 글꼴을 읽어옵니다. 하지만 코어 빌드는 아무것도 가정할 수 없습니다. 왜냐하면 용량이 작은 Linux 컨테이너에는 사용 가능한 글꼴이 아예 없는 경우가 많기 때문입니다. 따라서 첫 번째 Docker 배포는 적절한 글꼴을 찾을 수 없다는 예외 오류로 끝나는 경우가 흔합니다.

해결책은 IFontResolver 인터페이스를 구현하는 폰트 리졸버 클래스입니다. 이 클래스는 두 가지 메서드를 가지고 있습니다.

• ResolveTypeface는 요청된 글꼴 패밀리와 스타일(예: "Arial", 굵게)을 글꼴 이름으로 매핑합니다.
• GetFont는 해당 글꼴 이름에 대한 TTF 파일의 원시 바이트를 반환합니다.

첫 번째 XFont가 생성되기 전에 GlobalFontSettings.FontResolver를 통해 시작 시 한 번만 등록합니다.

```csharp
public class AppFontResolver : IFontResolver
{
public FontResolverInfo? ResolveTypeface(string family, bool bold, bool italic)
=> new FontResolverInfo(bold ? "Inter-Bold" : "Inter-Regular");

public byte[]? GetFont(string faceName) => File.ReadAllBytes(Path.Combine(AppContext.BaseDirectory, "Fonts", faceName + ".ttf"));

}

GlobalFontSettings.FontResolver = new AppFontResolver();
```

직접 부딪히기 전에 알아두면 좋은 것들:

• TTF 파일은 프로젝트 내의 Fonts 폴더에 보관하고 출력 디렉터리로 복사되도록 설정하거나, 컨테이너 이미지에 항상 포함되도록 리소스로 내장하세요.
• 릴리스 6.2.0에서 기존 CoreBuildFontResolver가 제거되었습니다. Windows 또는 WSL2에서는 GlobalFontSettings.UseWindowsFontsUnderWindows를 사용하여 유사한 동작을 복원할 수 있지만, Linux 또는 macOS에서는 아무런 효과가 없습니다.
• 공식 샘플 저장소에는 시작점으로 사용할 수 있는 SubstitutingFontResolver가 포함되어 있습니다.
• 생성된 파일에 상용 글꼴을 포함시키기 전에 글꼴 라이선스를 확인하십시오. Inter, Roboto, Noto와 같은 오픈 소스 글꼴은 이러한 문제가 아예 발생하지 않습니다.

리졸버가 설치되면 Windows, Linux 및 macOS에서 출력 결과가 동일하게 나타납니다.

PDFsharp 6을 이용한 파일 병합, 서명 및 보안

많은 팀들이 문서를 처음부터 새로 만들지 않습니다. 라이브러리를 활용하여 이미 존재하는 파일들을 병합하거나, 스탬프를 찍거나, 잠그는 방식으로 작업합니다. 병합은 몇 줄의 코드로 간단하게 완료할 수 있습니다. 각 소스 파일을 가져오기 모드로 열고 페이지를 복사하면 됩니다.

csharp var output = new PdfDocument(); foreach (var path in new[] { "part1.pdf", "part2.pdf" }) { using var input = PdfReader.Open(path, PdfDocumentOpenMode.Import); foreach (PdfPage p in input.Pages) output.AddPage(p); } output.Save("merged.pdf");

분할은 페이지 또는 범위별로 하나의 출력 파일을 생성하는 역방향 루프와 동일합니다. 보안을 위해 document.SecuritySettings는 사용자 암호, 소유자 암호 및 권한 플래그(인쇄, 텍스트 복사 등)를 사용합니다.

많은 사용자들이 오랫동안 요청했던 두 가지 기능이 마침내 6.2 버전에 포함되었습니다.

• CMS 기반 디지털 서명 기능을 제공합니다. 기본 서명기는 별도의 PDFsharp.Cryptography 어셈블리에 포함되어 있으며, IDigitalSigner 인터페이스를 구현하여 자체 서명기를 추가할 수 있습니다. 타임스탬프 서버 지원은 최신 .NET 환경에서는 작동하지만 .NET Framework 기반 빌드에서는 작동하지 않습니다.
• 보관용 PDF/A 출력 기능을 제공합니다. 공식 문서에서는 이 기능이 "일부 제한 사항"이 있으며 아직 개발 중이라고 설명하고 있으므로, 규정 준수 목적으로 사용하기 전에 PDF/A 검사 도구를 사용하여 결과를 검증하십시오.

이번 릴리스에는 색상 이모지 기호와 관리형 MD5 구현도 포함되었는데, 이는 FIPS 규정을 준수하거나 Blazor에서 실행하는 경우에 중요합니다.

PDFSharp 저장소, PDFSharpCore 포크 및 1.x 버전

GitHub에서 PDFsharp를 검색하면 거의 같은 이름을 가진 프로젝트가 여러 개 나옵니다. 다 과거의 일이죠.

이전 1.x 버전(1.50, 1.51)은 .NET Framework에서만 실행되었습니다. .NET Core가 출시되자 사람들은 기다리기 싫어 직접 Linux로 포팅했습니다. Stefan Steiger가 시작하고 이후 다른 포크들이 이어받은 PdfSharpCore가 가장 잘 알려져 있습니다. 이 프로젝트는 GDI+를 제거하고 공식 출시보다 몇 년 앞서 Linux에서 코드를 실행할 수 있도록 했습니다.

그러다가 PDFsharp 6이 출시되었습니다. 최신 .NET 기반으로 완전히 새롭게 작성되었고, 공식적인 크로스 플랫폼 코어 빌드도 제공되었습니다. 이로써 포크 버전들은 존재 이유를 대부분 잃었습니다.

레딧에 계속 올라오는 "PdfSharp vs PdfSharpCore" 논쟁 말인데요? 새 프로젝트를 만들고 공식 패키지를 사용하세요. 기존 코드가 이미 해당 라이브러리를 사용하고 있고, 지금 당장 마이그레이션하는 데 시간을 투자할 가치가 없다면 포크를 유지하는 게 좋습니다. 그리고 문서가 부족하다고 느껴질 때는 Empira의 별도 샘플 저장소를 참고하세요. 폴더와 파일 모두 실행 가능한 예제라서 직접 추측하는 것보다 훨씬 효율적입니다.

PDFSharp는 무료인가요? PDFSharp 6.5의 라이선스 변경 사항

대부분의 기간 동안은 그랬습니다. MIT 라이선스가 적용되었기 때문에 거의 제약 없이 상업적으로 사용할 수 있었습니다. 6.2.4 버전을 포함한 모든 릴리스는 여전히 MIT 라이선스를 따릅니다.

6.5.0 버전에서 변경되었습니다. 이제 라이브러리는 이중 라이선스를 사용합니다.

• AGPL(무료) 라이선스입니다. 라이브러리를 사용하기 전에 PdfSharpLicense.SetAgplLicense()를 호출하여 활성화할 수 있습니다. AGPL은 소스 코드를 사용자(네트워크를 통해 소프트웨어와 상호 작용하는 사용자 포함)에게 공개하도록 요구하므로, 폐쇄형 소스 SaaS에는 적합하지 않습니다.
• 상업용 라이선스입니다. 판매업체에서 라이선스 키를 구입하고 PdfSharpLicense.LoadLicense(...) 함수를 사용하여 로드하면 됩니다. 이렇게 하면 AGPL 의무가 해제됩니다.

6.5.0 버전부터는 코드에서 명시적으로 하나를 선택해야 합니다. 7.0 프리뷰 버전도 동일하게 작동합니다.

실제 적용 사례:

• AGPL과 호환되는 오픈 소스 프로젝트는 최신 버전을 무료로 계속 사용할 수 있습니다.
• 클로즈드 소스 제품은 상용 라이선스를 구매하거나 MIT 라이선스가 유지되는 6.2.x 버전을 사용할 수 있습니다. 현재 버전을 유지하면 향후 패치를 받지 못할 수 있으므로, 그 비용을 신중하게 고려해야 합니다.
• 어떤 선택을 하시든, 실제 라이선스 내용을 꼼꼼히 읽고 법무팀의 승인을 받으시기 바랍니다. 본 안내서는 법률 자문이 아닙니다.

PDFSharp의 단점은 무엇이며, 함께 사용하면 좋은 도구는 무엇일까요?

라이브러리는 제 역할을 잘 해냅니다. 다만 그 역할이 한정적이고, 모든 포럼 게시글에서 똑같은 부족한 점들이 지적됩니다.

• PDFSharp는 HTML을 PDF로 변환하지 않습니다. PDFSharp는 HTML이나 CSS를 렌더링하지 않습니다. 커뮤니티에서 제공하는 추가 기능인 HtmlRenderer.PdfSharp가 있지만 HTML 4.01 및 CSS 레벨 2만 지원하므로 flexbox나 grid를 사용하는 최신 레이아웃은 제대로 표시되지 않습니다. HTML 템플릿이 필요한 팀은 일반적으로 헤드리스 브라우저 렌더러를 사용하는 것이 좋습니다.
• JavaScript를 사용할 수 없습니다. 클라이언트 측에서 생성된 차트나 콘텐츠는 캡처할 수 없습니다.
• 이미지 렌더링은 지원하지 않습니다. PDFsharp는 PDF 페이지를 PNG 형식의 썸네일 또는 미리보기 이미지로 변환할 수 없습니다. 이를 위해서는 별도의 래스터라이저가 필요합니다.
• 텍스트 추출 기능이 제한적입니다. 콘텐츠 스트림을 탐색할 수는 있지만, 위치 정보와 함께 정제된 텍스트를 반환하는 고급 API는 제공되지 않습니다. PdfPig는 텍스트를 읽고 추출하기 위해 특별히 개발된 별도의 오픈 소스 라이브러리입니다.
• 부분적인 양식 지원만 제공합니다. 간단한 AcroForm 작성은 가능하지만, 스크립트가 포함된 복잡한 양식은 문제가 될 수 있습니다.
• 테이블을 사용하려면 MigraDoc이 필요합니다. 일반 PDFsharp를 사용하면 각 행의 높이를 직접 계산해야 합니다.

그렇다고 해서 나쁜 선택이라는 뜻은 아닙니다. 송장, 명세서, 라벨, 증명서와 같은 데이터 기반 문서는 이 도구의 강점이며, 용량도 매우 작습니다. 하지만 웹 페이지를 픽셀 단위로 완벽하게 복제하는 것은 그렇지 않습니다.

PDFsharp를 이용한 암호화폐 송장 및 결제 영수증 발행

PDFsharp로 가장 많이 만드는 문서는 아마도 영수증일 겁니다. 암호화폐 영수증은 카드 영수증보다 약간 더 복잡합니다. 하지만 좋은 소식은 결제 상태가 변경될 때 전송되는 HTTP 콜백인 웹훅에 데이터가 전달되면 모든 데이터를 얻을 수 있다는 것입니다. 추가로 찾아볼 필요가 없습니다.

제가 하나에 적을 내용은 다음과 같습니다.

• 주문 또는 송장 ID와 판매자 정보
• 결제 시점의 암호화폐 금액과 해당 금액에 상응하는 법정화폐 금액
• 코인과 네트워크 (예: 트론의 USDT와 이더리움의 USDT)
• 거래 해시값이 제공되므로 고객은 블록 탐색기에서 이를 확인할 수 있습니다.
• 단축된 수신 지갑 주소와 확인 시간
• 거래 내역이나 송장 페이지로 연결되는 QR 코드

해시값과 주소에는 고정폭 글꼴을 사용하세요. 고객은 글자를 하나씩 자세히 보기 때문에 Arial 글꼴에서는 숫자 0과 대문자 O가 쌍둥이처럼 보입니다. 해시값이 너무 넓으면 줄 바꿈을 하세요. 6pt 글꼴은 전혀 도움이 되지 않습니다. 글꼴을 파일에 포함시키고, 주문서와 함께 저장한 다음, 회계 담당자가 영수증을 요구할 경우 서명하세요.

위에서 설명한 것들은 실제로 결제를 받는 과정을 다루지 않습니다. 결제 처리를 위해서는 Plisio 같은 게이트웨이를 사용해야 합니다. Plisio는 BTC, USDT를 비롯한 다양한 코인을 결제 수단으로 받아들이고, 송장을 생성하며, 상태가 변경될 때마다 사용자의 엔드포인트를 호출합니다. 사용자의 핸들러는 MigraDoc에 페이로드를 전달하고, 구매자는 결제 완료 페이지에서 로고가 인쇄된 영수증을 받게 됩니다.

결론

제가 PDFsharp를 계속 사용하는 이유는 단 하나입니다. 용량이 작고 눈에 거슬리지 않기 때문입니다. Core 빌드는 .NET이 실행되는 모든 환경에서 작동하며, 캔버스가 충분하지 않을 때는 MigraDoc이 레이아웃 작업을 처리합니다. 초기에 결정해야 할 세 가지는 어떤 빌드를 사용할지, 글꼴을 어떻게 로드할지, 그리고 6.5 버전부터 AGPL 라이선스를 사용할지입니다. 웹 페이지가 아닌 인쇄용 데이터를 사용한다면 오랫동안 문제없이 사용할 수 있을 것입니다.

Lena Hartmann

Lena Hartmann is a freelance tech writer and software engineer with over 9 years of experience in backend development and 5 years of hands-on work with smart contracts on Ethereum and other EVM chains. She writes about programming fundamentals, algorithms, compilers, and developer tooling, from beginner coding challenges to time complexity and blockchain infrastructure. Her guides explain technical concepts through working code and practical examples.