1. Home
  2. Language Guides
  3. Xamarin
  4. Crash Reporting
  5. Xamarin.Forms

Xamarin.Forms

This provider targets .NET Standard 2.0. The currently supported platforms are Android and iOS with the following versions or newer:

  • Xamarin.Android 8.0
  • Xamarin.iOS 10.0

Installation

Step 1 - Install the NuGet package

Install the Raygun4Xamarin.Forms NuGet package into your project. You can either use the dotnet CLI command below, or the NuGet management GUI in the IDE that you use.

dotnet add package Raygun4Xamarin.Forms

NuGet documentation for the Raygun4Xamarin.Forms package can be found here.

Step 2 - Initialize RaygunClient

In the constructor of the App class in your base project, call the static RaygunClient.Init() method with your app API key. Using the static Init method will ensure a shared RaygunClient instance is available through the static property Current.

Note: Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

In App.xaml.cs:

public partial class App : Application
{
  public App()
  {
    InitializeComponent();

    // Initialising the Raygun client 
    RaygunClient.Init("paste_your_api_key_here");
    RaygunClient.Current.EnableCrashReporting();

    // Remaining application setup logic
    MainPage = new MainPage();
  }
}

Step 3 - Configure Raygun for your platform

Each platform being targeted requires an additional configuration step using the RaygunPlatform class in the following places.

In MainActivity.cs:

using Raygun4Xamarin.Forms.Android;

public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
{
  protected override void OnCreate(Bundle savedInstanceState)
  {
    // MainActivity startup logic
    base.OnCreate(savedInstanceState);
    global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
    LoadApplication(new App());

    // Configure Raygun for the current platform
    RaygunPlatform.Configure(this);
  }
}

Android Troubleshooting

You may need to install the Xamarin.Android.Support.LocalBroadcastManager package if you are having troubles getting Raygun working in your Android project. You may also need to set the minimum SDK version of your project to Android 9.

In AppDelegate.cs:

using Raygun4Xamarin.Forms.iOS;

public partial class AppDelegate : global::Xamarin.Forms.Platform.iOS.FormsApplicationDelegate
{
  public override bool FinishedLaunching(UIApplication app, NSDictionary options)
  {
    // AppDelegate startup logic
    global::Xamarin.Forms.Forms.Init();
    LoadApplication(new App());

    // Configure Raygun for the current platform
    RaygunPlatform.Configure();

    return base.FinishedLaunching(app, options);
  }
}

Step 4 - Release

Deploy Raygun into your production environment for best results, or raise a test exception like the example below. Once we detect your first error event, the Raygun app will automatically update.

try
{
  throw new Exception("Temporary example exception to send to Raygun");
}
catch (Exception ex)
{
  _raygunClient.SendInBackground(ex);
}

The Raygun client allows you to inspect the reports before they are sent to Raygun servers. You can inspect and modify the report details or cancel the report from being sent altogether.

This is done by setting an event handler on the shared Raygun client and will be called just before a report is sent - either automatically or manually.

RaygunClient.Current.BeforeSendingCrashReportEvent += (sender, e) =>
{
  if (e.Report.Details.Error.ClassName == "NotImplementedException")
  {
    e.Cancel = true;
  }
};

Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

Here's an example of manually sending a report from a try/catch block:

try
{
  DoSomethingRisky();
}
catch (Exception exception)
{
  var tags = new List<string>() { "ManuallyReport" };
  var customData = new Dictionary<string, object>()
  {
    { "CustomString", "Value" }, 
    { "CustomNumber", 123 }
  };

  RaygunClient.Current.Send(exception, tags, customData);
}

The tags and custom data that is passed through when manually reporting an error will only appear on the associated error report in Raygun. This allows you to add additional information to a report without worrying that all subsequent reports will include this information.

By default, the Raygun client will give a GUID (Globally Unique Identifier) to each user for distinguishing between them. If possible, we highly recommend providing your own unique identifiers for your users which can be done with the code below. The string you pass into the constructor can be whatever unique user id that works best for you - email address is a recommended example. Providing the first name and full name is optional.

RaygunClient.Current.User = new RaygunUserInfo("UNIQUE_ID")
{
  FirstName   = "Ronald",
  FullName    = "Ronald Raygun",
  Email       = "ronald@raygun.com",
  IsAnonymous = false
};

The string properties on a User have a maximum length of 255 characters. Users who have fields that exceed this amount will not be processed.

Using the breadcrumbs feature, you can attach an accurate trail of the events through your system leading up to the moment an error report was generated. You'll gain more insight into why the application crashed when it did, making prioritization of fixes much easier. The current breadcrumbs are included with each report sent.

RaygunClient.Current.RecordBreadcrumb("Entered login screen");

The Raygun client supports tracking a version of your application that is in use when a crash occurs. This is helpful to determine what version was in use when an issue occurred and so if the latest version of your application was in use.

var settings = new RaygunSettings("paste_your_api_key_here") 
{ 
  ApplicationVersion = "1.0.0",
};

// Initialise a client instance.
var client = RaygunClient.Init(settings);

An array of strings can be sent with each report and displayed in Raygun. This can be used to categorise errors or add additional contextual information. These tag values are also searchable in your Raygun dashboard so that you can find all error instances that you've marked with a particular tag.

// Initialise a client instance.
var client = RaygunClient.Init(settings);

// Setting tags that will be sent with every error report.
client.Tags = new List<string>() 
{ 
  "GlobalTag"
};

// Tags can also be added to individual error reports when reported manually
client.Send(exception, new List<string>() { "LocalTag" });

Each error can be reported with a dictionary of custom data. This data gets displayed in Raygun and can be used to record useful contextual information for debugging.

// Initialise a client instance.
var client = RaygunClient.Init(settings);

// Setting information that will be sent with every error report.
client.CustomData = new Dictionary<string, object>() 
{
  { "GlobalString", "Value" },
  { "GlobalValue", 123 }
};

// Tags can also be added to individual error reports when reported manually
client.Send(exception, null, new Dictionary<string, object>()
{
  { "LocalString", "Value" }, 
  { "LocalNumber", 123 }
});

For debugging purposes you can set the level of logging that the provider will print to your debug console. This can be helpful to determine what information is or is not being sent to the Raygun API. The logging level can be set before initialising the Raygun client.

var settings = new RaygunSettings("paste_your_api_key_here") 
{ 
  LogLevel = LogLevel.Verbose
};

// Initialise a client instance.
var client = RaygunClient.Init(settings);

The provider is open source and available at the Raygun4Xamarin repository. There are sample apps available here in the Raygun4Xamarin-samples repository.

On this page: