Datadog MAUI SDK - Developer Guide

Complete guide for developers working on the Datadog MAUI SDK.

Table of Contents

Prerequisites

Required Tools

  • .NET SDK - Version 9.0 or higher
  • Visual Studio 2022 or Visual Studio Code with C# extension
  • Android Workload - For Android development
  • iOS Workload - For iOS development (macOS only)
  • Xcode - Latest version (macOS only, for iOS builds)

Check Prerequisites 

make check-prereqs

This verifies that all required tools are installed.

First-Time Setup

1. Clone the Repository 

git clone https://github.com/DataDog/dd-sdk-maui.git
cd dd-sdk-maui

2. Run Development Setup 

make dev-setup

This command will:

  • Install Android and iOS workloads
  • Restore all NuGet packages
  • Verify prerequisites

3. View Available Commands 

make help

Or view the quick reference:

make readme

Common Development Tasks

Check Project Status 

make status

Shows:

  • .NET SDK version
  • Current git status

Restore NuGet Packages 

make restore

Restores packages for:

  • Main solution
  • Android bindings
  • iOS bindings (macOS only)
  • Sample app

Format Code 

make format

Runs dotnet format on the entire solution.

Clean Build Artifacts 

# Clean bin/obj and local packages
make clean

# Deep clean including generated files
make clean-all

Building the SDK

Build Everything 

make build

Builds all projects in the correct order:

  1. Android binding modules
  2. iOS binding modules (macOS only)
  3. MAUI Plugin

Note: Meta-packages (Android/iOS bindings) are only built during make pack.

Build Specific Platforms

Android Only 

make build-android

Android modules built:

  • dd-sdk-android-internal
  • dd-sdk-android-core
  • dd-sdk-android-logs
  • dd-sdk-android-rum
  • dd-sdk-android-trace
  • dd-sdk-android-ndk
  • dd-sdk-android-session-replay
  • dd-sdk-android-webview
  • dd-sdk-android-flags
  • opentracing-api (added via GitHub workflow)

iOS Only (macOS required) 

make build-ios

iOS modules built:

  • DatadogInternal
  • DatadogCore
  • DatadogLogs
  • DatadogRUM
  • DatadogTrace
  • DatadogCrashReporting
  • DatadogSessionReplay
  • DatadogWebViewTracking
  • DatadogFlags
  • OpenTelemetryApi

Plugin Only 

make build-plugin

Builds the cross-platform MAUI plugin that wraps Android and iOS bindings.

Packaging

Create All NuGet Packages 

make pack

This follows the proper dependency order documented in docs/PACKAGING_ARCHITECTURE.md:

  1. Builds all binding modules
  2. Packs individual Android modules (net9.0-android and net10.0-android)
  3. Combines Android packages into multi-target packages
  4. Packs individual iOS modules
  5. Packs Android and iOS meta-packages
  6. Packs the MAUI Plugin

Output: All packages are created in ./artifacts/

Debug builds: For debug configuration packages, run ./scripts/pack.sh Debug ./artifacts-debug directly.

Testing

Run Unit Tests 

make test

Runs all tests in Datadog.MAUI.Plugin.Tests/.

For verbose output, run dotnet test --verbosity detailed directly.

Sample Apps

Build and Run Android Sample 

# Build and launch on connected device/emulator
make sample-android

# Build only (don't run)
make sample-build-android

Requirements:

  • Android emulator running or device connected
  • Android SDK installed

Build and Run iOS Sample (macOS only) 

# Build and launch on default simulator
make sample-ios

# Build only (don't run)
make sample-build-ios

To list available iOS simulators, use xcrun simctl list devices available directly.

Android Binding Development

Generate Android Dependencies

When adding a new Android SDK module, analyze its Maven POM to get dependency information:

make generate-android-deps MODULE=dd-sdk-android-rum VERSION=3.5.0

This script:

  1. Downloads the module’s POM file from Maven Central
  2. Extracts all dependencies
  3. Generates <AndroidMavenLibrary> entries for your .csproj

See docs/ANDROID_DEPENDENCIES.md for details.

Setup Android Binding from Build Errors

When you have build errors in an Android binding project:

make setup-android-binding PROJECT=Datadog.MAUI.Android.Binding/dd-sdk-android-rum VERSION=3.5.0

This script:

  1. Attempts to build the project
  2. Analyzes error output
  3. Suggests missing dependencies
  4. Generates dependency entries

See docs/SCRIPTS_OVERVIEW.md for details.

Watch Android Bindings for Changes

Auto-rebuild on file changes:

make watch-android

Press Ctrl+C to stop.

iOS Binding Development

Download iOS XCFrameworks 

make download-ios-frameworks

Downloads XCFrameworks from the Datadog iOS SDK GitHub releases. The version is automatically read from Directory.Build.props.

This command is smart:

  • Checks if XCFrameworks are already downloaded
  • Verifies the version matches Directory.Build.props
  • Only downloads if missing or version mismatch
  • Automatically called by make build-ios and make pack

Requirements:

  • macOS
  • Internet connection

