Instrument Xamarin Applications

On this page:

Follow the steps below to manually instrument your Xamarin iOS, Android, and Forms apps.

The Xamarin Agent does not currently report application crashes.

Supported Platforms

As of AppDynamics 4.3.0, the Xamarin Agent can only be used with iOS and Android applications. All other platforms will build and run without errors, but no monitoring will occur.

Step 1: Get the Xamarin Agent

You obtain the Xamarin Agent from the NuGet Gallery. Follow the instructions given in Adding a Package to add the package AppDynamics Xamarin Agent from nuget.org.

Step 2: Get Your Application Key

Complete the Getting Started Wizard to get an EUM App Key. You will need this key when you modify the source code. In some cases, multiple mobile applications can share the same key.

Because there is no Xamarin platform option, you will need to choose either Android or iOS. For Android, you will need to select Manual.

If you have completed the Getting Started Wizard, but don't have your EUM App Key, see Get Your Application Key.

Step 3: Add the Required Permissions (Android Deployments Only)

Open the file Properties/AndroidManifest.xml and verify that it has these permissions:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>

If these permissions are not present, add them.

Step 4: Link the AppDynamics Agent Assembly

Forms Solution

Xamarin Forms is the unified development environment for running all platforms. If you try to run something on an unsupported platform, linking our agent won't allow you to monitor the application, but it also will not cause any errors.

To use the Xamarin Agent for your iOS/Android apps, add the using directive at the top of the App.xaml.cs file:

using Xamarin.Forms;
using AppDynamics.Agent;

namespace <AppName>
{
    public partial class App : Application
    {
        ...
    }
}

iOS Solution

To use the Xamarin Agent in iOS apps, add the using directive at the top of the AppDelegate.cs file:

using Foundation;
using UIKit;
using AppDynamics.Agent;
 
public class AppDelegate : UIApplicationDelegate
{
    ...
}

Android Solution

To use the Xamarin Agent in Android apps, add the using directive at the top of the MainActivity.cs file:

using Android.App;
using Android.Widget;
using Android.OS;
using System;
using Android.Content;
using AppDynamics.Agent;

namespace <AppName>
{
    [Activity(Label = "Phoneword", MainLauncher = true, Icon = "@mipmap/icon")]
    public class MainActivity : Activity
    {
       ...
    }
    ...
}

Step 5: Initialize the Agent

To initialize the Xamarin Agent, you use the code below for iOS and Android. Use the EUM app key that you received after completing step 2 .

var config = AppDynamics.Agent.AgentConfiguration.Create("EUM_APP_KEY");
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);

If you are running an on-premises EUM Server, you need to specify the URL to the EUM Server. See Step 9: Point to an On-Premises EUM Server (Optional) to learn how.

Forms Solution

You place the initialize code in the constructor of the App.xaml.cs file as shown below.

public App()
{
    InitializeComponent();
    // This initialization code is used by both iOS and Android apps.
    var config = AppDynamics.Agent.AgentConfiguration.Create("EUM_APP_KEY");
    AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
    MainPage = new FormsExamplePage();
}

Android

In the MainActivity.cs file, place the initialization code in the method OnCreate.

