Dynatrace.OneAgent.Xamarin 8.233.0

Dynatrace OneAgent for Xamarin

Use this NuGet package to instrument your Xamarin Forms and Native apps with the Dynatrace OneAgent for mobile. Adding the package to your Xamarin projects will allow you to use auto instrumentation for Android and iOS. Additionally the package contains the required stub libraries to add manual instrumentation directly in your C# code.

Licenses for libraries used:

• Plist-cil
• Newtonsoft JSON

Requirements of the NuGet package

• Android: API 15 or higher
  • Xamarin.Android SDK: 10.1.x or higher
• iOS: iOS 8 or higher
• Forms: .NET Standard 1.1 or higher

Quick setup

1. Install the NuGet Package
2. Setup Configuration in WebUI
3. Add Config File to Project
4. Add the Start Method

Advanced topics

• Using Different Build Configurations
• Xamarin Forms
• Xamarin Forms Initialization Workaround
• Manual Instrumentation
  • Start the OneAgent Manually
  • Create Manual Actions
  • Create Manual Sub Actions
  • Cancel Actions
  • Setup HTTP Client
  • Manually Instrument Web Requests
  • Report Values
  • Report an Error Stacktrace
  • Report a Crash Manually
  • Instant Crash Reporting for iOS
  • End a session
  • Identify a User
  • End a Session
  • Data Collection and UserPrivacyOptions
  • Report GPS Location
  • Structure of the dynatrace.config.json File
  • User Opt In Mode
  • Native OneAgent Debug Logs
  • Build Debug Logs
• How Dynatrace Determines the User Action Name
• More Info About Mobile Agents
• Troubleshooting
  • Change Net Version
  • Failed Build
  • Using Manual Startup
  • Dynatrace.Xamarin.Build.Android and iOS
  • Turn Off the Visual Studio Debugger for Android Projects
  • Contact Dynatrace ONE
• Changelog

Quick Setup

1. Install the NuGet Package

1. In Visual Studio, right-click the main project of your app and select Manage NuGet packages.
2. Search for Dynatrace.OneAgent.Xamarin from nuget.org and select Add Package.
3. Select the checkboxes of all the projects that you want to add the NuGet package to, then select OK.

2. Setup Configuration in WebUI

If your Dynatrace environment is not updated to version 1.214, you will not be able to access the Xamarin wizard. As a workaround, create the dynatrace.config.json file using information from Android or iOS instrumentation wizards.

1. Create a custom mobile app as explained below.
2. Instead of downloading the dynatrace.config.json file, create the file manually by copying the values from the Android or iOS wizard.
3. Save the file as dynatrace.config.json.
4. Add the dynatrace.config.json file you just created to your project. See Add config file to your project.

In Dynatrace, define a new mobile app.

1. From the navigation menu, select Deploy Dynatrace.
2. Select Set up mobile monitoring and type the name of your mobile app.
3. Select Create mobile app. Mobile app settings page appears.
4. Select Instrumentation wizard and then select Xamarin tile.
5. Download the dynatrace.config.json file.

3. Add Config File to Project

Android Add the downloaded dynatrace.config.json file into the Assets directory of your Android project.

iOS Add the downloaded dynatrace.config.json file into the Resources directory of your iOS project. Our package will automatically create a new Dynatrace.plist file based on the configuration you have in your config file every time before each build.

4. Add the Start Method

The start method is required for the OneAgent for mobile to start.

Android

using Dynatrace.Xamarin;

Agent.Instance.Start();

iOS

using Dynatrace.Xamarin;

Agent.Instance.Start();

Note: To allow for auto-instrumentation of web requests, see the Setup HTTP client section.

Using Different Build Configurations

When using a specific build configuration, i.e. Debug, Release, or a custom defined configuration, our package will search the Assets (Android) or Resources (iOS) folder for a config file named dynatrace<Configuration>.config.json. For example, if you are using the Debug build configuration, our package will look for a file name of dynatraceDebug.config.json. If the configuration specific file is not found, the default dynatrace.config.json file will be used.

Note:
If you do not add a config file to the Assets (Android) or Resources (iOS) folder with the minimum properties of DTXBeaconUrl and DTXApplicationId, the build will fail. Alternatively, you can use DTXAutoStart and set it to false if you want to use the Start method with a configuration dictionary (iOS) or configuration builder (Android). For more information, see Start the OneAgent manually.

Xamarin Forms

