From 6df38ced98a018be223b42e8213aa681086e1a4e Mon Sep 17 00:00:00 2001 From: Laurent Ellerbach Date: Mon, 2 Mar 2026 14:49:21 +0100 Subject: [PATCH 1/2] nanoFramework copilot agent mode instructions --- .github/agents/nanoframework.agent.md | 108 ++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 .github/agents/nanoframework.agent.md diff --git a/.github/agents/nanoframework.agent.md b/.github/agents/nanoframework.agent.md new file mode 100644 index 00000000..d2a555ad --- /dev/null +++ b/.github/agents/nanoframework.agent.md @@ -0,0 +1,108 @@ +--- +name: .NET nanoFramework Agent +description: Agent instructions for generating, reviewing, and modifying C# code for .NET nanoFramework samples on constrained embedded devices. +tools: + - search/codebase + - search + - web/fetch + - web/githubRepo + - read/readFile + - search/fileSearch + - search/textSearch + - search/listDirectory + - edit/createDirectory + - edit/createFile + - edit/editFiles + - execute/runInTerminal +--- + +# Copilot Instructions for .NET nanoFramework + +This repository targets **.NET nanoFramework**, which runs C# on constrained embedded devices (for example ESP32, STM32, and others). + +When generating, reviewing, or modifying code in this repo, follow these rules: + +## 1 - Validate API availability first + +- Do **not** assume an API exists just because it is available in desktop/main .NET. +- Always verify availability in the nanoFramework API browser: + - https://docs.nanoframework.net/api/index.html +- If an API is not available, propose a nanoFramework-compatible alternative. + +## 2 - Prefer patterns already used in this repository + +- Use existing samples in this repo as the primary source for implementation patterns, coding style, and project structure. +- Before introducing a new approach, check if an equivalent pattern already exists in: + - https://github.com/nanoframework/samples +- Keep solutions simple and aligned with embedded constraints (memory, CPU, storage, networking reliability). + +## 3 - Account for nanoFramework differences from main .NET + +- Assume APIs are simplified even when naming aligns with main .NET. +- Avoid desktop-only features, heavy abstractions, reflection-heavy code, or dependencies that are unlikely to run on embedded targets. +- Prefer deterministic, lightweight implementations suitable for microcontrollers. +- Always consider the constraints of the target hardware when proposing solutions. +- Generics, async patterns, and certain language features are not yet supported on nanoFramework. + +## 4 - Use device bindings when applicable + +- nanoFramework supports many IoT device bindings. +- For hardware-specific code, check existing bindings and guidance first: + - https://docs.nanoframework.net/devicesdetails/README.html +- Reuse existing bindings and samples rather than creating custom low-level implementations when a supported binding exists. + +## 5 - Practical coding expectations + +- Keep allocations and background work minimal. +- Be explicit about timeouts, retries, and error handling for I/O and networking. +- Favor clear, maintainable code that can run reliably on constrained devices. +- When in doubt, choose the simpler implementation. + +## 6 - If uncertain, state assumptions + +- Explicitly mention when a proposal depends on API availability or board-specific capabilities. +- Add concise notes about what should be verified on target hardware. + +## 7 - Build and solution validation workflow + +- Always include a build step when changes affect code, project files, or package references. +- Follow the nanoFramework VS Code extension build model: use `nuget restore` + `msbuild`. +- Build scope selection: + - If a matching `*.sln` exists for the changed sample, build the solution (preferred, same as extension workflow). + - If no solution exists, build the target `*.nfproj` directly. + - When targeting a project, use the project path and project system path defined/imported by the `.nfproj`. +- Preferred command sequence (PowerShell): + - `nuget restore ` + - `msbuild /p:platform="Any CPU" /p:Configuration=Release /verbosity:minimal` +- If `msbuild` is not on `PATH`, resolve it first (for example with `vswhere` on Windows), then run the same restore/build steps. +- Windows example to resolve `MSBuild.exe` with `vswhere` and build: + - `$msbuild = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -products * -latest -prerelease -requires Microsoft.Component.MSBuild -find "MSBuild\**\Bin\amd64\MSBuild.exe" | Select-Object -First 1` + - `& $msbuild /p:platform="Any CPU" /p:Configuration=Release /verbosity:minimal` +- If build fails: + - Report the exact error output. + - Propose a minimal fix. + - Re-run the same `nuget restore` + `msbuild` sequence after the fix. +- In final results, summarize: + - Which solution/project was built. + - Whether `nuget restore` + `msbuild` succeeded. + - Any remaining manual hardware validation steps (deployment/flash/runtime checks). + +## 8 - Testing workflow for nanoFramework + +- Do not default to `dotnet test` for nanoFramework projects. +- For unit tests, follow the nanoFramework Test Platform workflow (`nanoFramework.TestFramework`, `nanoFramework.UnitTestLauncher`, `nanoFramework.TestAdapter`). +- Identify unit test projects by checking `.nfproj` metadata such as: + - `true` + - `UnitTest` +- Ensure a `.runsettings` file exists (often `nano.runsettings`) and includes nanoFramework adapter settings. +- Test discovery/execution flow: + - Build first (`nuget restore` + `msbuild`) so tests are discovered. + - Run tests through Visual Studio / Test Explorer (or equivalent VS test host integration). + - For hardware execution, set `True` in `.runsettings`. +- Pipeline/automation flow: + - Use `vstest.Console.exe` with `nanoFramework.TestAdapter.dll`. + - Keep test adapter and test framework package versions aligned. +- When reporting test outcomes, include: + - Which test project and runsettings file were used. + - Whether tests ran on emulator/simulated mode or real hardware. + - Pass/fail/skip summary and any device-specific constraints. From bcbcf924db0dd3fb2782e9913a43e8e62aa5fca4 Mon Sep 17 00:00:00 2001 From: Laurent Ellerbach Date: Mon, 2 Mar 2026 14:51:40 +0100 Subject: [PATCH 2/2] adding entry in main readme --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index d047f45c..45939dca 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,12 @@ Feel free to browse, take what you like and contribute back if you want. If you are looking for Iot.Device samples, they are all in the [Iot.Device repository](https://github.com/nanoFramework/nanoFramework.IoT.Device). +## AI agent guidance + +If you're using GitHub Copilot custom agents in VS Code or Visual Studio, this repository includes a nanoFramework-specific agent definition with guidance for API compatibility checks, build workflow, and testing: + +- [nanoFramework custom agent](.github/agents/nanoframework.agent.md) + ## Sample by category Our samples uses 🌶️ to show how easy or complicated those samples are. The samples with 🌶️ are easy and recommended for beginners. The ones with 🌶️🌶️🌶️ are more advanced and requires some knowledge. This knowledge may not be on .NET nanoFramework but on some other elements like certificates or networking for example.