异常处理

异常处理

本指南展示了 Aspose.PDF FOSS for .NET 如何通过以 PdfException 为根的类型化异常层次结构来发出失败信号，PdfException 本身继承自 System.Exception，以及如何捕获每类错误。库中所有针对 PDF 的特定异常——密码错误、文件不可读、缺失字体或无效的表单操作——都继承自 PdfException，因此仅捕获 PdfException 就足以拦截任何库抛出的错误，而使用更具体的 catch 块则可以对每种失败模式作出不同的响应。

密码和安全错误

InvalidPasswordException 在尝试进行受密码保护的操作而未提供有效密码时抛出，例如使用错误密码打开加密文档。

try
{
    var doc = new Document("encrypted.pdf", "wrong-password");
}
catch (InvalidPasswordException ex)
{
    Console.WriteLine($"Password rejected: {ex.Message}");
}

文件格式错误

InvalidPdfFileFormatException 在流无法被打开为 PDF 时抛出——例如头部损坏、文件截断，或内容根本无法识别为 PDF。

try
{
    var doc = new Document("not-a-pdf.txt");
}
catch (InvalidPdfFileFormatException ex)
{
    Console.WriteLine($"Not a valid PDF: {ex.Message}");
}

字体错误

与字体相关的故障根据错误原因分为三种不同的异常类型：

• FontNotFoundException — 没有系统字体或自定义字体源匹配请求的字体名称。
• UnsupportedFontTypeException — 提供的文件不是已识别的字体程序。
• IncorrectFontUsageException — 当当前图形状态未设置字体时，内容流中出现了显示文本的操作符。

try
{
    var font = FontRepository.FindFont("NonexistentFont");
}
catch (FontNotFoundException ex)
{
    Console.WriteLine($"Font not found: {ex.Message}");
}

try
{
    var font = FontRepository.OpenFont("not-a-font-file.dat");
}
catch (UnsupportedFontTypeException ex)
{
    Console.WriteLine($"Unsupported font file: {ex.Message}");
}

try
{
    var extractor = new PdfExtractor(doc);
    extractor.ExtractText();
}
catch (IncorrectFontUsageException ex)
{
    Console.WriteLine($"Content stream font error: {ex.Message}");
}

文本提取错误

PdfTextDecodingException 在文本内容无法解码时抛出，例如当字体引用的编码缺失或损坏时。

try
{
    var extractor = new PdfExtractor(doc);
    extractor.GetText("output.txt");
}
catch (PdfTextDecodingException ex)
{
    Console.WriteLine($"Text decoding failed: {ex.Message}");
}

表单类型错误

InvalidFormTypeOperationException 在对错误的表单类型尝试操作时抛出——例如，在非 XFA 基础的表单上调用 XFA 专用方法。

try
{
    var form = new Form(doc);
    form.AssignXfa(xmlData);
}
catch (InvalidFormTypeOperationException ex)
{
    Console.WriteLine($"Wrong form type: {ex.Message}");
}

提示与最佳实践

• 首先捕获最具体的异常类型（例如，InvalidPasswordException），仅在需要时为库抛出的其他异常添加一个最终的 catch (PdfException) 块作为后备。
• 在调用 XFA 特定方法之前检查 Form.IsXfa 或 Form.Type，以避免 InvalidFormTypeOperationException。
• 在渲染之前使用 FontRepository.FindFont 查找字体，以便能够显式处理缺失的字体，而不是仅仅依赖异常处理。
• 当意外的 PdfException 到达顶层处理程序时，使用捕获的异常构建一个 CrashReportOptions，并调用 ex.GenerateCrashReport(options) 生成诊断报告以供支持请求使用。
• 始终通过 Document 构造函数重载传递文档密码，而不是先打开文件后再重试。

常见问题

FAQ

我应该捕获 PdfException 还是具体的子类？

当需要对该错误做不同处理时，请捕获具体的子类，例如 InvalidPasswordException。添加一个最终的 catch (PdfException) 块作为对其他库抛出的错误的回退。

所有 PDF 特定的异常都继承自 PdfException 吗？

是的。PdfTextDecodingException、IncorrectFontUsageException、InvalidPasswordException、InvalidPdfFileFormatException、FontNotFoundException、UnsupportedFontTypeException 和 InvalidFormTypeOperationException 都继承自 PdfException，而 PdfException 本身继承自 System.Exception。

PdfExceptionMessages 是用来做什么的？

PdfExceptionMessages 是一个静态类，集中管理库的异常和安全诊断中出现的消息字符串，包括 DangerousFile 消息。

当异常发生时，我可以生成诊断报告吗？

是的。使用捕获的异常创建一个 CrashReportOptions 实例，可选地设置诸如 ApplicationTitle 和 CrashReportDirectory 等属性，然后在 PdfException 上调用 GenerateCrashReport(options) 来写入详细的崩溃报告。

API Reference 摘要

另请参阅

• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation