Gestione delle eccezioni

Gestione delle eccezioni

Questa guida mostra come Aspose.PDF FOSS per .NET segnala i fallimenti attraverso una gerarchia di eccezioni tipizzata con radice in PdfException, che a sua volta deriva da System.Exception, e come catturare ogni categoria di errore. Ogni eccezione specifica per PDF nella libreria — una password errata, un file illeggibile, un font mancante o un’operazione di modulo non valida — deriva da PdfException, quindi catturare solo PdfException è sufficiente per intercettare qualsiasi errore sollevato dalla libreria, mentre blocchi più specifici catch ti consentono di reagire diversamente a ciascuna modalità di fallimento.

Errori di password e sicurezza

InvalidPasswordException viene lanciata quando si tenta un’operazione protetta da password senza fornire una password valida, ad esempio aprendo un documento criptato con la password errata.

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

Errori di formato file

InvalidPdfFileFormatException viene lanciata quando un flusso non può essere aperto come PDF — un’intestazione errata, un file troncato o contenuti che non sono affatto riconoscibili come PDF.

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

Errori di font

I fallimenti relativi ai font rientrano in tre distinti tipi di eccezione, a seconda di cosa sia andato storto:

• FontNotFoundException — nessun font di sistema o fonte di font personalizzato corrisponde al nome del font richiesto.
• UnsupportedFontTypeException — il file fornito come font non è un programma di font riconosciuto.
• IncorrectFontUsageException — un operatore di visualizzazione del testo appare in un flusso di contenuti mentre nessun font è impostato nello stato grafico corrente.

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

Errori di estrazione del testo

PdfTextDecodingException viene generato quando il contenuto del testo non può essere decodificato, ad esempio quando la codifica a cui fa riferimento un font è mancante o malformata.

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

Errori di tipo di modulo

InvalidFormTypeOperationException viene generato quando si tenta un’operazione sul tipo di modulo sbagliato — ad esempio, chiamare un metodo specifico XFA su un modulo che non è basato su XFA.

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

Suggerimenti e migliori pratiche

• Cattura per primo il tipo di eccezione più specifico (ad esempio, InvalidPasswordException) e aggiungi un blocco catch (PdfException) finale solo come fallback per qualsiasi altra eccezione sollevata dalla libreria.
• Verifica Form.IsXfa o Form.Type prima di chiamare i metodi specifici XFA per evitare InvalidFormTypeOperationException.
• Cerca i caratteri con FontRepository.FindFont prima del rendering, così i caratteri mancanti possono essere gestiti esplicitamente, invece di fare affidamento esclusivamente sulla gestione delle eccezioni.
• Quando un PdfException imprevisto raggiunge il tuo gestore di livello superiore, crea un CrashReportOptions con l’eccezione catturata e chiama ex.GenerateCrashReport(options) per acquisire un report diagnostico per le richieste di supporto.
• Passa sempre la password del documento tramite il sovraccarico del costruttore Document anziché aprire prima il file e riprovare.

Problemi comuni

FAQ

Devo catturare PdfException o la sottoclasse specifica?

Cattura la sottoclasse specifica, ad esempio InvalidPasswordException, quando devi reagire in modo diverso a quel fallimento. Aggiungi un blocco finale catch (PdfException) come fallback per qualsiasi altro errore sollevato dalla libreria.

Tutte le eccezioni specifiche per PDF derivano da PdfException?

Sì. PdfTextDecodingException, IncorrectFontUsageException, InvalidPasswordException, InvalidPdfFileFormatException, FontNotFoundException, UnsupportedFontTypeException e InvalidFormTypeOperationException derivano tutti da PdfException, che a sua volta deriva da System.Exception.

A cosa serve PdfExceptionMessages?

PdfExceptionMessages è una classe statica che centralizza le stringhe di messaggi emerse dalle eccezioni della libreria e dalle diagnosi di sicurezza, incluso il messaggio DangerousFile.

Posso generare un report diagnostico quando si verifica un’eccezione?

Sì. Crea un’istanza di CrashReportOptions con l’eccezione catturata, impostando opzionalmente proprietà come ApplicationTitle e CrashReportDirectory, e chiama GenerateCrashReport(options) sul PdfException per scrivere un report di crash dettagliato.

API Reference Riepilogo

Vedi anche

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