SDK-style deploy/debug: selected-device + checksum pre-check + pluggable engine-binding seam by danielmeza · Pull Request #929 · nanoframework/nf-Visual-Studio-extension

danielmeza · 2026-06-16T02:03:16Z

Description

Relax the deploy native-assembly pre-check to a checksum match, because the nativeMethodsChecksum is the native ABI fingerprint while the four-part native version is a cosmetic label; this mirrors the on-device resolver CLR_RT_TypeSystem::FindAssembly, which compares only major.minor.
Deploy to the device selected in Device Explorer (the same source the debug launcher resolves from) and make the launch PortName follow the chosen device, so deploy and debug agree on the target when more than one device is connected.
Introduce an INanoDebugEngineBinding seam with Ad7CorDebugEngineBinding (today's AD7/CorDebug engine, extracted without behaviour change) and a compiling ConcordEngineBinding stub, and refactor NanoDebuggerLaunchProvider to resolve the active binding, so a future engine can be swapped without touching the launch, deploy, or project-system layers.

Motivation and Context

Part of SDK-style MSBuild project system for .NET nanoFramework Home#1784 — the Visual Studio extension side of enabling debugging for SDK-style projects. The SDK changes are in a companion PRs Enable VS source debugging for SDK-style projects (full PDB + F5 wiring) + target v2 (NFMRK2) nanoFramework.NET.Sdk#2 and Migrate all samples to SDK-style projects Samples#464. This is one of several PRs for that effort, so it intentionally does not auto-close the tracking issue.

How Has This Been Tested?

Built VisualStudio.Extension-vs2022 in Debug with no compiler errors.
Verified end-to-end on physical hardware (ESP32_S3_OCTAL): deploy, F5, and source breakpoints work against the selected device. Demo: https://youtu.be/9qvXsgXCrjM

Types of changes

Improvement (non-breaking change that improves a feature, code or algorithm)
Bug fix (non-breaking change which fixes an issue with code or algorithm)
New feature (non-breaking change which adds functionality to code)
Breaking change (fix or feature that would cause existing functionality to change)
Config and build (change in the configuration and build system, has no impact on code or features)
Dependencies (update dependencies and changes associated, has no impact on code or features)
Unit Tests (add new Unit Test(s) or improved existing one(s), has no impact on code or features)
Documentation (changes or updates in the documentation, has no impact on code or features)

Checklist:

My code follows the code style of this project (only if there are changes in source code).
My changes require an update to the documentation (there are changes that require the docs website to be updated).
I have updated the documentation accordingly (the changes require an update on the docs in this repo).
I have read the CONTRIBUTING document.
I have tested everything locally and all new and existing tests passed (only if there are changes in source code).
I have added new tests to cover my changes.

…checksum-only Two fixes proven out in the SDK-style debugging POC, ported clean onto move-to-sdk (without the POC's [BP-DIAG] diagnostics or the larger INanoDebugEngineBinding device-selection refactor): DeployProvider - Deploy to deviceExplorer.SelectedDevice (the same source the debug launcher resolves from) instead of the global NanoDeviceCommService.Device, so deploy and debug always agree on the target when more than one device is connected. SelectedDevice is already guaranteed non-null by the guard earlier in the method; the ?? fallback preserves prior single-device behavior. - Relax CheckNativeAssembliesAvailability to a checksum-only match. The nativeMethodsChecksum is the native ABI fingerprint (minor field bumps with the ABI, so the checksum moves with it); the 4-part native version is a cosmetic label. Matching the checksum alone means the ABI is identical and the assembly is deployable even when build/revision differ. Mirrors the on-device resolver CLR_RT_TypeSystem::FindAssembly, which compares only major.minor. Confirmed: device flashes and runs with this relaxation. NanoDebuggerLaunchProvider - PortName now follows deployDeviceName (the device chosen for this launch) rather than the global NanoDeviceCommService.Device, so the per-device Run-dropdown selector targets the chosen device. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Per the migration plan, decouple *which Visual Studio debugger API* drives a session from *how nanoFramework launches and talks to the device*, so a future engine can be swapped in without touching the launch/deploy/project-system layers above it or the nf-debugger wire-protocol client below it. - INanoDebugEngineBinding: the seam. Exposes EngineId, EngineGuid, PortSupplierGuid and CreateLaunchSettings(launchOptions, device, peFilesToLoad, project). The three concerns NanoDebuggerLaunchProvider used to hard-code (CorDebug.EngineGuid, DebugPortSupplier.PortSupplierGuid, CorDebugProcess) now live behind it. - Ad7CorDebugEngineBinding: today's implementation — a faithful extraction of the existing custom AD7 / CorDebug launch, no behavior change. PortName follows the device chosen for this launch (the per-device Run-dropdown selector needs it). - ConcordEngineBinding: compiling placeholder that proves the swap point and MEF wiring (exported alongside AD7, selectable by EngineId = "Concord"); members throw NotImplementedException until the engine is built. Modeled on the Concord Iris sample. - NanoDebuggerLaunchProvider: now an engine-agnostic orchestrator. [ImportMany]s the bindings, resolves the active one in ResolveEngineBinding() (defaults to AD7; NANOFRAMEWORK_DEBUG_ENGINE selects another), crawls the PE files to load via the shared ReferenceCrawler in CollectPeFilesToLoadAsync(), and delegates the engine-specific launch settings to the binding. This is the single point a future AD7 -> Concord swap flips. The PortName=selected-device fix from the previous commit now lives in Ad7CorDebugEngineBinding. Builds clean (VisualStudio.Extension-vs2022, Debug). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…th implemented status Move the full SDK-style project-system migration plan from the standalone POC branch (poc/sdk-style-debugging) into this repo on move-to-sdk so it travels with the code it describes, and update it to match what's now implemented. Layout under docs/plans/sdk-style-projects/: - Design spec set (00-overview .. 10-tooling-specs), README index, the NanoMigrate converter, the home issue/chore bodies, and supporting analysis. - EXECUTION-PLAN.md promoted to the plan top level as the live tracker. - poc-findings/ holds the executed-POC evidence: RESULTS.md, DEBUGGING-LOG.md, DEVICE-RUN-DROPDOWN.md. Reconciled with reality (the enablers are no longer pending — they're commits): - EXECUTION-PLAN.md: A1-A4 (SDK) and B1-B3 + WS3 engine-binding seam (extension) marked done with their move-to-sdk commit SHAs; v2/NFMRK2 + DebugType=full "open questions" marked resolved; PR step called out as the remaining work. - README.md: added an "implemented & pushed" callout and listed EXECUTION-PLAN.md as the live tracker. Links fixed for the new home: relative findings links repointed to poc-findings/; the RESULTS.md reference to the standalone build-and-verify.sh repointed to a poc-branch permalink. The home issue/chore GitHub permalinks (pinned to b8c2ede) are intentionally preserved for copy-paste into nanoFramework/Home. All relative markdown links validated. The standalone POC harness (poc-sdk-style/ prototype SDK, samples, tools, build scripts) stays on poc/sdk-style-debugging — it's superseded by the real nanoFramework.Sdk repo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The POC branch is deleted (local + origin); only move-to-sdk remains. Its commit is preserved at tag poc-sdk-style-archive so the b8c2ede permalinks used by the public Home#1784 issue keep resolving. Repointed all plan references from the branch to the tag. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

coderabbitai · 2026-06-16T02:03:27Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: nanoframework/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 72cf79ea-cbbb-4456-916a-eb8b8fa0cc5c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

…upgrader Capture the org-wide pull-request template (nanoframework/.github) and the conventions for opening PRs (GitFlow base, issue links to Home, draft policy, slot-filling). The fleet upgrader (07 §7.7) must render every auto-created lib-* PR from this template rather than a bespoke body. Referenced from README + EXECUTION-PLAN PR strategy. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…tyle Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…tracker - 09-implementation-strategy.md Phase 1: add the Samples-update work item. - phase-1-execution.md (new): per-repo Phase 1 readiness, the samples conversion pilot (BlinkLed + Button built to NFMRK2 against the official SDK), the dev-local build harness, and remaining Phase 1 work. Linked from README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…erences The NanoMigrate converter now lives in the SDK repo (tools/NanoMigrate) where it belongs, not under the plan docs. Remove it from docs/plans/sdk-style-projects/NanoMigrate and repoint every reference (README, 07-library-migration, PR-INSTRUCTIONS, phase-1-execution, migration-rules, SKILL) to the SDK repo location; also fix the stale scripts/NanoMigrate paths to tools/NanoMigrate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…he Phase 1 tracker Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…+ test-first Add a dotnet nano migrate verb (05 §5.1/§5.3 + new §5.7) surfacing the NanoMigrate converter that ships in the SDK repo tools/NanoMigrate: idempotent + reentrant, --glob filtering, and a dry-run-a-directory-first-then-full workflow. Update 10-tooling-specs C6 (migrate verb) and C8 (converter location + dotnet nano migrate). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…grate.py mention The migration skill is now a proper text skill at nanoFramework.Sdk/skills/nanoframework-sdk-migration (binary .skill + nano-migrate.py removed). Update the plan README Tooling note and add a pointer at the top of the plan's SKILL.md to the canonical installable skill. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…xternal prebuilt tools) Design for the single dotnet nano CLI that ships with the SDK: a Spectre.Console.Cli host with built-in managed commands (migrate -> NanoMigrate.Core library, deploy/monitor/devices) and an IExternalTool model to deploy/wrap prebuilt external tools from other repos (e.g. nanoff), pinned via a tool manifest. Documents the engine-as-library + repo layout (NanoMigrate.Core/.Cli/.Tests) that the upcoming refactor + tests + NuGet packaging follow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ow-ups Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…dmap Record the three opened/cross-referenced draft PRs and the land order (SDK -> publish -> extension -> samples), and lay out the next steps per the impl plan (templates, VS Code dotnet build, CoreLibrary adoption, lib-* pilot exit gate, Phase 4 fleet) plus the gated items (samples v2 bump, nanoff download). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…osis Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…n PR text Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…jects under tools/

Point nano-tool.md, 07-library-migration.md, and the skill narrative at the as-built tools/nano/README.md and tools/migrate/README.md in the SDK repo as the source of truth, keeping the plan docs as design narrative.

…2026-06-16)

