docs: clarify global.json search logic for muxer vs MSBuild SDK resolver

[Copilot]

The global.json article described only the muxer's search behavior, omitting the distinct logic used by the MSBuild project SDK resolver—leading to confusion about how global.json is located during builds.

Changes

• docs/core/tools/global-json.md — Replaces the single-sentence description with a two-bullet breakdown:
  • Muxer (dotnet CLI): searches up from the current working directory
  • MSBuild project SDK resolver (build-time): searches up from the solution directory → project file directory → current working directory (fallback)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Incomplete information about global.json search logic</issue_title>
<issue_description>### Type of issue

Missing information

Description

The doc says:

The .NET SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

But the source in the SDK suggests the logic is:

• If there is a solution file, use its directory, otherwise
• if there is a project file, use its directory, otherwise
• use the current working directory

The logic is here: https://github.com/dotnet/sdk/blob/6a4e43d7322bf0f96e4a766a3bec2e3b9e8b67ad/src/Resolvers/Microsoft.DotNet.MSBuildSdkResolver/MSBuildSdkResolver.cs#L422C52-L422C68

Pinging @jeffkl as an author in this area.

Page URL

https://learn.microsoft.com/en-us/dotnet/core/tools/global-json

Content source URL

https://github.com/dotnet/docs/blob/main/docs/core/tools/global-json.md

Document Version Independent Id

6d80613f-42dc-35d7-aeff-3187a36dbbca

Platform Id

8e1f5348-e2c6-2d5e-9531-202d840f33ca

Article author

@meaghanlewis

Metadata

• ID: a94c335b-0b65-96cc-1c25-65777fbe4bb5
• PlatformId: 8e1f5348-e2c6-2d5e-9531-202d840f33ca
• Service: dotnet-fundamentals

Related Issues

---

Associated WorkItem - 556417</issue_description>

Comments on the Issue (you are @copilot in this section)

@jeffkl The NuGet-based MSBuild project SDK resolver has the same logic as the .NET MSBuild project SDK resolver:

https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/Microsoft.Build.NuGetSdkResolver/GlobalJsonReader.cs#L104-L122

That said, I think that section of the docs is how the muxer finds global.json, which knows nothing about the current project or solution. It only knows about the current directory.

@meaghanlewis @jeffkl thanks for your input. So, are you saying the sentence in the doc is fine as-is?

The .NET SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.</comment_new>
<comment_new>@jeffkl
@meaghanlewis yes, in my opinion

The .NET SDK = the SDK itself, including the muxer
The .NET MSBuild project SDK resolver = The MSBuild project SDK resolver that ships in the .NET SDK

So to say

The .NET SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

Sounds correct

And then to say

The .NET MSBuild project SDK resolver looks for a global.json file in the folder containing a solution if available, then next to the current project if available, otherwise the working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

I think the confusion is that the SDK and the SDK resolver are both in the SDK, but the docs mentioned are really just referring to the SDK itself, not the SDK resolver.

Clear as mud.</comment_new>
<comment_new>@meaghanlewis
Okay, great. Thanks for providing the extra clarity @jeffkl!

@drewnoakes I'm going to go ahead and close this issue then. </comment_new>
<comment_new>@drewnoakes
Sounded to me like @jeffkl was proposing adding some more context to the article.</comment_new>
<comment_new>@meaghanlewis
@drewnoakes, sorry if I misunderstood. It never hurts to add more context to the article.

Is this something you'd be up to add?</comment_new>
<comment_new>@drewnoakes
Sure. I think we can also mention how it is treated by VS. Will try and get to it this week.</comment_new>

• Fixes Incomplete information about global.json search logic #50073

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/tools/global-json.md	docs/core/tools/global-json