Обработка исключений

Обработка исключений

Это руководство показывает, как Aspose.PDF FOSS для .NET сигнализирует о сбоях через типизированную иерархию исключений, корневой элемент которой — 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) только как запасной вариант для всего, что может вызвать библиотека.
• Проверьте Form.IsXfa или Form.Type перед вызовом методов, специфичных для XFA, чтобы избежать InvalidFormTypeOperationException.
• Ищите шрифты с помощью FontRepository.FindFont перед рендерингом, чтобы отсутствующие шрифты можно было обработать явно, а не полагаться только на обработку исключений.
• Когда неожиданное PdfException попадает в ваш обработчик верхнего уровня, создайте CrashReportOptions с перехваченным исключением и вызовите ex.GenerateCrashReport(options), чтобы собрать диагностический отчёт для запросов в поддержку.
• Всегда передавайте пароль документа через перегрузку конструктора Document, а не открывайте файл сначала и повторно пытаясь.

Распространённые проблемы

FAQ

Стоит ли ловить PdfException или конкретный подкласс?

Ловите конкретный подкласс, например InvalidPasswordException, когда необходимо реагировать по-другому на эту ошибку. Добавьте финальный блок catch (PdfException) в качестве резервного варианта для любых других ошибок, вызываемых библиотекой.

Все ли исключения, связанные с PDF, наследуются от PdfException?

Да. PdfTextDecodingException, IncorrectFontUsageException, InvalidPasswordException, InvalidPdfFileFormatException, FontNotFoundException, UnsupportedFontTypeException и InvalidFormTypeOperationException все наследуются от PdfException, который сам наследуется от System.Exception.

Для чего предназначен PdfExceptionMessages?

PdfExceptionMessages — это статический класс, который централизует строки сообщений, выдаваемые исключениями библиотеки и диагностикой безопасности, включая сообщение DangerousFile.

Могу ли я сформировать диагностический отчёт при возникновении исключения?

Да. Создайте экземпляр CrashReportOptions, передав в него пойманное исключение, при желании задайте свойства, такие как ApplicationTitle и CrashReportDirectory, и вызовите GenerateCrashReport(options) у PdfException, чтобы записать подробный отчёт о сбое.

API Reference Сводка

См. также:

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