Hướng dẫn sử dụng PDFsharp: Tạo tệp PDF với MigraDoc và PdfSharpCore

PDFsharp là một thư viện mã nguồn mở dành cho .NET để tạo và chỉnh sửa tài liệu PDF từ mã C#. Bạn vẽ văn bản, đường kẻ và hình ảnh lên một trang, gọi hàm Save, và bạn sẽ có một tệp PDF. Không cần công cụ trình duyệt, không cần mã nhị phân gốc. Dự án này ra đời từ năm 2005, và rất nhiều hóa đơn, báo cáo và chứng chỉ được tạo ra từ các hệ thống phụ trợ .NET hiện nay vẫn sử dụng nó.

Tôi viết bài này dành cho các nhà phát triển cần lưu trữ PDF trên máy chủ và muốn biết mình cần chuẩn bị những gì. Chúng ta sẽ tìm hiểu cách PDFsharp và MigraDoc hoạt động cùng nhau, nên cài đặt bản dựng nào, tạo một tệp PDF hoạt động đầu tiên, vấn đề về phông chữ trên Linux, thay đổi giấy phép gần đây và thời điểm bạn nên chọn một phần mềm khác.

PDFsharp là gì và nó có thể làm được những gì?

Đằng sau thư viện PDFsharp là empira Software GmbH, một công ty nhỏ của Đức đã duy trì hoạt động của nó trong gần hai mươi năm. Hầu hết thời gian của bạn sẽ dành cho một lớp duy nhất, XGraphics. Nếu bạn đã từng vẽ đồ họa trong WinForms với System.Drawing.Graphics, bạn sẽ cảm thấy quen thuộc chỉ trong vòng mười phút: phông chữ, cọ vẽ, tọa độ x và y, bắt đầu thôi.

Khi mở hộp, bạn sẽ nhận được:

• Tạo tài liệu PDF từ đầu với văn bản, hình dạng vector, đường kẻ và hình ảnh.
• Mở các tệp PDF hiện có và thêm nội dung vào các trang của chúng, chẳng hạn như tem, hình mờ hoặc số trang.
• Ghép và tách tài liệu bằng cách nhập các trang từ tệp này sang tệp khác.
• Nhúng và trích xuất tập hợp con các phông chữ để tệp tin hiển thị giống nhau trên mọi máy tính.
• Thêm dấu trang, liên kết và siêu dữ liệu tài liệu như tiêu đề, tác giả và từ khóa.
• Bảo vệ tập tin bằng mật khẩu và cờ quyền truy cập
• Ký tài liệu điện tử (từ phiên bản 6.2 trở lên)

Quá trình triển khai khá nhàm chán, theo nghĩa tích cực. Mọi thứ đều là mã được quản lý, vì vậy người phụ trách vận hành của bạn sẽ không bao giờ phải cài đặt Chrome không giao diện người dùng lên máy tính hoặc tìm kiếm DLL Ghostscript lúc 2 giờ sáng. Bạn chỉ cần tham chiếu một gói NuGet, đẩy lên, xong.

Vấn đề nằm ở chỗ này. Bạn chỉ có một khung vẽ và không hơn không kém. Đoạn văn dài chạm lề dưới? Đó là vấn đề của bạn. Bảng dữ liệu vượt quá trang đầu tiên? Cũng là vấn đề của bạn, trừ khi bạn sử dụng MigraDoc.

PDFsharp và MigraDoc: Bạn cần lớp nào?

Cùng một nhà cung cấp, cùng lịch phát hành, nhưng công việc lại rất khác nhau. MigraDoc Foundation nằm ở tầng trên của PDFsharp. Thay vì chỉ định vị trí đặt chuỗi ký tự, bạn cung cấp cho nó các phần, đoạn văn, bảng, tiêu đề, chân trang, kiểu định dạng và cả biểu đồ, và nó sẽ tự động xác định vị trí của mọi thứ. Kết quả đầu ra là một tệp PDF. Hoặc RTF, dành cho người đồng nghiệp luôn muốn mở mọi thứ bằng Word.

Tóm lại, cách dùng PDFsharp là "đặt đoạn văn bản này tại tọa độ x=40, y=120". Còn MigraDoc thì là "đây là ba mươi dòng và một tiêu đề lặp lại, bạn tự sắp xếp các trang".

Các dự án thực tế thường kết hợp cả hai. Văn bản chính được tạo thông qua MigraDoc, bìa vẽ tay hoặc tem trên tệp PDF của nhà cung cấp thông qua lớp dưới. Dù sao thì bạn cũng không thể tránh khỏi việc cài đặt PDFsharp, vì gói MigraDoc đã bao gồm nó như một phần phụ thuộc.

