📘 Documentation for IrbyImaging/global.json.json


🗂 Table of Contents

  1. Overview & Purpose
  2. File Location & Naming
  3. Key Functional Areas
  4. Dependencies & Technologies
  5. SDK Version Resolution
  6. rollForward Policy Explained
  7. Usage Examples & Sample Code
  8. Common Roll‑forward Strategies
  9. Troubleshooting & FAQs
  10. View Models & Data Models
  11. Helper Methods & Utilities
  12. Error Handling & Return Types
  13. API Endpoints Overview
  14. Third‑party Integrations
  15. 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

  1. SDK Version Locking
    Guarantees that every developer uses the same .NET SDK version for build & test.
  2. Build Reproducibility
    Prevents “works on my machine” scenarios by aligning SDK behavior.
  3. Upgrade Flexibility
    The rollForward setting 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:

  1. Environment Variable: DOTNET_ROLL_FORWARD, if set
  2. global.json in the current or ancestor directory
  3. 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 rollForward to 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.json controls the CLI version; Directory.Build.props customizes 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 1 if it cannot satisfy the SDK requirement (depending on rollForward policy).
  • 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 on
  • rollForward: 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! 🎉