With Xamarin Insights installed and initialized, there are several ways that data can be logged to the service:

1. By catching exceptions (regardless of whether they are in a try/catch enclosure).
2. By sending event information directly to the service, such as to track feature use.
3. By sending time-based events to the service, such as how long a given feature took to execute.

In this section we'll examine how to catch and report exceptions. The other methods are covered in the track events guide.

Catching Exceptions

When running Xamarin Insights in an application, the service will report all exceptions during the lifetime of the application. These exceptions are sent to the server when they occur (provided there is a network connection) or the next time the application is started.

Uncaught Exceptions

When an exception occurs outside of a try/catch block, it is said to be an uncaught exception. Xamarin Insights will automatically report these exceptions in their entirety, by default.

No additional code, beyond the Initialize method, is required for Xamarin Insights to report uncaught exceptions automatically. They can, however, be disabled by setting the DisableExceptionCatching property to true, as explained here.

Inside a Try/Catch Enclosure

By using a try/catch enclosure, you can control what information is sent to the Xamarin Insights service when an exception occurs, and therefore get a clearer picture of the crash and the state of the device.

There are a number of benefits to using a try/catch enclosure:

• Greater stability for the application.
• Able to send reports to the service with greater accuracy.
• Able to send reports to the service with additional information.

Simple Exception Catching

To implement simple exception catching in an application add a call to Insights.Report inside a try/catch block similar to the following code:

try
{
     int divByZero = 42 / int.Parse("0");
}
catch (DivideByZeroException ex)
{
     Insights.Report(ex);
}

The information sent back to the Xamarin Insights service is the entire DivideByZeroException object. It is the same as if the code causing the exception was not wrapped in a try/catch at all, and Xamarin Insights' default reporting behavior was executed.

Adding Additional Information to Exception Catching

It's possible to tailor the exception report sent to Xamarin Insights to provide additional information.

This is achieved by passing a Dictionary of key/value pairs to the Insights.Report() method. For example:

try
 {
      using (var text = File.OpenText("saved_game001.txt"))
      {
           Console.WriteLine("{0}", text.ReadLine());
           ...
      }
 }
 catch (FileNotFoundException ex)
 {
      Insights.Report(ex, new Dictionary<string,string>
      {
           { "Filename", "saved_game001.txt" },
           { "Where", "Reload game" },
           { "Issue", "Index of available games is corrupted" }
      });
}

Here the full exception (ex) is still being sent back to the Xamarin Insights service, but in addition to this, a simple Dictionary containing additional debugging information is also being created and sent. We can send any set of key/value pairs that would be helpful in tracking down an issue, or we could even use reflection to automatically fill the dictionary.

The severity of the exception can be set as an Error or Warning by appending the following after the Dictionary:

• Error: Insights.Severity.Error
• Warning: Insights.Severity.Warning

Note that by default the severity is set to a Warning.