从ActivePDF迁移到 IronPDF：完整的 C# 迁移指南。

ActivePDF 长期以来一直是 .NET 开发人员可靠的 PDF 操作工具包。 然而，自从被福昕收购后，许多开发团队都面临着平台未来发展方向、License 条款和持续创新的不确定性。 本指南提供了从ActivePDF到IronPDF的全面、逐步的迁移路径--IronPDF 是一个现代化的、积极维护的 .NET PDF 库，完全支持从 .NET Framework 4.6.2 到 .NET 9 及更高版本。

为什么要从ActivePDF迁移？ 福昕软件收购ActivePDF后，给在 .NET 应用程序中构建 PDF 生成和处理解决方案的开发人员带来了一些挑战。 ### 不确定的产品未来 ActivePDF 在福昕所有权下的过渡引发了对该工具包长期发展轨迹的合理质疑。 依赖ActivePDF的开发人员面临着该库成为支持减少和创新停滞的传统产品的潜在风险。 对于计划将项目延长到 2025 年和 2026 年的团队来说，这种不确定性会带来巨大的技术风险。 ### 许可复杂性 收购带来了许可方面的不确定性，可能会使部署复杂化。ActivePDF传统的机器锁定许可模式在现代云和容器环境中会产生摩擦，在这种环境中，应用程序会在基础设施上动态扩展。 ### 传统架构模式 ActivePDF 的架构反映了以有状态工具包模式为中心的旧设计理念。 `OpenOutputFile`/`CloseOutputFile`工作流需要明确的文件句柄管理，这与现代 C# 的约定不一致，如果处理不慎，可能会引入资源管理问题。 ### 安装和配置开销 与当代基于 NuGet 的软件包管理不同，ActivePDF 在实例化工具包时通常需要手动引用 DLL 和显式路径配置--这种模式增加了入门的摩擦，并使 CI/CD 管道复杂化。 ##ActivePDF与 IronPDF：主要区别 在深入了解迁移过程之前，了解ActivePDF和IronPDF之间的根本区别有助于为所需的代码更改设定预期。 |方面|ActivePDF|IronPDF| |--------|-----------|---------| |**公司状态**|被福昕软件收购（前途未卜）|独立、清晰的开发路线图| |**安装**|手动 DLL 引用|简单的 NuGet 软件包打开输出文件/<代码>关闭输出文件ChromePdfRenderer + <代码>PdfDocument打开输出文件()/<代码>关闭输出文件()SaveAs()NewPage()方法|从 HTML 自动生成|删除页面创建调用| |返回值|整数错误代码|例外情况|实施 try/catch| |页面大小单位|点数（612x792 = 字母）|枚举或毫米|更新测量| ### 前提条件 确保您的环境符合这些要求： - .NET Framework 4.6.2+ 或 .NET Core 3.1 / .NET 5-9 - Visual Studio 2019+ 或 JetBrains Rider - 访问 NuGet 包管理器 -IronPDF许可证密钥（可在[ironpdf.com](https://ironpdf.com/licensing/)免费试用） ## 逐步迁移过程 ### 步骤 1：更新 NuGet 软件包 移除ActivePDF软件包并安装 IronPDF： ```bash # RemoveActivePDFpackage dotnet remove package APToolkitNET # Install IronPDF dotnet add package IronPdf ``` 也可通过 Visual Studio 软件包管理器控制台进行翻译： ```powershell Uninstall-Package APToolkitNET Install-Package IronPdf ``` 对于手动引用 DLL 的项目，请从 `.csproj` 文件中删除引用： ```xml path\to\APToolkitNET.dll ``` ### 步骤 2：配置许可证密钥 在启动应用程序时，在进行任何 PDF 操作前，添加IronPDF许可证密钥： ```csharp // Add at application startup (Program.cs or Startup.cs) IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"; // Verify license status bool isLicensed = IronPdf.License.IsLicensed; ``` ### 步骤 3：更新命名空间引用 在解决方案中执行全局查找和替换： |查找|替换为| |------|--------------| |<代码>使用 ActivePDF.Toolkit;使用 IronPdf;使用 APToolkitNET；使用 IronPdf;使用 APToolkitNET.PDFObjects;使用 IronPdf;使用 APToolkitNET.Common；使用 IronPdf;新工具包()new ChromePdfRenderer()toolkit.OpenOutputFile(路径)toolkit.CloseOutputFile()toolkit.AddHTML(html)renderer.RenderHtmlAsPdf(html)toolkit.AddURL(url)renderer.RenderUrlAsPdf(url)toolkit.SaveAs(路径)pdf.SaveAs(路径)toolkit.OpenInputFile(路径)PdfDocument.FromFile(路径)toolkit.AddPDF(路径)PdfDocument.Merge()toolkit.GetPageCount()pdf.PageCounttoolkit.GetText()pdf.ExtractAllText()toolkit.SetPageSize(612, 792)RenderingOptions.PaperSize = PdfPaperSize.Lettertoolkit.SetOrientation("横向")RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscapetoolkit.SetMargins(t, b, l, r)RenderingOptions.MarginTop/Bottom/Left/Righttoolkit.Encrypt(password)pdf.SecuritySettings.OwnerPasswordtoolkit.SetUserPassword(pwd)pdf.SecuritySettings.UserPasswordtoolkit.SetPermissions(flags)pdf.SecuritySettings.AllowUserXxxtoolkit.AddWatermark(text)pdf.ApplyWatermark(html)