Giải thích về các bản dựng PDFsharp: Bản dựng cốt lõi, GDI+ và WPF

Người mới thường gặp khó khăn khi tìm kiếm gói tiếp theo trong NuGet. PDFsharp 6 có ba phiên bản, mỗi phiên bản đều có phiên bản MigraDoc tương ứng.

Các gói hiện tại nhắm đến .NET 8, 9 và 10, cùng với .NET Standard 2.0 và .NET Framework 4.6.2. Vì vậy, hầu như mọi thứ vẫn đang được phát triển đều được hỗ trợ, từ một công cụ WinForms cũ kỹ đến một API ASP.NET Core hoàn toàn mới.

Ứng dụng dòng lệnh, API web, Docker, Azure Functions, bất cứ thứ gì trên Linux? Bản dựng cốt lõi. GDI+ hoặc WPF chỉ có ý nghĩa đối với ứng dụng máy tính để bàn Windows khi bạn muốn sử dụng phông chữ hệ thống hoặc xem trước trong một điều khiển gốc. Có người trên Stack Overflow từng hỏi liệu ứng dụng dòng lệnh của họ có cần phiên bản WPF hay không. Câu trả lời là không cần.

Hướng dẫn cài đặt PDFsharp từ NuGet trong Visual Studio

Bạn vẫn sẽ thấy những bài đăng trên diễn đàn từ thời WinForms hướng dẫn bạn tải file ZIP, tìm file DLL và tự thêm tham chiếu. Hãy bỏ qua chúng. Cài đặt PDFsharp thông qua NuGet; trình quản lý gói sẽ theo dõi các phiên bản nên bạn không cần phải làm điều đó.

1. Mở giải pháp của bạn trong Visual Studio và nhấp chuột phải vào dự án trong Solution Explorer.
2. Chọn Quản lý gói NuGet , chuyển sang tab Duyệt và tìm kiếm "PDFsharp".
3. Chọn PDFsharp (phiên bản Core) hoặc PDFsharp-MigraDoc nếu bạn cũng cần chức năng bố cục tài liệu. Kiểm tra xem nhà phát hành có phải là empira Software GmbH hay không.
4. Nhấp vào Cài đặt và chấp nhận yêu cầu cấp phép.
5. Hãy biên dịch dự án một lần để xác nhận gói đã được khôi phục chính xác.

Người dùng máy tính có thể bỏ qua thao tác nhấp chuột:

bash dotnet add package PDFsharp dotnet add package PDFsharp-MigraDoc

Trong Package Manager Console, lệnh tương tự là Install-Package PDFsharp. Và xin đừng trộn lẫn các bản dựng. Tôi đã chứng kiến một nhóm mất cả buổi chiều vì xung đột kiểu dữ liệu do một dự án tham chiếu đến PDFsharp trong khi dự án kế bên lại sử dụng PDFsharp-GDI.

Tạo tài liệu PDF đầu tiên của bạn với PDFsharp bằng C

Dưới đây là chương trình nhỏ nhất tạo ra tệp PDF một trang. Chương trình này chạy trên bản dựng Core trên bất kỳ hệ điều hành nào, miễn là đã thiết lập trình phân giải phông chữ (phần tiếp theo).

```csharp
Sử dụng PdfSharp.Drawing;
Sử dụng PdfSharp.Pdf;

// PDFsharp 6.5 trở lên yêu cầu chọn giấy phép trước khi sử dụng lần đầu.
PdfSharpLicen.SetAgplLicen();

var document = new PdfDocument();
document.Info.Title = "Xin chào PDFsharp";

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

var font = new XFont("Arial", 20, XFontStyleEx.Bold);
gfx.DrawString("Xin chào, PDFsharp!", font, XBrushes.Black,
new XRect(0, 0, page.Width.Point, page.Height.Point),
XStringFormats.Center);

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

Mọi chương trình PDFsharp đều tuân theo quy trình này: tài liệu, trang, XGraphics, vẽ, lưu. Đơn vị là điểm (1/72 inch) và gốc tọa độ nằm ở góc trên bên trái. Trên phiên bản 6.2.x, hãy xóa dòng giấy phép. API đó chỉ xuất hiện trong phiên bản 6.5.0.

Và đây là phiên bản của MigraDoc:

```csharp
sử dụng MigraDoc.DocumentObjectModel;
Sử dụng MigraDoc.Rendering;

