[TrimmableTypeMap] Improve array handling

[simonrozsival]

Summary

Replaces the per-T JavaPeerContainerFactory<T>.CreateArray factory with a runtime fork that uses the .NET runtime type loader on CoreCLR/Mono and a per-rank trimmable typemap on NativeAOT. Eliminates the per-peer array-creation IL bloat that JavaPeerContainerFactory<T> was contributing — without the trim regressions we evaluated through several alternative designs (see Considered alternatives at the end).

Tracking: #11234 Phase 2 (arrays-only — container types JavaList<T> / JavaCollection<T> / JavaDictionary<K, V> stay untouched and have their own follow-up PR).

Runtime fork

JNIEnv.ArrayCreateInstance branches on RuntimeFeature.IsDynamicCodeSupported:

if (RuntimeFeature.TrimmableTypeMap) {
    if (System.Runtime.CompilerServices.RuntimeFeature.IsDynamicCodeSupported) {
        // CoreCLR / Mono — runtime type loader can construct any T[] dynamically.
        // No typemap roundtrip; supports unlimited array rank.
        return Array.CreateInstance (elementType, length);
    }
    // NativeAOT — resolve via per-rank trimmable typemap +
    // AOT-safe Array.CreateInstanceFromArrayType.
    if (TrimmableTypeMap.Instance.TryGetArrayType (elementType, out var arrayType)) {
        return Array.CreateInstanceFromArrayType (arrayType, length);
    }
    throw new NotSupportedException ("...");
}
// legacy non-trimmable fallback unchanged

Why fork? CoreCLR's runtime type loader can construct any T[] from its element-type metadata at runtime, so going through the typemap is unnecessary work and trim warnings. NativeAOT cannot (value-type arrays each need their own codegen, and our marshaling call sites are opaque to the trimmer), so the typemap is the only AOT-safe route.

Generator changes

For every non-aliased, non-generic peer (excluding JNI primitive-keyword keys), the generator emits three speculative TypeMap entries keyed by the element JNI name and anchored to per-typemap-assembly rank sentinel TypeDefs:

// Inside each per-assembly typemap dll, when $(PublishAot) == true:
internal sealed class __ArrayMapRank1 { }
internal sealed class __ArrayMapRank2 { }
internal sealed class __ArrayMapRank3 { }

[assembly: TypeMap<__ArrayMapRank1>("java/lang/String", typeof(string[]),     typeof(string[]))]
[assembly: TypeMap<__ArrayMapRank2>("java/lang/String", typeof(string[][]),   typeof(string[][]))]
[assembly: TypeMap<__ArrayMapRank3>("java/lang/String", typeof(string[][][]), typeof(string[][][]))]

• Trim target = closed array type so ILC's per-shape conditional drops the entry when the array shape is never constructed (validated at ~/Projects/playground/TestTypeMapArrays with disjoint type sets — works for both ref- and value-type elements).
• Element-only JNI keys — no "[" + "L" + jni + ";" runtime concat.
• Per-rank groups — rank is a switch dispatch at runtime, not part of the key. The __ArrayMapRank{N} sentinels mirror the existing __TypeMapAnchor pattern (per-assembly, like generic anchor types).
• Conditional emission gated on $(PublishAot) == true. Saves attribute metadata on CoreCLR-only builds where the runtime fork bypasses the typemap entirely.
• Skip rules: open-generic peers (typeof(T<>[]) invalid), JNI primitive-keyword keys (handled by the legacy primitive-array path), alias groups (would produce duplicate keys; deferred until alias-aware design).

Runtime API

ITypeMapWithAliasing gains:

bool TryGetArrayType (string jniElementTypeName, int rank, [NotNullWhen (true)] out Type? arrayType);

SingleUniverseTypeMap carries three nullable IReadOnlyDictionary<string, Type>? fields (rank 1, 2, 3); AggregateTypeMap does first-wins iteration. TrimmableTypeMap.Initialize gains 5-arg overloads (single + aggregate) accepting the per-rank dicts; the existing 2-arg overloads stay as wrappers passing null per-rank dicts.