Add a C1-C11 + developer-loop coverage matrix to EXECUTION-PLAN.md so every doc 00-10 deliverable maps to done/tracked/missing, and capture the untracked items (C4 checksum gate, NanoDeploy task/target, dotnet watch, device selection, CI fast-fail, fleet CI rewriter, auto-PR renderer) as paste-ready nanoFramework/Home backlog stubs under epic Home#1784.

…them Filed the seven untracked docs-00-10 deliverables as child issues of epic Home#1784 (checksum gate, deploy task/target+verbs, watch, device selection, CI fast-fail, fleet CI rewriter, auto-PR renderer). Annotate the coverage matrix rows with their issue numbers, turn the backlog file into a filed-issue index, and list the children in the chore epic doc.

…s-reference File the larger spec deliverables and infrastructure that lacked a tracking issue: VS Code dotnet build switch, SDK repo CI/CD, dotnet new templates, the lib-* Phase 1 pilot, the fleet campaign, CoreLibrary adoption, the workload manifest, the nanoff downloader, and Samples v2 alignment. Annotate the coverage matrix (incl. a new CI/CD row), the deferred items, the backlog index, and the chore epic with their numbers.

josesimoes

We prefer atomic commits. This one is 4 parts! 😅
Please:

Move docs to https://github.com/nanoframework/nanoframework.github.io (add new folder docs/plans/sdk-style-projects)
Breaking change on checksum has to be evaluated/discussed and whatever comes out of it, will be on its own PR.
Extract the fix for the selected device handling on its own PR. OK to submit against main branch as this a general fix.
Leave this PR for engine-binding seam only.

