예외 처리

예외 처리

이 가이드는 Aspose.PDF FOSS for .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) 블록을 대체용으로만 추가합니다.
• XFA 전용 메서드를 호출하기 전에 Form.IsXfa 또는 Form.Type을 확인하여 InvalidFormTypeOperationException를 방지하세요.
• 렌더링 전에 FontRepository.FindFont을 사용해 글꼴을 조회하면 누락된 글꼴을 명시적으로 처리할 수 있어 예외 처리에만 의존하지 않아도 됩니다.
• 예기치 않은 PdfException이 최상위 핸들러에 도달하면, 잡힌 예외를 사용해 CrashReportOptions을 만들고 ex.GenerateCrashReport(options)를 호출하여 지원 요청용 진단 보고서를 수집합니다.
• 파일을 먼저 열고 재시도하는 대신, 항상 Document 생성자 오버로드를 통해 문서 비밀번호를 전달하세요.

일반적인 문제

FAQ

제가 PdfException를 잡아야 하나요, 아니면 특정 서브클래스를 잡아야 하나요?

특정 서브클래스(예: InvalidPasswordException)를 잡으세요, 그 실패에 다르게 반응해야 할 때입니다. 다른 라이브러리에서 발생한 오류에 대한 대체로 최종 catch (PdfException) 블록을 추가하세요.

모든 PDF 전용 예외가 PdfException에서 파생되나요?

네. PdfTextDecodingException, IncorrectFontUsageException, InvalidPasswordException, InvalidPdfFileFormatException, FontNotFoundException, UnsupportedFontTypeException, 그리고 InvalidFormTypeOperationException은 모두 PdfException에서 파생되며, PdfException은 다시 System.Exception에서 파생됩니다.

PdfExceptionMessages는 무엇을 위한 건가요?

PdfExceptionMessages는 라이브러리 예외와 보안 진단에서 표시되는 메시지 문자열을 중앙 집중화하는 정적 클래스이며, DangerousFile 메시지를 포함합니다.

예외가 발생했을 때 진단 보고서를 생성할 수 있나요?

네. 잡힌 예외를 사용해 CrashReportOptions 인스턴스를 만들고, 선택적으로 ApplicationTitle 및 CrashReportDirectory와 같은 속성을 설정한 뒤, PdfException에서 GenerateCrashReport(options)을 호출하여 상세한 충돌 보고서를 작성하세요.

API Reference 요약

참조

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