--- title: Monitor your .NET MAUI mobile app source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-maui-dotnet/monitor-your-net-maui-application --- Our New Relic .NET MAUI agent monitors your .NET MAUI mobile app and provides deep insights into your app's performance, errors, and user experience. Once you install and configure the .NET MAUI agent, you'll be able to: - **Capture C# errors:** Identify and fix problems quickly. - **Track network requests:** See how your app interacts with the backend. - **Use distributed tracing:** Drill down into handled exceptions and find the root cause. - **Create custom events and metrics:** Understand how your users interact with your app. ![Summary view of a .NET MAUI mobile app in New Relic](https://docs.newrelic.com/images/mobile_screenshot-full_hybrid-summary.webp "Mobile summary view in the UI") **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select your .NET MAUI app) > Summary**: View .NET MAUI data, track HTTP requests and errors, and monitor how your app is performing over time. ## (Recommended) Guided installation [#guided-install] To install the .NET MAUI agent, follow our [guided install](https://onenr.io/0BR664ABdRO), located directly in the UI. ## Manual installation [#manual-install] If you need to install the agent manually, follow these steps: ### Review the requirements [#requirements] Before you install our .NET MAUI agent, make sure your app meets these version requirements: - .NET version 7.0 or higher - For Android-native apps: Android 7 (API 24) or higher - For iOS-native apps: - iOS 16 or higher, using the latest release of Xcode ### Add the .NET MAUI agent to your project [#add-project] First, you'll need to add our agent, a NuGet package, to your MAUI project: 1. Open your .NET MAUI solution, select the project you want to add the agent to, and open its context menu. 2. Click **Add > Add NuGet packages**, then select `NewRelic.MAUI.Plugin`. ### Copy your application token from the UI [#app-token] The application token is used for New Relic to authenticate your .NET MAUI app's data. To view and copy your application token in the New Relic UI: 1. Go to **[one.newrelic.com](https://one.newrelic.com/all-capabilities)**, click **Integrations & Agents**, then click **Mobile**. 2. Select your .NET MAUI app. 3. Go to **Settings > Application** and copy the displayed **Application token**. You'll add this application token in the next step. ### Add our agent configuration file to your .NET MAUI project [#add-configuration] In your project, open `MauiProgram.cs` and add the following code: ````csharp using NewRelic.MAUI.Plugin; ... public static MauiApp CreateMauiApp() { var builder = MauiApp.CreateBuilder(); builder .UseMauiAppApp_()_ .ConfigureFonts(fonts => { fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular"); fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold"); }); builder.ConfigureLifecycleEvents(AppLifecycle => { #if ANDROID AppLifecycle.AddAndroid(android => android .OnCreate((activity, savedInstanceState) => StartNewRelic())); #endif #if IOS AppLifecycle.AddiOS(iOS => iOS.WillFinishLaunching((_,__) => { StartNewRelic(); return false; })); #endif }); return builder.Build(); } private static void StartNewRelic() { CrossNewRelic.Current.HandleUncaughtException(); // Set optional agent configuration // Options are: crashReportingEnabled, loggingEnabled, logLevel, collectorAddress, // crashCollectorAddress, analyticsEventEnabled, networkErrorRequestEnabled, // networkRequestEnabled, interactionTracingEnabled, webViewInstrumentation, // fedRampEnabled, offlineStorageEnabled, newEventSystemEnabled, backgroundReportingEnabled // AgentStartConfiguration agentConfig = new AgentStartConfiguration(crashReportingEnabled:false); if (DeviceInfo.Current.Platform == DevicePlatform.Android) { CrossNewRelic.Current.Start("APP_TOKEN_HERE"); // Start with optional agent configuration // CrossNewRelic.Current.Start("APP_TOKEN_HERE", agentConfig); } else if (DeviceInfo.Current.Platform == DevicePlatform.iOS) { CrossNewRelic.Current.Start("APP_TOKEN_HERE"); // Start with optional agent configuration // CrossNewRelic.Current.Start("APP_TOKEN_HERE", agentConfig); } } ``` Make sure you paste your application token(s) into `appToken = ""` in the code above. If you deployed your hybrid app to both iOS and Android platforms, you'll need to add two separate tokens: one for iOS and one for Android. ```` ### Screen tracking events [#screen-tracking-events] The .NET MAUI mobile plugin allows you to track navigation events within the [.NET MAUI Shell](https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/shell/navigation). There are two ways to initialize this depending on your app's startup timing in `App.xaml.cs`. **Option 1: In the App Constructor** You can call the tracking method directly in the constructor immediately after setting the `MainPage`. ````C# public App() { InitializeComponent(); MainPage = new AppShell(); CrossNewRelic.Current.TrackShellNavigatedEvents(); } ``` **Option 2: In the OnStart Method (Recommended for timing/NullReferenceException issues)** If your application shell is not fully initialized during the constructor execution, calling the navigation tracker may result in a `System.NullReferenceException`. To avoid this, move the call into the MAUI `OnStart()` lifecycle method: ```C# public App() { InitializeComponent(); MainPage = new AppShell(); } protected override void OnStart() { base.OnStart(); CrossNewRelic.Current.TrackShellNavigatedEvents(); } ``` It is recommended to call this method along when starting the agent. These events will only be recorded after navigation is complete. You can find this data through the data explorer in `MobileBreadcrumb` (under the name `ShellNavigated`) or by a NRQL query: ```sql SELECT * FROM MobileBreadcrumb WHERE name = 'ShellNavigated' SINCE 24 HOURS AGO ``` The breadcrumb will contain three attributes: * `Current`: The URI of the current page. * `Source`: The type of navigation that occurred. * `Previous`: The URI of the previous page. This won't exist if the previous page was null. ```` ## Customize the agent instrumentation [#mobile-sdk] Need to customize your agent instrumentation? Our public mobile SDK API methods let you collect custom data, configure default settings, and more. The following customizations are available for the .NET MAUI agent. | If you want to... | Use this method | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Record breadcrumbs to track app activity that may be helpful for troubleshooting crashes. | [Record breadcrumbs](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-breadcrumb) | | Track a method as an interaction. | [Start interactions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/start-interaction) [Stop interactions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/stop-interaction) | | Record custom metrics. | [Record custom metrics](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-metrics/) | | Record handled exceptions. | [Record handled exceptions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-handled-exceptions) | | Record custom attributes and events. | There are several ways to report custom attributes and events: - [Record custom attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute) - [Increment session attribute count](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/increment-session-attribute-count) - [Remove an attribute](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-attribute) - [Remove all attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-all-attributes) - [Record custom events](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-events) - [Set the maximum size of an event pool](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-pool-size) - [Set maximum time the agent stores events in memory](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-buffer-time) - [Get a current session's ID](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/current-session-id) - [Set a custom user ID to associate with events and attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-custom-user-id) For more about which would be the best method to use and why, see [Report mobile monitoring custom events and attributes](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/report-mobile-monitoring-custom-events-attributes/). | | Track custom network requests and failures. | [Track HTTP requests](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-success) [Track failing HTTP requests](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-failures) | | Shut down the agent. | [Shut down the agent](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/shut-down-agent) | | Enable/disable default mobile monitoring settings. | [Enable/disable monitoring features](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/configure-settings) | | Run a test crash report. | [Test crash reporting](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/test-crash-reporting) | ## Troubleshooting [#troubleshooting] ### Troubleshoot HTTP errors [#http-errors] Missing HTTP data in the UI? After installing the .NET MAUI agent, wait at least 5 minutes. If no HTTP data appears on the HTTP errors and HTTP requests UI pages, make sure you used `HttpMessageHandler` in `HttpClient`. ### Missing Distributed Tracing Data in the UI [#missing-distributed-tracing] Distributed Tracing does not work when you use static methods to report HTTP data. To enable Distributed Tracing, you must use `HttpMessageHandler` with `HttpClient`. ```csharp HttpClient myClient = new HttpClient(CrossNewRelic.Current.GetHttpMessageHandler()); var response = await myClient.GetAsync(new Uri("https://jsonplaceholder.typicode.com/todos/1")); if (response.IsSuccessStatusCode) { var content = await response.Content.ReadAsStringAsync(); } else { Console.WriteLine("Http request failed"); } ``` ### App crashes with TrackShellNavigatedEvents [#track-shell-crash] If you experience a `System.NullReferenceException` when calling `CrossNewRelic.Current.TrackShellNavigatedEvents()` in the `App()` constructor, it is likely because the application shell is not fully bootstrapped yet. To resolve this, move the call out of the constructor and into the MAUI `OnStart()` lifecycle method within your `App.xaml.cs` file (see the [Screen tracking events](#screen-tracking-events) section for code examples).