Mobile Platforms

Triage and fix .NET failures on Apple mobile (iOS, tvOS, MacCatalyst) and Android in dotnet/runtime.

Why mobile is different

Mobile platforms run .NET on devices and simulators/emulators where the host OS controls code execution. Apple forbids JIT in production (simulators allow it), requires code signing, and has six OS variants that often need identical handling. Android requires cross-compilation and APK packaging across four architectures. Both surface failures invisible on desktop: provisioning errors, emulator boot timeouts, app bundle signing, native toolchain mismatches.

CoreCLR is the primary runtime. NativeAOT is the default publish framework for ahead-of-time compilation. Mono also runs in CI alongside CoreCLR.

CI pipeline

Mobile tests run in the runtime-extra-platforms pipeline (AzDO definition 154, org dnceng-public, project public), daily on main and on relevant PRs.

Jobs follow {platform} {config} {subset}:

Suffixes: empty (libraries), RuntimeTests, Smoke, AppSandbox, Interp.

Where to look

Start from the failure type, not the platform. The tables below map failure symptoms to code paths.

Build and packaging failures

These happen before tests run. The app bundle fails to build, sign, or package.

Apple code signing uses DevTeamProvisioning: - for simulators, adhoc for MacCatalyst. If a signing error mentions provisioning profiles, check whether the right value is passed in the pipeline YAML.

Test failures

The test itself fails or crashes on the device/emulator.

Common cause: a test assumes desktop behavior (process spawning, filesystem layout, JIT availability). Check whether the test has platform-specific skip conditions using PlatformDetection.

NativeAOT compilation failures

NativeAOT on mobile has a different target resolution path than desktop. Directory.Build.targets evaluates before NuGet package targets, so properties like _IsApplePlatform from Microsoft.DotNet.ILCompiler are not available in eng/toolAot.targets. For Apple mobile library tests, ILCompilerTargetsPath must be set to $(CoreCLRBuildIntegrationDir)Microsoft.DotNet.ILCompiler.SingleEntry.targets with _IlcReferencedAsPackage=false.

Key files: eng/targetingpacks.targets, eng/toolAot.targets.

Native interop crashes

Stack traces pointing into native code or P/Invoke calls.

Pipeline YAML

When the job definition itself is wrong (e.g., missing a platform, wrong build args):

Platform gotchas

Things that have caused confusion before and will again:

• Apple has six OS variants: ios, iossimulator, tvos, tvossimulator, maccatalyst (x64 + arm64). A fix for one variant almost always needs to cover all six. Missing one causes the next pipeline run to fail on a different job.
• dsymutil outputs errors to stdout, not stderr. 2>/dev/null does not suppress its errors; use >/dev/null 2>&1.
• Android has four architectures: android-arm, android-arm64, android-x64, android-x86. x86 is 32-bit and can expose different issues than the 64-bit targets.
• MSBuild evaluation order: Directory.Build.targets runs before NuGet package .targets. Properties from packages are not available in eng/toolAot.targets.

Failure triage

Classify every failure as infrastructure or code before acting.

Infrastructure failures

Caused by the test environment, not code. Indicators:

• Timeout with no test output (emulator/simulator boot failure)
• "device not found", "provisioning profile", "code signing" errors
• Network errors during Helix payload download
• Machine-specific: same test passes on other machines
• "No space left on device", Helix agent crashes

Report infrastructure failures on existing tracking issues with a table entry:

If no matching issue exists, create one with area-Infrastructure and platform labels (os-ios, os-tvos, os-maccatalyst, os-android).

For already tracked known issues, check whether the root cause is actionable. If a code or configuration fix is feasible, open a PR. If the issue is purely infrastructure (device provisioning, network), add occurrence data to the tracking issue instead.

Code failures

Caused by recent commits. Indicators:

• Test was passing in previous builds
• Error references managed code
• Recent commit touched platform-sensitive code

Investigate code failures by starting with git log --oneline --since='3 days ago' on the relevant path. If nothing matches, widen the window or check for intermittent patterns across recent builds. Common patterns:

• New API missing mobile platform handling
• #if conditional compilation missing a mobile target
• P/Invoke change without a mobile native implementation
• Test assuming desktop behavior (process spawning, JIT, filesystem paths)

Self-improvement

When a mobile fix workflow discovers new patterns or workarounds, record the finding as a comment on the tracking issue (or create a new issue labeled area-Infrastructure-mono) so the team can later incorporate it into this document. Add findings to the relevant section above:

• New failure patterns not yet documented
• Code paths that turned out to be relevant
• Recurring infrastructure issues and their workarounds
• Platform gotchas discovered during investigation

Keep PRs focused on the mobile failure being fixed. Unrelated skill edits make review and blame harder, so avoid editing this file in PRs that are not fixing or documenting mobile platform work.