Backtrace's integration with C# applications allows customers to capture and report handled and unhandled C# exceptions to their Backtrace instance, instantly offering the ability to prioritize and debug software errors.
var backtraceCredentials =
new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
// replace with your endpoint url and token
var backtraceClient = new BacktraceClient(backtraceCredentials);
try{
//throw exception here
}
catch(Exception exception){
backtraceClient.Send(new BacktraceReport(exception));
}
- Supported .NET Frameworks
- Installation
- Running sample application
- Documentation
- Architecture
- Good to know
- .NET Framework 3.5 +
- .NET Framework 4.5 +
- getting information about application thread
- handling unhandled application exceptions
- .NET Standard:
- .NET Core 2.0 application
- Xamarin
- Universal Windows Platform
- Unity
- On
Windows
, we recommendVisual Studio 2017
or above for IDE. You can download and installVisual Studio
here. As an alternative toVisual Studio
you can use .NET Core command line interface, see installation guide here - On
Mac OS X
, you can download and installVisual Studio
here if you prefer using an IDE. For command line, you should to download and install .NET Core 2.0 or above. - On
Linux
, Visual Studio Code is available as a light-weight IDE. Similarly, you can use .NET Core command line interface, see instruction forLinux
here
The Backtrace
library is available via NuGet. You can read more about NuGet and how to download the packages here
You can install Backtrace via NuGet using the following commands:
Windows NuGet CLI:
Install-Package Backtrace
Linux/Mac OS X .NET Core CLI:
dotnet add package Backtrace
Visual Studio allows you to build a project and run all available samples (prepared for .NET Core, .NET Framework 4.5, .NET Framework 3.5).
- Double click
.sln
file oropen
project directory in Visual Studio. - In
Solution Explorer
navigate to directorySample
and set preffered project (.NET Core/Framework) as startup project.
- Open
Program.cs
class in any Backtrace Sample project and replaceBacktraceCredential
constructor patemeters with with yourBacktrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) andsubmission token
:
var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
- Press
Ctrl+Shift+B
tobuild
solution - Press
F5
to run the project - You should see new errors in your Backtrace instance. Refresh the Project page or Query Builder to see new details in real-time.
You can use .NET Core's CLI to run sample project on Windows, Mac OS and Linux. To run a sample project using .NET Core CLI:
- While in solution directory, navigate to Backtrace.Core sample application:
cd Backtrace.Core
- Open
Program.cs
in project Backtrace.Core and replaceBacktraceCredential
constructor patemeters with with yourBacktrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) andsubmission token
:
var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
- Build the project:
dotnet build
- When the build completes, run the project:
dotnet run
- You should see new errors in your Backtrace instance. Refresh the Project page or Query Builder to see new details in real-time.
- Open the Backtrace solution in Visual Studio, unload all projects except Backtrace, Backtrace.Tests and Backtrace.Core, and set Backtrace.Core as your startup project:
- Open
Program.cs
class in project Backtrace.Core and replaceBacktraceCredential
constructor patemeters with with yourBacktrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) andsubmission token
:
var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
- Build the project.
- Upon successful build, run the project.
- You should see new errors in your Backtrace instance. Refresh the Project page or Query Builder to see new details in real-time.
First create a BacktraceCredential
instance with your Backtrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) and submission token
, and supply it as a parameter in the BacktraceClient
constructor:
var credentials = new BacktraceCredentials("backtrace_endpoint_url", "token");
var backtraceClient = new BacktraceClient(credentials);
Additionally and optionally, BacktraceClient
constructor also accepts the following parameters: custom attributes, database directory path and maximum number of error reports per minute.
var backtraceClient = new BacktraceClient(
sectionName: "BacktraceCredentials",
attributes: new Dictionary<string, object>() { { "Attribute", "value" } },
databaseDirectory: "pathToDatabaseDirectory",
reportPerMin: 0
);
Note:
databaseDirectory
parameter is optional. Make sure the directory designated is empty. BacktraceClient will use this directory to save additional information relating to program execution. If adatabaseDirectory
path is supplied, the Backtrace library will generate and attach a minidump to each error report automatically.- If parameter
reportPerMin
is equal to 0, there is no limit on the number of error reports per minute. When an error is submitted when thereportPerMin
cap is reached,BacktraceClient.Send
method will return false.
BacktraceClient.Send
method will send an error report to the Backtrace endpoint specified. There Send
method is overloaded, see examples below:
The BacktraceReport
class extends BacktraceReportBase
and represents a single error report. (Optional) You can also submit custom attributes using the attributes
parameter, or attach files by supplying an array of file paths in the attachmentPaths
parameter.
try
{
//throw exception here
}
catch (Exception exception)
{
var report = new BacktraceReport(
exception: exception,
attributes: new Dictionary<string, object>() { { "key", "value" } },
attachmentPaths: new List<string>() { @"file_path_1", @"file_path_2" }
);
backtraceClient.Send(backtraceReport);
}
BacktraceClient
can also automatically create BacktraceReport
given an exception or a custom message using the following overloads of the BacktraceClient.Send
method:
try
{
//throw exception here
}
catch (Exception exception)
{
backtraceClient.Send(exception);
backtraceClient.Send("Message");
}
BacktraceClient
allows you to attach your custom event handlers. For example, you can trigger actions before the Send
method:
//Add your own handler to client API
backtraceClient.BeforeSend =
(Model.BacktraceData<object> model) =>
{
var data = model;
//do something with data for example:
data.Attributes.Add("eventAtrtibute", "EventAttributeValue");
if(data.Classifier == null || !data.Classifier.Any())
{
data.Attachments.Add("path to attachment");
}
return data;
};
BacktraceClient
currently supports the following events:
BeforeSend
AfterSend
OnReportStart
OnClientReportLimitReached
OnUnhandledApplicationException
OnServerResponse
OnServerError
BacktraceClient
also supports reporting of unhandled application exceptions not captured by your try-catch blocks. To enable reporting of unhandled exceptions:
backtraceClient.HandleApplicationException();
You can extend BacktraceReportBase
and BacktraceBase
to create your own Backtrace client and error report implementation. You can refer to BacktraceClient
and BacktraceReport
for implementation inspirations.
BacktraceReport
is a class that describe a single error report that extends BacktraceReportBase
generic class. Argument T
is value type of Attribute
dictionary. Keep in mind that BacktraceClient
uses CallingAssembly
method to retrieve information about your application.
BacktraceClient
is a class that allows you to instantiate a client instance that interacts with BacktraceApi
. This class sets up connection to the Backtrace endpoint and manages error reporting behavior (for example, saving minidump files on your local hard drive and limiting the number of error reports per minute). BacktraceClient
extends BacktraceBase
generic class. T
argument is a value type in Attribute
dictionary.
BacktraceData
is a generic, serializable class that holds the data to create a diagnostic JSON to be sent to the Backtrace endpoint via BacktraceApi
. You can add additional pre-processors for BacktraceData
by attaching an event handler to the BacktraceClient.BeforeSend
event. BacktraceData
require BacktraceReport
and BacktraceClient
client attributes.
BacktraceApi
is a class that sends diagnostic JSON to the Backtrace endpoint. BacktraceApi
is instantiated when the BacktraceClient
constructor is called. You use the following event handlers in BacktraceApi
to customize how you want to handle JSON data:
RequestHandler
- attach an event handler to this event to override the defaultBacktraceApi.Send
method. ARequestHandler
handler requires 3 parameters -uri
,header
andformdata
bytes. DefaultSend
method won't execute when aRequestHandler
handler is attached.OnServerError
- attach an event handler to be invoked when the server returns with a400 bad request
,401 unauthorized
or other HTTP error codes.OnServerResponse
- attach an event handler to be invoked when the server returns with a valid response.
BacktraceApi
can send synchronous and asynchronous reports to the Backtrace endpoint. To prepare asynchronous report (default is synchronous) you have to set AsynchronousRequest
property to true
.
BacktraceDatabase
is a class stores data in your local harddrive. An BacktraceDatabase
instance is instantiated when the BacktraceClient
constructor is called. If databaseDirectory
isn't set in the BacktraceClient
constructor call, BacktraceDatabase
won't generate minidump files. Before start - make sure that the directory designed in BacktraceClient.databaseDirectory is empty.
ReportWatcher
is a class that validate send requests to the Backtrace endpoint. If reportPerMin
is set in the BacktraceClient
constructor call, ReportWatcher
will drop error reports that go over the limit.
You can use this Backtrace library with Xamarin if you change your HttpClient
Implementation to Android
. To change HttpClient
settings, navigate to Android Options
under Project Settings
and click on Advanced
button.