TrimmableTypeMap.TryGetArrayType(Type elementType, out Type? arrayType) walks down elementType.IsArray / GetElementType() to find the leaf type and the element array depth, resolves the leaf JNI element name (primitive static dict OR TryGetJniNameForManagedType wrapped), and delegates the (elementJni, rank=elementDepth+1) lookup to _typeMap.TryGetArrayType.

Generator IL emission

RootTypeMapAssemblyGenerator.EmitTypeMapLoader branches on emitArrayEntries. When true, the generated TypeMapLoader.Initialize IL collects per-rank dicts from each per-assembly typemap (5 IReadOnlyDictionary<...>[] arrays total — typeMaps, proxyMaps, arrayMapsRank1/2/3) and passes them to the 5-arg TrimmableTypeMap.Initialize. The aggregate (Debug) path is fully implemented; the merged-universe (Release) path throws at generation time with a clear message — wiring the shared-universe array sentinels is a small follow-up.

What's deleted

• JavaPeerContainerFactory<T>.CreateArray and CreateHigherRankArray.
• The abstract base method on JavaPeerContainerFactory.

Other factory methods (CreateList, CreateCollection, CreateDictionary*) stay — those will be addressed in the follow-up Phase 2-collections PR.

Files changed

File	Notes
Generator/Model/TypeMapAssemblyData.cs	New TypeMapAttributeData.AnchorRank (1-based per-rank anchor) and TypeMapAssemblyData.RankSentinels (sentinel TypeDef names).
Generator/TypeMapAssemblyEmitter.cs	EmitRankSentinels mirrors EmitAnchorType; per-anchor TypeMap<TGroup> 3-arg ctor caching via GetOrAddTypeMapAttr3ArgCtorRef.
Generator/ModelBuilder.cs	New bool emitArrayEntries parameter on Build; per-rank trio emitted via new EmitArrayEntries (skip rules: generics, primitive keywords, aliases).
Generator/RootTypeMapAssemblyGenerator.cs	New bool emitArrayEntries parameter; aggregate path emits per-rank dict arrays in TypeMapLoader.Initialize; new 5-arg Initialize member refs.
TrimmableTypeMapGenerator.cs	Execute and GenerateTypeMapAssemblies propagate emitArrayEntries.
Generator/TypeMapAssemblyGenerator.cs	Generate propagates emitArrayEntries.
Tasks/GenerateTrimmableTypeMap.cs	New EmitArrayEntries MSBuild task property.
targets/Microsoft.Android.Sdk.TypeMap.Trimmable.targets	Sets EmitArrayEntries="$(PublishAot)" on the task invocation.
Microsoft.Android.Runtime/ITypeMapWithAliasing.cs	TryGetArrayType interface method.
Microsoft.Android.Runtime/SingleUniverseTypeMap.cs	Per-rank dict ctor + TryGetArrayType impl.
Microsoft.Android.Runtime/AggregateTypeMap.cs	First-wins TryGetArrayType impl.
Microsoft.Android.Runtime/TrimmableTypeMap.cs	New 5-arg Initialize overloads + TryGetArrayType(Type, out Type?) + TryGetPrimitiveJniName helper.
Android.Runtime/JNIEnv.cs	ArrayCreateInstance runtime fork.
Java.Interop/JavaPeerContainerFactory.cs	CreateArray / CreateHigherRankArray deleted; class doc updated.
tests/.../TypeMapModelBuilderTests.cs	14 new generator unit tests covering default-off behavior, sentinel emission, per-rank trio, element-only key, closed-array trim target, conditional-only entries, skip rules (open generic, alias group, primitive keywords), multi-peer isolation, and PE blob round-trip.

Validation

