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 supported platforms
  2. Understand the limitations of the Xamarin Agent
  3. Instrument a Xamarin Application
  4. (Optional) Enable Automatic Instrumentation of Network Requests
  5. (Optional) Customize the Xamarin Instrumentation

  6. (Optional) Point to an On-Premises EUM Server

Xamarin Agent Support

Supported Platforms

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

Supported Libraries

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.

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  Xamarin Agent from nuget.org. 
  2. Add the Xamarin.Forms package from AppDynamics.Agent.Forms.
  3. In the Xamarin.Android project, add the following to MainActivity.cs under OnCreate:
AppDynamics.Droid.Agent.Init(this, bundle);
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()); 
    }
}

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>

If these permissions are not present, add them to the file Properties/AndroidManifest.xml .

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

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

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

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

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 >= 21.6.0, you must add the additional MtouchExtraArgs --registrar:static for each simulator build configuration, such as the debug and release builds. This does not apply for physical device configurations since the static registrar is already the default.

If the iOS project file is edited directly, the build configuration should contain the MtouchExtraArgs element:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|iPhoneSimulator' ">
     ...
    <MtouchExtraArgs>--registrar:static</MtouchExtraArgs>
</PropertyGroup>
"


(Optional) Enable Xamarin Automatic Instrumentation

The Xamarin Agent can automatically inject Xamarin-specific instrumentation code into your project. You can: 

  1. Automatically track HttpClient or Refit network requests.
  2. Automatically track Xamarin.Forms pages.
  3. Automatically track Xamarin.Forms UI elements.

This can be achieved using a different beta nuget package called AppDynamics.Agent.AutoInstrument.Fody.

Set Up the AppDynamics.Agent.AutoInstrument.Fody Package

  1. Add the AppDynamics.Agent package.

  2. Add the AppDynamics.Agent.AutoInstrument.Fody package. 

    To install the AppDynamics.Agent.AutoInstrument.Fody beta package, check the "Include prereleases" option in order for the version to be displayed.

  3. Build the solution.
     

    After you build the solution, two files should be generated automatically: 

    These files should be checked into source control. 

    If the above files are not generated automatically, a new file called FodyWeavers.xml should be created manually with the following content:

    <Weavers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FodyWeavers.xsd">
  <AppDynamics.Agent.AutoInstrument />
</Weavers>

    If the project is already using Fody, these files will already be there and only the FodyWeavers.xml file has to be updated to include the AppDynamics.Agent.AutoInstrument weaver. 

    For example:

    <Weavers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FodyWeavers.xsd">
  ... Existing weavers ...
  <AppDynamics.Agent.AutoInstrument />
</Weavers>

(Optional) Customize Your Instrumentation

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.

(Optional) Point to an On-Premises EUM Server

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

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  Agent.
  3. Right-click and click Update.
    AppDynamics Packages