From c8ec964f8f8d1a9d27a7a9dc6208099a18ab4bcb Mon Sep 17 00:00:00 2001 From: Rui Marinho Date: Thu, 19 Mar 2026 17:33:47 +0000 Subject: [PATCH 1/3] Update copilot-instructions.md with learnings from recent PRs - Document external/xamarin-android-tools submodule in Architecture - Add AsyncTask guidance (base class, thread-safe logging) - Add error message localization requirement (Properties.Resources) - Add error code lifecycle guidance (no orphaned XA codes) - Add null-forgiving operator workarounds for test code - Clarify AsyncTask vs AndroidTask base class usage Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index dc057a1e03e..906ab863b91 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,6 +7,7 @@ - `src/Xamarin.Android.Build.Tasks/` - MSBuild tasks for Android apps - `src/native/` - Native runtime (MonoVM/CoreCLR/NativeAOT) - `external/Java.Interop/` - JNI bindings and Java-to-.NET interop +- `external/xamarin-android-tools/` - Shared SDK tooling: `AndroidTask`/`AsyncTask` base classes, `AdbRunner`, `EmulatorRunner`, NRT extensions (`IsNullOrEmpty()`, `IsNullOrWhiteSpace()`), `CreateTaskLogger`, and SDK info utilities - `tests/` - NUnit tests, integration tests, device tests **Build System:** MSBuild + .NET Arcade SDK + CMake (native) @@ -32,7 +33,7 @@ Reference official Android documentation where helpful: **Use Microsoft docs:** Search MS Learn before making .NET, Windows, or Microsoft features, APIs, or integrations. Use the `microsoft_docs_search` tool. -**MSBuild Tasks:** Extend `AndroidTask` base class, use `XA####` error codes, test in isolation. +**MSBuild Tasks:** Extend `AndroidTask` base class, use `XA####` error codes, test in isolation. Use `AsyncTask` for tasks that need `async`/`await` — it handles `Yield()`, `try`/`finally`, and `Reacquire()` automatically. **Internal build `` elements:** For `xa-prep-tasks` and `BootstrapTasks` (internal build-time tasks, not shipped to customers), always use `TaskFactory="TaskHostFactory"` and `Runtime="NET"` attributes on `` elements. This runs the task in a separate process to avoid Windows file locking issues and ensures the task runs on .NET (even when MSBuild.exe in Visual Studio uses .NET Framework). Example: @@ -57,6 +58,10 @@ When opting C# code into nullable reference types: * Don't *ever* use `!` (null-forgiving operator) to handle `null`! Always check for null explicitly and throw appropriate exceptions. +* **In test code**, avoid `!` too. Common workarounds: + - `[SetUp]`-initialized fields: declare as nullable (`MockBuildEngine? engine;`) instead of `MockBuildEngine engine = null!;` + - After `Assert.IsNotNull`: extract into a local variable (`var opts = task.Options; Assert.IsNotNull (opts); opts.Foo...`) instead of using `task.Options!.Foo` + * Declare variables non-nullable, and check for `null` at entry points. * Use `throw new ArgumentNullException (nameof (parameter))` in `netstandard2.0` projects. @@ -181,7 +186,9 @@ This pattern ensures proper encoding, timestamps, and file attributes are handle ## Error Patterns - **MSBuild Errors:** `XA####` (errors), `XA####` (warnings), `APT####` (Android tools) -- **Logging:** Use `Log.LogError`, `Log.LogWarning` with error codes and context +- **Error messages:** Must come from `Properties.Resources` (e.g., `Properties.Resources.XA0143`) for localization support. Add new messages to the English `Resources.resx` file. +- **Error code lifecycle:** When removing functionality that used an `XA####` code, either repurpose the code or remove it from `Resources.resx` and `Resources.Designer.cs`. Don't leave orphaned codes. +- **Logging in `AsyncTask`:** Use the thread-safe helpers (`LogCodedError()`, `LogMessage()`, `LogCodedWarning()`, `LogDebugMessage()`) instead of `Log.*`. The `Log` property is marked `[Obsolete]` on `AsyncTask` because calling `Log.LogMessage` directly from a background thread can hang Visual Studio. ## Troubleshooting - **Build:** Clean `bin/`+`obj/`, check Android SDK/NDK, `make clean` From 933bd43d492d3d8e3e4e87ff9070806b0214679e Mon Sep 17 00:00:00 2001 From: Rui Marinho Date: Thu, 19 Mar 2026 18:35:35 +0000 Subject: [PATCH 2/3] Add emulator black screen troubleshooting note Outdated emulator tools (pre-35.x) render a black screen on Apple Silicon Macs. Document the fix: update via sdkmanager. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 906ab863b91..3dddd62a576 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -195,3 +195,4 @@ This pattern ensures proper encoding, timestamps, and file attributes are handle - **MSBuild:** Test in isolation, validate inputs - **Device:** Use update directories for rapid Debug iteration - **Performance:** See `../Documentation/guides/profiling.md` and `../Documentation/guides/tracing.md` +- **Emulator black screen on macOS:** If the Android emulator launches but shows only a black screen, the emulator tools are likely outdated. Update via `sdkmanager --install "emulator"` or Android Studio SDK Manager. Versions older than ~35.x are known to render incorrectly on Apple Silicon Macs. From 8b049138490616e5a3572df4da529e68944ca160 Mon Sep 17 00:00:00 2001 From: Jonathan Peppers Date: Fri, 20 Mar 2026 08:31:23 -0500 Subject: [PATCH 3/3] AIs can't see if the emulator has a black screen --- .github/copilot-instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3dddd62a576..906ab863b91 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -195,4 +195,3 @@ This pattern ensures proper encoding, timestamps, and file attributes are handle - **MSBuild:** Test in isolation, validate inputs - **Device:** Use update directories for rapid Debug iteration - **Performance:** See `../Documentation/guides/profiling.md` and `../Documentation/guides/tracing.md` -- **Emulator black screen on macOS:** If the Android emulator launches but shows only a black screen, the emulator tools are likely outdated. Update via `sdkmanager --install "emulator"` or Android Studio SDK Manager. Versions older than ~35.x are known to render incorrectly on Apple Silicon Macs.