The XCFrameworks will be downloaded to Datadog.MAUI.iOS.Binding/artifacts/.

Note: You typically don’t need to run this manually - make pack will automatically download frameworks if needed.

Generate iOS Bindings with Objective Sharpie 

make generate-ios-bindings

Uses Objective Sharpie to generate C# bindings from iOS XCFrameworks.

Requirements:

  • macOS
  • Objective Sharpie installed
  • XCFrameworks in Datadog.MAUI.iOS.Binding/artifacts/

See docs/IOS_BINDING_STRATEGY.md for details.

Watch iOS Bindings for Changes

Auto-rebuild on file changes:

make watch-ios

Press Ctrl+C to stop.

Troubleshooting

Sample App Fails to Build

Problem: Duplicate class errors (XA4215) when building Android sample.

Solution:

  1. Rebuild binding packages: make pack
  2. Clean sample: cd samples/DatadogMauiSample && dotnet clean
  3. Rebuild sample: make sample-build-android

Missing XCFrameworks for iOS

Problem: make build-ios or make pack fails with “No XCFrameworks found”

Solution: This should happen automatically now. The make build-ios and make pack commands automatically download XCFrameworks if they’re missing or out of date.

If you need to manually trigger a download:

make download-ios-frameworks

Note: The GitHub workflow build-ios.yml also handles this automatically.

OpenTracingApi Package Missing

Problem: Android builds fail with NU1101: Unable to find package Datadog.MAUI.Android.OpenTracingApi

Solution: The opentracing-api module is now included in the build loops. Re-run the GitHub workflow or:

make clean
make pack

Gradle Plugin Versioning Mismatch

Problem: dd-sdk-android-gradle-plugin version doesn’t match SDK version.

Note: The gradle plugin has been archived (moved to _archive/) because it’s incompatible with MAUI’s MSBuild system. For mapping file uploads, see docs/MAPPING_FILE_UPLOADS.md.

R8 Mapping Files Not Generated

Problem: mapping.txt file not found after Release build.

Solution: Enable R8 in your .csproj:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <AndroidEnableR8>True</AndroidEnableR8>
  <AndroidLinkTool>r8</AndroidLinkTool>
  <AndroidLinkMode>SdkOnly</AndroidLinkMode>
</PropertyGroup>

See docs/MAPPING_FILE_UPLOADS.md for complete guide.

Architecture Documentation

Core Documentation

Build & Packaging

Binding Development

API Design

Deployment

Automation

Quick Command Reference

Task Command
First-time setup make dev-setup
Download iOS XCFrameworks make download-ios-frameworks
Build everything make build
Build Android only make build-android
Build iOS only make build-ios
Build plugin only make build-plugin
Create all packages make pack
Run tests make test
Clean artifacts make clean
Restore packages make restore
Run Android sample make sample-android
Run iOS sample make sample-ios
Check prerequisites make check-prereqs
View all commands make help

Development Workflow

Adding a New Feature

  1. Create a feature branch: 
    git checkout -b feature/my-feature
  2. Make your changes to the appropriate projects:
    • Android bindings: Datadog.MAUI.Android.Binding/
    • iOS bindings: Datadog.MAUI.iOS.Binding/
    • Plugin: Datadog.MAUI.Plugin/
  3. Build and test: 
    make build
make test
  4. Format code: 
    make format
  5. Test with sample app: 
    make pack
make sample-android  # or sample-ios
  6. Commit and push: 
    git add .
git commit -m "feat: add my feature"
git push origin feature/my-feature

Fixing a Binding Issue

  1. Identify which binding module has the issue

  2. Build just that module to see errors: 
    cd Datadog.MAUI.Android.Binding/dd-sdk-android-rum
dotnet build

  3. Fix issues (usually in Transforms/Metadata.xml)

  4. Rebuild: 
    make build-android
  5. Test: 
    make pack
make sample-android

Updating SDK Versions

When Datadog releases a new Android or iOS SDK version:

  1. Update version in Directory.Build.props: 
    <DatadogSdkVersion>3.6.0</DatadogSdkVersion>
  2. For Android, regenerate dependencies if needed: 
    make generate-android-deps MODULE=dd-sdk-android-core VERSION=3.6.0

  3. For iOS, download new XCFrameworks and place in Datadog.MAUI.iOS.Binding/artifacts/

  4. Build and test: 
    make clean-all
make pack
make test
  5. Test sample apps on both platforms

CI/CD Integration

The project uses GitHub Actions for automated builds. See WORKFLOW_ARCHITECTURE.md for details.

Workflows

  • build-all.yml - Builds Android and iOS in parallel
  • build-android.yml - Android-specific build
  • build-ios.yml - iOS-specific build (downloads XCFrameworks automatically)

Local Testing Before Push

Before pushing changes, ensure everything builds:

make clean
make build
make test
make pack

Getting Help

  • View all commands: make help
  • Check status: make status
  • Documentation: Browse docs/ directory

Contributing

See CONTRIBUTING.md for detailed contribution guidelines.