Before you can monitor your Xamarin application, you will need to instrument your application to enable the Xamarin Agent to collect mobile metrics. 

After you have set up and accessed Mobile RUM, follow these instructions:

  1. Confirm that the Xamarin Agent supports your platform
  2. Understand the limitations of the Xamarin Agent
  3. Instrument a Xamarin Application
  4. Customize the Xamarin Instrumentation (Optional)

Xamarin Agent Support

Supported Platforms

  • iOS and Android platforms

All other platforms will build and run without errors, but no monitoring will occur.

Supported Libraries

  • .Net Standard 2.0 (with Xamarin Agent >= 20.10.0)

Recommendations

Xamarin <= 50.2 only supported the instrumentation of applications that reference the Portable Class Libraries (PCL). From Xamarin >= 50.3, the Xamarin Agent only supports the .NET Standard library and the instrumentation of applications that reference the .NET Standard library. If you still need PCL support, you are recommended to use Xamarin <= 50.2.


Limitations

The Xamarin Agent has these limitations:

  • Automatic instrumentation is not supported, so you will need to manually report events and metrics.
  • Symbolication is not supported, although the Xamarin Agent does report uncaught exceptions and native application crashes.

Instrument Xamarin Applications

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

Add the Xamarin Agent Package

  1. Get 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. 
  2. In the Xamarin.Android project, add the following to MainActivity.cs under OnCreate:
AppDynamics.Droid.Agent.Init(this, bundle);
CODE

Example

public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity {
    protected override void OnCreate(Bundle bundle) {
        base.OnCreate(bundle);  //existing code
        global::Xamarin.Forms.Forms.Init(this, bundle);

        AppDynamics.Droid.Agent.Init(this, bundle); //initialize the agent on the Android Platform 
        
        LoadApplication(new App()); 
    }
}
C#

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.

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>
XML

If these permissions are not present, add them.

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
    {
        ...
    }
}
C#

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
{
    ...
}
C#

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
    {
       ...
    }
    ...
}
C#

Initialize the Agent

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

var config = AppDynamics.Agent.AgentConfiguration.Create(<EUM_APP_KEY>);
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
C#

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

Forms Solution

For Forms Solutions, you only need to place the initialize code in the constructor of the App.xaml.cs file for the Xamarin Agent to instrument both Android and iOS applications. 

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();
}
C#

If you have application code in the MainActivity.cs file for Android or AppDelegate.cs for iOS that you want to instrument, however, you should initialize the Xamarin Agent in those files as you would do for iOS Solutions and Android Solutions.

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;
    }
    ...
}
C#

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);
    ...
  }
}
C#

Build the Application

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

For iOS projects with Xamarin Agent 20.10.0 - 21.4.0, you must add the additional MtouchExtraArgs argument --gcc_flags "-ObjC -lz" for each build configuration, such as the debug and release builds. If the iOS project file is edited directly, the build configuration should contain the MtouchExtraArgs element:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|iPhoneSimulator' ">
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <OutputPath>bin\iPhoneSimulator\Debug</OutputPath>
    <DefineConstants>DEBUG;ENABLE_TEST_CLOUD;</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
    <CodesignKey>iPhone Developer</CodesignKey>
    <MtouchDebug>true</MtouchDebug>
    <MtouchFastDev>true</MtouchFastDev>
    <MtouchLink>SdkOnly</MtouchLink>
    <MtouchArch>x86_64</MtouchArch>
    <MtouchHttpClientHandler>HttpClientHandler</MtouchHttpClientHandler>
    <MtouchTlsProvider>Default</MtouchTlsProvider>
    <DeviceSpecificBuild>false</DeviceSpecificBuild>
    <MtouchExtraArgs>--gcc_flags "-ObjC -lz"</MtouchExtraArgs>
  </PropertyGroup>
C#

Customize Your Instrumentation (Optional)

The Xamarin SDK has additional classes to allow you to extend the kinds of application data you can collect and aggregate using Mobile RUM. See Customize the Xamarin Instrumentation.

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 Get Your Application Key:

var config = AppDynamics.Agent.AgentConfiguration.Create(<EUM_APP_KEY>);
config.CollectorURL = <COLLECTOR_URL:PORT>;
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
CODE

Upgrade the Xamarin Agent

As new features are added to the agent, you will need to upgrade the Xamarin Agent package in your app.

  1. From Visual Studio, open the Xamarin application that has the AppDynamics Agent package.
  2. From the Packages folder, select the AppDynamics Agent.
  3. Right-click and click Update.
    AppDynamics Packages