Dynatrace.OneAgent.Xamarin 7.2.1

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.

Requirements of the NuGet package

• Android: API 15 and above
• iOS: iOS 6 and above
• Forms: .NET Standard 1.5 and above

Configuration for Android Auto-Instrumentation

Adding Properties File

The Android Auto-Instrumentation needs some properties in order to work correctly. Those properties can be viewed when you look into the documentation links that are provided at the bottom of this documentation, here.

The properties file shoud be in the assets folder of your Android application and should be called 'Dynatrace.properties'.

Adding Target (Only for Forms based application)

This only needs to be done for Forms applications. The target will invoke the Android auto-instrumentation every time you bundle/build your APK. Open your .csproj file of your Android application with a file editor of your choice and include the following target within the <Project> tag.

<Target Name="DynatraceInstrumentation" AfterTargets="_BuildApkEmbed" Condition="Exists('@(ApkFiles)')">
    <PropertyGroup Condition=" '$(OS)' != 'Windows_NT' ">
        <PathSeparator>/</PathSeparator>
        <Instrumentor>instrument.sh</Instrumentor>
    </PropertyGroup>

    <PropertyGroup Condition=" '$(OS)' == 'Windows_NT' ">
        <PathSeparator>\</PathSeparator>
        <Instrumentor>instrument.cmd</Instrumentor>
    </PropertyGroup>
	
    <Error Condition="!Exists('$(ProjectDir)Assets$(PathSeparator)Dynatrace.properties')" Text="Properties File is not available!" />
    <Error Condition="!Exists('%(ApkFiles.Identity)')" Text="APK File(s) is (are) not available!" />
    <Error Condition="!Exists('$(ProjectDir)%(ApkFiles.Identity)')" Text="APK File(s) is (are) not available!" />

	<ItemGroup>
        <FilteredReferencesNuGet Include="@(_ReferencesFromNuGetPackages)" Condition="$([System.String]::new('%(_ReferencesFromNuGetPackages.FullPath)').Contains('Dynatrace.OneAgent.Android.dll'))" />
	    <FilteredReferences Include="@(Reference)" Condition="$([System.String]::new('%(Reference.HintPath)').Contains('Dynatrace.OneAgent'))" />
    </ItemGroup>
	
	<PropertyGroup>
	    <AgentDir Condition="'@(FilteredReferences)' != ''">@(FilteredReferences-&gt;'%(HintPath)')</AgentDir>
        <AgentDir Condition="'@(FilteredReferencesNuGet)' != ''">@(FilteredReferencesNuGet-&gt;'%(FullPath)')</AgentDir>
        <AgentDir Condition="'$(AgentDir.IndexOf(&quot;;&quot;))' != -1">$(AgentDir.Substring(0, $(AgentDir.IndexOf(";"))))</AgentDir>
    </PropertyGroup>

    <Error Condition="!Exists('$(AgentDir.Substring(0, $(AgentDir.LastIndexOf(&quot;$(PathSeparator)lib&quot;))))$(PathSeparator)tools$(PathSeparator)$(Instrumentor)')" Text="Agent component directory not found!" />
    <Exec Command="&#xD;&#xA;     &quot;$(AgentDir.Substring(0, $(AgentDir.LastIndexOf(&quot;$(PathSeparator)lib&quot;))))$(PathSeparator)tools$(PathSeparator)$(Instrumentor)&quot; apk=&quot;$(ProjectDir)%(ApkFiles.Identity)&quot; prop=&quot;$(ProjectDir)Assets$(PathSeparator)Dynatrace.properties&quot;&#xD;&#xA;" />
    <Copy SourceFiles="@(ApkFiles)" DestinationFolder="$(IntermediateOutputPath)android$(PathSeparator)bin$(PathSeparator)orginal$(PathSeparator)" />
    <Copy SourceFiles="$(IntermediateOutputPath)android$(PathSeparator)bin$(PathSeparator)%(ApkFiles.Filename)$(PathSeparator)dist$(PathSeparator)%(ApkFiles.Filename).apk" DestinationFolder="$(IntermediateOutputPath)android$(PathSeparator)bin$(PathSeparator)" />
    <RemoveDir Directories="$(IntermediateOutputPath)android$(PathSeparator)bin$(PathSeparator)%(ApkFiles.Filename)" />
</Target>

Configuration for iOS Auto-Instrumentation

• Add some properties to the .plist file
• Add at least one manual call to Dynatrace library

Adding Properties to .plist file

The iOS Auto-Instrumentation needs some properties in order to work correctly. Those properties can be viewed when you look into the documentation links that are provided at the bottom of this documentation, here.

Adding Manual call to the Dynatrace library

The Dynatrace framework would be removed during the build if no call happens to it. In this case it is necessary to add at least one call. Therefore you can use at the beginning of your application

Dynatrace.Start();

Manual Instrumentation in Xamarin Native

This can be done via package DynatraceIOS or DynatraceAndroid. Please refer to the official documentation of the Mobile Agent which contains the description for the API. Be aware that the API might be slightly different because the libraries had to be converted.

Manual Instrumentation in Xamarin Forms

To be able to use the Mobile Agent, even though you are in a Forms application, we added interfaces which can be registered via dependency service. To use those, you have to register them in the Startup of your native application part. Place this code right after Forms.Init() :

Xamarin.Forms.DependencyService.Register<Dynatrace.Dynatrace>();
Xamarin.Forms.DependencyService.Register<Dynatrace.Action>();

Be aware that not all functions are available that are in the available through the native packages DynatraceIOS.* or DynatraceAndroid.* . The following piece of code in your forms application allows you to access the agent:

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

The only additional functions is the function SetupHttpClient(HttpClient httpClient). Every HttpClient passed to this function will get an additonal handler which will take care of the manual web request instrumentation. All other available functions behave the same as their native counterparts.

Documentation Links

Please look into the platform you want to instrument. Both platforms have different requirements. Also pay attention if you use Dynatrace Appmon or Dynatrace Saas/Managed, they mostly need different configurations.

• AppMon: https://www.dynatrace.com/support/doc/appmon/user-experience-management/mobile-uem/
• Dynatrace: https://www.dynatrace.com/support/help/deploy-dynatrace/oneagent/android/ or https://www.dynatrace.com/support/help/deploy-dynatrace/oneagent/ios/

Troubleshooting and current restrictions

• WebRequests are not automatically instrumented (Android, iOS)
• Lifecycles are tracked but not reported (iOS)
• Some User Actions in iOS are not reported. (e.g. didSelectRowAt)