Gestion des exceptions

Gestion des exceptions

Ce guide montre comment Aspose.PDF FOSS pour .NET signale les échecs via une hiérarchie d’exceptions typées dont la racine est PdfException, qui hérite de System.Exception, et comment intercepter chaque catégorie d’erreur. Chaque exception spécifique aux PDF dans la bibliothèque — un code secret erroné, un fichier illisible, une police manquante ou une opération de formulaire non valide — dérive de PdfException, de sorte que capturer PdfException suffit à intercepter toute erreur levée par la bibliothèque, tandis que des blocs catch plus spécifiques vous permettent de réagir différemment selon chaque mode d’échec.

Erreurs de code secret et de sécurité

InvalidPasswordException est déclenchée lorsqu’une opération protégée par un code secret est tentée sans fournir de code secret valide, par exemple lors de l’ouverture d’un document chiffré avec un code secret incorrect.

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

Erreurs de format de fichier

InvalidPdfFileFormatException est déclenchée lorsqu’un flux ne peut pas être ouvert en tant que PDF — un en-tête incorrect, un fichier tronqué ou un contenu qui n’est pas du tout reconnaissable comme PDF.

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

Erreurs de police

Les échecs liés aux polices se répartissent en trois types d’exceptions distincts, selon ce qui s’est mal passé :

• FontNotFoundException — aucune police système ou source de police personnalisée ne correspond au nom de police demandé.
• UnsupportedFontTypeException — le fichier fourni en tant que police n’est pas un programme de police reconnu.
• IncorrectFontUsageException — un opérateur d’affichage de texte apparaît dans un flux de contenu alors qu’aucune police n’est définie dans l’état graphique actuel.

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

Erreurs d’extraction de texte

PdfTextDecodingException est levée lorsque le contenu texte ne peut pas être décodé, par exemple lorsque l’encodage référencé par une police est absent ou malformé.

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

Erreurs de type de formulaire

InvalidFormTypeOperationException est levée lorsqu’une opération est tentée sur le mauvais type de formulaire — par exemple, appeler une méthode spécifique à XFA sur un formulaire qui n’est pas basé sur XFA.

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

Conseils et bonnes pratiques

• Capturez d’abord le type d’exception le plus spécifique (par exemple, InvalidPasswordException) et ajoutez un bloc catch (PdfException) final uniquement comme solution de repli pour tout le reste que la bibliothèque lève.
• Vérifiez Form.IsXfa ou Form.Type avant d’appeler les méthodes spécifiques à XFA afin d’éviter InvalidFormTypeOperationException.
• Recherchez les polices avec FontRepository.FindFont avant le rendu afin que les polices manquantes puissent être gérées explicitement, plutôt que de se fier uniquement à la gestion des exceptions.
• Lorsqu’un PdfException inattendu atteint votre gestionnaire de niveau supérieur, créez un CrashReportOptions avec l’exception capturée et appelez ex.GenerateCrashReport(options) pour générer un rapport de diagnostic destiné aux demandes d’assistance.
• Passez toujours le mot de passe du document via la surcharge du constructeur Document plutôt que d’ouvrir d’abord le fichier et de réessayer.

Problèmes courants

FAQ

Dois-je attraper PdfException ou la sous-classe spécifique?

Attrapez la sous-classe spécifique, comme InvalidPasswordException, lorsque vous devez réagir différemment à cet échec. Ajoutez un bloc catch (PdfException) final comme solution de repli pour toute autre erreur levée par la bibliothèque.

Toutes les exceptions spécifiques aux PDF dérivent-elles de PdfException?

Oui. PdfTextDecodingException, IncorrectFontUsageException, InvalidPasswordException, InvalidPdfFileFormatException, FontNotFoundException, UnsupportedFontTypeException et InvalidFormTypeOperationException dérivent tous de PdfException, qui dérive lui-même de System.Exception.

À quoi sert PdfExceptionMessages?

PdfExceptionMessages est une classe statique qui centralise les chaînes de messages exposées par les exceptions de la bibliothèque et les diagnostics de sécurité, y compris le message DangerousFile.

Puis-je générer un rapport de diagnostic lorsqu’une exception se produit?

Oui. Créez une instance de CrashReportOptions avec l’exception capturée, définissez éventuellement des propriétés comme ApplicationTitle et CrashReportDirectory, puis appelez GenerateCrashReport(options) sur le PdfException pour écrire un rapport de plantage détaillé.

API Reference Résumé

Voir aussi

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