Tratamento de Exceções

Manipulação de Exceções

Este guia mostra como Aspose.PDF FOSS para .NET sinaliza falhas através de uma hierarquia de exceções tipada, enraizada em PdfException, que por sua vez deriva de System.Exception, e como capturar cada categoria de erro. Cada exceção específica de PDF na biblioteca — senha incorreta, arquivo ilegível, fonte ausente ou operação de formulário inválida — deriva de PdfException, portanto capturar apenas PdfException é suficiente para interceptar qualquer erro levantado pela biblioteca, enquanto blocos catch mais específicos permitem reagir de forma diferente a cada modo de falha.

Erros de Senha e Segurança

InvalidPasswordException é lançada quando uma operação protegida por senha é tentada sem fornecer uma senha válida, como ao abrir um documento criptografado com a senha errada.

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

Erros de Formato de Arquivo

InvalidPdfFileFormatException é lançada quando um fluxo não pode ser aberto como PDF — um cabeçalho inválido, um arquivo truncado ou conteúdo que não é reconhecível como PDF de forma alguma.

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

Erros de Fonte

Falhas relacionadas a fontes se dividem em três tipos distintos de exceção, dependendo do que deu errado:

• FontNotFoundException — nenhuma fonte do sistema ou fonte personalizada corresponde ao nome de fonte solicitado.
• UnsupportedFontTypeException — o arquivo fornecido como fonte não é um programa de fonte reconhecido.
• IncorrectFontUsageException — um operador de exibição de texto aparece em um fluxo de conteúdo enquanto nenhuma fonte está definida no estado gráfico atual.

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

Erros de Extração de Texto

PdfTextDecodingException é lançada quando o conteúdo de texto não pode ser decodificado, por exemplo quando a codificação referenciada por uma fonte está ausente ou malformada.

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

Erros de Tipo de Formulário

InvalidFormTypeOperationException é lançada quando uma operação é tentada no tipo de formulário errado — por exemplo, chamar um método específico de XFA em um formulário que não é baseado em XFA.

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

Dicas e Melhores Práticas

• Capture o tipo de exceção mais específico primeiro (por exemplo, InvalidPasswordException) e adicione um bloco final catch (PdfException) apenas como alternativa para qualquer outra coisa que a biblioteca levante.
• Verifique Form.IsXfa ou Form.Type antes de chamar métodos específicos de XFA para evitar InvalidFormTypeOperationException.
• Procure fontes com FontRepository.FindFont antes da renderização, para que fontes ausentes possam ser tratadas explicitamente, em vez de depender apenas do tratamento de exceções.
• Quando um PdfException inesperado chega ao seu manipulador de nível superior, crie um CrashReportOptions com a exceção capturada e chame ex.GenerateCrashReport(options) para capturar um relatório de diagnóstico para solicitações de suporte.
• Sempre passe a senha do documento através da sobrecarga do construtor Document em vez de abrir o arquivo primeiro e tentar novamente.

Problemas Comuns

FAQ

Devo capturar PdfException ou a subclasse específica?

Capture a subclasse específica, como InvalidPasswordException, quando precisar reagir de forma diferente a essa falha. Adicione um bloco final catch (PdfException) como fallback para qualquer outro erro gerado pela biblioteca.

Todas as exceções específicas de PDF derivam de PdfException?

Sim. PdfTextDecodingException, IncorrectFontUsageException, InvalidPasswordException, InvalidPdfFileFormatException, FontNotFoundException, UnsupportedFontTypeException e InvalidFormTypeOperationException derivam todos de PdfException, que por sua vez deriva de System.Exception.

Para que serve PdfExceptionMessages?

PdfExceptionMessages é uma classe estática que centraliza as strings de mensagem expostas pelas exceções da biblioteca e pelos diagnósticos de segurança, incluindo a mensagem DangerousFile.

Posso gerar um relatório de diagnóstico quando ocorre uma exceção?

Sim. Construa uma instância de CrashReportOptions com a exceção capturada, opcionalmente defina propriedades como ApplicationTitle e CrashReportDirectory, e chame GenerateCrashReport(options) no PdfException para gravar um relatório detalhado de falha.

API Reference Resumo

Ver também

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