namespace <AppName>.Droid
{
    [Activity(Label = "<AppName>.Droid", Icon = "@drawable/icon", Theme = "@style/MyTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]
    public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
    {
        protected override void OnCreate(Bundle bundle)
        {
            var config = AppDynamics.Agent.AgentConfiguration.Create("EUM_APP_KEY");
            AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
            ...
            base.OnCreate(bundle);

            global::Xamarin.Forms.Forms.Init(this, bundle);

            LoadApplication(new App());
        }
    }
}

iOS Solution

For iOS apps, you place the initialize code In the AppDelegate.cs file in the method FinishedLaunching of the class AppDelegate as shown below.

public class AppDelegate : UIApplicationDelegate
{
   // class-level declarations
   public override UIWindow Window
   {
      get;
      set;
   }
   public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
   {
       // The two lines below initialize the AppDynamics instrumentation.
       var config = AppDynamics.Agent.AgentConfiguration.Create("EUM_APP_KEY");
       AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
       ...
       return true;
    }
    ...
}

You may also consider placing it in the Main.cs int the method Main.

Android Solution

In the MainActivity.cs file, place the initialization code in the method OnCreate.

class MainActivity {
 
  protected override void OnCreate(Bundle savedInstanceState) {
    // The two lines below initialize the AppDynamics instrumentation.
    var config = AppDynamics.Agent.AgentConfiguration.Create("EUM_APP_KEY");
    AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
    ...
  }
}

Step 6: Build the Application

Run and build your application from Xamarin Studio. From the Getting Started Wizard, you should see that the application has connected and the instrumentation has been verified.

Step 7: Customize Your Instrumentation (Optional)

The following sections show you how to use the Xamarin SDK to customize your instrumentation. See also the latest Xamarin SDK documentation for the complete Xamarin SDK API.

See the following for past versions of the Xamarin SDK documentation:

Track Calls

You can instrument methods to see how often the instrumented a method is invoked and how long it takes to run. To do this, add a call at the beginning and end of the method you'd like to instrument.

In the example below, the code executed in the constructor for the class MyClass will be tracked and reported. In your own code, start tracking calls by specifying the class and method in BeginCall and then complete the tracking and report the data by calling ReportCallEnded.

public class MyClass {
    public MyClass() {
        var tracker = AppDynamics.Agent.Instrumentation.BeginCall("MyClass", "Constructor");
        // The code placed here will be tracked and reported.
        tracker.ReportCallEnded();
    }
}

Timing Events

Sometimes you want to time an event in your application that spans multiple methods. You can do this by calling StartTimerWithName when the event starts, and then StopTimerWithName when it ends. For example, to track the time a user spends viewing a screen, the instrumentation might look something like the following:

async private void StartCapturePreview_Click(object sender, RoutedEventArgs e) {
    capturePreview.Source = captureManager;
    AppDynamics.Agent.Instrumentation.StartTimerWithName("CapturePreview");
    await captureManager.StartPreviewAsync();
}
async private void StopCapturePreview_Click(object sender, RoutedEventArgs e) {
    await captureManager.StopPreviewAsync();
    AppDynamics.Agent.Instrumentation.StopTimerWithName("CapturePreview");
}

Report Metrics

To report other types of data, you can use a metric. The only requirement is that the metric value must be a long integer. The snippet below shows how you might report a metric.

AppDynamics.Agent.Instrumentation.ReportMetricWithName("Database Rows", 5123);

HTTP Requests

You can report a Network Request by reporting using the AppDynamics.Agent.HTTPRequestTracker class.

The following is an example of using AppDynamics.Agent.HTTPRequestTracker with the System.Net.Http.HttpClient class. Note that AppDynamics.Agent.HTTPRequestTracker is implemented as a "wrapper" and executes the the entire transaction synchronously.

public async Task<string> Fetch(Uri uri) {
 var client = new HttpClient();
 // Create AppDynamics Tracker
 var tracker = AppDynamics.Agent.HTTPRequestTracker.Create(uri);
 // Add AppDynamics Server Correlation Headers
 foreach (var header in AppDynamics.Agent.ServerCorrelationHeaders.Generate) {
   // each header could have multiple values
   foreach (var value in header.Value) {
     client.DefaultRequestHeaders.Add(header.Key, value);
   }
 }
 var response = await client.GetAsync(uri);
 // Add response information
 tracker.ResponseCode = (int)response.StatusCode;
 tracker.StatusLine = response.ReasonPhrase;
 tracker.ResponseHeaderFields = response.Headers;
 tracker.ReportDone();
 return await response.Content.ReadAsStringAsync();
}

Step 8: Point to an On-Premises EUM Server (Optional)

To use an on-premises EUM Server, you pass the URL to the on-premises EUM Server when you initialize the instrumentation with the EUM App Key from Step 2: Get Your Application Key:

var config = AppDynamics.Agent.AgentConfiguration.Create("EUM_APP_KEY");
config.CollectorURL ="http://myEUMHost.com:7001";
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);