📘 Documentation for IrbyImaging/global.json.json
🗂 Table of Contents
- Overview & Purpose
- File Location & Naming
- Key Functional Areas
- Dependencies & Technologies
- SDK Version Resolution
- rollForward Policy Explained
- Usage Examples & Sample Code
- Common Roll‑forward Strategies
- Troubleshooting & FAQs
- View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- API Endpoints Overview
- Third‑party Integrations
- Conclusion
🔍 Overview & Purpose
The global.json file is a simple yet powerful configuration mechanism provided by the .NET CLI to control which SDK version your project or solution uses. By placing this JSON file in the root (or any ancestor folder) of your codebase, you ensure consistent builds across different environments and developers’ machines.
File Contents
{ "sdk": { "version": "6.0.302", "rollForward": "latestMajor" } }
version: Specifies the exact .NET SDK version (here, 6.0.302) that the CLI should use.rollForward: Defines how the CLI can pick a newer SDK if the specified version isn’t available.
🏠 File Location & Naming
| Aspect | Details |
|---|---|
| File Name | global.json (in this repo named global.json.json) |
| Default Location | Root folder of solution or project |
| Search Behavior | CLI walks up directory tree until a matching file is found |
| Priority | Local > Environment variable > Machine-wide default |
🚀 Key Functional Areas
- SDK Version Locking
Guarantees that every developer uses the same .NET SDK version for build & test. - Build Reproducibility
Prevents “works on my machine” scenarios by aligning SDK behavior. - Upgrade Flexibility
TherollForwardsetting lets you adopt newer, compatible SDKs automatically.
🛠 Dependencies & Technologies
- .NET CLI (dotnet) – Core command-line interface
- .NET SDK 6.0.302 – Target SDK version
- MSBuild – Underlying build engine that respects
global.json - JSON Schema – Standard JSON configuration format
⚙️ SDK Version Resolution
When you run a command like dotnet build or dotnet run, the CLI follows this resolution order:
- Environment Variable:
DOTNET_ROLL_FORWARD, if set global.jsonin the current or ancestor directory- Machine-Wide Default (latest installed SDK)
The CLI will attempt to load the exact SDK version specified. If not found, it uses the rollForward policy.
🔄 rollForward Policy Explained
| Value | Behavior |
|---|---|
patch |
Use the same major.minor but higher patch (e.g., 6.0.302 → 6.0.400). |
minor |
Use the same major but higher minor (e.g., 6.0.x → 6.1.x). |
major |
Use any higher major version (e.g., 6.x.x → 7.x.x). |
latestPatch |
Highest patch for the same major.minor (default behavior if patch not set). |
latestMinor |
Highest minor for the same major (if minor not set). |
latestMajor |
Highest installed major (this setting allows auto-upgrade to .NET 7, .NET 8, etc.) |
In our file:
"rollForward": "latestMajor"The CLI may pick .NET 7, 8, or newer if 6.0.302 is missing.
📝 Usage Examples & Sample Code
1. Basic Setup
Place global.json in your repo’s root:
/my-cool-app/
├── global.json
├── src/
│ └── MyCoolApp.csproj
└── tests/
└── MyCoolApp.Tests.csproj
Run:
dotnet --version
# ➜ 6.0.302 (or the latest major installed if not found)
2. Forcing a Specific SDK
{
"sdk": {
"version": "6.0.302",
"rollForward": "patch"
}
}
- Guarantees 6.0.x but only higher patches (6.0.303, 6.0.304…).
3. Pin to Minor Version
{
"sdk": {
"version": "6.1.100",
"rollForward": "minor"
}
}
- Accepts SDKs 6.1.x or higher minor under 6.x.x (e.g., 6.2.0).
📊 Common Roll‑forward Strategies
| Strategy | Use Case |
|---|---|
patch |
You want to stay within a specific minor release. |
minor |
You’re OK with new minor features in the same major. |
latestMajor |
Embrace the latest SDK with minimal config friction. |
disable |
Strict lock: fail if the exact version is missing. |
❓ Troubleshooting & FAQs
Q1. CLI Error: No SDKs were found that satisfy global.json requirements.
- Install the exact version:
dotnet-install-script.sh --version 6.0.302 - Or adjust
rollForwardto a compatible policy.
Q2. I want to force only the exact version.
- Set
"rollForward": "disable".
Q3. How does global.json interact with Directory.Build.props?
global.jsoncontrols the CLI version;Directory.Build.propscustomizes MSBuild properties.
📐 View Models & Data Models
Not Applicable
This configuration file does not define view models or domain data models.
🧰 Helper Methods & Utilities
Not Applicable
No helper methods; solely instructs the .NET CLI.
⚠️ Error Handling & Return Types
- The .NET CLI will exit with code
1if it cannot satisfy the SDK requirement (depending onrollForwardpolicy). - Build and restore errors bubble up through MSBuild as usual.
🔗 API Endpoints Overview
Not Applicable
This file does not expose web API endpoints.
🔌 Third‑party Integrations
- None – Purely a .NET CLI configuration mechanism.
🏁 Conclusion
The global.json file is your lightweight version manager for .NET projects. By specifying:
version: the SDK your team agrees onrollForward: the policy for future upgrades
you ensure reproducible builds, reduce “works on my machine” issues, and control how your codebase evolves with new .NET releases.
Keep this file at the root of your repository to lock in the ideal development environment for IrbyImaging (or any other .NET solution).
Happy coding with a stable .NET environment! 🎉