Note: Following introduction is targeting Xamarin Forms > 4.7.0, as it is using registerSingelton. If you can't upgrade there is a workaround for older version.

Register the interface at the startup in the native part of your Xamarin Forms application, and paste the following code right after Forms.Init() - Following example is from an Android Forms application:

using Dynatrace.Xamarin;

Xamarin.Essentials.Platform.Init(this, savedInstanceState);
            global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
Xamarin.Forms.DependencyService.RegisterSingleton<IDynatrace>(Agent.Instance);

LoadApplication(new App());

The following piece of code in your forms application allows you to access the agent:

using Dynatrace.Xamarin;

IDynatrace dynatrace = DependencyService.Get<IDynatrace>();

Make sure that in case of auto instrumentation, you also need to apply the package to the native parts.

Xamarin Forms Initialization Workaround

If you are unable to use DependencyService.RegisterSingleton as your Xamarin Forms version is below 4.7, there is a workaround possible. The following snippet shows how this works with Forms + Android, but could easily be applied for iOS as well.

The App.xaml.cs file in the Forms part:

public partial class App : Application
{
	static readonly Dictionary<Type, Func<object, object>> factories = new Dictionary<Type, Func<object, object>>();

	public App()
	{
		InitializeComponent();
		
		DependencyResolver.ResolveUsing((type, args) => factories.ContainsKey(type) ? factories[type].Invoke(args) : null);

		IDynatrace Dynatrace = DependencyService.Resolve<IDynatrace>();
		Dynatrace.Start(null);
	}
	
	public static void Register(Type type, Func<object, object> factory)
	{
		factories[type] = factory;
	}

	...
}

The Android part where you have to usually call registerSingelton has to look like this:

public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
{
	protected override void OnCreate(Bundle savedInstanceState)
	{
		...

		Xamarin.Essentials.Platform.Init(this, savedInstanceState);
		global::Xamarin.Forms.Forms.Init(this, savedInstanceState);

		App.Register(typeof(IDynatrace), (o) => Agent.Instance);

		LoadApplication(new App());
	}
	
	...
}

Manual Instrumentation

Start the OneAgent Manually

Using manual startup with configuration builder:

Android/iOS

using Dynatrace.Xamarin;

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

Using a dictionary: iOS only

using Dynatrace.Xamarin;

var configDict = new Dictionary<string, object>();
configDict.Add("DTXApplicationID", "<insertApplicationID>");
configDict.Add("DTXBeaconURL", "<insertBeaconURL>");
Agent.Instance.Start(configDict);

Create Manual Actions

To create a manual action named "MyButton tapped", use the following code. The leaveAction closes the action again. To report values for this action before closing, see Report Values.

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("MyButton tapped");
//Perform the action and whatever else is needed.
myAction.LeaveAction();

Create Manual Sub Actions

You can create a single manual action as well as sub actions. The MyButton Sub Action is automatically put under the MyButton tapped. As long as MyButton tapped is open, it gathers all the web requests.

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("MyButton tapped");
var mySubAction = myAction.EnterAction("MyButton SubAction");
//Perform the action and whatever else is needed.
mySubAction.LeaveAction();
myAction.LeaveAction();

Cancel actions

Actions can be canceled. That means they will not be sent and discarded fully. This also means that any values and sub actions attached to the action will be removed.

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("MyButton tapped");
// Action will be canceled
myAction.Cancel();

// Has no impact as the action is already canceled
myAction.LeaveAction();

Setup HTTP Client

To enable the auto-instrumentation of web requests, you will need to use the following method:

using Dynatrace.Xamarin;

var httpHandler = Agent.Instance.GetHttpMessageHandler();
var httpClient = new HttpClient(httpHandler);

The HttpMessageHandler used by HttpClient will take care of the manual web request instrumentation. You can also combine/chain the HttpMessageHandler with a different handler:

using Dynatrace.Xamarin;

var defaultHttpHandler = new HttpClientHandler();
var httpHandler = Agent.Instance.GetHttpMessageHandler(defaultHttpHandler);
var httpClient = new HttpClient(httpHandler);

Manually Instrument Web Requests

using Dynatrace.Xamarin;

