In .NET 10, The .NET Runtime, MSBuild, and SDK have worked towards a [gradual loosening][decoupling-epic] of the tight coupling between the IDE (both VS and VSCode) and the CLI/SDK that the user has selected. This work is leading to much greater flexibility at the build-layer for both users and build logic authors

* users can expect that when they explicitly manage SDKs, the CLI and IDE respect that explicit decision
* build logic authors now have the ability to only target modern .NET and actually have that work in the VS IDE

However, despite these build-time sucesses, key user experiences remain inconsistent. The _run-time_ experience of users that have customized their SDK/tool-chain selection is not consistently aware of these choices, and so cracks in our overall story around SDK management show.

This document will demonstrate examples of the experiences that work and do not work today, propose a solution, and document the expected toolchain resolution behavior that all tools should adhere to in order to allow users to bring their own SDK to a much greater degree than they have in the past.

### The Happy Path

Today, many .NET repos use bleeding-edge SDKs to build and test locally. They use the new [repo-local SDK] feature in .NET 10 preview 3 to inform the .NET muxer (`dotnet.exe` or `dotnet` depending on platform), via the `hostfxr` native component, that SDK resolution can be satisfied from both a repo-local directory as well as the location of the current muxer.

As a result, using repo-local SDK-level tooling Just Works when using the `dotnet` CLI.

Because this resolution was implemented in `hostfxr`, the .NET SDK's `MSBuildSdkResolver` component automatically inherited this new capability, and so preview builds of VS also look for and use repo-local SDKs for all SDK-resolvable Tasks/Targets when in the VS context. There are some components of the build that still come from the VS install, but there is a plan to reduce this coupling further over time. Functionally, `CTRL+B` in the IDE now uses local-SDK assets.

### Cracks in the sidewalk

Unfortunately, developers do more than just build their applications. Sometimes they would like to run, debug, or test them. We'll focus on testing for now, but the scenario will also hold for many other types of interactions in the IDE.

Until Microsoft Test Platform, most tests in VS and other environments are run by launching a bundled `testhost.exe` executable , which then is responsible for loading and executing the tests the user wanted to run. This `testhost.exe`component itself is a .NET Framework-dependent application. This means that it needs a .NET Runtime to execute on - and how should it find such a Runtime? It, like all other applications based on the .NET Apphost, uses our documented discovery algorithm: it tries to find a `hostfxr` and then ask it where the appropriate runtimes might be. The apphost searches for `hostfxr` in the following locations (taken from the [runtime docs][host-entry-points]):

> * The app's folder is searched first. This is either the folder where the entry-point host lives or in case of apphost it is the path it has embedded in it as the app path.
> * If the DOTNET_ROOT environment variable is defined, that path is searched
> * The default shared locations are searched

In our scenario today, this is the root (if you'll pardon the pun) of the problem - the apphosts for framework-dependent apps:

* do not have a `hostfxr` alongside them
* for 'global' .NET SDK installs (MSI/WinGet/pkg/Linux packages), DOTNET_ROOT is not typically set
* the 'default shared locations' mentioned point to the locations of 'global' .NET SDK installs, not the user-intended repo-local install

As a result, when `testhost.exe` is launched from VS, if you don't have a matching (e.g. at time of writing) 10.0.100 preview 7 runtime installed into your global install location, the dotnet/sdk repo tests simply will not launch from VS previews.

The dotnet/sdk repo (and many other dotnet-org repos) have a solution for this - they typically require devs to run an environment-setup script that sets required environment variables so that VS _can_ correctly invoke apphost-based executables. This requirement is the thing we should work to solve.

## Proposal

Much like the `MSBuildSdkResolver` is the centralized place for all MSBuild-based tooling to be told how to resolve/launch .NET SDK-based tooling, we need a component in each IDE we support that can supply the same kind of information to all tooling that needs to be able to correctly launch .NET framework-dependent applications.

This component should ideally be based on an extraction of the logic that already exists inside the MSBuildSdkResolver today, and it should implement the [spec defined below][resolution-spec].

This component _may_ be aided by an independent packaging/distribution of `hostfxr` + managed bindings to it. There are several partial bindings that exist in various projects (SDK, MSBuild Locator, a few community ones that I'm aware of) - we should just distribute the native binary and make it easier for people to make .NET and node bindings to it, so we can reuse the logic more easily in our core editor experiences.

This component _ideally_ would be able to make its changes without _requiring_ specific work from editor tooling developers. It would drastically increase the scope of work if every tool that could launch a .NET apphost in VS would need to do some work here.

## Alternative designs

The above requires each tooling layer to separately include and make use of a component to do the detection and resolution. An ideal solution would only require one component to update, and deliver the feature to all .NET tools. In that spirit, it _would_ be possible for the Framework-dependent AppHosts to learn how to check the presence of global.json for _runtime_ location. If this were done, then eventually all re-built .NET applications would be able to natively do this resolution.

## SDK and Toolchain resolution specification

A component that ensures uniform invocation of .NET SDK- and .NET Runtime-dependent components will
* discover the location of an ambiently-available `dotnet` muxer
* for `dotnet`-based tooling, this should be the path of the current process
* for non-`dotnet`-based tooling (.NET Framework, node), `PATH` should be probed for the first instance of `dotnet.exe` on Windows, `dotnet` on non-Windows platforms
* choose the location to search for global.json (if any)
* if the tooling is solution- or project-based, then the starting directory will be the directory containing the solution or project
* if the tooling is not solution- or project- based, then the currently-open workspace root (aka working directory) will be the starting directory
* use a copy of `hostfxr` to resolve the SDK/tooling to use based on the chosen `dotnet` muxer path and the discovered `global.json` search root
* this is effectively a call to `hostfxr_resolve_sdk2`
* if the SDK is resolved successfully from this call, the values of the following environment variables should be calculated:
* `DOTNET_ROOT`
* should always be two directories above the resolved SDK path
* e.g. `Path.GetDirectoryName(Path.GetDirectoryName(resolverResult.ResolvedSdkDirectory))`
* if this value is indistinguishable from the IDE/tooling's own resolved `dotnet` muxer, this value may be omitted
* components that wish to spawn .NET framework-dependent processes _must_ apply (implicitly or explicitly) the computed environment variables (if any) to their invocations before execution.

## Appendices

### A: Potential components to author as part of this

* hostfxr separate distributable
* needs to be separate-per-platform/RID
* .NET (+ Framework) managed binding to hostfxr
* Node managed binding to hostfxr
* .NET (+ Framework) library to implement the resolution logic in the doc spec
* Node library to implement the resolution logic in the doc spec
* VS IDE component to host the .NET library (and dependencies) and provide/inject/supply the resolved vars into other tooling/VS environment/etc
* VS Code IDE component to host the Node library (and dependencies) and provide/inject/supply the resolved vars into other tooling/VS Codeenvironment/etc

[decoupling-epic]: https://github.com/dotnet/msbuild/issues/11142
[repo-local SDK]: https://github.com/dotnet/designs/blob/main/accepted/2025/local-sdk-global-json.md
[host-entry-points]: https://github.com/dotnet/runtime/blob/43d7609b7028faac5f17bbd5de8cf9efa200121f/docs/design/features/host-components.md#entry-point-hosts
[resolution-spec]: #sdk-and-toolchain-resolution-specification