Copilot instructions

1---
2applyTo:
3  - "**/*.Android.cs"
4  - "**/Android/**/*.cs"
5  - "**/Platforms/Android/**/*.cs"
6  - "**/Platform/Android/**/*.cs"
7  - "**/AndroidNative/**"
8  - "eng/init.gradle"
9  - "eng/ingest-maven-deps.sh"
10---
11 
12# Android Platform Development Guidelines
13 
14Guidance for Android handler implementations and platform code.
15 
16## Common Build Issues
17 
18### View Namespace Collision
19 
20**Problem:** Both MAUI and Android have a `View` type, causing ambiguous reference errors when implementing Android listeners or using Android View APIs.
21 
22**Namespace collision between:**
23- `Microsoft.Maui.Controls.View` (MAUI's View type)
24- `Android.Views.View` (Android's native View type)
25 
26**Common symptoms:**
27```
28error CS0234: The type or namespace name 'Views' does not exist in the namespace 'Android'
29error CS0104: 'View' is an ambiguous reference between 'Microsoft.Maui.Controls.View' and 'Android.Views.View'
30```
31 
32**When this occurs:**
33- Implementing Android listeners: `IOnLayoutChangeListener`, `IOnClickListener`, `IOnTouchListener`
34- Using Android View APIs directly
35- Working with RecyclerView, ViewGroup, or Android layout classes
36- Accessing Android view properties or methods
37 
38**Solution: Use type aliases**
39 
40Add type alias at the top of the file:
41 
42```csharp
43using AView = Android.Views.View;
44```
45 
46Then use the alias throughout the file:
47 
48```csharp
49class LayoutChangeListener : Java.Lang.Object, AView.IOnLayoutChangeListener
50{
51    public void OnLayoutChange(AView v, int left, int top, int right, int bottom, 
52                               int oldLeft, int oldTop, int oldRight, int oldBottom)
53    {
54        // Use AView to unambiguously refer to Android.Views.View
55    }
56}
57```
58 
59**Common type aliases used in MAUI Android code:**
60 
61| Alias | Full Type | When to Use |
62|-------|-----------|-------------|
63| `AView` | `Android.Views.View` | View APIs, listeners |
64| `AColor` | `Android.Graphics.Color` | vs `Microsoft.Maui.Graphics.Color` |
65| `ALayoutParams` | `Android.Views.ViewGroup.LayoutParams` | Layout parameters |
66| `AContext` | `Android.Content.Context` | vs `Microsoft.Maui.ApplicationModel.Context` (rare) |
67 
68**Alternative: Use global:: qualifier**
69 
70If type alias would conflict with existing code:
71 
72```csharp
73class MyListener : Java.Lang.Object, global::Android.Views.View.IOnLayoutChangeListener
74{
75    public void OnLayoutChange(global::Android.Views.View v, ...)
76    {
77        // Explicit namespace qualification
78    }
79}
80```
81 
82## Android Handler Best Practices
83 
84### Lifecycle Management
85 
86When implementing Android listeners/callbacks in handlers:
87 
881. **Register in ConnectHandler:**
89```csharp
90protected override void ConnectHandler(RecyclerView platformView)
91{
92    base.ConnectHandler(platformView);
93    _listener = new MyListener(this);
94    platformView.AddSomeListener(_listener);
95}
96```
97 
982. **Unregister in DisconnectHandler:**
99```csharp
100protected override void DisconnectHandler(RecyclerView platformView)
101{
102    if (_listener != null)
103    {
104        platformView.RemoveSomeListener(_listener);
105        _listener?.Dispose();
106        _listener = null;
107    }
108    base.DisconnectHandler(platformView);
109}
110```
111 
1123. **Always dispose Java.Lang.Object derivatives** to prevent memory leaks
113 
114### Thread Safety
115 
116- Android View APIs are **UI-thread-only**
117- Handler methods are called on UI thread by default
118- If accessing from background thread, use `platformView.Post(() => { })`
119 
120## Quick Reference
121 
122| Issue | Solution |
123|-------|----------|
124| View ambiguous reference | Add `using AView = Android.Views.View;` |
125| Color ambiguous reference | Add `using AColor = Android.Graphics.Color;` |
126| Listener not working | Check lifecycle (register/unregister) |
127| Memory leak | Ensure Dispose() called on Java.Lang.Object |
128| Threading error | Use `platformView.Post()` for UI thread |
129| Gradle 401 / Maven dependency failure | Run `./eng/ingest-maven-deps.sh` — see `copilot-instructions.md` |
130 
131## Gradle / Maven Dependency Failures
132 
133CI uses CFSClean which blocks Maven Central. All deps go through the `dotnet-public-maven` Azure Artifacts feed. If a new package hasn't been ingested, CI fails with `XAGRDL0000` / 401. Run `./eng/ingest-maven-deps.sh` locally to fix. Do NOT upgrade Gradle past 8.x (`dotnet/android#10738`).
134