|
| 1 | +--- |
| 2 | +name: .NET nanoFramework Agent |
| 3 | +description: Agent instructions for generating, reviewing, and modifying C# code for .NET nanoFramework samples on constrained embedded devices. |
| 4 | +tools: |
| 5 | + - search/codebase |
| 6 | + - search |
| 7 | + - web/fetch |
| 8 | + - web/githubRepo |
| 9 | + - read/readFile |
| 10 | + - search/fileSearch |
| 11 | + - search/textSearch |
| 12 | + - search/listDirectory |
| 13 | + - edit/createDirectory |
| 14 | + - edit/createFile |
| 15 | + - edit/editFiles |
| 16 | + - execute/runInTerminal |
| 17 | +--- |
| 18 | + |
| 19 | +# Copilot Instructions for .NET nanoFramework |
| 20 | + |
| 21 | +This repository targets **.NET nanoFramework**, which runs C# on constrained embedded devices (for example ESP32, STM32, and others). |
| 22 | + |
| 23 | +When generating, reviewing, or modifying code in this repo, follow these rules: |
| 24 | + |
| 25 | +## 1 - Validate API availability first |
| 26 | + |
| 27 | +- Do **not** assume an API exists just because it is available in desktop/main .NET. |
| 28 | +- Always verify availability in the nanoFramework API browser: |
| 29 | + - https://docs.nanoframework.net/api/index.html |
| 30 | +- If an API is not available, propose a nanoFramework-compatible alternative. |
| 31 | + |
| 32 | +## 2 - Prefer patterns already used in this repository |
| 33 | + |
| 34 | +- Use existing samples in this repo as the primary source for implementation patterns, coding style, and project structure. |
| 35 | +- Before introducing a new approach, check if an equivalent pattern already exists in: |
| 36 | + - https://github.com/nanoframework/samples |
| 37 | +- Keep solutions simple and aligned with embedded constraints (memory, CPU, storage, networking reliability). |
| 38 | + |
| 39 | +## 3 - Account for nanoFramework differences from main .NET |
| 40 | + |
| 41 | +- Assume APIs are simplified even when naming aligns with main .NET. |
| 42 | +- Avoid desktop-only features, heavy abstractions, reflection-heavy code, or dependencies that are unlikely to run on embedded targets. |
| 43 | +- Prefer deterministic, lightweight implementations suitable for microcontrollers. |
| 44 | +- Always consider the constraints of the target hardware when proposing solutions. |
| 45 | +- Generics, async patterns, and certain language features are not yet supported on nanoFramework. |
| 46 | + |
| 47 | +## 4 - Use device bindings when applicable |
| 48 | + |
| 49 | +- nanoFramework supports many IoT device bindings. |
| 50 | +- For hardware-specific code, check existing bindings and guidance first: |
| 51 | + - https://docs.nanoframework.net/devicesdetails/README.html |
| 52 | +- Reuse existing bindings and samples rather than creating custom low-level implementations when a supported binding exists. |
| 53 | + |
| 54 | +## 5 - Practical coding expectations |
| 55 | + |
| 56 | +- Keep allocations and background work minimal. |
| 57 | +- Be explicit about timeouts, retries, and error handling for I/O and networking. |
| 58 | +- Favor clear, maintainable code that can run reliably on constrained devices. |
| 59 | +- When in doubt, choose the simpler implementation. |
| 60 | + |
| 61 | +## 6 - If uncertain, state assumptions |
| 62 | + |
| 63 | +- Explicitly mention when a proposal depends on API availability or board-specific capabilities. |
| 64 | +- Add concise notes about what should be verified on target hardware. |
| 65 | + |
| 66 | +## 7 - Build and solution validation workflow |
| 67 | + |
| 68 | +- Always include a build step when changes affect code, project files, or package references. |
| 69 | +- Follow the nanoFramework VS Code extension build model: use `nuget restore` + `msbuild`. |
| 70 | +- Build scope selection: |
| 71 | + - If a matching `*.sln` exists for the changed sample, build the solution (preferred, same as extension workflow). |
| 72 | + - If no solution exists, build the target `*.nfproj` directly. |
| 73 | + - When targeting a project, use the project path and project system path defined/imported by the `.nfproj`. |
| 74 | +- Preferred command sequence (PowerShell): |
| 75 | + - `nuget restore <path-to-solution-or-project>` |
| 76 | + - `msbuild <path-to-solution-or-project> /p:platform="Any CPU" /p:Configuration=Release /verbosity:minimal` |
| 77 | +- If `msbuild` is not on `PATH`, resolve it first (for example with `vswhere` on Windows), then run the same restore/build steps. |
| 78 | +- Windows example to resolve `MSBuild.exe` with `vswhere` and build: |
| 79 | + - `$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` |
| 80 | + - `& $msbuild <path-to-solution-or-project> /p:platform="Any CPU" /p:Configuration=Release /verbosity:minimal` |
| 81 | +- If build fails: |
| 82 | + - Report the exact error output. |
| 83 | + - Propose a minimal fix. |
| 84 | + - Re-run the same `nuget restore` + `msbuild` sequence after the fix. |
| 85 | +- In final results, summarize: |
| 86 | + - Which solution/project was built. |
| 87 | + - Whether `nuget restore` + `msbuild` succeeded. |
| 88 | + - Any remaining manual hardware validation steps (deployment/flash/runtime checks). |
| 89 | + |
| 90 | +## 8 - Testing workflow for nanoFramework |
| 91 | + |
| 92 | +- Do not default to `dotnet test` for nanoFramework projects. |
| 93 | +- For unit tests, follow the nanoFramework Test Platform workflow (`nanoFramework.TestFramework`, `nanoFramework.UnitTestLauncher`, `nanoFramework.TestAdapter`). |
| 94 | +- Identify unit test projects by checking `.nfproj` metadata such as: |
| 95 | + - `<IsTestProject>true</IsTestProject>` |
| 96 | + - `<TestProjectType>UnitTest</TestProjectType>` |
| 97 | +- Ensure a `.runsettings` file exists (often `nano.runsettings`) and includes nanoFramework adapter settings. |
| 98 | +- Test discovery/execution flow: |
| 99 | + - Build first (`nuget restore` + `msbuild`) so tests are discovered. |
| 100 | + - Run tests through Visual Studio / Test Explorer (or equivalent VS test host integration). |
| 101 | + - For hardware execution, set `<IsRealHardware>True</IsRealHardware>` in `.runsettings`. |
| 102 | +- Pipeline/automation flow: |
| 103 | + - Use `vstest.Console.exe` with `nanoFramework.TestAdapter.dll`. |
| 104 | + - Keep test adapter and test framework package versions aligned. |
| 105 | +- When reporting test outcomes, include: |
| 106 | + - Which test project and runsettings file were used. |
| 107 | + - Whether tests ran on emulator/simulated mode or real hardware. |
| 108 | + - Pass/fail/skip summary and any device-specific constraints. |
0 commit comments