> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ASP.NET Core — تتبع الأخطاء

> إبلاغ تلقائي عن الاستثناءات غير المعالَجة في ASP.NET Core، مع إبلاغ يدوي بالنوع والخطورة والبيانات الوصفية.

## مقدمة

بعد إكمال [تثبيت ASP.NET Core](/ar/frameworks/aspnet/installation)، يُبلَّغ
عن الاستثناءات غير المعالَجة تلقائياً. احقن `LerixClient` للإبلاغ عن
الاستثناءات المعالَجة بنفسك مع سياق إضافي.

## الالتقاط التلقائي

تسجّل `AddLerix` و`UseLerix` أمرين:

* **وسيط.** يمرّ عبره كل استثناء يفلت من الوسائط التي تليه (التوجيه،
  المصادقة، نقاط النهاية). يبلّغ افتراضياً عن كل استثناء باستثناء ما يحمل
  رمز حالة أقل من 500، مثل `BadHttpRequestException` برمز 400. ثم يعيد
  الوسيط إلقاء الاستثناء، فيبني `UseExceptionHandler` أو صفحة استثناءات
  المطوّر الاستجابة نفسها التي كان سيبنيها بدون Lerix. لا يُبلَّغ عن
  الطلبات التي ألغاها العميل.
* **معالجات على مستوى العملية.** يُبلَّغ عن `AppDomain.UnhandledException`
  و`TaskScheduler.UnobservedTaskException` بنوع `Crash` وخطورة `Critical`.
  اضبط `CaptureUnhandled = false` لتخطيها.

يحمل كل تقرير تلقائي طريقة الطلب وعنوانه ونمط مساره ورمز الحالة، وترويسة
`X-Request-Id` (أو `TraceIdentifier` الخاص بـ ASP.NET)، تحت `metadata.request`.

### تغيير ما يُبلَّغ عنه

تتلقى `ShouldCapture` الاستثناء و`HttpContext` ورمز الحالة الذي سيُرسَل إن كان
معروفاً:

```csharp Program.cs theme={"dark"}
builder.Services.AddLerix(o =>
{
    o.IgnorePaths.Add("/health");
    o.ShouldCapture = (exception, context, status) =>
    {
        if (exception is OperationCanceledException) return false;
        return status is null or >= 500;
    };
});
```

`IgnorePaths` اختصار لتخطي بادئات مسارات كاملة دون كتابة دالة.

### ترتيب الوسائط

يجب أن يأتي `UseLerix` بعد `UseExceptionHandler` (الذي سيلتقط الاستثناء
أولاً لولا ذلك) وقبل الوسائط التي تريد تغطيتها. خط أنابيب نموذجي:

```csharp Program.cs theme={"dark"}
app.UseExceptionHandler("/error");
app.UseLerix();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
```

## الإبلاغ عن خطأ يدوياً

`LerixClient` مسجَّل كـ singleton في الحاوية:

```csharp OrdersService.cs theme={"dark"}
using Lerix;

public class OrdersService(LerixClient lerix, ILedger ledger)
{
    public async Task Reconcile(string orderId)
    {
        try
        {
            await ledger.Reconcile(orderId);
        }
        catch (Exception error)
        {
            await lerix.CaptureException(error, new CaptureOptions
            {
                Type = BugType.LogicBug,
                Severity = BugSeverity.High,
                Metadata = new Dictionary<string, object?> { ["orderId"] = orderId, ["job"] = "reconcile" },
            });
            throw;
        }
    }
}
```

لا تُلقي `CaptureException` استثناءً أبداً وتكتمل عند قبول التقرير أو التخلي
عنه. يمكنك أيضاً تجاهل المهمة بـ `_ =` للمتابعة دون انتظار. استخدم
`CaptureMessage` لشيء لم يُلقَ كاستثناء:

```csharp theme={"dark"}
await lerix.CaptureMessage("Inventory drift detected", new CaptureOptions
{
    Severity = BugSeverity.Medium,
    Metadata = new Dictionary<string, object?> { ["sku"] = "A-1", ["expected"] = 10, ["actual"] = 7 },
});
```

### المعاملات

| المعامل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `error` / `message` | `Exception` / `string` | نعم | الاستثناء الملتقط، أو رسالة |
| `Type` | `BugType` | لا | تصنيف الخطأ (الافتراضي `RuntimeError` للاستثناءات و`LogicBug` للرسائل) |
| `Severity` | `BugSeverity` | لا | مستوى الخطورة (الافتراضي `High` للاستثناءات و`Medium` للرسائل) |
| `Metadata` | `IDictionary<string, object?>` | لا | سياق JSON إضافي يُرفق بالتقرير |