• Generator unit tests: 445 / 445 pass (425 baseline + 20 new).
• Trimmable + CoreCLR RunTestApp lane on emulator (-p:_AndroidTypeMapImplementation=trimmable -p:UseMonoRuntime=false): 917 total, 0 errors, 3 failures (the 3 are pre-existing TryGetJniNameForManagedType_* from [TrimmableTypeMap] JavaCast/JavaAs + container support #11225, called out as out-of-scope there). No regression.
• NativeAOT path with array TypeMap entries: validated with the standalone repro at ~/Projects/playground/TestTypeMapArrays against .NET 11 nightly 11.0.100-preview.5.26228.123 (which bundles [ILLink/ILCompiler] Fix crash when array types are used as TypeMap trim targets runtime#126380's TypeMapHandler.UnwrapToResolvableType fix). The dotnet/android end-to-end NativeAOT lane needs the SDK to ship a build with #126380 — currently in our SDK we have 11.0.0-preview.4.26215.121 which crashes ILLink before reaching the new code.

SDK gating

The NativeAOT array-emission path requires dotnet/runtime#126380 (TypeMapHandler.UnwrapToResolvableType, merged 2026-04-20, ships in .NET 11 nightly preview.5+). Until dotnet/android picks up an SDK with that fix:

• CoreCLR / Mono — works today. The runtime fork hits Array.CreateInstance directly; the typemap isn't consulted.
• NativeAOT with _AndroidTypeMapImplementation=trimmable — would crash in ILLink's TypeMapHandler.RecordTypeMapEntry on the [assembly: TypeMap<__ArrayMapRank{N}>(...)] array entries. Not in any current dotnet/android CI lane (the typical NativeAOT lanes use Mono runtime or don't enable trimmable typemap), so the PR can land without blocking on the SDK bump. Once the SDK bumps, the path becomes live with no further changes.

Considered alternatives

Documented in detail in #11234. Summary:

• Proxy map (TypeMapAssociation<G>(typeof(T), typeof(T[]))): cleaner Type → Type lookup, but ProxyTypeMapNode.GetConditionalStaticDependencies conditions on MaximallyConstructableType(key) (the element), so T[] survives whenever T is reachable — losing per-shape trimming. Validated on disjoint-set NativeAOT tests.
• Single composite-key external map ("[L<jni>;", "[[L<jni>;"): same trim behavior as per-rank groups but pays a string.Concat at every JNIEnv.ArrayCreateInstance call. Per-rank groups eliminate that cost.
• Scanner-based emission: tighter trim than speculative emission, but requires a metadata signature walker. Layerable on top of this PR as a follow-up if app-size measurement shows speculative emission is too costly.

Out of scope

• Container types (JavaList<T> / JavaCollection<T> / JavaDictionary<K, V>) and the corresponding JavaPeerContainerFactory<T>.Create* methods.
• JavaPeerProxy<T>.GetContainerFactory() virtual / override (deletion follows in the Phase 3 PR).
• TrimmableTypeMap.GetContainerFactory(Type).
• Removing [DAM(Constructors)] annotations ([TrimmableTypeMap] Address all trimming and AOT warnings #10794).
• Alias-aware array emission.
• Merged-universe (Release) array emission — generator throws at generation time today; small follow-up to wire the shared-universe loader.

[simonrozsival]

/review

[github-actions]

✅ Android PR Reviewer completed successfully!

[github-actions]

✅ LGTM — Clean design, minor doc/style nits

Well-architected PR. The runtime fork (CoreCLR → Array.CreateInstance directly, NativeAOT → per-rank typemap + Array.CreateInstanceFromArrayType) is sound and avoids unnecessary typemap lookups on CoreCLR while remaining AOT-safe on NativeAOT.

What looks good:

• IL emission for both aggregate (Debug) and single-universe (Release) paths is correct — stack discipline, local variable encoding, and member reference blobs all check out.
• Thorough edge-case handling in EmitArrayEntries: primitives skipped (dedicated JNI handlers exist), open generics rejected (typeof(T<>[]) invalid), alias groups deferred.
• TryGetArrayType's unwrap loop correctly handles nested szarrays and rejects multi-dim arrays.
• 14+ new generator unit tests cover the key scenarios including PE round-trip verification.
• Sentinel types in ArrayMapAnchors.cs mirror the established __TypeMapAnchor pattern nicely.
• MaxSupportedArrayRank = 8 matches the 8 anchor types, with the MSBuild default of 3 for NativeAOT being practical for typical apps.

Minor nits (3 inline 💡):

Sev	Category	File
💡	Formatting	Array.Empty<T>() → [] (2 instances)
💡	Documentation	EmitArrayEntries doc comment mentions [L<jni>;-shaped keys but keys are bare element names
💡	Documentation	Stale 2-arg Initialize references in comments

No correctness, safety, or performance issues found.

Generated by Android PR Reviewer for issue #11238 · ● 9.8M

[github-actions]

🤖 💡 Formatting — Repo convention prefers [] over Array.Empty<T>().

Suggested change

	EntityHandle [] _rankAnchorHandles = Array.Empty<EntityHandle> ();
	EntityHandle [] _rankAnchorHandles = [];

Same applies to TrimmableTypeMap.cs line 41:

_arrayMapsByRank = arrayMapsByRank ?? [];

Rule: Use [] not Array.Empty<T>()

[github-actions]

🤖 💡 Documentation — The xml-doc says "the loader uses the 2-arg Initialize", but the old 2-arg overloads were replaced by the new 3-arg overloads that always take arrayMapsByRank (passing null when 0). Consider updating:

	/// no array sentinels were emitted; the loader passes <c>null</c> for <c>arrayMapsByRank</c>.

Also, the class-level pseudo-C# example at lines 36–49 still shows the old 2-arg TrimmableTypeMap.Initialize(typeMaps, proxyMaps) call — updating that would keep it consistent with the new 3-arg signature.

Rule: Stale comments (Postmortem #59)

[github-actions]

🤖 💡 Documentation — The doc comment says "[L<jni>;-shaped TypeMap entries", but the design choice here is specifically to use the bare element JNI name as the key (no [L...; wrapping). The test Build_EmitArrayEntries_KeyIsElementJniName documents this explicitly. Consider rewording to avoid confusion:

Suggested change

	/// Emits per-rank <c>[L&lt;jni&gt;;</c>-shaped TypeMap entries for one peer, anchored to
	/// the per-assembly <c>__ArrayMapRank{N}</c> sentinels. Skips open generics, primitive
	/// JNI keyword keys (handled by the legacy primitive-array path), and alias groups.
	/// Emits per-rank array TypeMap entries for one peer, anchored to
	/// the per-assembly <c>__ArrayMapRank{N}</c> sentinels. Keys are bare element JNI names
	/// (rank is encoded by the sentinel anchor, not by JNI array prefixes). Skips open generics,
	/// primitive JNI keyword keys (handled by the legacy primitive-array path), and alias groups.

Rule: Comments explain "why", not "what" — and shouldn't contradict the implementation

[Copilot]

Pull request overview

Refactors trimmable typemap array creation to avoid per-T factory IL bloat by routing array construction through JNIEnv.ArrayCreateInstance, using Array.CreateInstance when dynamic code is supported and a per-rank array typemap under NativeAOT.

Changes:

• Add generator support for per-rank array TypeMap entries (with rank anchors) and plumb MaxArrayRank through the MSBuild task + targets.
• Update the runtime typemap initialization and lookup to support array-type resolution under NativeAOT, and update JNIEnv.ArrayCreateInstance to use the new runtime fork.
• Remove JavaPeerContainerFactory<T> array creation APIs and update tests to cover the new generator/root-assembly behavior.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/Microsoft.Android.Sdk.TrimmableTypeMap.Tests/Generator/TypeMapModelBuilderTests.cs	Adds unit tests validating array-entry model emission (ranks, keys, skip rules, blob round-trip).
tests/Microsoft.Android.Sdk.TrimmableTypeMap.Tests/Generator/RootTypeMapAssemblyGeneratorTests.cs	Adds tests for merged-universe root assembly generation when arrays are enabled.
src/Xamarin.Android.Build.Tasks/Tasks/GenerateTrimmableTypeMap.cs	Adds MaxArrayRank task input and forwards it into typemap generation.
src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.TypeMap.Trimmable.targets	Introduces $(_AndroidTrimmableTypeMapMaxArrayRank) defaults and passes it to the task.
src/Mono.Android/Microsoft.Android.Runtime/TrimmableTypeMap.cs	Extends initialization to accept per-rank array dictionaries and adds TryGetArrayType lookup used by NativeAOT.
src/Mono.Android/Microsoft.Android.Runtime/ArrayMapAnchors.cs	Adds shared __ArrayMapRank{N} anchor types in Mono.Android for rank grouping.
src/Mono.Android/Java.Interop/JavaPeerContainerFactory.cs	Removes array creation APIs from the container factory surface (arrays move to JNIEnv).
src/Mono.Android/Android.Runtime/JNIEnv.cs	Implements the runtime fork for array creation (dynamic-code vs NativeAOT typemap).
src/Microsoft.Android.Sdk.TrimmableTypeMap/TrimmableTypeMapGenerator.cs	Adds MaxSupportedArrayRank validation and threads maxArrayRank through generation.
src/Microsoft.Android.Sdk.TrimmableTypeMap/Generator/TypeMapAssemblyGenerator.cs	Passes maxArrayRank into ModelBuilder.Build.
src/Microsoft.Android.Sdk.TrimmableTypeMap/Generator/TypeMapAssemblyEmitter.cs	Emits rank anchor refs and supports rank-anchored 3-arg TypeMap<TGroup> constructor emission.
src/Microsoft.Android.Sdk.TrimmableTypeMap/Generator/RootTypeMapAssemblyGenerator.cs	Emits root-loader initialization that passes array rank dictionaries (or null) into TrimmableTypeMap.Initialize.
src/Microsoft.Android.Sdk.TrimmableTypeMap/Generator/ModelBuilder.cs	Emits per-rank array entries into the typemap model when enabled.
src/Microsoft.Android.Sdk.TrimmableTypeMap/Generator/Model/TypeMapAssemblyData.cs	Adds MaxArrayRank and per-entry AnchorRank metadata for array mapping.

[Copilot]

TrimmableTypeMap.Initialize previously had 2-arg overloads; this change replaces them with 3-arg overloads only. That’s a breaking API change and can also break older generated _Microsoft.Android.TypeMaps assemblies at runtime (MissingMethodException) if they still call the 2-arg overloads. Consider re-introducing the 2-arg overloads as wrappers that forward null for arrayMapsByRank to preserve backward compatibility.

[Copilot]

TryGetArrayType currently relies on _arrayMapsByRank lookups using primitive JNI keywords (Z/B/C/...). However the generator intentionally skips emitting array entries for primitive JNI keyword keys, so NativeAOT + trimmable typemap will fail to create jagged primitive arrays (e.g. byte[][] where elementType is typeof(byte[])), leading to JNIEnv.ArrayCreateInstance throwing NotSupportedException. Please add an AOT-safe fallback for primitive-leaf arrays (e.g. a precomputed (primitive, rank)->Type table) or ensure primitive-key array entries are present in the rank maps.

Suggested change

	if ((uint)rankIndex >= (uint)_arrayMapsByRank.Length || _arrayMapsByRank [rankIndex] is not { } dict) {
	return false;
	}
	string? leafJniName = leaf.IsPrimitive
	? TryGetPrimitiveJniName (leaf, out var p) ? p : null
	: TryGetJniNameForManagedType (leaf, out var jni) ? jni : null;
	return leafJniName is not null && dict.TryGetValue (leafJniName, out arrayType);
	bool isPrimitiveLeaf = leaf.IsPrimitive;
	if ((uint)rankIndex < (uint)_arrayMapsByRank.Length && _arrayMapsByRank [rankIndex] is { } dict) {
	string? leafJniName = isPrimitiveLeaf
	? TryGetPrimitiveJniName (leaf, out var p) ? p : null
	: TryGetJniNameForManagedType (leaf, out var jni) ? jni : null;
	if (leafJniName is not null && dict.TryGetValue (leafJniName, out arrayType)) {
	return true;
	}
	}
	// Primitive leaf arrays intentionally do not have primitive-keyed rank-map entries,
	// so construct the next szarray type directly as an AOT-safe fallback.
	if (isPrimitiveLeaf) {
	arrayType = elementType.MakeArrayType ();
	return true;
	}
	return false;

[Copilot]

The comment references TrimmableTypeMap.MaxSupportedArrayRank, but the max-rank constant introduced in this PR lives in TrimmableTypeMapGenerator.MaxSupportedArrayRank. Please update the comment to point at the correct symbol/location so future rank bumps don’t miss updating the generator limit.

Suggested change

	// TrimmableTypeMap.MaxSupportedArrayRank.
	// TrimmableTypeMapGenerator.MaxSupportedArrayRank.

[Copilot]

The comment says "Defaults to 3 under AOT (CoreCLR reaches Array.CreateInstance directly and skips the typemap roundtrip)", but $(PublishAot)==true is exactly the scenario where RuntimeFeature.IsDynamicCodeSupported is false and JNIEnv.ArrayCreateInstance must use the typemap/Array.CreateInstanceFromArrayType path. Please reword this comment to reflect the actual behavior (e.g., default 3 for NativeAOT; 0 for non-AOT where dynamic code can use Array.CreateInstance).

Suggested change

	<!-- Max array rank for __ArrayMapRank{N} sentinel emission. Defaults to 3 under AOT (CoreCLR
	reaches Array.CreateInstance directly and skips the typemap roundtrip). -->
	<!-- Max array rank for __ArrayMapRank{N} sentinel emission. Defaults to 3 for NativeAOT
	(PublishAot=true, dynamic code is unavailable, so array creation uses the typemap path);
	defaults to 0 otherwise, where dynamic code can use Array.CreateInstance directly. -->

[Copilot]

The maxArrayRank doc says the loader uses the 2-arg Initialize overload when maxArrayRank is 0, but the generator now emits calls to the 3-arg Initialize(..., arrayMapsByRank) and passes null when maxArrayRank == 0. Please update this doc comment to match the emitted IL.

Suggested change

	/// no array sentinels were emitted; the loader uses the 2-arg <c>Initialize</c>.
	/// no array sentinels were emitted; the loader still calls the 3-arg <c>Initialize</c>
	/// overload and passes <see langword="null"/> for the array-maps argument.

[Copilot]

PR description states that merged-universe (Release) array emission currently throws at generation time and needs a follow-up, but these new merged-mode array tests indicate the merged-universe path is implemented. Please update the PR description (or the code/tests) so they agree about whether merged-mode array emission is supported in this PR.

[Copilot]

The NotSupportedException guidance is misleading: TryGetArrayType looks up entries in the per-rank __ArrayMapRank{N} TypeMap groups keyed by the element JNI name, so adding a generic [assembly: TypeMap] entry for the closed array type may not fix the issue unless it’s anchored to the correct rank group. Consider updating the message to mention the required __ArrayMapRank{rank} group / MaxArrayRank setting (or point users at the MSBuild property that controls emission) so the suggested remediation is accurate.

Suggested change

	$"Add an [assembly: TypeMap] entry for the closed array type or report an issue.");
	$"Array lookups use the element type within the per-rank '__ArrayMapRank1' typemap group; ensure the mapping is emitted for rank 1 (for example by increasing MaxArrayRank) or report an issue.");