raygun4net
Tidy up release of TLS 1.2 work
مزود Raygun لـ .NET Framework
يتم دعم المشاريع المصممة مع الأطر التالية:
قم بتثبيت حزمة nuget على مشروع يستخدم أحد الأطر المذكورة أعلاه وسيتم الرجوع إلى التجميع الصحيح.
بالنسبة إلى Xamarin ، أوصينا بإضافة إما Raygun4xamarin.forms ، أو Mindscape.raygun4net.xamarin.android & mindscape.raygun4net.xamarin.ios.unified.
بالنسبة إلى .NET Core و .NET Versions 5.0 أو أعلى ، نوصي باستخدام حزمة Mindscape.raygun4net.netcore.
dotnet add package Mindscape.Raygun4Netراجع مستندات Raygun للحصول على المزيد من الإرشادات التفصيلية حول كيفية استخدام هذا المزود.
عند إرسال استثناءات إلى خدمة Raygun ، يُطلب من مفتاح APP API تعيين الرسائل إلى التطبيق الخاص بك.
عندما تقوم بإنشاء تطبيق جديد في لوحة معلومات Raygun الخاصة بك ، يتم عرض مفتاح API App الخاص بك ضمن صفحة التعليمات. يمكنك أيضًا العثور على مفتاح API بالنقر فوق الزر "إعدادات التطبيق" في الشريط الجانبي للوحة معلومات Raygun.
يمكن العثور على الفصول الرئيسية في مساحة اسم Mindscape.raygun4net.
يتضمن مزود Raygun4Net دعمًا للعديد من أطر عمل .NET. قم بالتمرير لأسفل للعثور على معلومات حول استخدام Raygun لنوع التطبيق الخاص بك.
اعتبارًا من الإصدار 5.0.0 ، تم نقل دعم ASP.NET إلى حزمة Nuget جديدة. إذا كان لديك مشروع ASP.NET ، فيرجى إلغاء تثبيت حزمة Raygun4Net Nuget وتثبيت Mindscape.raygun4net.aspnetcore Nuget Package بدلاً من ذلك.
بمجرد تثبيت الحزمة ، أضف الكود التالي إلى AppSettings.json (إذا كنت تستخدم نوعًا آخر من التكوين ، أضفه هناك):
"RaygunSettings" : {
"ApiKey" : " YOUR_APP_API_KEY "
}قم بتكوين البرامج الوسيطة Raygun للتعامل مع الاستثناءات التي تم تشغيلها وإرسال استثناءات غير معطلة تلقائيًا.
في Program.cs .
using Mindscape.Raygun4Net.AspNetCore; لاستخدام البيانات الخاصة بك.builder.Services.AddRaygun(builder.Configuration); .app.UseRaygun(); بعد أي أساليب استثناء أخرى على سبيل المثال app.UseDeveloperExceptionPage() أو app.UseExceptionHandler("/Home/Error") . using Mindscape . Raygun4Net . AspNetCore ; var builder = WebApplication . CreateBuilder ( args ) ;
// Add services to the container.
builder . Services . AddRaygun ( builder . Configuration ) ;
/*The rest of your builder setup*/
var app = builder . Build ( ) ;
// Configure the HTTP request pipeline.
if ( ! app . Environment . IsDevelopment ( ) )
{
app . UseExceptionHandler ( "/Error" ) ;
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app . UseHsts ( ) ;
}
app . MapGet ( "/throw" , ( Func < string > ) ( ( ) => throw new Exception ( "Exception in request pipeline" ) ) ) ;
app . UseRaygun ( ) ;
/*The rest of your app setup*/سيؤدي الإعداد أعلاه إلى إرسال جميع الاستثناءات غير المعلنة إلى حساب Raygun الخاص بك ، حيث يمكنك بسهولة عرض جميع بيانات مراقبة الأخطاء وتقرير التصادم.
تتطلب عقد ابتلاع Raygun TLS 1.2 أو TLS 1.3 إذا كنت تستخدم .NET 3.5 أو قبل ذلك ، فقد تحتاج إلى تمكين هذه البروتوكولات في تطبيقك وتصحيح نظام التشغيل الخاص بك.
تحقق من دليل استكشاف الأخطاء وإصلاحها TLS من Microsoft للحصول على توصياتها.
تحديث خاصية البروتوكول في رمز بدء التطبيق الخاص بك.
protected void Application_Start ( )
{
// Enable TLS 1.2 and TLS 1.3
ServicePointManager . SecurityProtocol |= ( ( SecurityProtocolType ) 3072 /*TLS 1.2*/ | ( SecurityProtocolType ) 12288 /*TLS 1.3*/ ) ;
} في ملف web.config الخاص بك ، ابحث أو إضافة عنصر <configSections> ، والذي يجب أن يكون متداخلًا ضمن عنصر <configuration> ، وأضف الإدخال التالي:
<section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/>
ثم الرجوع إليه بإضافة السطر التالي في مكان ما بعد علامة configSections .
< RaygunSettings apikey = " YOUR_APP_API_KEY " />الآن يمكنك إما إعداد Raygun لإرسال استثناءات غير معطلة تلقائيًا أو/وإرسال استثناءات يدويًا.
لإرسال استثناءات غير معطلة تلقائيًا ، استخدم وحدة Raygun HTTP ضمن عنصر <configuration> في Web.Config. يتم ذلك بشكل مختلف قليلاً اعتمادًا على إصدار IIS الذي تستخدمه. إذا كنت في شك ، فقط جربهما على حد سواء:
< system .web>
< httpModules >
< add name = " RaygunErrorModule " type = " Mindscape.Raygun4Net.RaygunHttpModule " />
</ httpModules >
</ system .web> ل IIS 7.0 ، استخدم system.webServer
< system .webServer>
< modules >
< add name = " RaygunErrorModule " type = " Mindscape.Raygun4Net.RaygunHttpModule " />
</ modules >
</ system .webServer>في أي مكان في رمزك ، يمكنك أيضًا إرسال تقارير استثناء يدويًا ببساطة عن طريق إنشاء مثيل جديد من Raygunclient والاتصال بأحد طرق Send أو SendBackground. هذا هو الأكثر استخدامًا لإرسال استثناءات تم صيدها في كتلة المحاولة/الصيد.
try
{
}
catch ( Exception e )
{
new RaygunClient ( ) . SendInBackground ( e ) ;
}أو لإرسال استثناءات في معالجاتك بدلاً من استخدام الإعداد التلقائي أعلاه.
protected void Application_Error ( )
{
var exception = Server . GetLastError ( ) ;
new RaygunClient ( ) . Send ( exception ) ;
} استبعاد الأخطاء بواسطة رمز حالة HTTP
إذا كنت تستخدم وحدة HTTP ، فيمكنك استبعاد الأخطاء بواسطة رمز حالة HTTP الخاص بهم عن طريق توفير قائمة مفصولة بفاصلة من رموز الحالة لتجاهلها في التكوين. على سبيل المثال ، إذا كنت ترغب في استبعاد الأخطاء التي تُرجع رمز استجابة Teapot ، فيمكنك استخدام التكوين أدناه.
< RaygunSettings apikey = " YOUR_APP_API_KEY " excludeHttpStatusCodes = " 418 " />استبعاد الأخطاء التي تنشأ من أصل محلي
تبديل هذه الوحدة المنطقية ولن ترسل وحدة HTTP أخطاء إلى Raygun إذا نشأ الطلب من أصل محلي. أي وسيلة لمنع التصحيح/التطوير المحلي من إخطار Raygun دون الحاجة إلى اللجوء إلى Web.Config.
< RaygunSettings apikey = " YOUR_APP_API_KEY " excludeErrorsFromLocal = " true " />إزالة بيانات الطلب الحساسة
إذا كان لديك بيانات حساسة في طلب HTTP ترغب في منع نقله إلى Raygun ، فيمكنك تقديم قوائم للمفاتيح الممكنة (الأسماء) لإزالتها. يمكن تحديد مفاتيح التجاهل على علامة Raygunsettings في web.config ، (أو يمكنك استخدام الأساليب المكافئة على Raygunclient إذا كنت تقوم بإعداد الأشياء في التعليمات البرمجية). الخيارات المتاحة هي:
يمكن ضبط هذه على قائمة مفاتيح مفصولة فاصلة لتجاهلها. سيشير تحديد خيار As * إلى أنه لن يتم إرسال جميع المفاتيح إلى Raygun. إن وضع * قبل أو بعد أو على طرفي المفتاح سيؤدي إلى نهايات أو تبدأ أو تحتوي على عملية على التوالي. على سبيل المثال ، سيؤدي DectionFormfieldNames = "*Password*" إلى تجاهل Raygun جميع حقول النماذج التي تحتوي على "كلمة مرور" في أي مكان في الاسم. هذه الخيارات ليست حساسة للحالة.
توفير Raygunclient مخصص لوحدة HTTP
في بعض الأحيان عند إعداد Raygun باستخدام وحدة HTTP لإرسال استثناءات تلقائيًا ، قد تحتاج إلى تزويد وحدة HTTP بمثيل Raygunclient مخصص من أجل استخدام بعض الميزة الاختيارية الموضحة في نهاية هذا الملف. للقيام بذلك ، احصل على تطبيق HTTP لتنفيذ واجهة iraygunapplication. قم بتنفيذ طريقة generateraygunclient لإرجاع مثيل Raygunclient جديد (أو تم إنشاؤه مسبقًا). ستستخدم وحدة HTTP Raygunclient التي تم إرجاعها من هذه الطريقة لإرسال الاستثناءات غير المعلنة. في هذه الطريقة ، يمكنك إعداد أي خيارات إضافية على مثيل Raygunclient الذي تحتاجه - يتم وصف مزيد من المعلومات حول كل ميزة في نهاية هذا الملف.
اعتبارًا من الإصدار 4.0.0 ، تم نقل دعم MVC إلى حزمة Nuget جديدة. إذا كان لديك مشروع MVC ، فيرجى إلغاء تثبيت حزمة Raygun4Net Nuget وتثبيت Mindscape.Raygun4Net.Mvc nuget بدلاً من ذلك.
بمجرد تثبيت الحزمة ، راجع الحزمة ReadMe للحصول على إرشادات حول التكوين.
يمكن تثبيت حزم MVC و WebAPI nuget في نفس المشروع بأمان.
اعتبارًا من الإصدار 4.0.0 ، تم نقل دعم WebAPI إلى حزمة Nuget جديدة. إذا كان لديك مشروع WebAPI ، فيرجى إلغاء تثبيت حزمة Raygun4net nuget وتثبيت Mindscape.Raygun4Net.WebApi nuget بدلاً من ذلك.
بمجرد تثبيت الحزمة ، راجع الحزمة ReadMe للحصول على إرشادات حول التكوين.
يمكن تثبيت حزم MVC و WebAPI nuget في نفس المشروع بأمان.
قم بإنشاء مثيل من Raygunclient عن طريق تمرير مفتاح API الخاص بـ APP في المنشئ. إرفاق معالج الحدث بحدث DispatcherUnhandleDexception من طلبك. في معالج الأحداث ، استخدم طريقة Raygunclient.send لإرسال الاستثناء.
private RaygunClient _client = new RaygunClient ( "YOUR_APP_API_KEY" ) ;
public App ( )
{
DispatcherUnhandledException += OnDispatcherUnhandledException ;
}
void OnDispatcherUnhandledException ( object sender , DispatcherUnhandledExceptionEventArgs e )
{
_client . Send ( e . Exception ) ;
}قم بإنشاء مثيل من Raygunclient عن طريق تمرير مفتاح API الخاص بـ APP في المنشئ. قم بإرفاق معالج حدث بحدث Application.ThreadException قبل استدعاء Application.Run (...). في معالج الأحداث ، استخدم طريقة Raygunclient.send لإرسال الاستثناء.
private static readonly RaygunClient _raygunClient = new RaygunClient ( "YOUR_APP_API_KEY" ) ;
[ STAThread ]
static void Main ( )
{
Application . EnableVisualStyles ( ) ;
Application . SetCompatibleTextRenderingDefault ( false ) ;
Application . ThreadException += new ThreadExceptionEventHandler ( Application_ThreadException ) ;
Application . Run ( new Form1 ( ) ) ;
}
private static void Application_ThreadException ( object sender , ThreadExceptionEventArgs e )
{
_raygunClient . Send ( e . Exception ) ;
}في مُنشئ app.xaml.cs (أو أي نقطة إدخال رئيسية إلى التطبيق الخاص بك) ، اتصل بالطريقة الثابتة raygunclient.attach باستخدام مفتاح API الخاص بك.
public App ( )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
}في أي وقت بعد استدعاء طريقة الملحق ، يمكنك استخدام RaygunClient.current للحصول على المثيل الثابت. يمكن استخدام هذا لإرسال الرسائل يدويًا (عبر طرق الإرسال) أو تغيير الخيارات مثل سلسلة هوية المستخدم.
الخيارات المتوفرة في WinRT لالتقاط استثناءات غير معطلة في هذه المرحلة الزمنية أكثر محدودة مقارنة بالخيارات في إطار .NET الأكثر نضجًا. سيتم رفع حدث UnhandledException عندما يتم تحليل XAML غير صالح ، بالإضافة إلى استثناءات وقت التشغيل الأخرى التي تحدث في سلسلة واجهة المستخدم الرئيسية. على الرغم من أن العديد من الأخطاء سيتم التقاطها بهذه الطريقة ، وبالتالي تكون قادرة على إرسالها إلى Raygun ، سيتم تفويت الآخرين من قبل معالج الاستثناء هذا. على وجه الخصوص ، لن يتم صيد التعليمات البرمجية غير المتزامنة أو المهام التي تنفذ على مؤشرات ترابط الخلفية.
يتم توفير حل بديل لهذه المشكلة مع طريقة WRAP (). هذه تتيح لك تمرير الرمز الذي تريد تنفيذه إلى مثيل لعميل Raygun - سيسميه ببساطة محاطًا بكتلة محاولة. إذا كانت الطريقة التي تمر بها تؤدي إلى إلقاء استثناء ، فسيتم إرسال ذلك إلى Raygun ، وسيتم طرح الاستثناء مرة أخرى. اثنين من الأحمال الزائدة متوفرة ؛ واحد للطرق التي تعود باطلة وآخر للطرق التي تُرجع كائنًا.
خيار آخر هو استخدام مكتبة Fody ، وتمديد عدم التزامن. سيؤدي ذلك تلقائيًا إلى استثناءات Async وتنقلها إلى معالج من اختيارك (والذي سيرسل إلى Raygun على النحو الوارد أعلاه). راجع تعليمات التثبيت هنا ، ثم تحقق من عينة مشروع كيفية الاستخدام.
في النشاط الرئيسي/الدخول للتطبيق الخاص بك ، استخدم طريقة static raygunclient.attach باستخدام مفتاح API App الخاص بك. هناك أيضًا تحميل زائد لطريقة الإرفاق التي تتيح لك تمرير سلسلة هوية المستخدم والتي تعد مفيدة لتتبع المستخدمين المتأثرين في لوحة معلومات Raygun الخاصة بك.
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;في أي وقت بعد استدعاء طريقة الملحق ، يمكنك استخدام RaygunClient.current للحصول على المثيل الثابت. يمكن استخدام هذا لإرسال الرسائل يدويًا أو تغيير الخيارات مثل سلسلة هوية المستخدم.
في نقطة الدخول الرئيسية للتطبيق ، استخدم طريقة RaygunClient.attach الثابتة باستخدام مفتاح API App الخاص بك.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
UIApplication . Main ( args , null , "AppDelegate" ) ;
}هناك أيضًا حمولة زائدة لطريقة الإرفاق التي تتيح لك تمكين الإبلاغ عن تصادم iOS الأصلي.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" , true , true ) ;
UIApplication . Main ( args , null , "AppDelegate" ) ;
}المعلمة المنطقية الأولى هي ببساطة تمكين الإبلاغ عن خطأ iOS الأصلي. المعلمة المنطقية الثانية هي ما إذا كان سيتم اختطاف بعض الإشارات الأصلية أم لا - وهذا هو حل مشكلة مراسل تحطم iOS المعروفة حيث يمكن أن يتسبب استثناءات مرجعية فارغة داخل كتلة المحاولة/الصيد في تعطل التطبيق. من خلال تعيين المعلمة المنطقية الثانية إلى True ، سوف يتولى الرمز المدارة إشارات Sigbus و Sigsegv IOS التي تحل المشكلة المرجعية الفارغة. ومع ذلك ، فإن القيام بذلك يمنع الأخطاء الأصلية SIGBUS و SIGSEGV ، مما يعني أنه لم يتم إرسالها إلى Raygun. هذا هو السبب في أننا نقدم هذا كخيار - لذلك إذا لم يكن لديك أي مشكلات مع استثناءات مرجعية خالية تحدث في كتل Try/Catch وتريد تعظيم الأخطاء الأصلية التي يمكنك إخطارك بها ، ثم قم بتعيين المعلمة المنطقية الثانية على خطأ.
في أي وقت بعد استدعاء طريقة الملحق ، يمكنك استخدام RaygunClient.current للحصول على المثيل الثابت. يمكن استخدام هذا لإرسال الرسائل يدويًا أو تغيير الخيارات مثل سلسلة هوية المستخدم.
في نقطة الدخول الرئيسية للتطبيق ، استخدم طريقة RaygunClient.attach الثابتة باستخدام مفتاح API App الخاص بك.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
NSApplication . Init ( ) ;
NSApplication . Main ( args ) ;
}في أي وقت بعد استدعاء طريقة الملحق ، يمكنك استخدام RaygunClient.current للحصول على المثيل الثابت. يمكن استخدام هذا لإرسال الرسائل يدويًا أو تغيير الخيارات مثل سلسلة هوية المستخدم.
على مثيل Raygunclient ، قم بإرفاق معالج حدث بحدث SendingMessage. سيتم استدعاء معالج الحدث هذا قبل أن يرسل Raygunclient استثناء - إما تلقائيًا أو يدويًا. توفر وسيطات الحدث كائن RaygunMessage الذي على وشك إرساله. أحد الاستخدامات لهذا معالج الحدث هو إضافة أو تعديل أي معلومات عن RaygunMessage. استخدام آخر لهذه الطريقة هو تحديد الاستثناءات التي لا ترغب أبدًا في إرسالها إلى Raygun ، وإذا كان الأمر كذلك ، فقم بتعيين E.Cancel = True لإلغاء الإرسال.
إذا كان لديك استثناءات خارجية شائعة ترفف استثناءًا داخليًا قيمة تفضل تجميعه ، فيمكنك تحديدها باستخدام طريقة المعلمة المتعددة:
raygunClient . AddWrapperExceptions ( typeof ( TargetInvocationException ) ) ;في هذه الحالة ، في حالة حدوث TargetInvocationException ، ستتم إزالتها واستبدالها مع innerexception الفعلي الذي كان السبب. لاحظ أنه يتم بالفعل إضافة httpunhandlexception و targetInvocationException إلى قائمة استثناءات Wrapper ؛ ليس عليك إضافة هذه يدويًا. تكون هذه الطريقة مفيدة إذا كان لديك استثناءات ملفات مخصصة خاصة بك ، أو إطار العمل هو إلقاء الاستثناءات باستخدام غلافه الخاص.
يوجد خاصية تسمى User على RaygunClient والتي يمكنك تعيينها لتكون معرف المستخدم الحالي. يتيح لك ذلك رؤية عدد المستخدمين المتأثرين لكل خطأ في لوحة معلومات Raygun.
إذا كنت تريد المزيد من المعلومات التفصيلية حول المستخدمين (والقدرة على استخدام ميزة الإبلاغ عن المستخدم المتأثرة الجديدة عند إصدارها) ، فيمكنك تعيين خاصية UserInfo على RaygunClient إلى كائن RayGunidentIdifiStage جديد. تحتوي هذه الفئة على عدد من الخصائص عليه للمساعدة في تحديد هوية المستخدم الذي عانى من تعطل.
تأكد من الالتزام بأي سياسات خصوصية تتبعها شركتك عند استخدام هذه الميزة.
الحقل الوحيد المطلوب هو معرف.
Identifier هو المعرف الفريد من نظامك لهذا المستخدم.
IsAnonymous هو علامة تشير إلى ما إذا كان المستخدم مسجلاً (أو يمكن التعرف عليه) أو إذا كان مجهول الهوية. لا يزال من الممكن أن يكون لدى المستخدم المجهول معرفًا فريدًا.
Email بريد إلكتروني المستخدم بالبريد الإلكتروني. إذا كنت تستخدم عناوين البريد الإلكتروني لتحديد المستخدمين ، فلا تتردد في تعيين المعرف على بريدهم الإلكتروني وترك هذا الفراغ ، حيث سنستخدم المعرف كعنوان البريد الإلكتروني إذا بدا أنه واحد ، ولم يتم تحديد عنوان بريد إلكتروني.
FullName اسم المستخدم الكامل.
FirstName اسم المستخدم الأول (أو المفضل).
UUID معرف الجهاز. يمكن استخدامها لتحديد المستخدمين عبر الأجهزة ، أو الآلات التي تكسر للعديد من المستخدمين.
raygunClient . User = "[email protected]" ;
// OR
raygunClient . UserInfo = new RaygunIdentifierMessage ( "[email protected]" )
{
IsAnonymous = false ,
FullName = "Robbie Raygun" ,
FirstName = "Robbie"
} ; بشكل افتراضي ، سيرسل Raygun إصدار التجميع من مشروعك مع كل تقرير.
إذا كنت بحاجة إلى توفير قيمة الإصدار المخصص الخاص بك ، فيمكنك القيام بذلك عن طريق تعيين خاصية Applicationversion الخاصة بـ Raygunclient (بالتنسيق xxxx حيث X عبارة عن عدد صحيح موجب).
عند إرسال استثناءات يدويًا ، يمكنك أيضًا إرسال قائمة علامات تعسفية (مجموعة من الأوتار) ، ومجموعة من البيانات المخصصة (قاموس أي كائنات). يمكن القيام بذلك باستخدام مختلف عمليات التحميل الزائد للرسالة والرسل.
يستخدم موفر Raygun4Net إعدادات Windows Proxy الافتراضية (كما هو محدد في علامة التبويب اتصال Internet Explorer ، أو Web.Config) عند إرسال الرسائل إلى API Raygun. إذا كان الوكيل الخاص بك يتطلب بيانات اعتماد المصادقة ، فيمكنك تقديمها عن طريق تعيين خاصية ProxyCredentials بعد إنشاء رايغونكلينت ، ثم استخدامها لإرسالها لاحقًا:
var raygunClient = new RaygunClient ( )
{
ProxyCredentials = new NetworkCredential ( "user" , "password" )
} ; يمكنك توفير مفتاح التجميع الخاص بك إذا كنت ترغب في ذلك. نوصي فقط بهذا ، فأنت تواجه مشكلات مع الأخطاء التي لا يتم تجميعها بشكل صحيح.
على مثيل Raygunclient ، قم بإرفاق معالج حدث بحدث CustomGroupingKey. سيتم استدعاء معالج الحدث هذا بعد أن قام Raygun ببناء كائن RaygunMessage ، ولكن قبل أن يتم استدعاء حدث SendingMessage. توفر وسيطات الحدث كائن RaygunMessage الذي على وشك إرساله ، والاستثناء الأصلي الذي أثاره. يمكنك استخدام أي شيء ترغب في إنشاء المفتاح ، وتعيينه بواسطة خاصية CustomGroupingKey على وسيطات الحدث. سيترك تعيينه على سلسلة فارغة أو فارغة الاستثناء الذي يتم تجميعه بواسطة Raygun ، مما يؤدي إلى شيء ما سيؤدي إلى تجميع Raygun مع استثناءات أخرى أرسلتها باستخدام هذا المفتاح.
المفتاح لديه الحد الأقصى للطول 100.
<RaygunSettings apikey="[Raygun4Net api key goes here]" throwOnError="true"/>
