Advanced configuration

• Latest Dynatrace
• How-to guide
• 1-min read
• Published Jan 12, 2026

The Dynatrace .NET MAUI package is configured via the dynatrace.config.json file. This file allows you to define configuration settings for both Android and iOS platforms in a single file. It is typically downloaded from the Dynatrace UI during the initial setup and placed in each platform folders (see Initial Setup step 6 for more details) of your .NET MAUI project.

Configuration file structure

The dynatrace.config.json file consists of two main sections, android and ios, where you define the platform-specific settings.

{
  "android": {
    "autoStart": {
      "beaconUrl": "https://your-environment.dynatrace.com/mbeacon",
      "applicationId": "Insert-Your-Application-ID-Here"
    }
  },
  "ios": {
    "DTXApplicationId": "Insert-Your-Application-ID-Here",
    "DTXBeaconUrl": "https://your-environment.dynatrace.com/mbeacon"
  }
}

Advanced configuration example

Below is an example of a dynatrace.config.json file showing additional properties that can be used for each platform.

{
  "android": {
    "autoStart": {
      "beaconUrl": "https://your-environment.dynatrace.com/mbeacon",
      "applicationId": "Insert-Your-Application-ID-Here"
    },
    "debug": {
      "agentLogging": true,
      "certificateValidation": true
    },
    "userOptIn": true,
    "crashReporting": true,
    "agentBehavior": {
      "startupLoadBalancing": true,
      "startupWithGrailEnabled": true
    }
  },
  "ios": {
    "DTXApplicationId": "Insert-Your-Application-ID-Here",
    "DTXBeaconUrl": "https://your-environment.dynatrace.com/mbeacon",
    "DTXStartupWithGrailEnabled": true,
    "DTXUserOptIn": false,
    "DTXAllowAnyCert": true,
    "DTXCrashReportingEnabled": true,
    "DTXStartupLoadBalancing": true,
    "DTXLogLevel": "ALL"
  }
}

For a complete list of available configuration options, refer to the platform-specific documentation:

Common configuration options

The following table lists common configuration options and their equivalents on Android and iOS:

Apply configuration changes

Modifying the dynatrace.config.json file automatically updates your native Android and iOS projects when the app is rebuilt. For iOS, it will create/update the Dynatrace.plist with the updated properties set in the dynatrace.config.json.

Configuration file options

By default, we look for a file named dynatrace.config.json in each platform folders (see Initial Setup step 6 for more details). If your project structure differs or you want to use alternative options, here is what is available.

Custom configuration path

If you have a specific setup or want to use a specific path for your dynatrace.config.json file, you can set a custom path via the DynatraceConfigurationFile property.

Create Directory.Build.props in the Android/iOS (or general) project directory:

<Project>
  <PropertyGroup>
    <DynatraceConfigurationFile>CUSTOM_PATH/dynatrace.config.json</DynatraceConfigurationFile>
  </PropertyGroup>
</Project>

Build or custom defined configuration

If you want to use a specific setup/configuration based on a certain build or custom defined configuration, you can create the Dynatrace configuration file like dynatrace<Configuration>.config.json. For example, when using Debug, Release, or a custom-defined configuration, our package searches the Assets (Android) or Resources (iOS) directory for a configuration file named dynatrace<Configuration>.config.json. More specifically, if you're using the Debug build configuration, our package looks for a file named dynatraceDebug.config.json.

Manual startup

By default, the Dynatrace OneAgent starts automatically using the configuration from dynatrace.config.json. If you need to configure values like beaconUrl or applicationId at runtime, you can use manual startup instead.

Disable automatic startup

Configuration options

The ConfigurationBuilder supports the following options:

Example ConfigurationBuilder

using Dynatrace.MAUI;

Agent.Instance.Start(new ConfigurationBuilder(
            "https://your-environment.dynatrace.com/mbeacon", "Insert-Your-Application-ID-Here")
            .WithCrashReporting(true)
            .WithDebugLogging(true)
            .WithCertificateValidation(true)
            .WithThirdGenEnabled(true)
            .BuildConfiguration());

Enable OneAgent debug logs

If the instrumentation runs through and your application starts, but you see no data in your Dynatrace environment, you probably need to dig deeper to find out why OneAgents aren't sending any data. Opening up a support ticket is a great idea but gathering logs first is even better.

{
    "android": {
        "autoStart": {
            "applicationId": "<insertApplicationID>",
            "beaconUrl": "<insertBeaconURL>"
        },
        "userOptIn": true,
        "debug": {
            "agentLogging": true
        }
    }
}

{
  "ios": {
    "DTXApplicationId": "<insertApplicationID>",
    "DTXBeaconUrl": "<insertBeaconURL>",
    "DTXUserOptIn": true,
    "DTXLogLevel": "ALL"
  }
}

Enable build debug logs for Android

Android only

If the Android instrumentation fails, you most likely need to open a support ticket and provide build debug logs. To provide those logs, you need to set the DynatraceInstrumentationLogging property and change the build log level to Diagnostic.