var doc = new Document();
Section section = doc.AddSection();
section.AddParagraph("Xin chào, MigraDoc!");

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

Không có tọa độ nào cả. Cứ viết 500 đoạn văn vào đó, bạn sẽ nhận được số trang tương ứng, mà không cần mã phân trang nào.

Phông chữ trong bản dựng lõi PDFsharp: Vấn đề về bộ giải quyết

Hỏi xung quanh và bạn sẽ thấy phàn nàn nhiều nhất về phông chữ. Các bản dựng GDI+ và WPF chỉ đọc các phông chữ TrueType đã được cài đặt từ Windows. Bản dựng Core không thể giả định bất cứ điều gì, bởi vì một container Linux nhỏ gọn thường không có bất kỳ phông chữ nào có thể sử dụng được. Vì vậy, lần triển khai Docker đầu tiên thường kết thúc bằng một ngoại lệ về việc không tìm thấy phông chữ phù hợp.

Giải pháp là một bộ phân giải phông chữ, một lớp triển khai giao diện IFontResolver. Nó có hai phương thức:

• ResolveTypeface ánh xạ họ và kiểu chữ được yêu cầu (ví dụ: "Arial", in đậm) tới tên kiểu chữ.
• GetFont trả về các byte thô của tệp TTF cho tên phông chữ đó.

Đăng ký nó một lần khi khởi động thông qua GlobalFontSettings.FontResolver, trước khi XFont đầu tiên được tạo.

```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();
```

Những điều cần biết trước khi bạn tự mình gặp phải:

• Hãy lưu trữ các tệp TTF của bạn trong thư mục Fonts trong dự án và thiết lập để chúng được sao chép vào thư mục đầu ra, hoặc nhúng chúng dưới dạng tài nguyên để ảnh container luôn có sẵn chúng.
• Phiên bản 6.2.0 đã loại bỏ CoreBuildFontResolver cũ. Trên Windows hoặc WSL2, bạn có thể khôi phục hành vi tương tự bằng GlobalFontSettings.UseWindowsFontsUnderWindows, nhưng điều này không có tác dụng gì trên Linux hoặc macOS.
• Kho lưu trữ mẫu chính thức bao gồm một SubstitutingFontResolver mà bạn có thể sao chép để làm điểm xuất phát.
• Hãy kiểm tra giấy phép phông chữ trước khi nhúng một kiểu chữ thương mại vào các tệp được tạo ra. Các phông chữ mã nguồn mở như Inter, Roboto hoặc Noto hoàn toàn tránh được vấn đề này.

Sau khi cài đặt trình phân giải, kết quả hiển thị giống hệt nhau trên Windows, Linux và macOS.

Hợp nhất, ký tên và bảo mật tệp với PDFsharp 6

Nhiều nhóm không bao giờ tạo tài liệu từ đầu. Họ sử dụng thư viện để ghép, đóng dấu hoặc khóa các tệp đã tồn tại. Việc hợp nhất chỉ mất vài dòng: mở từng nguồn ở chế độ nhập và sao chép các trang.

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

Việc chia nhỏ cũng tương tự như vòng lặp ngược, mỗi trang hoặc mỗi vùng dữ liệu sẽ có một tệp đầu ra riêng. Để bảo vệ, thuộc tính document.SecuritySettings yêu cầu mật khẩu người dùng, mật khẩu chủ sở hữu và các cờ quyền (in, sao chép văn bản, v.v.).

Hai tính năng được yêu cầu từ lâu cuối cùng đã xuất hiện trong phiên bản 6.2:

• Chữ ký số dựa trên CMS. Trình ký mặc định được cung cấp trong một assembly PDFsharp.Cryptography riêng biệt, và bạn có thể tích hợp trình ký của riêng mình bằng cách triển khai giao diện IDigitalSigner. Hỗ trợ máy chủ dấu thời gian hoạt động trên các phiên bản .NET hiện đại nhưng không hoạt động trên bản dựng .NET Framework.
• Định dạng PDF/A dùng để lưu trữ. Tài liệu chính thức mô tả chức năng này hoạt động "với một số hạn chế" và vẫn đang trong quá trình phát triển, vì vậy hãy kiểm tra kết quả bằng trình kiểm tra PDF/A trước khi dựa vào nó để đáp ứng các yêu cầu tuân thủ.

Bản phát hành đó cũng mang đến các biểu tượng cảm xúc màu sắc và triển khai MD5 được quản lý, điều này rất quan trọng nếu bạn chạy theo quy tắc FIPS hoặc trong Blazor.