### قيم `BugType`

| القيمة | الوصف |
| - | - |
| `RuntimeError` | استثناء غير معالَج أُلقي وقت التشغيل |
| `LogicBug` | سلوك خاطئ لا يُلقي استثناءً |
| `UiBug` | عيب مرئي أو في التخطيط |
| `NetworkError` | طلب شبكة فاشل أو مشوّه |
| `Performance` | بطء أو استهلاك مفرط للموارد |
| `Compatibility` | يتعطل على بيئة تشغيل أو نظام أو منصة محددة |
| `ValidationError` | مدخل غير صالح اجتاز التحقق |
| `Security` | عيب متعلق بالأمان |
| `Crash` | توقفت العملية بشكل غير متوقع |
| `Unknown` | لا شيء مما سبق |

### قيم `BugSeverity`

| القيمة | الوصف |
| - | - |
| `Critical` | يعطّل وظيفة أساسية أو يؤثر على كل المستخدمين |
| `High` | تأثير خطير مع وجود حل بديل |
| `Medium` | تأثير ملحوظ لكنه محدود |
| `Low` | بسيط أو شكلي |
| `Unknown` | لم تُقيَّم الخطورة بعد |

## ما يُرفق بالتقرير

| الحقل | القيمة |
| - | - |
| الجهاز | اسم الجهاز، معمارية المعالج، اسم النظام وإصداره، المنطقة الزمنية |
| التطبيق | اسم الخدمة ومعرّفها من تجميعة الدخول (أو الخيار `App`)، الإصدار ورقم البناء |
| البيانات الوصفية | `environment`، وصف بيئة تشغيل .NET ومعرّف العملية، إضافة إلى ما تمرّره في `Metadata` |

تتضمن تتبّعات المكدس الاستثناءات الداخلية، يسبق كلاً منها سطر
`--- caused by ... ---`.

<a id="file-and-line-numbers" />

## الملفات وأرقام الأسطر

لا تضع .NET الملف ورقم السطر في تتبّعات المكدس إلا عندما تكون ملفات `.pdb`
الخاصة بتطبيقك متاحة وقت التشغيل. أضِف ملف `Directory.Build.props` في جذر
مستودعك:

```xml Directory.Build.props theme={"dark"}
<Project>
  <PropertyGroup>
    <!-- Ship debug info inside the .dll so line numbers survive publish and Docker -->
    <DebugType>embedded</DebugType>
    <!-- Report paths relative to the repository instead of the build machine -->
    <PathMap>$(MSBuildThisFileDirectory)=/_/</PathMap>
  </PropertyGroup>
</Project>
```

يحذف الـ SDK الجذر الحتمي (deterministic) `/_/`، فهذا الإطار:

```text theme={"dark"}
at Api.Orders.Find() in /_/src/Api/Orders.cs:line 42
```

يُبلَّغ عنه على أنه `src/Api/Orders.cs:line 42`. وينتج بناء
`ContinuousIntegrationBuild` الجذر `/_/` نفسه.

إذا وصلت تتبّعات المكدس دون ملف أو سطر على الإطلاق، يسجّل الـ SDK تحذيراً
واحداً لكل عملية يشير إلى هذه الصفحة.

## أعضاء `LerixClient` الأخرى

| العضو | الوصف |
| - | - |
| `GetUserId()` | معرّف المستخدم المجهول المسجّلة به هذه الخدمة |
| `FlushAsync(timeout?)` | انتظار التقارير قيد الإرسال؛ تستدعيها الخدمة المستضافة عند الإيقاف |
| `DeleteUserAsync()` / `ReRegisterUserAsync()` | إعادة تعيين المستخدم المجهول، مثلاً بعد توجيه الخدمة إلى مشروع آخر |
| `InstallProcessHandlers()` | تثبيت معالجات مستوى العملية بنفسك عند عدم استخدام الخدمة المستضافة |

## التعطيل في الاختبارات

اضبط `Enabled = false` لتحويل كل استدعاء إلى لا شيء دون تغيير الكود:

```csharp theme={"dark"}
builder.Services.AddLerix(o => o.Enabled = !builder.Environment.IsEnvironment("Testing"));
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.