From 2d411234c176b5882c79971851c200cb17a8b92a Mon Sep 17 00:00:00 2001 From: Matt Kotsenas Date: Mon, 3 Feb 2025 15:14:14 -0800 Subject: [PATCH 1/2] Clarify that using global.json may not be rare Update the word choice for using global.json to select the SDK. The previous word choice made it sound like using a global.json wasn't recommended and reserved for "rare" situations. In practice, many teams want reproducible builds, and as such need to pin developers to a specific version. To address the concern that global.json can lead to pinning old versions of the SDK, I added a new section calling out that devs can use tools like `dotnet sdk check` and Dependabot to manage SDK updates. --- docs/core/versions/selection.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 810511defdfbf..5f94af46f40ca 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -31,7 +31,7 @@ SDK commands include `dotnet new` and `dotnet run`. The .NET CLI must choose an You can take advantage of the latest SDK features and improvements while targeting earlier .NET runtime versions. You can target different runtime versions of .NET using the same SDK tools. -On rare occasions, you may need to use an earlier version of the SDK. You specify that version in a [*global.json* file](../tools/global-json.md). The "use latest" policy means you only use *global.json* to specify a .NET SDK version earlier than the latest installed version. +In some circumstances, you may need to use a specific version of the SDK. You specify that version in a [*global.json* file](../tools/global-json.md). *global.json* can be placed anywhere in the file hierarchy. You control which projects a given *global.json* applies to by its place in the file system. The .NET CLI searches for a *global.json* file iteratively navigating the path upward from the current working directory (which isn't necessarily the same as the project directory). The first *global.json* file found specifies the version used. If that SDK version is installed, that version is used. If the SDK specified in the *global.json* isn't found, the .NET CLI uses [matching rules](../tools/global-json.md#matching-rules) to select a compatible SDK, or fails if none is found. @@ -53,6 +53,10 @@ The process for selecting an SDK version is: For more information about SDK version selection, see the [Matching rules](../tools/global-json.md#matching-rules) and [rollForward](../tools/global-json.md#rollforward) sections of the [global.json overview](../tools/global-json.md) article. +### Updating the SDK version + +It is important to update to the latest version of the SDK regularly to adopt the latest features, performance improvements, and bug fixes. To easily check for updates to the SDK, use the `dotnet sdk check` [command](../tools/dotnet-sdk-check.md). Additionally, if you specify a specific version using *global.json*, consider a tool such as Dependabot to automatically update pinned the SDK as new versions become available. + ## Target framework monikers define build time APIs You build your project against APIs defined in a **target framework moniker** (TFM). You specify the [target framework](../../standard/frameworks.md) in the project file. Set the `TargetFramework` element in your project file as shown in the following example: @@ -175,5 +179,7 @@ The `RuntimeFrameworkVersion` element overrides the default version policy. For ## See also +- [Dependabot supported ecosystems and repositories](https://docs.github.com/en/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories). - [Download and install .NET](../install/index.yml). +- [How to check that .NET is already installed](../install/how-to-detect-installed-versions.md). - [How to remove the .NET Runtime and SDK](../install/remove-runtime-sdk-versions.md). From 870cde916ac4685bfce85e8d6ce1a41e0754ad27 Mon Sep 17 00:00:00 2001 From: Matt Kotsenas Date: Tue, 4 Feb 2025 14:03:01 -0800 Subject: [PATCH 2/2] Fix grammar in update section Co-authored-by: Bill Wagner --- docs/core/versions/selection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 5f94af46f40ca..98a04662854e8 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -55,7 +55,7 @@ For more information about SDK version selection, see the [Matching rules](../to ### Updating the SDK version -It is important to update to the latest version of the SDK regularly to adopt the latest features, performance improvements, and bug fixes. To easily check for updates to the SDK, use the `dotnet sdk check` [command](../tools/dotnet-sdk-check.md). Additionally, if you specify a specific version using *global.json*, consider a tool such as Dependabot to automatically update pinned the SDK as new versions become available. +It is important to update to the latest version of the SDK regularly to adopt the latest features, performance improvements, and bug fixes. To easily check for updates to the SDK, use the `dotnet sdk check` [command](../tools/dotnet-sdk-check.md). Additionally, if you select a specific version using *global.json*, consider a tool such as Dependabot to automatically update the pinned SDK version as new versions become available. ## Target framework monikers define build time APIs