Kho lưu trữ PDFsharp, các phiên bản phân nhánh của PdfSharpCore và các phiên bản 1.x

Tìm kiếm PDFsharp trên GitHub và bạn sẽ thấy một số dự án có tên gần như giống hệt. Lý do là vì lịch sử đã cũ.

Dòng phần mềm cũ 1.x (1.50, 1.51) chỉ chạy trên .NET Framework. Khi .NET Core ra đời, mọi người không muốn chờ đợi nên đã tự mình chuyển đổi nó. PdfSharpCore, do Stefan Steiger khởi xướng và sau đó được các nhánh khác tiếp tục phát triển, là phiên bản được nhiều người biết đến nhất. Nó đã loại bỏ GDI+ và giúp mã nguồn chạy trên Linux nhiều năm trước khi phát hành chính thức.

Rồi PDFsharp 6 ra đời: một bản viết lại hoàn chỉnh trên nền tảng .NET hiện đại với bản dựng Core chính thức đa nền tảng. Các phiên bản phái sinh trước đó hầu như mất đi lý do tồn tại.

Vậy, chủ đề "PdfSharp vs PdfSharpCore" cứ liên tục xuất hiện trên Reddit? Đây là dự án mới, có các gói chính thức. Chỉ nên giữ lại bản sao (fork) nếu mã nguồn cũ đã dựa vào nó và việc chuyển đổi không đáng tốn nhiều thời gian vào lúc này. Và khi thấy tài liệu còn sơ sài, hãy xem kho lưu trữ mẫu riêng của empira. Các thư mục và tệp của nó chứa các ví dụ có thể chạy được, tốt hơn là phải đoán mò.

PDFsharp có miễn phí không? Những thay đổi về giấy phép trong PDFsharp 6.5

Trong phần lớn thời gian tồn tại của nó, đúng vậy. Nó được cấp phép theo giấy phép MIT, có nghĩa là được sử dụng thương mại gần như không kèm theo bất kỳ điều kiện ràng buộc nào. Mọi phiên bản phát hành cho đến và bao gồm cả phiên bản 6.2.4 đều vẫn được cấp phép như vậy.

Phiên bản 6.5.0 đã thay đổi điều đó. Thư viện hiện được cấp phép kép:

• AGPL (miễn phí). Bạn kích hoạt nó bằng cách gọi PdfSharpLicense.SetAgplLicense() trước khi sử dụng thư viện. AGPL yêu cầu bạn phải cung cấp mã nguồn cho người dùng, bao gồm cả những người dùng tương tác với phần mềm của bạn qua mạng, vì vậy nó không phù hợp với mô hình SaaS mã nguồn đóng.
• Giấy phép thương mại. Bạn mua khóa cấp phép từ nhà cung cấp và tải nó bằng PdfSharpLicense.LoadLicense(...). Điều này loại bỏ các nghĩa vụ của AGPL.

Từ phiên bản 6.5.0 trở đi, mã của bạn phải chọn một tùy chọn một cách rõ ràng. Các bản xem trước 7.0 cũng hoạt động tương tự.

Trên thực tế:

• Các dự án mã nguồn mở tương thích với AGPL có thể tiếp tục sử dụng phiên bản mới nhất miễn phí.
• Các sản phẩm mã nguồn đóng có thể mua giấy phép thương mại hoặc tiếp tục sử dụng phiên bản 6.2.x, vẫn thuộc giấy phép MIT. Việc giữ nguyên phiên bản hiện tại đồng nghĩa với việc bỏ lỡ các bản vá lỗi trong tương lai, vì vậy hãy cân nhắc kỹ lưỡng chi phí này.
• Dù bạn chọn phương án nào, hãy đọc kỹ văn bản giấy phép và yêu cầu nhóm pháp lý của bạn phê duyệt. Hướng dẫn này không phải là lời khuyên pháp lý.

Những hạn chế của PDFsharp và phần mềm nên dùng kèm với nó

Thư viện làm tốt nhiệm vụ của mình. Chỉ có điều phạm vi hoạt động hẹp, và những thiếu sót tương tự lại xuất hiện trong mọi chủ đề thảo luận trên diễn đàn.