danielmeza and others added 4 commits June 15, 2026 20:13

danielmeza and others added 2 commits June 15, 2026 21:08

docs: PR text is plain professional prose, never caveman/compressed s…

c2022c9

…tyle Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

nfbot added Type: enhancement Type: documentation labels Jun 16, 2026

danielmeza and others added 3 commits June 15, 2026 21:37

docs: record CPM, coexistence, and fleet-conversion test results in t…

6c9b08a

…he Phase 1 tracker Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

danielmeza mentioned this pull request Jun 16, 2026

Enable VS source debugging for SDK-style projects (full PDB + F5 wiring) + target v2 (NFMRK2) nanoframework/nanoFramework.NET.Sdk#2

Closed

14 tasks

danielmeza and others added 5 commits June 15, 2026 22:31

docs: note dotnet nano migrate is solution-aware (.sln/.slnx)

c428543

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: record samples migration complete + v1/v2 PE note + sample foll…

531850c

…ow-ups Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

danielmeza mentioned this pull request Jun 16, 2026

Migrate all samples to SDK-style projects nanoframework/Samples#463

Closed

14 tasks

danielmeza and others added 2 commits June 16, 2026 01:10

docs: record full build sweep (152/155) + AMQP pre-existing-rot diagn…

1a65a5d

…osis Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

danielmeza mentioned this pull request Jun 16, 2026

Migrate all samples to SDK-style projects nanoframework/Samples#464

Draft

14 tasks

danielmeza and others added 8 commits June 16, 2026 13:17

docs: PR rule — no AI/tool attribution (no 'Generated with Claude') i…

a7f0e3f

…n PR text Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: nano-tool layout — umbrella moved under tools/nano; all CLI pro…

2204daf

…jects under tools/

docs: update migrate tool path tools/NanoMigrate -> tools/migrate

4d6e51b

docs(nano-tool): grouping dir migrate/ (was NanoMigrate/)

f0749a1

docs: redirect tool plan docs to the shipped SDK-repo READMEs

c382bbf

Point nano-tool.md, 07-library-migration.md, and the skill narrative at the as-built tools/nano/README.md and tools/migrate/README.md in the SDK repo as the source of truth, keeping the plan docs as design narrative.

docs: execution plan — record tooling + samples-migration milestone (…

f9e01ee

…2026-06-16)

danielmeza marked this pull request as ready for review June 17, 2026 17:05

danielmeza mentioned this pull request Jun 23, 2026

Rework targets and props for SDK nanoframework/nanoFramework.NET.Sdk#3

Merged

14 tasks

josesimoes requested changes Jun 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

SDK-style deploy/debug: selected-device + checksum pre-check + pluggable engine-binding seam - #929

SDK-style deploy/debug: selected-device + checksum pre-check + pluggable engine-binding seam#929
danielmeza wants to merge 25 commits into
nanoframework:developfrom
danielmeza:move-to-sdk

danielmeza commented Jun 16, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 16, 2026 •

edited

Loading

Review skipped

Uh oh!

josesimoes left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

danielmeza commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

How Has This Been Tested?

Types of changes

Checklist:

Uh oh!

coderabbitai Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

josesimoes left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

danielmeza commented Jun 16, 2026 •

edited

Loading

coderabbitai Bot commented Jun 16, 2026 •

edited

Loading