raygun4net
Tidy up release of TLS 1.2 work
Fournisseur Raygun pour .NET Framework
Les projets construits avec les cadres suivants sont pris en charge:
Installez le package NuGet sur un projet qui utilise l'un des cadres ci-dessus et l'assemblage correct sera référencé.
Pour Xamarin, nous avons recommandé d'ajouter Raygun4xamarin.Forms, ou le MindScape.Raygun4Net.xamarin.Android & MindScape.Raygun4net.xamarin.ios.Unified Packages.
Pour .NET Core et .NET Versions 5.0 ou supérieur, nous vous recommandons d'utiliser le package MindScape.Raygun4Net.netcore.
dotnet add package Mindscape.Raygun4NetVoir les documents Raygun pour des instructions plus détaillées sur la façon d'utiliser ce fournisseur.
Lors de l'envoi d'exceptions au service Raygun, une clé API APP est nécessaire pour mapper les messages à votre application.
Lorsque vous créez une nouvelle application dans votre tableau de bord Raygun, la touche API de votre application s'affiche dans la page Instructions. Vous pouvez également trouver la touche API en cliquant sur le bouton "Paramètres d'application" dans la barre latérale du tableau de bord Raygun.
Les classes principales se trouvent dans l'espace de noms MindScape.RayGun4Net.
Le fournisseur Raygun4Net comprend la prise en charge de nombreux frameworks .NET. Faites défiler vers le bas pour trouver des informations sur l'utilisation de Raygun pour votre type d'application.
À partir de la version 5.0.0, le support ASP.NET a été transféré dans un nouveau package NuGet. Si vous avez un projet ASP.NET, veuillez désinstaller le package Raygun4Net NuGet et installer le package MindScape.Raygun4net.Aspnetcore NuGet.
Une fois le package installé, ajoutez le code suivant à votre appSettings.json (si vous utilisez un autre type de configuration, ajoutez-le là-bas):
"RaygunSettings" : {
"ApiKey" : " YOUR_APP_API_KEY "
}Configurez le middleware Raygun pour gérer les exceptions qui ont été déclenchées et envoyer automatiquement des exceptions non gérées.
Dans Program.cs :
using Mindscape.Raygun4Net.AspNetCore; à vos instructions en utilisant.builder.Services.AddRaygun(builder.Configuration); .app.UseRaygun(); Après toute autre méthode d'exception d'autorité de matière, par exemple, app.UseDeveloperExceptionPage() ou 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*/La configuration ci-dessus entraînera l'envoi de toutes les exceptions non gérées à votre compte Raygun, où vous pouvez facilement afficher toutes vos données de surveillance des erreurs et de rapport de plantage.
Les nœuds d'ingestion de Raygun nécessitent TLS 1.2 ou TLS 1.3 Si vous utilisez .NET 3.5 ou plus tôt , vous devrez peut-être activer ces protocoles dans votre application et patcher votre système d'exploitation.
Consultez le guide de dépannage TLS de Microsoft pour leurs recommandations.
Mise à jour de la propriété Protocole dans le code de démarrage de votre application.
protected void Application_Start ( )
{
// Enable TLS 1.2 and TLS 1.3
ServicePointManager . SecurityProtocol |= ( ( SecurityProtocolType ) 3072 /*TLS 1.2*/ | ( SecurityProtocolType ) 12288 /*TLS 1.3*/ ) ;
} Dans votre fichier web.config, recherchez ou ajoutez un élément <configSections> , qui doit être imbriqué sous l'élément <configuration> , et ajouter l'entrée suivante:
<section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/>
Ensuite, référencez-le en ajoutant la ligne suivante quelque part après la balise configSections .
< RaygunSettings apikey = " YOUR_APP_API_KEY " />Vous pouvez désormais configurer Raygun pour envoyer automatiquement des exceptions non gérées ou / et envoyer des exceptions manuellement.
Pour envoyer automatiquement des exceptions non gérées, utilisez le module Raygun HTTP dans l'élément <configuration> dans web.config. Cela se fait légèrement différemment en fonction de la version de l'IIS que vous utilisez. En cas de doute, essayez-les tous les deux:
< system .web>
< httpModules >
< add name = " RaygunErrorModule " type = " Mindscape.Raygun4Net.RaygunHttpModule " />
</ httpModules >
</ system .web> Pour IIS 7.0, utilisez system.webServer
< system .webServer>
< modules >
< add name = " RaygunErrorModule " type = " Mindscape.Raygun4Net.RaygunHttpModule " />
</ modules >
</ system .webServer>Partout dans votre code, vous pouvez également envoyer des rapports d'exception manuellement simplement en créant une nouvelle instance du RaygunClient et appeler l'une des méthodes Sending ou Sendinbackground. Ceci est le plus souvent utilisé pour envoyer des exceptions prises dans un bloc d'essai / capture.
try
{
}
catch ( Exception e )
{
new RaygunClient ( ) . SendInBackground ( e ) ;
}Ou pour envoyer des exceptions dans vos propres gestionnaires plutôt que d'utiliser la configuration automatique ci-dessus.
protected void Application_Error ( )
{
var exception = Server . GetLastError ( ) ;
new RaygunClient ( ) . Send ( exception ) ;
} Exclure les erreurs par code d'état HTTP
Si vous utilisez le module HTTP, vous pouvez exclure les erreurs par leur code d'état HTTP en fournissant une liste de codes d'état séparée par des virgules à ignorer dans la configuration. Par exemple, si vous vouliez exclure les erreurs qui renvoient le code de réponse à I'm a Teapot, vous pouvez utiliser la configuration ci-dessous.
< RaygunSettings apikey = " YOUR_APP_API_KEY " excludeHttpStatusCodes = " 418 " />Exclure les erreurs provenant d'une origine locale
Basculer ce booléen et le module HTTP n'enverra pas d'erreurs à Raygun si la demande provient d'une origine locale. c'est-à-dire un moyen d'empêcher le débogage / développement local de notifier Raygun sans avoir à recourir à des transformations Web.config.
< RaygunSettings apikey = " YOUR_APP_API_KEY " excludeErrorsFromLocal = " true " />Supprimer les données de demande sensible
Si vous avez des données sensibles dans une demande HTTP que vous souhaitez empêcher d'être transmise à Raygun, vous pouvez fournir des listes de clés (noms) possibles à supprimer. Les clés à ignorer peuvent être spécifiées sur la balise RayGunSettings dans web.config, (ou vous pouvez utiliser les méthodes équivalentes sur RayGunClient si vous définissez des choses dans le code). Les options disponibles sont:
Ceux-ci peuvent être définis pour être une liste de clés séparée par des virgules à ignorer. La définition d'une option comme * indiquera que toutes les clés ne seront pas envoyées à Raygun. Placer * avant, après ou aux deux extrémités d'une clé effectuera une extrémité avec, commence avec ou contient respectivement l'opération. Par exemple, IgnoreFormFieldNames = "* Mot de passe *" fera ignorer Raygun tous les champs de formulaire qui contiennent "mot de passe" n'importe où dans le nom. Ces options ne sont pas sensibles à la casse.
Fournir un raygunclient personnalisé au module HTTP
Parfois, lors de la configuration de Raygun à l'aide du module HTTP pour envoyer automatiquement des exceptions, vous devrez peut-être fournir au module HTTP une instance RayGunClient personnalisée afin d'utiliser une partie de la fonction facultative décrite à la fin de ce fichier. Pour ce faire, demandez à votre application HTTP d'implémenter l'interface IraygunApplication. Implémentez la méthode GeneraterayGunClient pour renvoyer une nouvelle instance RayGunClient (ou précédemment créée). Le module HTTP utilisera le RayGunClient renvoyé de cette méthode pour envoyer les exceptions non gérées. Dans cette méthode, vous pouvez configurer toutes les options supplémentaires sur l'instance RayGunClient dont vous avez besoin - plus d'informations sur chaque fonctionnalité sont décrites à la fin de ce fichier.
À partir de la version 4.0.0, le support MVC a été transféré dans un nouveau package NuGet. Si vous avez un projet MVC, veuillez désinstaller le package Raygun4Net NuGet et installer le package Mindscape.Raygun4Net.Mvc Nuget à la place.
Une fois le package installé, consultez le Package Readme pour les instructions sur la configuration.
Les packages MVC et WebAPI NuGet peuvent être installés dans le même projet en toute sécurité.
À partir de la version 4.0.0, le support WebAPI a été transféré dans un nouveau package NuGet. Si vous avez un projet WebAPI, veuillez désinstaller le package Raygun4Net NuGet et installer le package Mindscape.Raygun4Net.WebApi Nuget.
Une fois le package installé, consultez le Package Readme pour les instructions sur la configuration.
Les packages MVC et WebAPI NuGet peuvent être installés dans le même projet en toute sécurité.
Créez une instance de RayGunClient en passant votre clé API d'application dans le constructeur. Joignez un gestionnaire d'événements à l'événement DispatcherUnhandledException de votre application. Dans le gestionnaire d'événements, utilisez la méthode RayGunClient.Send pour envoyer l'exception.
private RaygunClient _client = new RaygunClient ( "YOUR_APP_API_KEY" ) ;
public App ( )
{
DispatcherUnhandledException += OnDispatcherUnhandledException ;
}
void OnDispatcherUnhandledException ( object sender , DispatcherUnhandledExceptionEventArgs e )
{
_client . Send ( e . Exception ) ;
}Créez une instance de RayGunClient en passant votre clé API d'application dans le constructeur. Joignez un gestionnaire d'événements à l'événement Application.ThreadException avant d'appeler Application.Run (...). Dans le gestionnaire d'événements, utilisez la méthode RayGunClient.Send pour envoyer l'exception.
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 ) ;
}Dans le constructeur app.xaml.cs (ou tout point d'entrée principal de votre application), appelez la méthode statique RaygunClient.attach à l'aide de votre clé API.
public App ( )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
}À tout moment après avoir appelé la méthode de joints, vous pouvez utiliser RayGunClient.Current pour obtenir l'instance statique. Ceci peut être utilisé pour l'envoi manuel des messages (via les méthodes d'envoi) ou des options de modification telles que la chaîne d'identité utilisateur.
Les options disponibles dans WinRT pour attraper des exceptions non gérées à ce stade sont plus limitées par rapport aux options du framework .NET plus mature. L'événement UNHANDLEDException sera soulevé lorsque le XAML non valide sera analysé, en plus d'autres exceptions d'exécution qui se produisent sur le fil d'interface utilisateur principal. Bien que de nombreuses erreurs soient ramassées de cette façon et pourront donc être envoyées à Raygun, d'autres seront manquées par ce gestionnaire d'exceptions. En particulier, le code ou les tâches asynchrones qui s'exécutent sur les threads d'arrière-plan n'auront pas leurs exceptions capturées.
Une solution de contournement pour ce problème est fournie avec la méthode wrap (). Ceux-ci vous permettent de transmettre le code que vous souhaitez exécuter à une instance du client Raygun - il l'appellera simplement entouré d'un bloc de coups d'essai. Si la méthode que vous transmettez entraîne une exception qui est lancée, cela sera transmis à Raygun, et l'exception sera à nouveau lancée. Deux surcharges sont disponibles; L'une pour les méthodes qui renvoient vide et une autre pour les méthodes qui renvoient un objet.
Une autre option consiste à utiliser la bibliothèque Fody et son extension AsynCerrorHandler. Cela prendra automatiquement des exceptions asynchrones et les transmettra à un gestionnaire de votre choix (qui enverrait à Raygun comme ci-dessus). Voir les instructions d'installation ici, puis consultez l'exemple de projet pour utiliser comment utiliser.
Dans l'activité principale / d'entrée de votre application, utilisez la méthode statique RaygunClient.attach à l'aide de la clé de votre API APP. Il existe également une surcharge pour la méthode d'attache qui vous permet de transmettre une chaîne d'identité utilisateur qui est utile pour suivre les utilisateurs affectés dans votre tableau de bord Raygun.
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;À tout moment après avoir appelé la méthode de joints, vous pouvez utiliser RayGunClient.Current pour obtenir l'instance statique. Cela peut être utilisé pour l'envoi manuellement des messages ou la modification des options telles que la chaîne d'identité utilisateur.
Dans le point d'entrée principal de l'application, utilisez la méthode statique RaygunClient.attach à l'aide de votre clé API d'application.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
UIApplication . Main ( args , null , "AppDelegate" ) ;
}Il existe également une surcharge pour la méthode d'attache qui vous permet d'activer les rapports de crash iOS natifs.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" , true , true ) ;
UIApplication . Main ( args , null , "AppDelegate" ) ;
}Le premier paramètre booléen consiste simplement à activer les rapports d'erreur iOS natifs. Le deuxième paramètre booléen est de savoir si pour détourner certains des signaux natifs - il s'agit de résoudre le problème bien connu du rapporteur de crash iOS où les exceptions de référence null dans un bloc d'essai / capture peuvent entraîner le plantage de l'application. En définissant le deuxième paramètre booléen sur true, le code géré reprendra les signaux Sigbus et Sigsegv iOS qui résout le problème de référence nul. Cela empêche cependant les erreurs natives de Sigbus et Sigsegv, ce qui signifie qu'ils ne sont pas envoyés à Raygun. C'est pourquoi nous fournissons cela en option - donc si vous n'avez aucun problème avec les exceptions de référence nuls se produisant dans les blocs Try / Catch et que vous souhaitez maximiser les erreurs natives dont vous pouvez être informé, puis définissez le deuxième paramètre booléen sur FALSE.
À tout moment après avoir appelé la méthode de joints, vous pouvez utiliser RayGunClient.Current pour obtenir l'instance statique. Cela peut être utilisé pour l'envoi manuellement des messages ou la modification des options telles que la chaîne d'identité utilisateur.
Dans le point d'entrée principal de l'application, utilisez la méthode statique RaygunClient.attach à l'aide de votre clé API d'application.
static void Main ( string [ ] args )
{
RaygunClient . Attach ( "YOUR_APP_API_KEY" ) ;
NSApplication . Init ( ) ;
NSApplication . Main ( args ) ;
}À tout moment après avoir appelé la méthode de joints, vous pouvez utiliser RayGunClient.Current pour obtenir l'instance statique. Cela peut être utilisé pour l'envoi manuellement des messages ou la modification des options telles que la chaîne d'identité utilisateur.
Sur une instance RayGunClient, joignez un gestionnaire d'événements à l'événement SendingMessage. Ce gestionnaire d'événements sera appelé juste avant que RaygunClient envoie une exception - automatiquement ou manuellement. Les arguments de l'événement fournissent l'objet RaygunMessage qui est sur le point d'être envoyé. Une utilisation pour ce gestionnaire d'événements consiste à ajouter ou à modifier toute information sur RaygunMessage. Une autre utilisation pour cette méthode consiste à identifier les exceptions que vous ne souhaitez jamais envoyer à Raygun, et si oui, définissez e.cancel = true pour annuler l'envoi.
Si vous avez des exceptions extérieures courantes qui enveloppent une précieuse exception intérieure que vous préférez vous regrouper, vous pouvez les spécifier en utilisant la méthode multi-paramètres:
raygunClient . AddWrapperExceptions ( typeof ( TargetInvocationException ) ) ;Dans ce cas, si une conception ciblévocation de Target se produit, elle sera supprimée et remplacée par l'intexception réelle qui a été la cause. Notez que HttpunHandledException et TargetInvocationException sont déjà ajoutés à la liste des exceptions de wrapper; Vous n'avez pas à les ajouter manuellement. Cette méthode est utile si vous avez vos propres exceptions de wrapper personnalisées ou si un framework lance des exceptions en utilisant son propre wrapper.
Il existe une propriété nommée User sur RayGunClient que vous pouvez définir pour être l'ID de l'utilisateur actuel. Cela vous permet de voir le nombre d'utilisateurs affectés pour chaque erreur du tableau de bord Raygun.
Si vous souhaitez des informations plus détaillées sur les utilisateurs (et la possibilité d'utiliser la nouvelle fonctionnalité de rapport utilisateur affectée lors de sa publication), vous pouvez définir la propriété UserInfo sur le RayGunClient sur un nouvel objet RayGunIdentifiRemmessage. Cette classe contient un certain nombre de propriétés pour aider à identifier l'utilisateur qui a connu un crash.
Assurez-vous de respecter les politiques de confidentialité que votre entreprise suit lors de l'utilisation de cette fonctionnalité.
Le seul champ requis est l'identifiant.
Identifier est l'identifiant unique de votre système pour cet utilisateur.
IsAnonymous est un indicateur indiquant si l'utilisateur est connecté (ou identifiable) ou s'il est anonyme. Un utilisateur anonyme peut toujours avoir un identifiant unique.
Email à l'adresse e-mail de l'utilisateur. Si vous utilisez des adresses e-mail pour identifier vos utilisateurs, n'hésitez pas à définir l'identifiant sur leur e-mail et à laisser ce blanc, car nous utiliserons l'identifiant comme l'adresse e-mail s'il en ressemble, et aucune adresse e-mail n'est spécifiée.
FullName le nom complet de l'utilisateur.
FirstName premier nom de l'utilisateur (ou préféré).
UUID un identifiant d'appareil. Pourrait être utilisé pour identifier les utilisateurs sur des appareils ou des machines qui se brisent pour de nombreux utilisateurs.
raygunClient . User = "[email protected]" ;
// OR
raygunClient . UserInfo = new RaygunIdentifierMessage ( "[email protected]" )
{
IsAnonymous = false ,
FullName = "Robbie Raygun" ,
FirstName = "Robbie"
} ; Par défaut, Raygun enverra la version assemblée de votre projet avec chaque rapport.
Si vous devez fournir votre propre valeur de version personnalisée, vous pouvez le faire en définissant la propriété ApplicationVersion du RaygunClient (au format xxxx où x est un entier positif).
Lorsque vous envoyez des exceptions manuellement, vous pouvez également envoyer une liste arbitraire de balises (un tableau de chaînes) et une collection de données personnalisées (un dictionnaire de tous les objets). Cela peut être fait en utilisant les diverses surcharges de méthode Send et Sendinbackground.
Le fournisseur Raygun4Net utilise les paramètres de proxy Windows par défaut (comme défini dans l'onglet Connexion d'Internet Explorer, ou web.config) lors de l'envoi de messages à l'API Raygun. Si votre proxy nécessite des informations d'authentification, vous pouvez les fournir en définissant la propriété ProxyCredentials après avoir instancié un RayGunClient, puis en l'utilisant pour envoyer plus tard:
var raygunClient = new RaygunClient ( )
{
ProxyCredentials = new NetworkCredential ( "user" , "password" )
} ; Vous pouvez fournir votre propre clé de regroupement si vous le souhaitez. Nous recommandons seulement que vous ayez des problèmes avec des erreurs qui ne sont pas regroupés correctement.
Sur une instance RayGunClient, joignez un gestionnaire d'événements à l'événement CustomGroupingKey. Ce gestionnaire d'événements sera appelé après que Raygun a construit l'objet RaygunMessage, mais avant que l'événement SendingMessage ne soit appelé. Les arguments de l'événement fournissent l'objet RaygunMessage qui est sur le point d'être envoyé et l'exception originale qui l'a déclenchée. Vous pouvez utiliser tout ce que vous aimez pour générer la clé et le définir par la propriété CustomGroupingKey sur les arguments de l'événement. Le définir sur NULL ou Empty String laissera l'exception pour être regroupé par Raygun, le définir sur quelque chose obligera Raygun à le regrouper avec d'autres exceptions que vous avez envoyées avec cette clé.
La clé a une longueur maximale de 100.
<RaygunSettings apikey="[Raygun4Net api key goes here]" throwOnError="true"/>