Hello World

"; if (toolkit.OpenOutputFile("output.pdf") == 0) { toolkit.AddHTML(htmlContent); toolkit.CloseOutputFile(); Console.WriteLine("PDF created successfully"); } } } ``` **IronPDF 实现：** ```csharp // NuGet: Install-Package IronPdf using IronPdf; using System; class Program { static void Main() { var renderer = new ChromePdfRenderer(); string htmlContent = "

Hello World

"; var pdf = renderer.RenderHtmlAsPdf(htmlContent); pdf.SaveAs("output.pdf"); Console.WriteLine("PDF created successfully"); } } ``` IronPDF 方法消除了显式文件句柄管理，同时提供了更简洁、可读性更强的代码。 对于高级 [HTML 转 PDF 场景](https://ironpdf.com/how-to/html-file-to-pdf/)，IronPDF 的 `ChromePdfRenderer` 使用基于 Chromium 的渲染引擎，支持像素级完美 CSS 和 JavaScript。 ### URL到PDF转换 将网页截取为 PDF 文档也遵循类似的现代化模式。 **ActivePDF 实现：** ```csharp using ActivePDF.Toolkit; using System; class Program { static void Main() { Toolkit toolkit = new Toolkit(); string url = "https://www.example.com"; if (toolkit.OpenOutputFile("webpage.pdf") == 0) { toolkit.AddURL(url); toolkit.CloseOutputFile(); Console.WriteLine("PDF from URL created successfully"); } } } ``` **IronPDF 实现：** ```csharp using IronPdf; using System; class Program { static void Main() { var renderer = new ChromePdfRenderer(); string url = "https://www.example.com"; var pdf = renderer.RenderUrlAsPdf(url); pdf.SaveAs("webpage.pdf"); Console.WriteLine("PDF from URL created successfully"); } } ``` ### 合并多个 PDF 文件 将多个 PDF 文档合并为一个文件展示了IronPDF的文档操作功能方法。 **ActivePDF 实现：** ```csharp using ActivePDF.Toolkit; using System; class Program { static void Main() { Toolkit toolkit = new Toolkit(); if (toolkit.OpenOutputFile("merged.pdf") == 0) { toolkit.AddPDF("document1.pdf"); toolkit.AddPDF("document2.pdf"); toolkit.CloseOutputFile(); Console.WriteLine("PDFs merged successfully"); } } } ``` **IronPDF 实现：** ```csharp using IronPdf; using System; using System.Collections.Generic; class Program { static void Main() { var pdf1 = PdfDocument.FromFile("document1.pdf"); var pdf2 = PdfDocument.FromFile("document2.pdf"); var merged = PdfDocument.Merge(pdf1, pdf2); merged.SaveAs("merged.pdf"); Console.WriteLine("PDFs merged successfully"); } } ``` 有关包括选择性页面提取在内的更高级合并场景，请参阅 [IronPDF合并文档](https://ironpdf.com/how-to/merge-split-pdfs/)。 ### 添加页眉和页脚 **ActivePDF 实现：** ```csharp using ActivePDF.Toolkit; public void CreatePdfWithHeaderFooter(string html, string outputPath) { Toolkit toolkit = new Toolkit(); if (toolkit.OpenOutputFile(outputPath) == 0) { toolkit.SetHeader("My Document", 12, "Arial"); toolkit.SetFooter("Page %p of %P", 10, "Arial"); toolkit.AddHTML(html); toolkit.CloseOutputFile(); } } ``` **IronPDF 实现：** ```csharp using IronPdf; public void CreatePdfWithHeaderFooter(string html, string outputPath) { var renderer = new ChromePdfRenderer(); renderer.RenderingOptions.TextHeader = new TextHeaderFooter { CenterText = "My Document", FontSize = 12, FontFamily = "Arial" }; renderer.RenderingOptions.TextFooter = new TextHeaderFooter { CenterText = "Page {page} of {total-pages}", FontSize = 10, FontFamily = "Arial" }; using var pdf = renderer.RenderHtmlAsPdf(html); pdf.SaveAs(outputPath); } ``` IronPdf 支持基于文本的页眉和页脚[HTML页眉和页脚](https://ironpdf.com/how-to/headers-and-footers/)，提供完全灵活的设计。 ### 密码保护和安全性 **ActivePDF 实现：** ```csharp using ActivePDF.Toolkit; public void ProtectPdf(string inputPath, string outputPath, string password) { Toolkit toolkit = new Toolkit(); if (toolkit.OpenInputFile(inputPath) == 0) { toolkit.Encrypt(password); toolkit.SetUserPassword(password); toolkit.SetPermissions(4); // Print only toolkit.SaveAs(outputPath); toolkit.CloseInputFile(); } } ``` **IronPDF 实现：** ```csharp using IronPdf; public void ProtectPdf(string inputPath, string outputPath, string password) { using var pdf = PdfDocument.FromFile(inputPath); pdf.SecuritySettings.OwnerPassword = password; pdf.SecuritySettings.UserPassword = password; pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.FullPrintRights; pdf.SecuritySettings.AllowUserCopyPasteContent = false; pdf.SecuritySettings.AllowUserEdits = PdfEditSecurity.NoEdit; pdf.SaveAs(outputPath); } ``` IronPdf 的 [ 安全设置 API](https://ironpdf.com/how-to/pdf-encryption-and-decryption/) 使用强类型枚举而非整数标志对文档权限进行细粒度控制。 ### 文本提取 **ActivePDF 实现：** ```csharp using ActivePDF.Toolkit; public string ExtractText(string pdfPath) { Toolkit toolkit = new Toolkit(); string text = ""; if (toolkit.OpenInputFile(pdfPath) == 0) { int pageCount = toolkit.GetPageCount(); for (int i = 1; i <= pageCount; i++) { text += toolkit.GetTextFromPage(i) + "\n"; } toolkit.CloseInputFile(); } return text; } ``` **IronPDF 实现：** ```csharp using IronPdf; public string ExtractText(string pdfPath) { using var pdf = PdfDocument.FromFile(pdfPath); return pdf.ExtractAllText(); } ``` IronPDF 实现将文本提取从多行减少到单个方法调用。 ### 添加水印 **ActivePDF 实现：** ```csharp using ActivePDF.Toolkit; public void AddWatermark(string inputPath, string outputPath, string watermarkText) { Toolkit toolkit = new Toolkit(); if (toolkit.OpenInputFile(inputPath) == 0) { int pageCount = toolkit.GetPageCount(); for (int i = 1; i <= pageCount; i++) { toolkit.SetPage(i); toolkit.AddWatermark(watermarkText, 45, 0.5f); } toolkit.SaveAs(outputPath); toolkit.CloseInputFile(); } } ``` **IronPDF 实现：** ```csharp using IronPdf; public void AddWatermark(string inputPath, string outputPath, string watermarkText) { using var pdf = PdfDocument.FromFile(inputPath); pdf.ApplyWatermark( $"