• Không thể chuyển đổi HTML sang PDF. PDFsharp không hỗ trợ hiển thị HTML hoặc CSS. Có một tiện ích bổ sung do cộng đồng phát triển, HtmlRenderer.PdfSharp, nhưng chỉ hỗ trợ HTML 4.01 và CSS cấp độ 2, vì vậy các bố cục hiện đại với flexbox hoặc grid sẽ không hoạt động. Các nhóm cần mẫu HTML thường sử dụng trình hiển thị không giao diện người dùng (headless-browser renderer) thay thế.
• Không có JavaScript. Biểu đồ hoặc nội dung được xây dựng ở phía máy khách không thể được thu thập.
• Không thể chuyển đổi sang hình ảnh. PDFsharp không thể chuyển đổi một trang PDF thành ảnh PNG để tạo ảnh thu nhỏ hoặc xem trước. Bạn cần một trình chuyển đổi ảnh raster riêng biệt cho việc đó.
• Khả năng trích xuất văn bản còn hạn chế. Bạn có thể duyệt qua luồng nội dung, nhưng không có API cấp cao nào trả về văn bản sạch kèm vị trí. PdfPig, một thư viện mã nguồn mở riêng biệt, được xây dựng đặc biệt để đọc và trích xuất văn bản.
• Hỗ trợ biểu mẫu một phần. Việc điền biểu mẫu AcroForm đơn giản hoạt động tốt; các biểu mẫu phức tạp có chứa mã lệnh lại là chuyện khác.
• Bảng cần sử dụng MigraDoc. Với PDFsharp thông thường, bạn phải tự tính toán chiều cao của từng hàng.

Điều đó không có nghĩa là nó là một lựa chọn tồi. Các tài liệu dựa trên dữ liệu như hóa đơn, bảng sao kê, nhãn và chứng chỉ chính là thế mạnh của nó, và dung lượng chiếm dụng thì rất nhỏ. Tuy nhiên, việc sao chép chính xác từng pixel của các trang web thì không hề dễ dàng như vậy.

PDFsharp dành cho hóa đơn tiền điện tử và biên lai thanh toán

Biên lai có lẽ là thứ phổ biến nhất mà mọi người tạo ra bằng PDFsharp. Biên lai tiền điện tử phức tạp hơn một chút so với biên lai thẻ. Tin tốt là: một khi cổng thanh toán gửi yêu cầu đến webhook của bạn (một lệnh gọi lại HTTP được gửi khi trạng thái thanh toán thay đổi), bạn sẽ có tất cả dữ liệu. Không cần phải tìm kiếm thêm gì nữa.

Tôi sẽ viết gì lên đó:

• Mã đơn hàng hoặc hóa đơn và thông tin chi tiết của người bán
• Số tiền bằng tiền điện tử và giá trị tương đương bằng tiền pháp định tại thời điểm thanh toán.
• Loại tiền điện tử và mạng lưới (ví dụ: USDT trên TRON so với USDT trên Ethereum)
• Mã băm giao dịch, để khách hàng có thể xác minh trên trình khám phá khối.
• Địa chỉ ví nhận rút gọn và thời gian xác nhận
• Mã QR dẫn đến trang giao dịch hoặc hóa đơn.

Sử dụng phông chữ đơn cách cho mã băm và địa chỉ. Khách hàng sẽ nheo mắt nhìn từng ký tự một, và trong phông Arial, số 0 và chữ O viết hoa trông giống hệt nhau. Nếu mã băm quá rộng, hãy xuống dòng; cỡ chữ 6pt chẳng giúp ích gì cả. Nhúng phông chữ, lưu tệp cùng với đơn đặt hàng và ký tên nếu kế toán của bạn yêu cầu biên lai.

Tất cả những điều đó chưa đề cập đến việc thực sự nhận tiền. Đối với phần đó, bạn sẽ sử dụng một cổng thanh toán như Plisio . Nó chấp nhận BTC, USDT và nhiều loại tiền điện tử khác, tạo hóa đơn và gọi đến điểm cuối của bạn mỗi khi trạng thái thay đổi. Trình xử lý của bạn sẽ chuyển dữ liệu đến MigraDoc và người mua sẽ nhận được biên lai có logo của bạn ngay trên trang cảm ơn.

Phần kết luận

Tôi cứ quay lại dùng PDFsharp vì một lý do: nó nhỏ gọn và không gây vướng víu. Phiên bản Core chạy được ở bất cứ đâu có .NET, và MigraDoc sẽ đảm nhiệm việc bố cục khi canvas không đủ. Ba điều cần giải quyết sớm: phiên bản nào, cách tải font chữ và giấy phép bạn đang sử dụng hiện nay (sau khi 6.5 chuyển sang AGPL). Hãy in dữ liệu, chứ không phải trang web, và nó sẽ đáp ứng được nhu cầu trong nhiều năm.

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.