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

To instrument your application, see the following sections:

Review MAUI Agent Support

The MAUI Agent supports the following:

  • Platforms:
    • iOS
    • Android
  • Libraries:
    • net6.0-ios (AppDynamics.Agent.MAUI or AppDynamics.Agent version >= 2022.9.0)
    • net6.0-android (AppDynamics.Agent.MAUI or AppDynamics.Agent version >= 2022.9.0)
  • .NET version >= 6

Limitations

The MAUI Agent has the following limitations for which crash data is reported:

  • Reported: Managed crashes - crashes that occur on .NET Runtime).
  • Not reported: Native crashes - crashes that occur on Objective-C runtime

Choose a MAUI Agent Instrumentation Package

The MAUI Agent is an instrumentation package that you add to your .NET MAUI application. Depending on your application needs, choose one of the following instrumentation packages:

  • AppDynamics.Agent.MAUI includes instrumentation for iOS and Android applications, as well as instrumentation of MAUI UI elements.
  • AppDynamics.Agent includes instrumentation for iOS and Android applications, but without any MAUI dependencies.

Add the Maui Agent Package

To add a MAUI Agent package from the NuGet Gallery to your application, see the instructions on Install and use a package in Visual Studio.

(Android-only) Add Initialization Code to your Android Application

  1. In your Android application's MainActivity, add the following initialization line to the OnCreate method:

    AppDynamics.Droid.Agent.Init(activity, bundle);
    C#

  2. On Maui, you can include this in MauiProgram, within CreateMauiApp():

    public static MAUIApp CreateMAUIApp()
{
    var builder = MAUIApp.CreateBuilder();
    builder
        .UseMAUIApp<App>()
        .ConfigureLifecycleEvents(events =>
        {
#if ANDROID
            events.AddAndroid(android => android
                .OnCreate((activity, bundle) => AppDynamics.Droid.Agent.Init(activity, bundle)));
#endif
        });
    return builder.Build();
}
    C#


Get an EUM App Key

The EUM App Key is a unique identifier used to associate end user data which specific End-User Monitoring applications. Each .NET MAUI application is usually associated with one EUM App Key. For your applications to be monitored, you must add the EUM App Key to the MAUI Agent instrumentation package. 

To get the EUM App Key in the Controller:

  1. Go to User Experience.
  2. Under the Mobile Apps tab, click Add App > Cross Platform.
  3. In Step 1, select a Mobile App Group.
  4. In Step 2, select the Xamarin framework.

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

(Android-only) Add Required Permissions

In your Android application's Properties/AndroidManifest.xml file, verify the following permissions (or add them if not present):

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

Initialize the Agent

Depending on the type of your application, you have two options to initialize the agent:

  • For cross-platform applications: Add this initialization code in the App.xaml.cs file, which is available to cross-platform applications (both iOS and Android):

    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 MainPage();
}
    C#
  • For native applications:

    • iOS: Add this initialization code in your application's AppDelegate's FinishedLaunching method: 

      public class AppDelegate : UIApplicationDelegate
{
   ...
   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;
    }
    ...
}
      CODE

    • Android: Add this initialization code under your application's MainActivity OnCreate method:

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

(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:

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

For a list of on-premises EUM Server URLs per region, see https://docs.appdynamics.com/paa/saas-domains-and-ip-ranges.

Build Your 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.

(iOS-only) Add Additional Arguments

For iOS applications, you must add the additional MtouchExtraArgs --registrar:static for simulator configuration to avoid runtime errors. This is already the default for physical devices. Add the following arguments in your MAUI project: 

<PropertyGroup Condition="$(TargetFramework.Contains('-ios'))">
    <MTouchExtraArgs>--registrar:static</MTouchExtraArgs>
</PropertyGroup>
C#

(Optional) Enable Automatic Instrumentation

The MAUI Agent can be configured to automatically inject specific instrumentation code into your project. This can be achieved using a different beta nuget package called AppDynamics.Agent.AutoInstrument.Fody.

Automatic instrumentation allows you to: 

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

Set Up the Automatic Instrumentation Package

Before you set up the automatic instrumentation package AppDynamics.Agent.AutoInstrument.Fody, make sure you completed the agent instrumentation setup above and have added the AppDynamics.Agent or AppDynamics.Agent.MAUIpackages to your project. 

  1. 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.

     

  2. Build the solution.

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

    • FodyWeavers.xml
    • FodyWeavers.xsd 

    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>
    C#

    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>
    C#

(Optional) Customize Your Instrumentation

You can make further customizations to the MAUI Agent instrumentation using the MAUI SDK. The SDK has additional classes to allow you to extend the kinds of application data you can collect and report to AppDynamics. See Customize the MAUI Instrumentation.