معالجة الاستثناءات

معالجة الاستثناءات

يوضح هذا الدليل كيف يقوم Aspose.PDF FOSS لـ .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) نهائية فقط كاحتياط لأي شيء آخر تطرحه المكتبة.
• تحقق من Form.IsXfa أو Form.Type قبل استدعاء الطرق الخاصة بـ XFA لتجنب InvalidFormTypeOperationException.
• ابحث عن الخطوط باستخدام FontRepository.FindFont قبل عملية العرض بحيث يمكن التعامل مع الخطوط المفقودة بشكل صريح، بدلاً من الاعتماد فقط على معالجة الاستثناءات.
• عند وصول PdfException غير متوقع إلى المعالج الأعلى مستوى، أنشئ CrashReportOptions باستخدام الاستثناء الملتقط واستدعِ ex.GenerateCrashReport(options) لالتقاط تقرير تشخيصي لطلبات الدعم.
• دائمًا مرّر كلمة مرور المستند عبر تحميل البناء Document بدلاً من فتح الملف أولاً وإعادة المحاولة.

المشكلات الشائعة

FAQ

هل يجب أن ألتقط PdfException أم الفئة الفرعية المحددة؟

التقط الفئة الفرعية المحددة، مثل InvalidPasswordException، عندما تحتاج إلى الاستجابة بشكل مختلف لهذا الفشل. أضف كتلة catch (PdfException) نهائية كاحتياط لأي خطأ آخر تثيره المكتبة.

هل جميع الاستثناءات الخاصة بـ PDF تورّث من PdfException؟

نعم. PdfTextDecodingException، IncorrectFontUsageException، InvalidPasswordException، InvalidPdfFileFormatException، FontNotFoundException، UnsupportedFontTypeException، وInvalidFormTypeOperationException جميعها تورّث من PdfException، التي هي نفسها تورّث من System.Exception.

ما هو غرض PdfExceptionMessages؟

PdfExceptionMessages هي فئة ثابتة تُركز سلاسل الرسائل التي تظهرها استثناءات المكتبة وتشخيصات الأمان، بما في ذلك رسالة DangerousFile.

هل يمكنني إنشاء تقرير تشخيصي عندما يحدث استثناء؟

نعم. أنشئ مثيلًا من CrashReportOptions باستخدام الاستثناء الملتقط، ويمكنك اختيارياً تعيين خصائص مثل ApplicationTitle وCrashReportDirectory، ثم استدعِ GenerateCrashReport(options) على PdfException لكتابة تقرير تعطل مفصل.

ملخص API Reference

انظر أيضاً

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