{watermarkText}

", rotation: 45, opacity: 50); pdf.SaveAs(outputPath); } ``` IronPdf 的[基于 HTML 的水印](https://ironpdf.com/how-to/background-foreground/)可通过 CSS 风格实现完全的设计控制，无需逐页迭代。 ## ASP.NET Core 集成 现代网络应用程序从 IronPdf 更简洁的集成模式中获益匪浅。 **ActivePDF模式：** ```csharp [HttpPost] public IActionResult GeneratePdf([FromBody] ReportRequest request) { Toolkit toolkit = new Toolkit(); if (toolkit.OpenOutputFile("temp.pdf") == 0) { toolkit.AddHTML(request.Html); toolkit.CloseOutputFile(); byte[] bytes = System.IO.File.ReadAllBytes("temp.pdf"); return File(bytes, "application/pdf", "report.pdf"); } return BadRequest("PDF generation failed"); } ``` **IronPdf模式：** ```csharp [HttpPost] public IActionResult GeneratePdf([FromBody] ReportRequest request) { var renderer = new ChromePdfRenderer(); using var pdf = renderer.RenderHtmlAsPdf(request.Html); return File(pdf.BinaryData, "application/pdf", "report.pdf"); } ``` IronPDF 不需要临时文件，直接从内存返回 PDF 二进制数据。 ### Web 应用程序的同步支持 ActivePDF 缺乏本地异步支持。IronPDF提供可扩展网络应用程序所必需的全部异步/等待功能： ```csharp using IronPdf; public async Task GeneratePdfAsync(string html) { var renderer = new ChromePdfRenderer(); using var pdf = await renderer.RenderHtmlAsPdfAsync(html); return pdf.BinaryData; } ``` ### 依赖注入配置 对于 .NET 6+ 应用程序，请在 DI 容器中注册IronPDF服务： ```csharp // Program.cs (.NET 6+) builder.Services.AddSingleton(); // Service wrapper public interface IPdfService { Task GeneratePdfAsync(string html); Task GeneratePdfFromUrlAsync(string url); } public class IronPdfService : IPdfService { private readonly ChromePdfRenderer _renderer; public IronPdfService() { _renderer = new ChromePdfRenderer(); _renderer.RenderingOptions.PaperSize = PdfPaperSize.A4; } public async Task GeneratePdfAsync(string html) { using var pdf = await _renderer.RenderHtmlAsPdfAsync(html); return pdf.BinaryData; } public async Task GeneratePdfFromUrlAsync(string url) { using var pdf = await _renderer.RenderUrlAsPdfAsync(url); return pdf.BinaryData; } } ``` ## 错误处理迁移 ActivePDF 使用整数返回代码，需要查找表。 IronPdf 使用现代异常处理技术： **ActivePDF 错误处理：** ```csharp Toolkit toolkit = new Toolkit(); int result = toolkit.OpenOutputFile(path); if (result != 0) { // Error - need to look up error code Console.WriteLine($"Error code: {result}"); } ``` **IronPDF 错误处理：** ```csharp try { var renderer = new ChromePdfRenderer(); using var pdf = renderer.RenderHtmlAsPdf(html); pdf.SaveAs(path); } catch (IronPdf.Exceptions.IronPdfProductException ex) { Console.WriteLine($"IronPDF Error: {ex.Message}"); } catch (Exception ex) { Console.WriteLine($"General Error: {ex.Message}"); } ``` ## 性能优化技巧 ### 重复使用渲染器实例 创建一个新的 `ChromePdfRenderer` 有初始化开销。 对于批量操作，请重复使用单个实例： ```csharp var renderer = new ChromePdfRenderer(); foreach (var html in htmlList) { using var pdf = renderer.RenderHtmlAsPdf(html); pdf.SaveAs($"output_{i}.pdf"); } ``` ### 在 Web 应用程序中使用异步 对于 ASP.NET Core 应用程序，异步 PDF 生成提高了吞吐量： ```csharp public async Task GenerateReport() { var renderer = new ChromePdfRenderer(); using var pdf = await renderer.RenderHtmlAsPdfAsync(html); return File(pdf.BinaryData, "application/pdf"); } ``` ### 正确的资源处置 始终使用 `using` 语句以确保正确的清理： ```csharp using var pdf = renderer.RenderHtmlAsPdf(html); return pdf.BinaryData; ``` ### 图像压缩 通过图像压缩减少输出文件大小： ```csharp using var pdf = renderer.RenderHtmlAsPdf(html); pdf.CompressImages(85); // 85% quality pdf.SaveAs("compressed.pdf"); ``` ## 常见迁移问题的故障排除 ### 问题：页面大小差异 ActivePDF 使用点（612x792 = Letter），而IronPDF使用枚举或毫米： ```csharp // ActivePDF: Points toolkit.SetPageSize(612, 792); // IronPDF: Use enum renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter; // Or custom in mm: renderer.RenderingOptions.SetCustomPaperSizeInMillimeters(215.9, 279.4); ``` ### 问题：缺少 CloseOutputFile 等价函数 IronPDF 使用现代范式，没有明确的文件句柄管理： ```csharp // ActivePDF toolkit.OpenOutputFile(path); toolkit.AddHTML(html); toolkit.CloseOutputFile(); // Required! //IronPDF- no open/close needed using var pdf = renderer.RenderHtmlAsPdf(html); pdf.SaveAs(path); // 'using' handles cleanup ``` ### 问题：PDF 渲染空白 如果依赖 JavaScript 的内容呈现空白，请配置呈现延迟： ```csharp var renderer = new ChromePdfRenderer(); renderer.RenderingOptions.WaitFor.RenderDelay(2000); // Or wait for element: renderer.RenderingOptions.WaitFor.HtmlElementById("content-loaded"); ``` ### 问题：CSS/ 图像无法加载 为相对路径解析配置基本 URL： ```csharp renderer.RenderingOptions.BaseUrl = new Uri("https://yourdomain.com/assets/"); ``` ## 迁移后核对表 完成代码迁移后，请验证以下内容： - [ ] 运行所有现有的单元测试和集成测试 - [ ] 将 PDF 输出与以前的版本进行直观比较 - [ ] 在暂存环境中测试所有 PDF 工作流程 - [ ] 验证许可是否正常工作（IronPdf.License.IsLicensed