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));
}

1. Supported .NET Frameworks
2. Installation
   1. Prerequisites
   2. NuGet installation
3. Running sample application
   1. Visual Studio
   2. .NET Core CLI
   3. Visual Studio for Mac
4. Documentation
   1. Initialize new BacktraceClient
   2. Sending a report
   3. Events
   4. Customization
5. Architecture
   1. BacktraceReport
   2. BacktraceClient
   3. BacktraceData
   4. BacktraceApi
   5. BacktraceDatabase
   6. ReportWatcher
6. 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 recommend Visual Studio 2017 or above for IDE. You can download and install Visual Studio here. As an alternative to Visual Studio you can use .NET Core command line interface, see installation guide here
• On Mac OS X, you can download and install Visual 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 for Linux 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 or open project directory in Visual Studio.
• In Solution Explorer navigate to directory Sample and set preffered project (.NET Core/Framework) as startup project.

• Open Program.cs class in any Backtrace Sample project and replace BacktraceCredential constructor patemeters with with your Backtrace endpoint URL (e.g. https://xxx.sp.backtrace.io:6098) and submission token:

    var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");

• Press Ctrl+Shift+B to build 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 replace BacktraceCredential constructor patemeters with with your Backtrace endpoint URL (e.g. https://xxx.sp.backtrace.io:6098) and submission 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 replace BacktraceCredential constructor patemeters with with your Backtrace endpoint URL (e.g. https://xxx.sp.backtrace.io:6098) and submission 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 a databaseDirectory 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 the reportPerMin 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 default BacktraceApi.Send method. A RequestHandler handler requires 3 parameters - uri, header and formdata bytes. Default Send method won't execute when a RequestHandler handler is attached.
• OnServerError - attach an event handler to be invoked when the server returns with a 400 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.