Manejo de excepciones

Manejo de Excepciones

Esta guía muestra cómo Aspose.PDF FOSS para .NET señala los fallos mediante una jerarquía de excepciones tipada con raíz en PdfException, que a su vez hereda de System.Exception, y cómo capturar cada categoría de error. Cada excepción específica de PDF en la biblioteca — una contraseña incorrecta, un archivo ilegible, una fuente faltante o una operación de formulario inválida — hereda de PdfException, por lo que capturar PdfException por sí solo es suficiente para interceptar cualquier error generado por la biblioteca, mientras que bloques más específicos de catch le permiten reaccionar de manera diferente a cada modo de falla.

Errores de contraseña y seguridad

InvalidPasswordException se lanza cuando se intenta una operación protegida por contraseña sin proporcionar una contraseña válida, como abrir un documento cifrado con la contraseña incorrecta.

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

Errores de formato de archivo

InvalidPdfFileFormatException se lanza cuando una secuencia no puede abrirse como PDF — un encabezado incorrecto, un archivo truncado o contenido que no es reconocible como PDF en absoluto.

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

Errores de fuentes

Los fallos relacionados con fuentes se dividen en tres tipos de excepción distintos, según lo que salió mal:

• FontNotFoundException — ninguna fuente del sistema o fuente personalizada coincide con el nombre de fuente solicitado.
• UnsupportedFontTypeException — el archivo proporcionado como fuente no es un programa de fuente reconocido.
• IncorrectFontUsageException — un operador de visualización de texto aparece en un flujo de contenido mientras no hay ninguna fuente establecida en el estado gráfico actual.

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

Errores de extracción de texto

PdfTextDecodingException se lanza cuando el contenido de texto no puede decodificarse, por ejemplo cuando la codificación referenciada por una fuente falta o está malformada.

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

Errores de tipo de formulario

InvalidFormTypeOperationException se lanza cuando se intenta una operación en el tipo de formulario incorrecto — por ejemplo, llamando a un método específico de XFA en un formulario que no está basado en XFA.

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

Consejos y mejores prácticas

• Capture el tipo de excepción más específico primero (por ejemplo, InvalidPasswordException) y añada un bloque final catch (PdfException) solo como alternativa para cualquier otro error que genere la biblioteca.
• Verifique Form.IsXfa o Form.Type antes de llamar a los métodos específicos de XFA para evitar InvalidFormTypeOperationException.
• Busque fuentes con FontRepository.FindFont antes de renderizar para que las fuentes faltantes puedan manejarse explícitamente, en lugar de depender únicamente del manejo de excepciones.
• Cuando un PdfException inesperado llega a su manejador de nivel superior, construya un CrashReportOptions con la excepción capturada y llame a ex.GenerateCrashReport(options) para obtener un informe de diagnóstico para solicitudes de soporte.
• Siempre pase la contraseña del documento mediante la sobrecarga del constructor Document en lugar de abrir el archivo primero y volver a intentarlo.

Problemas comunes

FAQ

¿Debo capturar PdfException o la subclase específica?

Capture la subclase específica, como InvalidPasswordException, cuando necesite reaccionar de manera diferente a esa falla. Añada un bloque final catch (PdfException) como alternativa para cualquier otro error generado por la biblioteca.

¿Todas las excepciones específicas de PDF derivan de PdfException?

Sí. PdfTextDecodingException, IncorrectFontUsageException, InvalidPasswordException, InvalidPdfFileFormatException, FontNotFoundException, UnsupportedFontTypeException y InvalidFormTypeOperationException derivan todos de PdfException, que a su vez deriva de System.Exception.

¿Para qué sirve PdfExceptionMessages?

PdfExceptionMessages es una clase estática que centraliza las cadenas de mensajes expuestas por las excepciones de la biblioteca y los diagnósticos de seguridad, incluido el mensaje DangerousFile.

¿Puedo generar un informe de diagnóstico cuando ocurre una excepción?

Sí. Construya una instancia de CrashReportOptions con la excepción capturada, opcionalmente establezca propiedades como ApplicationTitle y CrashReportDirectory, y llame a GenerateCrashReport(options) en el PdfException para escribir un informe detallado del fallo.

API Reference Resumen

Ver también

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