// Create action
var webAction = Agent.Instance.EnterAction(actionName: "WebRequest Action");
// Generate a new unique tag associated with the web request action
string requestTag = webAction.GetRequestTag(url);
string requestTagHeader = webAction.GetRequestTagHeader();
// Place the Dynatrace HTTP header on your web request
httpClient.DefaultRequestHeaders.Add(requestTagHeader, requestTag);
// Generate a WebRequestTiming object based on the unique tag
WebRequestTiming timing = (WebRequestTiming)Agent.Instance.GetWebRequestTiming(requestTag, url);
// Start web request timing before the HTTP request is sent
timing.StartWebRequestTiming();
try
{
  var response = await httpClient.GetAsync(url);
  // Stop web request timing when the HTTP response is received and the response body was obtained
  timing.StopWebRequestTiming(url, (int)response.StatusCode, response.ReasonPhrase);
}
catch (HttpRequestException exception)
{
  // Stop web request timing when a connection exception occurs
  timing.StopWebRequestTiming(url, -1, exception.ToString());
}
finally
{
  // Leave Action
  webAction.LeaveAction();
}

Report Values

For any open action you can report certain values. The following API is available for action:

ReportValue(valueName: string, value: int);
ReportValue(valueName: string, value: double);
ReportValue(valueName: string, value: string);
ReportError(errorName: string, errorCode: number);
ReportEvent(eventName: string);

To report a string value, use the following:

using Dynatrace.Xamarin;

var myAction = Agent.Instance.EnterAction("MyButton tapped");
myAction.ReportValue("ValueName", "ImportantValue");
myAction.LeaveAction();

Report an Error Stacktrace

To manually report an error stacktrace, use the following API call:

using Dynatrace.Xamarin;

Agent.Instance.ReportErrorStacktrace("Error_Class", "Error_Value", "Error_Reason", "Error_Stacktrace");

Report a crash manually

Android only: When using automated crash reporting, be aware that Visual Studio might catch the exception in front of OneAgent. If you notice that crashes on Android devices are not reported to your environment, make sure you are not using the debug option in Visual Studio or the debugger will catch the crash and nothing will be reported. See Turn off the Visual Studio Debugger for Android projects.

To manually report a crash, use the following API call:

using Dynatrace.Xamarin;

Agent.Instance.ReportCrash("CrashWithoutException", "Crash_Reason", "Crash_Stacktrace");

Using an exception object:

using Dynatrace.Xamarin;

Agent.Instance.ReportCrashWithException("CrashWithExceptionObj", exception);

Note: When you use the API calls ReportCrash and ReportCrashWithException to report a crash manually, it will force the session to be completed. Any new actions that are captured afterward will be added into a new session.

Instant Crash Reporting for iOS

Note: This section is for iOS only as Android will instantly send crash reports by default.

By default for iOS, our NuGet package will capture the C# stacktrace (if crash happens on the c# layer) or the native iOS crash report (if the crash happens on the native layer) and send it on the next app start up.

IMPORTANT: If you use the instant crash reporting option, you will see the crash report in the format of a native crash report and NOT a stacktrace like you would for a standard unhandled exception triggered on the C# layer.

If you want to change this behavior to allow our NuGet package to send native formatted crash reports instantly by default, use one of the below options:

Using the dynatrace.config.js file:

{
  "ios": {
    "DTXApplicationId": "<insertApplicationID>",
    "DTXBeaconUrl": "<insertBeaconURL>",
    "DTXCrashReportingEnabled": true,
    "DTXInstantCrashReportingEnabled": true
  }
}

Using the ConfigurationBuilder:

using Dynatrace.Xamarin;

Agent.Instance.Start(new ConfigurationBuilder("<insertBeaconURL>","<insertApplicationID>")
                .WithCertificateValidation(true)
                .WithCrashReporting(true)
                .WithInstantCrashReporting(true)
                .WithUserOptIn(true)
                .BuildConfiguration());

Using a Dictionary:

using Dynatrace.Xamarin;

var configDict = new Dictionary<string, object>();
configDict.Add("DTXApplicationID", "<insertApplicationID>");
configDict.Add("DTXBeaconURL", "<insertBeaconURL>");
configDict.Add("DTXCrashReportingEnabled", true);
configDict.Add("DTXInstantCrashReportingEnabled", true);
Agent.Instance.Start(configDict);

Identify a User

You can identify a user and tag the current session with a name by making the following call:

using Dynatrace.Xamarin;

Agent.Instance.IdentifyUser("User XY");

End a Session

You can force a session to end via the API. This will also close all open actions.

using Dynatrace.Xamarin;

Agent.Instance.EndVisit();

Data Collection and UserPrivacyOptions

