مدیریت استثنا

مدیریت استثناها

این راهنما نشان می‌دهد که چگونه 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) فقط به‌عنوان بازگشت برای هر چیز دیگری که کتابخانه ایجاد می‌کند اضافه کنید.
• قبل از فراخوانی روش‌های مخصوص 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 ارث می‌برند، که خود از 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