raygun4net
Tidy up release of TLS 1.2 work
Penyedia Raygun untuk .NET Framework
Proyek yang dibangun dengan kerangka kerja berikut didukung:
Instal Paket Nuget ke proyek yang menggunakan salah satu kerangka kerja di atas dan perakitan yang benar akan direferensikan.
Untuk Xamarin, kami merekomendasikan untuk menambahkan raygun4xamarin.Forms, atau mindscape.raygun4net.xamarin.android & mindscape.raygun4net.xamarin.ios.
Untuk .NET Core dan .NET versi 5.0 atau lebih tinggi, kami sarankan menggunakan paket mindscape.raygun4net.netcore.
dotnet add package Mindscape.Raygun4NetLihat dokumen Raygun untuk instruksi yang lebih rinci tentang cara menggunakan penyedia ini.
Saat mengirim pengecualian ke layanan Raygun, tombol API API diperlukan untuk memetakan pesan ke aplikasi Anda.
Saat Anda membuat aplikasi baru di dasbor Raygun Anda, tombol API aplikasi Anda ditampilkan di dalam halaman Instruksi. Anda juga dapat menemukan tombol API dengan mengklik tombol "Pengaturan Aplikasi" di bilah samping dasbor Raygun.
Kelas -kelas utama dapat ditemukan di namespace mindscape.raygun4net.
Penyedia Raygun4Net mencakup dukungan untuk banyak kerangka kerja. Gulir ke bawah untuk menemukan informasi tentang penggunaan Raygun untuk jenis aplikasi Anda.
Pada versi 5.0.0, dukungan ASP.NET telah dipindahkan ke paket Nuget baru. Jika Anda memiliki proyek ASP.NET, silakan hapus instalasi paket Raygun4net Nuget dan instal paket nuget mindscape.raygun4net.aspnetcore.
Setelah paket diinstal, tambahkan kode berikut ke appsettings.json (jika Anda menggunakan jenis konfigurasi lain, tambahkan di sana):
"RaygunSettings" : {
"ApiKey" : " YOUR_APP_API_KEY "
}Mengkonfigurasi Raygun Middleware untuk menangani pengecualian yang telah dipicu dan mengirim pengecualian yang tidak ditangani secara otomatis.
Di Program.cs :
using Mindscape.Raygun4Net.AspNetCore; ke pernyataan menggunakan Anda.builder.Services.AddRaygun(builder.Configuration); .app.UseRaygun(); Setelah metode Pengecualian lainnya misalnya app.UseDeveloperExceptionPage() atau 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*/Pengaturan di atas akan menyebabkan semua pengecualian yang tidak ditangani dikirim ke akun Raygun Anda, di mana Anda dapat dengan mudah melihat semua data pemantauan kesalahan dan crash Anda.
Node konsumsi Raygun memerlukan TLS 1.2 atau TLS 1.3 jika Anda menggunakan .NET 3.5 atau lebih awal , Anda mungkin perlu mengaktifkan protokol ini dalam aplikasi Anda dan menambal OS Anda.
Lihat Panduan Pemecahan Masalah TLS dari Microsoft untuk rekomendasi mereka.
Memperbarui properti Protokol dalam kode startup aplikasi Anda.
protected void Application_Start ( )
{
// Enable TLS 1.2 and TLS 1.3
ServicePointManager . SecurityProtocol |= ( ( SecurityProtocolType ) 3072 /*TLS 1.2*/ | ( SecurityProtocolType ) 12288 /*TLS 1.3*/ ) ;
} Di file web.config Anda, temukan atau tambahkan elemen <configSections> , yang harus bersarang di bawah elemen <configuration> , dan tambahkan entri berikut:
<section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/>
Kemudian referensi dengan menambahkan baris berikut di suatu tempat setelah tag configSections .
< RaygunSettings apikey = " YOUR_APP_API_KEY " />Sekarang Anda dapat mengatur Raygun untuk mengirim pengecualian yang tidak ditangani secara otomatis atau/dan mengirim pengecualian secara manual.
Untuk mengirim pengecualian yang tidak ditangani secara otomatis, gunakan modul Raygun HTTP dalam elemen <configuration> di Web.config. Ini dilakukan sedikit berbeda tergantung pada versi IIS apa yang Anda gunakan. Jika ragu, coba keduanya:
< system .web>
< httpModules >
< add name = " RaygunErrorModule " type = " Mindscape.Raygun4Net.RaygunHttpModule " />
</ httpModules >
</ system .web> Untuk IIS 7.0, gunakan system.webServer
< system .webServer>
< modules >
< add name = " RaygunErrorModule " type = " Mindscape.Raygun4Net.RaygunHttpModule " />
</ modules >
</ system .webServer>Di mana saja dalam kode Anda, Anda juga dapat mengirim laporan pengecualian secara manual hanya dengan membuat instance baru dari Raygunclient dan memanggil salah satu metode Send atau SendInbackground. Ini paling umum digunakan untuk mengirim pengecualian yang ditangkap dalam blok mencoba/menangkap.
try
{
}
catch ( Exception e )
{
new RaygunClient ( ) . SendInBackground ( e ) ;
}Atau untuk mengirim pengecualian di penangan Anda sendiri daripada menggunakan pengaturan otomatis di atas.
protected void Application_Error ( )
{
var exception = Server . GetLastError ( ) ;
new RaygunClient ( ) . Send ( exception ) ;
} Kecualikan kesalahan dengan kode status http
Jika menggunakan modul HTTP maka Anda dapat mengecualikan kesalahan dengan kode status HTTP mereka dengan memberikan daftar kode status yang terpisah koma untuk diabaikan dalam konfigurasi. Misalnya jika Anda ingin mengecualikan kesalahan yang mengembalikan kode respons TEAPOOT I'm a Teapot, Anda dapat menggunakan konfigurasi di bawah ini.
< RaygunSettings apikey = " YOUR_APP_API_KEY " excludeHttpStatusCodes = " 418 " />Mengecualikan kesalahan yang berasal dari asal lokal
Toggle Boolean ini dan modul HTTP tidak akan mengirim kesalahan ke Raygun jika permintaan berasal dari asal lokal. yaitu cara untuk mencegah debug/pengembangan lokal memberi tahu Raygun tanpa harus menggunakan transformasi Web.config.
< RaygunSettings apikey = " YOUR_APP_API_KEY " excludeErrorsFromLocal = " true " />Hapus Data Permintaan Sensitif
Jika Anda memiliki data sensitif dalam permintaan HTTP yang ingin Anda cegah untuk ditransmisikan ke Raygun, Anda dapat memberikan daftar kunci (nama) yang mungkin untuk dihapus. Kunci yang harus diabaikan dapat ditentukan pada tag RaygunSettings di web.config, (atau Anda dapat menggunakan metode yang setara pada rayguncclient jika Anda menyiapkan segalanya dalam kode). Opsi yang tersedia adalah:
Ini dapat diatur untuk menjadi daftar kunci yang terpisah untuk diabaikan. Menetapkan opsi sebagai * akan menunjukkan bahwa semua kunci tidak akan dikirim ke Raygun. Menempatkan * sebelum, setelah atau di kedua ujung kunci akan melakukan ujung-dengan, mulai dengan atau berisi operasi masing-masing. Misalnya, IgnoreFormFieldNames = "*Kata Sandi*" akan menyebabkan Raygun mengabaikan semua bidang formulir yang berisi "Kata Sandi" di mana saja dalam nama. Opsi -opsi ini tidak sensitif pada kasus.
Memberikan Raygunclient Kustom ke Modul HTTP
Kadang -kadang saat menyiapkan Raygun menggunakan modul HTTP untuk mengirim pengecualian secara otomatis, Anda mungkin perlu menyediakan modul HTTP dengan instance RayGunclient khusus untuk menggunakan beberapa fitur opsional yang dijelaskan di akhir file ini. Untuk melakukan ini, dapatkan aplikasi HTTP Anda untuk mengimplementasikan antarmuka IrayGunApplication. Menerapkan metode GeneraterayGunclient untuk mengembalikan instance RayGunclient yang baru (atau sebelumnya dibuat). Modul HTTP akan menggunakan raygunclient yang dikembalikan dari metode ini untuk mengirim pengecualian yang tidak ditangani. Dalam metode ini Anda dapat mengatur opsi tambahan apa pun pada instance RayGunclient yang Anda butuhkan - informasi lebih lanjut tentang setiap fitur dijelaskan di akhir file ini.
Pada versi 4.0.0, dukungan MVC telah dipindahkan ke paket Nuget baru. Jika Anda memiliki proyek MVC, silakan hapus instalasi paket Raygun4net Nuget dan instal paket nuget Mindscape.Raygun4Net.Mvc sebagai gantinya.
Setelah paket diinstal, lihat paket ReadMe untuk instruksi tentang konfigurasi.
Paket MVC dan WebAPI Nuget dapat diinstal dalam proyek yang sama dengan aman.
Pada versi 4.0.0, dukungan WebAPI telah dipindahkan ke paket Nuget baru. Jika Anda memiliki proyek WebAPI, silakan hapus instalasi paket Raygun4net Nuget dan instal paket nuget Mindscape.Raygun4Net.WebApi sebagai gantinya.
Setelah paket diinstal, lihat paket ReadMe untuk instruksi tentang konfigurasi.
Paket MVC dan WebAPI Nuget dapat diinstal dalam proyek yang sama dengan aman.
Buat instance Raygunclient dengan menyampaikan tombol API aplikasi Anda di konstruktor. Lampirkan event handler ke acara DispatcherunhandledException dari aplikasi Anda. Dalam event handler, gunakan metode raygunclient.send untuk mengirim pengecualian.
private RaygunClient _client = new RaygunClient ( "YOUR_APP_API_KEY" ) ;
public App ( )
{
DispatcherUnhandledException += OnDispatcherUnhandledException ;
}
void OnDispatcherUnhandledException ( object sender , DispatcherUnhandledExceptionEventArgs e )
{
_client . Send ( e . Exception ) ;
}Buat instance Raygunclient dengan menyampaikan tombol API aplikasi Anda di konstruktor. Lampirkan event handler ke acara application.threadException sebelum memanggil application.run (...). Dalam event handler, gunakan metode raygunclient.send untuk mengirim pengecualian.
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 ) ;
}Dalam konstruktor app.xaml.cs (atau titik masuk utama apa pun ke aplikasi Anda), hubungi metode statis raygunclient.Attach menggunakan kunci API Anda.
public App ( )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
}Pada titik mana pun setelah memanggil metode lampirkan, Anda dapat menggunakan rayguncclient.current untuk mendapatkan instance statis. Ini dapat digunakan untuk mengirim pesan secara manual (melalui metode kirim) atau mengubah opsi seperti string identitas pengguna.
Opsi yang tersedia di WinRT untuk menangkap pengecualian yang tidak ditangani pada saat ini lebih terbatas dibandingkan dengan opsi dalam kerangka kerja .NET yang lebih matang. Peristiwa UNHANDLEDEXCEPTION akan dinaikkan ketika XAML tidak valid diuraikan, di samping pengecualian runtime lain yang terjadi pada utas UI utama. Sementara banyak kesalahan akan diambil dengan cara ini dan karena itu dapat dikirim ke Raygun, yang lain akan dirindukan oleh penangan pengecualian ini. Khususnya kode atau tugas asinkron yang dieksekusi pada utas latar tidak akan memiliki pengecualian mereka.
Solusi untuk masalah ini disediakan dengan metode Wrap (). Ini memungkinkan Anda untuk meneruskan kode yang ingin Anda jalankan ke instance dari klien Raygun - itu hanya akan menyebutnya dikelilingi oleh blok mencoba -tangkapan. Jika metode yang Anda lewati tidak menghasilkan pengecualian yang dilemparkan, ini akan ditransmisikan ke Raygun, dan pengecualian akan dilemparkan kembali. Tersedia dua kelebihan; satu untuk metode yang mengembalikan void dan satu lagi untuk metode yang mengembalikan objek.
Pilihan lain adalah menggunakan perpustakaan Fody, dan ekstensi AsyncerrorHandler -nya. Ini akan secara otomatis menangkap pengecualian async dan meneruskannya ke pawang pilihan Anda (yang akan dikirim ke Raygun seperti di atas). Lihat instruksi instalasi di sini, lalu periksa proyek sampel untuk cara menggunakannya.
Dalam aktivitas utama/entri aplikasi Anda, gunakan metode statis rayguncclient.Attach menggunakan tombol API aplikasi Anda. Ada juga kelebihan untuk metode lampirkan yang memungkinkan Anda meneruskan string identitas pengguna yang berguna untuk melacak pengguna yang terkena dampak di dasbor Raygun Anda.
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;Pada titik mana pun setelah memanggil metode lampirkan, Anda dapat menggunakan rayguncclient.current untuk mendapatkan instance statis. Ini dapat digunakan untuk mengirim pesan secara manual atau mengubah opsi seperti string identitas pengguna.
Di titik masuk utama aplikasi, gunakan metode statis raygunclient.Attach menggunakan tombol API aplikasi Anda.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
UIApplication . Main ( args , null , "AppDelegate" ) ;
}Ada juga kelebihan metode lampirkan yang memungkinkan Anda mengaktifkan pelaporan crash iOS asli.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" , true , true ) ;
UIApplication . Main ( args , null , "AppDelegate" ) ;
}Parameter boolean pertama adalah hanya untuk mengaktifkan pelaporan kesalahan iOS asli. Parameter boolean kedua adalah apakah akan membajak beberapa sinyal asli atau tidak - ini untuk menyelesaikan masalah Reporter Kecelakaan IOS yang terkenal di mana pengecualian referensi nol dalam blok Coba/Catch dapat menyebabkan aplikasi macet. Dengan mengatur parameter Boolean kedua ke True, kode yang dikelola akan mengambil alih sinyal iOS Sigbus dan Sigsegv yang memecahkan masalah referensi nol. Namun melakukan hal ini mencegah kesalahan asli Sigbus dan Sigsegv dari terdeteksi, yang berarti mereka tidak dikirim ke Raygun. Inilah sebabnya kami memberikan ini sebagai opsi - jadi jika Anda tidak memiliki masalah dengan pengecualian referensi nol yang terjadi dalam blok coba/tangkap dan Anda ingin memaksimalkan kesalahan asli yang dapat Anda beri tahu, kemudian atur parameter boolean kedua menjadi false.
Pada titik mana pun setelah memanggil metode lampirkan, Anda dapat menggunakan rayguncclient.current untuk mendapatkan instance statis. Ini dapat digunakan untuk mengirim pesan secara manual atau mengubah opsi seperti string identitas pengguna.
Di titik masuk utama aplikasi, gunakan metode statis raygunclient.Attach menggunakan tombol API aplikasi Anda.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
NSApplication . Init ( ) ;
NSApplication . Main ( args ) ;
}Pada titik mana pun setelah memanggil metode lampirkan, Anda dapat menggunakan rayguncclient.current untuk mendapatkan instance statis. Ini dapat digunakan untuk mengirim pesan secara manual atau mengubah opsi seperti string identitas pengguna.
Pada instance RayGunclient, lampirkan pawang acara ke acara SendingMessage. Penangan acara ini akan dipanggil tepat sebelum Raygunclient mengirimkan pengecualian - baik secara otomatis maupun secara manual. Argumen acara memberikan objek Raygunmessage yang akan dikirim. Salah satu penggunaan untuk penangan acara ini adalah menambahkan atau memodifikasi informasi apa pun di Raygunmessage. Penggunaan lain untuk metode ini adalah mengidentifikasi pengecualian yang tidak ingin Anda kirim ke Raygun, dan jika demikian, atur e.cancel = true untuk membatalkan kirim.
Jika Anda memiliki pengecualian luar yang umum yang membungkus pengecualian dalam yang berharga yang Anda lebih suka kelompokkan, Anda dapat menentukannya dengan menggunakan metode multi-parameter:
raygunClient . AddWrapperExceptions ( typeof ( TargetInvocationException ) ) ;Dalam hal ini, jika terjadi targetInvocationException, itu akan dihapus dan diganti dengan innerexception yang sebenarnya yang menjadi penyebabnya. Perhatikan bahwa httpunhandledException dan targetInvocationException sudah ditambahkan ke daftar pengecualian pembungkus; Anda tidak perlu menambahkan ini secara manual. Metode ini berguna jika Anda memiliki pengecualian pembungkus khusus sendiri, atau kerangka kerja melempar pengecualian menggunakan pembungkusnya sendiri.
Ada properti bernama User di Raygunclient yang dapat Anda tetapkan untuk menjadi ID pengguna saat ini. Ini memungkinkan Anda untuk melihat jumlah pengguna yang terkena dampak untuk setiap kesalahan di dasbor Raygun.
Jika Anda ingin informasi lebih rinci tentang pengguna (dan kemampuan untuk menggunakan fitur pelaporan pengguna yang terkena dampak baru saat dirilis), Anda dapat mengatur properti UserInfo pada RayGunclient ke objek RayGunIdenIfierMessage baru. Kelas ini memiliki sejumlah properti di atasnya untuk membantu mengidentifikasi pengguna yang mengalami kerusakan.
Pastikan untuk mematuhi kebijakan privasi apa pun yang diikuti perusahaan Anda saat menggunakan fitur ini.
Satu -satunya bidang yang diperlukan adalah pengidentifikasi.
Identifier adalah pengidentifikasi unik dari sistem Anda untuk pengguna ini.
IsAnonymous adalah bendera yang menunjukkan apakah pengguna masuk (atau dapat diidentifikasi) atau jika mereka anonim. Pengguna anonim masih dapat memiliki pengidentifikasi yang unik.
Email alamat email pengguna. Jika Anda menggunakan alamat email untuk mengidentifikasi pengguna Anda, jangan ragu untuk mengatur pengidentifikasi ke email mereka dan membiarkan ini kosong, karena kami akan menggunakan pengidentifikasi sebagai alamat email jika terlihat seperti itu, dan tidak ada alamat email yang tidak ditentukan.
FullName nama lengkap pengguna.
FirstName nama pengguna pertama (atau lebih disukai).
UUID A Device Identifier. Dapat digunakan untuk mengidentifikasi pengguna di seluruh perangkat, atau mesin yang melanggar banyak pengguna.
raygunClient . User = "[email protected]" ;
// OR
raygunClient . UserInfo = new RaygunIdentifierMessage ( "[email protected]" )
{
IsAnonymous = false ,
FullName = "Robbie Raygun" ,
FirstName = "Robbie"
} ; Secara default, Raygun akan mengirim versi perakitan proyek Anda dengan setiap laporan.
Jika Anda perlu memberikan nilai versi kustom Anda sendiri, Anda dapat melakukannya dengan mengatur properti ApplicationVersion dari RayGunclient (dalam format xxxx di mana x adalah bilangan bulat positif).
Saat mengirim pengecualian secara manual, Anda juga dapat mengirim daftar tag yang sewenang -wenang (serangkaian string), dan kumpulan data khusus (kamus objek apa pun). Ini dapat dilakukan dengan menggunakan berbagai Metode Kirim dan SendInbackground yang berlebihan.
Penyedia Raygun4Net menggunakan pengaturan proxy Windows default (sebagaimana diatur dalam tab Koneksi Internet Explorer, atau Web.config) saat mengirim pesan ke Raygun API. Jika proxy Anda memerlukan kredensial otentikasi, Anda dapat menyediakannya dengan mengatur properti ProxyCredentials setelah instantiating raygunclient, kemudian menggunakannya untuk mengirim nanti:
var raygunClient = new RaygunClient ( )
{
ProxyCredentials = new NetworkCredential ( "user" , "password" )
} ; Anda dapat memberikan kunci pengelompokan Anda sendiri jika diinginkan. Kami hanya merekomendasikan ini Anda mengalami masalah dengan kesalahan yang tidak dikelompokkan dengan benar.
Pada instance RayGunclient, lampirkan pawang acara ke acara CustomGroupingKey. Penangan acara ini akan dipanggil setelah Raygun telah membangun objek Raygunmessage, tetapi sebelum acara SendingMessage dipanggil. Argumen acara memberikan objek Raygunmessage yang akan dikirim, dan pengecualian asli yang memicu. Anda dapat menggunakan apa pun yang Anda suka untuk menghasilkan kunci, dan atur dengan properti CustomGroupingKey pada argumen acara. Mengaturnya ke NULL atau EMPKED STRING akan meninggalkan pengecualian untuk dikelompokkan oleh Raygun, mengaturnya ke sesuatu akan menyebabkan Raygun mengelompokkannya dengan pengecualian lain yang telah Anda kirim dengan kunci itu.
Kunci memiliki panjang maksimum 100.
<RaygunSettings apikey="[Raygun4Net api key goes here]" throwOnError="true"/>