The privacy API methods allow you to dynamically change the data-collection level based on the individual preferences of your end users. Each end user can select from three data-privacy levels:

enum DataCollectionLevel {
    Off, Performance, UserBehavior
}

1. Off: Native OneAgent doesn't capture any monitoring data.
2. Performance: Native OneAgent captures only anonymous performance data. Monitoring data that can be used to identify individual users, such as user tags and custom values, aren't captured.
3. UserBehavior: Native OneAgent captures both performance and user data. In this mode, Native OneAgent recognizes and reports users who re-visit in future sessions.

The API to get and set the current level looks like this:

To get current UserPrivacyOptions configuration:

using Dynatrace.Xamarin;

// Get the UserPrivacyOptions object:
UserPrivacyOptions currentOptions = Agent.Instance.GetUserPrivacyOptions();

// Get the individual settings for DataCollectionLevel and or crash reporting:
bool crashOptedIn = Agent.Instance.GetUserPrivacyOptions().CrashReportingOptedIn;
DataCollectionLevel dataCollectionLevel = Agent.Instance.GetUserPrivacyOptions().DataCollectionLevel;

Setting new options on a UserPrivacyOptions object:

using Dynatrace.Xamarin;

// Creating a new UserPrivacyOptions object requires setting the two parameters of DataCollectionLevel and crash reporting:
UserPrivacyOptions options = new UserPrivacyOptions(DataCollectionLevel.Performance, false);

// You can update the options with the setter:
options.DataCollectionLevel = DataCollectionLevel.UserBehavior;
options.CrashReportingOptedIn = true;

// You can get the values of the configuration with the getter:
options.DataCollectionLevel;
options.CrashReportingOptedIn;

// You can get the UserPrivacyOptions object with the following:
UserPrivacyOptions currentOptions = Agent.Instance.GetUserPrivacyOptions();

Apply new UserPrivacyOptions configuration:

using Dynatrace.Xamarin;

UserPrivacyOptions options = new UserPrivacyOptions(DataCollectionLevel.UserBehavior, true);
Agent.Instance.ApplyUserPrivacyOptions(options);

Report GPS Location

You can report latitude and longitude and specify an optional platform.

SetGPSLocation(latitude: double, longitude: double);

Structure of the dynatrace.config.json File

The configuration is structured in the following way:

Android

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

iOS

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

User Opt In Mode

Specifies if the user has to opt-in before they are monitored. When enabled, you must specify the privacy setting. For more information, see the API section and the configuration above.

Native OneAgent Debug Logs

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

Android Add the following configuration snippet to your other configuration in dynatrace.config.json right under the autoStart block (the whole structure is visible, so you know where the config belongs):

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

iOS Add the following configuration snippet to your other configuration in 'dynatrace.config.json' (the whole structure is visible, so you know where the config belongs):

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

Build Debug Logs

If, for instance, 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 property DynatraceInstrumentationLogging and change the build log level to Diagnostic.

• Enable the property DynatraceInstrumentationLogging:

Setting the property DynatraceInstrumentationLogging is possible in several ways. One is to create Directory.Build.props in the Android project directory:

<Project>
	<PropertyGroup>
		<DynatraceInstrumentationLogging>true</DynatraceInstrumentationLogging>
	</PropertyGroup>
</Project>

Another option is to add the property in the .csproj file of your project. Insert it into some existing PropertyGroup, depending on the configuration that you are executing (such as Debug or Release).

• Set build output verbosity

To learn how to change the output verbosity to Diagnostic, see the Microsoft documentation: To change the amount of information included in the build log.

• After setting the property and changing the build output verbosity, rebuild your project and attach the build logs to the support ticket so we can further analyze your problems.

How Dynatrace Determines the User Action Name

Android For more information on the user action name, see User action naming

iOS Auto-instrumentation captures the title from UIButton by calling the following objects in order and stopping when valid text is received: titleLabel.attributedText, attributedTitleForState:UIControlStateNormal, and accessibilityLabel. If none of these produce usable text the default value is set to Button.

More Info About Mobile Agents

• OneAgent for Android
• OneAgent for iOS

Troubleshooting

Change Net Version

Our target file internally uses net5.0 as default. If you have not installed this version you basically have the chance to change to the following versions:

• net6.0
• net5.0
• netcoreapp3.1
• netcoreapp2.1

