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"
  }
}

Android—contains configuration for the Android OneAgent using JSON format.
iOS—contains configuration for the iOS OneAgent using the .plist properties but in JSON format.

Advanced configuration example

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

Advanced configuration example

{
  "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:

Configuration	Default	Android	iOS	Description
Application ID	Required	`autoStart - applicationId`	`DTXApplicationID`	Identifies your mobile app in Dynatrace
Beacon URL	Required	`autoStart - beaconUrl`	`DTXBeaconURL`	Identifies your Dynatrace environment
Crash Reporting	true	`crashReporting`	`DTXCrashReportingEnabled`	Enables automatic crash reporting
Debug Logging	false	`debug - agentLogging`	`DTXLogLevel`	Enables detailed agent logging to the mobile devices OSLog/Logcat
User Opt-In	false	`userOptIn`	`DTXUserOptIn`	Enables privacy mode requiring user consent
Certificate Validation	true	`debug - certificateValidation`	`DTXAllowAnyCert`	Controls self-signed certificate acceptance
Third Gen Enabled	false	`agentBehavior - startupWithGrailEnabled`	`DTXStartupWithGrailEnabled`	Allows 3rd gen data to be captured when agent's first startup

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.

Never use dot notation for the configuration file. Always write in full bracket style.

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.

Automated startup captures early lifecycle events, such as the application start. Manual startup occurs later, meaning those early events will be missed until the agent is initialized.

Disable automatic startup

Modify the dynatrace.config.json file to disable OneAgent autostart.
{
"android": {
"autoStart": {
"enabled": false
}
}
}
{
"ios": {
"DTXAutoStart": false
}
}
Don't add additional properties to the configuration file. If you do that, the build fails with an exception.

Start OneAgent manually and pass the required properties.

using Dynatrace.MAUI;

Agent.Instance.Start(new ConfigurationBuilder("<insertBeaconURL>","<insertApplicationID>").BuildConfiguration());

Configuration options

The ConfigurationBuilder supports the following options:

Property	Type	Default	Description
`beaconUrl`	String	Required	Identifies your Dynatrace environment
`applicationId`	String	Required	Identifies your mobile app
`WithCrashReporting`	bool	true	Enables automatic crash reporting
`WithDebugLogging`	bool	Info	Set verbose debug logging
`WithUserOptIn`	bool	false	Enables privacy mode requiring user consent
`WithCertificateValidation`	bool	true	Set to `false` to accept self-signed certificates
`WithThirdGenEnabled`	bool	false	Allows 3rd gen data to be captured when agent's first startup

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

Any values not explicitly set in the ConfigurationBuilder will fall back to their default values.

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.

Update your dynatrace.config.json file to enable OneAgent debug logs.

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

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.

Set the DynatraceInstrumentationLogging property. Choose one of the following options to do that:
- Create Directory.Build.props in the Android project directory:
```
<Project>
  <PropertyGroup>
    <DynatraceInstrumentationLogging>true</DynatraceInstrumentationLogging>
  </PropertyGroup>
</Project>
```
- Add the DynatraceInstrumentationLogging property to the .csproj file of your project. Insert it into some existing PropertyGroup, depending on the configuration that you're executing.
Change the build output verbosity to Diagnostic. For details, see the Microsoft documentation on how to change the amount of information included in the build log.
Rebuild your project.
Attach the build logs to the support ticket so that we can further analyze your issue.