To apply this change you need to set the Dynatrace_Net_Version build property in your csproj file. The following block shows an example and is inserting the property in the block of the debug configuration. With this change the target file will use the net6.0 version.

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
	<Dynatrace_Net_Version>net6.0</Dynatrace_Net_Version>
	...
  </PropertyGroup>
  ...
</Project>

Failed build

If you receive a failed build while the NuGet package is added for iOS, make sure you add the dynatrace.config.json file to your Resources folder and that you include the following:

• Minimal Auto-instrumentation properties
  • DTXApplicationId
  • DTXBeaconUrl Note: If you forget to add either DTXApplicationId or DTXBeaconUrl, you will see a failed build with an exception. You need both properties added to the dynatrace.config.json as they both are required properties. You will also encounter an exception if DTXAutoStart => false while including either the DTXApplicationId or DTXBeaconUrl properties. For a manual startup, see below.

Using manual startup

Add DTXAutoStart and set the value to false Note: Only use this property as no other properties will be considered when manually starting OneAgent for iOS and you will encounter a failed build with an exception if additional properties are added other than DTXAutoStart => false.

Dynatrace.Xamarin.Build.Android and iOS

The following error can happen on older Xamarin Android/iOS projects:

Android

Target DynatraceAndroidBuildVerify:
    dotnet "/tools/netcoreapp3.1/Dynatrace.Xamarin.Build.Android.dll" verify config="obj/Debug/assets/dynatrace.config.json" java="/Users/<user>/Library/Developer/Xamarin/jdk/microsoft_dist_openjdk_1.8.0.25/bin" dynatraceJar="/tools/java/instrumentor-cli-8.223.1.1003.jar"
    Could not execute because the specified command or file was not found.

iOS

dotnet "/tools/netcoreapp3.1/Dynatrace.Xamarin.Build.iOS.dll" "Debug"

Could not execute because the specified command or file was not found.

The Dynatrace Xamarin package MSBuild command can't resolve the package directory because the .csproj file references Dynatrace Xamarin package dependencies individually, not as a package. To resolve the problem

1. Open your Android/iOS .csproj file and remove all Dynatrace Xamarin package .dll references. For example for iOS you would remove the following:

   <Reference Include="Dynatrace.Xamarin.Abstraction">
     <HintPath>..\packages\Dynatrace.OneAgent.Xamarin.8.x.x.x\lib\xamarinios10\Dynatrace.Xamarin.Abstraction.dll</HintPath>
   </Reference>
   <Reference Include="Dynatrace.Xamarin.Binding.iOS">
     <HintPath>..\packages\Dynatrace.OneAgent.Xamarin.8.x.x.x\lib\xamarinios10\Dynatrace.Xamarin.Binding.iOS.dll</HintPath>
   </Reference>
   <Reference Include="Dynatrace.Xamarin.iOS">
     <HintPath>..\packages\Dynatrace.OneAgent.Xamarin.8.x.x.x\lib\xamarinios10\Dynatrace.Xamarin.iOS.dll</HintPath>
   </Reference>
   

2. Add the Dynatrace Xamarin package reference to the .csproj file. Add the actual package version as the value of <Version>.

   <ItemGroup>
     <PackageReference Include="Dynatrace.OneAgent.Xamarin">
       <Version>8.x.x.x</Version>
     </PackageReference>
   </ItemGroup>
   

3. Rebuild your project.

Turn Off the Visual Studio Debugger for Android Projects

The following options were tested with the latest Visual Studio. If you are using an older version, the options below might look slightly different.

Use a right-click on your Android project and select properties. This will show your project-related settings. Then select Android Options and clear Enable developer instrumentation. Keep in mind this will disable debugging. Use this option only to verify that crashes are sent. Optionally, you can create a release build that is detached from Visual Studio.

Contact Dynatrace ONE

If you're unable to resolve a problem, please contact a Dynatrace ONE product specialist via in-product chat. Have the following details available:

• Logs from the OneAgent
• Your dynatrace.config.json file

Changelog

8.233.0

• Added Cancel API for actions
• Added version compatability with net6.0 and others
• Deprecated SetupHttpClient

8.225.0

• Target file automatically resolves path for older projects
• Fixed crash handler bug with null or empty crash message/stacktrace values

8.219.0:

• ReportCrash is now ending the session
• Added ReportError to API to use exception objects
• Fixes Android Startup Issue

8.213.0:

• Updated Documentation (added link)
• Changed API
• Changed Configuration Format
• Added new Android instrumentation