From 09b467e6df4d063faebdc03a6d146e3079419d73 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 23:22:24 +0000 Subject: [PATCH 1/7] Initial plan From d897dc97c991c139750600ebe9cc7b965c50552c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 23:29:58 +0000 Subject: [PATCH 2/7] Add breaking change documentation for dotnet.acquire API Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../10.0/vscode-dotnet-acquire-no-latest.md | 73 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 76 insertions(+) create mode 100644 docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 2d92b51f5a69a..66fbfe0ab7f14 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -77,6 +77,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|---------------------|--------------------| | [BackgroundService runs all of ExecuteAsync as a Task](extensions/10.0/backgroundservice-executeasync-task.md) | Behavioral change | Preview 1 | +| [dotnet.acquire API for VS Code no longer always downloads latest](extensions/10.0/vscode-dotnet-acquire-no-latest.md) | Behavioral change | .NET Install Tool 3.0.0 | | [Null values preserved in configuration](extensions/10.0/configuration-null-values-preserved.md) | Behavioral change | Preview 7 | | [Message no longer duplicated in Console log output](extensions/10.0/console-json-logging-duplicate-messages.md) | Behavioral change | Preview 7 | | [ProviderAliasAttribute moved to Microsoft.Extensions.Logging.Abstractions assembly](extensions/10.0/provideraliasattribute-moved-assembly.md) | Source incompatible | Preview 4 | diff --git a/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md b/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md new file mode 100644 index 0000000000000..5845a34c37931 --- /dev/null +++ b/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md @@ -0,0 +1,73 @@ +--- +title: "Breaking change: dotnet.acquire API for VS Code no longer always downloads latest" +description: "Learn about the breaking change in .NET 10 where the dotnet.acquire VS Code API no longer always checks for the latest runtime version before returning a path." +ms.date: 11/04/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/vscode-dotnet-runtime/issues/2359 +--- + +# dotnet.acquire API for VS Code no longer always downloads latest + +The .NET Install Tool Extension for VS Code provides the `dotnet.acquire` command to install a .NET runtime for VS Code extensions. Starting in version 3.0.0 of the .NET Install Tool, calling `dotnet.acquire` no longer always checks for the latest runtime version. Instead, it uses existing runtime installations and checks daily for newer versions after a configurable delay. + +## Version introduced + +.NET Install Tool 3.0.0 + +## Previous behavior + +Up until version 3.0.0 of the .NET Install Tool (or pre-release version 2.4.1), calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the user was online and did not specify any settings to do otherwise. If that latest runtime was not available on the machine, it would be installed, and the path to it would be returned. + +This runtime is used for C# Dev Kit, C#, and other VS Code extensions to run internal C# code and processes, such as the language server host. + +## New behavior + +Starting in .NET Install Tool 3.0.0, `dotnet.acquire` no longer always checks for a newer runtime version before returning the path to a runtime that matches the `major.minor`. Instead, the tool: + +1. Uses existing runtime installations it made. +1. Checks daily for a new runtime after `runtimeUpdateDelaySeconds` (defaults to 5 minutes). This is a setting that can be changed in the VS Code Extension Settings. +1. After the delay, checks for newer runtime versions and installs the new runtime if needed. +1. After installation, automatically uninstalls all remaining .NET runtimes that are not 'in-use' and are not the latest patch for a specific `major.minor`, `architecture`, and `mode` (`runtime` vs `aspnetcore` runtime) combination. + +'In-use' means that the executable path to that .NET runtime install was: + +- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or otherwise that has a currently live, running process. This includes but is not limited to: `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. +- Part of the PATH or DOTNET_ROOT environment variable in which VS Code is operating within. + +Additionally, the `dotnet.uninstall` command no longer allows uninstalling an install that is 'in-use'. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change speeds up the developer loop by deferring the network call and installation time away from the launch of extensions that utilize .NET. For users in the worst 3% of networks who did not have their own .NET runtime that matched the requirements of any extension's .NET version, the download time alone created a 9-36 second delay at startup. For the median user, this represented a 287 ms delay. + +## Recommended action + +Developers who rely on `dotnet.acquire` and want to enforce that a new runtime is used every single time should consider using `forceUpdate: true` in their call to `dotnet.acquire`. We generally recommend against this unless a runtime security patch, feature, or bug is dramatic enough to warrant downloading the latest runtime. + +Example: + +```javascript +const dotnetRuntimePath = (await vscode.commands.executeCommand( + 'dotnet.acquire', + { version: '9.0', requestingExtensionId, forceUpdate: true } +)).dotnetPath; +``` + +Developers who rely on the .NET Install Tool should make sure that they don't cache or reuse any path from the .NET Install Tool without calling `dotnet.availableInstalls` again to demonstrate that they are using the installation in a given session if it's not in the PATH. + +Developers should continue to use `dotnet.uninstall` as they previously did to decrement the reference counts of the installs they own. However, this is less vital since uninstallation happens when the older version is replaced with the newer version. + +Customers should avoid relying on hard-coded private runtime installations managed by the .NET Install Tool as that is not the intended purpose of these runtimes. If they must, they should set the PATH or DOTNET_ROOT for their VS Code instances such that the install does not get automatically cleaned up. + +## Affected APIs + +None. + +## See also + +- [.NET Install Tool for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscode-dotnet-runtime) +- [.NET Install Tool commands documentation](https://github.com/dotnet/vscode-dotnet-runtime/blob/main/Documentation/commands.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index ec9c94695b2f9..e2b50bbd4607a 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -88,6 +88,8 @@ items: items: - name: BackgroundService runs all of ExecuteAsync as a Task href: extensions/10.0/backgroundservice-executeasync-task.md + - name: dotnet.acquire API for VS Code no longer always downloads latest + href: extensions/10.0/vscode-dotnet-acquire-no-latest.md - name: Message no longer duplicated in Console log output href: extensions/10.0/console-json-logging-duplicate-messages.md - name: Null values preserved in configuration From 6783e1defab3efeeeb02f6a3b39943f3a987bfc1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 23:31:43 +0000 Subject: [PATCH 3/7] Fix writing style issues in breaking change doc Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- .../extensions/10.0/vscode-dotnet-acquire-no-latest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md b/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md index 5845a34c37931..6f31b65e5306f 100644 --- a/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md +++ b/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md @@ -31,7 +31,7 @@ Starting in .NET Install Tool 3.0.0, `dotnet.acquire` no longer always checks fo 'In-use' means that the executable path to that .NET runtime install was: -- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or otherwise that has a currently live, running process. This includes but is not limited to: `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. +- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or otherwise that has a currently live, running process. Commands include `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. - Part of the PATH or DOTNET_ROOT environment variable in which VS Code is operating within. Additionally, the `dotnet.uninstall` command no longer allows uninstalling an install that is 'in-use'. @@ -46,7 +46,7 @@ This change speeds up the developer loop by deferring the network call and insta ## Recommended action -Developers who rely on `dotnet.acquire` and want to enforce that a new runtime is used every single time should consider using `forceUpdate: true` in their call to `dotnet.acquire`. We generally recommend against this unless a runtime security patch, feature, or bug is dramatic enough to warrant downloading the latest runtime. +Developers who rely on `dotnet.acquire` and want to enforce that a new runtime is used every single time should use `forceUpdate: true` in their call to `dotnet.acquire`. This is generally not recommended unless a runtime security patch, feature, or bug is dramatic enough to warrant downloading the latest runtime. Example: From b47e8c1b9ecc422666339fe81d146d17d5566e83 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 4 Nov 2025 17:34:28 -0800 Subject: [PATCH 4/7] human edits --- docs/core/compatibility/10.0.md | 7 +- .../10.0/vscode-dotnet-acquire-no-latest.md | 73 ------------------- .../3.0.0/vscode-dotnet-acquire-no-latest.md | 73 +++++++++++++++++++ docs/core/compatibility/toc.yml | 6 +- 4 files changed, 83 insertions(+), 76 deletions(-) delete mode 100644 docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md create mode 100644 docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 66fbfe0ab7f14..ceccaba271156 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -77,7 +77,6 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|---------------------|--------------------| | [BackgroundService runs all of ExecuteAsync as a Task](extensions/10.0/backgroundservice-executeasync-task.md) | Behavioral change | Preview 1 | -| [dotnet.acquire API for VS Code no longer always downloads latest](extensions/10.0/vscode-dotnet-acquire-no-latest.md) | Behavioral change | .NET Install Tool 3.0.0 | | [Null values preserved in configuration](extensions/10.0/configuration-null-values-preserved.md) | Behavioral change | Preview 7 | | [Message no longer duplicated in Console log output](extensions/10.0/console-json-logging-duplicate-messages.md) | Behavioral change | Preview 7 | | [ProviderAliasAttribute moved to Microsoft.Extensions.Logging.Abstractions assembly](extensions/10.0/provideraliasattribute-moved-assembly.md) | Source incompatible | Preview 4 | @@ -89,6 +88,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af |-------|-------------------|--------------------| | [Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE](globalization/10.0/version-override.md) | Behavioral change | Preview 1 | +## Install tool + +| Title | Type of change | Introduced version | +|-------|-------------------|--------------------| +| [dotnet.acquire API for VS Code no longer always downloads latest](install-tool/10.0/vscode-dotnet-acquire-no-latest.md) | Behavioral change | .NET Install Tool 3.0.0 | + ## Interop | Title | Type of change | Introduced version | diff --git a/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md b/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md deleted file mode 100644 index 6f31b65e5306f..0000000000000 --- a/docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Breaking change: dotnet.acquire API for VS Code no longer always downloads latest" -description: "Learn about the breaking change in .NET 10 where the dotnet.acquire VS Code API no longer always checks for the latest runtime version before returning a path." -ms.date: 11/04/2025 -ai-usage: ai-assisted -ms.custom: https://github.com/dotnet/vscode-dotnet-runtime/issues/2359 ---- - -# dotnet.acquire API for VS Code no longer always downloads latest - -The .NET Install Tool Extension for VS Code provides the `dotnet.acquire` command to install a .NET runtime for VS Code extensions. Starting in version 3.0.0 of the .NET Install Tool, calling `dotnet.acquire` no longer always checks for the latest runtime version. Instead, it uses existing runtime installations and checks daily for newer versions after a configurable delay. - -## Version introduced - -.NET Install Tool 3.0.0 - -## Previous behavior - -Up until version 3.0.0 of the .NET Install Tool (or pre-release version 2.4.1), calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the user was online and did not specify any settings to do otherwise. If that latest runtime was not available on the machine, it would be installed, and the path to it would be returned. - -This runtime is used for C# Dev Kit, C#, and other VS Code extensions to run internal C# code and processes, such as the language server host. - -## New behavior - -Starting in .NET Install Tool 3.0.0, `dotnet.acquire` no longer always checks for a newer runtime version before returning the path to a runtime that matches the `major.minor`. Instead, the tool: - -1. Uses existing runtime installations it made. -1. Checks daily for a new runtime after `runtimeUpdateDelaySeconds` (defaults to 5 minutes). This is a setting that can be changed in the VS Code Extension Settings. -1. After the delay, checks for newer runtime versions and installs the new runtime if needed. -1. After installation, automatically uninstalls all remaining .NET runtimes that are not 'in-use' and are not the latest patch for a specific `major.minor`, `architecture`, and `mode` (`runtime` vs `aspnetcore` runtime) combination. - -'In-use' means that the executable path to that .NET runtime install was: - -- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or otherwise that has a currently live, running process. Commands include `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. -- Part of the PATH or DOTNET_ROOT environment variable in which VS Code is operating within. - -Additionally, the `dotnet.uninstall` command no longer allows uninstalling an install that is 'in-use'. - -## Type of breaking change - -This change is a [behavioral change](../../categories.md#behavioral-change). - -## Reason for change - -This change speeds up the developer loop by deferring the network call and installation time away from the launch of extensions that utilize .NET. For users in the worst 3% of networks who did not have their own .NET runtime that matched the requirements of any extension's .NET version, the download time alone created a 9-36 second delay at startup. For the median user, this represented a 287 ms delay. - -## Recommended action - -Developers who rely on `dotnet.acquire` and want to enforce that a new runtime is used every single time should use `forceUpdate: true` in their call to `dotnet.acquire`. This is generally not recommended unless a runtime security patch, feature, or bug is dramatic enough to warrant downloading the latest runtime. - -Example: - -```javascript -const dotnetRuntimePath = (await vscode.commands.executeCommand( - 'dotnet.acquire', - { version: '9.0', requestingExtensionId, forceUpdate: true } -)).dotnetPath; -``` - -Developers who rely on the .NET Install Tool should make sure that they don't cache or reuse any path from the .NET Install Tool without calling `dotnet.availableInstalls` again to demonstrate that they are using the installation in a given session if it's not in the PATH. - -Developers should continue to use `dotnet.uninstall` as they previously did to decrement the reference counts of the installs they own. However, this is less vital since uninstallation happens when the older version is replaced with the newer version. - -Customers should avoid relying on hard-coded private runtime installations managed by the .NET Install Tool as that is not the intended purpose of these runtimes. If they must, they should set the PATH or DOTNET_ROOT for their VS Code instances such that the install does not get automatically cleaned up. - -## Affected APIs - -None. - -## See also - -- [.NET Install Tool for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscode-dotnet-runtime) -- [.NET Install Tool commands documentation](https://github.com/dotnet/vscode-dotnet-runtime/blob/main/Documentation/commands.md) diff --git a/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md b/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md new file mode 100644 index 0000000000000..f9c4c660ddf55 --- /dev/null +++ b/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md @@ -0,0 +1,73 @@ +--- +title: "Breaking change: dotnet.acquire API for VS Code no longer always downloads latest" +description: "Learn about the breaking change where the dotnet.acquire VS Code API no longer always checks for the latest runtime version before returning a path." +ms.date: 11/04/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/49127 +--- + +# dotnet.acquire API for VS Code no longer always downloads latest + +The .NET Install Tool Extension for VS Code provides the `dotnet.acquire` command to install a .NET runtime for VS Code extensions. Starting in version 3.0.0 of the .NET Install Tool, calling `dotnet.acquire` no longer always checks for the latest runtime version. Instead, it uses existing runtime installations and checks daily for newer versions after a configurable delay. + +## Version introduced + +.NET Install Tool 3.0.0 + +## Previous behavior + +Up until version 3.0.0 of the .NET Install Tool (or prerelease version 2.4.1), calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the user was online and did not specify any settings to do otherwise. If that latest runtime wasn't available on the machine, it was installed, and the path to it was returned. + +This runtime is used for C# Dev Kit, C#, and other VS Code extensions to run internal C# code and processes, such as the language server host. + +## New behavior + +Starting with .NET Install Tool 3.0.0, `dotnet.acquire` no longer always checks for a newer runtime version before returning the path to a runtime that matches the `major.minor`. Instead, the tool: + +1. Uses existing runtime installations it made. +1. Checks daily for a new runtime after `runtimeUpdateDelaySeconds` (defaults to 5 minutes). This setting can be changed in the VS Code Extension Settings. +1. After the delay, checks for newer runtime versions and installs the new runtime if needed. +1. After installation, automatically uninstalls all remaining .NET runtimes that aren't *in-use* and aren't the latest patch for a specific `major.minor`, `architecture`, and `mode` (`runtime` or `aspnetcore` runtime) combination. + +*In-use* means that the executable path to that .NET runtime install was: + +- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or otherwise that has a currently live, running process. Commands include `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. +- Part of the `PATH` or `DOTNET_ROOT` environment variable in which VS Code is operating. + +Additionally, the `dotnet.uninstall` command no longer allows uninstalling an install that's *in-use*. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change speeds up the developer loop by deferring the network call and installation time away from the launch of extensions that utilize .NET. For users in the worst 3% of networks who didn't have their own .NET runtime that matched the requirements of any extension's .NET version, the download time alone created a 9-36 second delay at startup. For the median user, this represented a 287 ms delay. + +## Recommended action + +If you rely on `dotnet.acquire` and want to enforce that a new runtime is used every single time, use `forceUpdate: true` in your call to `dotnet.acquire`. This is generally not recommended unless a runtime security patch, feature, or bug is dramatic enough to warrant downloading the latest runtime. + +Example: + +```javascript +const dotnetRuntimePath = (await vscode.commands.executeCommand( + 'dotnet.acquire', + { version: '9.0', requestingExtensionId, forceUpdate: true } +)).dotnetPath; +``` + +Make sure you don't cache or reuse any path from the .NET Install Tool without calling `dotnet.availableInstalls` again (to demonstrate that you're using the installation in a given session) if it's not in the `PATH`. + +Continue to use `dotnet.uninstall` as you did previously to decrement the reference counts of the installs you own. However, this is less vital since uninstallation happens when the older version is replaced with the newer version. + +Avoid relying on hard-coded private runtime installations managed by the .NET Install Tool as that isn't the intended purpose of these runtimes. If you must, set the `PATH` or `DOTNET_ROOT` for your VS Code instances such that the install doesn't get cleaned up automatically. + +## Affected APIs + +None. + +## See also + +- [.NET Install Tool for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscode-dotnet-runtime) +- [.NET Install Tool commands documentation](https://github.com/dotnet/vscode-dotnet-runtime/blob/main/Documentation/commands.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index e2b50bbd4607a..f9e95aeaa6d79 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -88,8 +88,6 @@ items: items: - name: BackgroundService runs all of ExecuteAsync as a Task href: extensions/10.0/backgroundservice-executeasync-task.md - - name: dotnet.acquire API for VS Code no longer always downloads latest - href: extensions/10.0/vscode-dotnet-acquire-no-latest.md - name: Message no longer duplicated in Console log output href: extensions/10.0/console-json-logging-duplicate-messages.md - name: Null values preserved in configuration @@ -102,6 +100,10 @@ items: items: - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE href: globalization/10.0/version-override.md + - name: Install tool + items: + - name: dotnet.acquire API for VS Code no longer always downloads latest + href: install-tool/10.0/vscode-dotnet-acquire-no-latest.md - name: Interop items: - name: Single-file apps no longer look for native libraries in executable directory From 320f0d1f0eaf35799a195025fbe7ce9d5cb50965 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 4 Nov 2025 17:37:30 -0800 Subject: [PATCH 5/7] fix links --- docs/core/compatibility/10.0.md | 2 +- docs/core/compatibility/toc.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index ceccaba271156..74dc1e753cd7c 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -92,7 +92,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| -| [dotnet.acquire API for VS Code no longer always downloads latest](install-tool/10.0/vscode-dotnet-acquire-no-latest.md) | Behavioral change | .NET Install Tool 3.0.0 | +| [dotnet.acquire API for VS Code no longer always downloads latest](install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md) | Behavioral change | .NET Install Tool 3.0.0 | ## Interop diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index f9e95aeaa6d79..4a8275fc15e8d 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -103,7 +103,7 @@ items: - name: Install tool items: - name: dotnet.acquire API for VS Code no longer always downloads latest - href: install-tool/10.0/vscode-dotnet-acquire-no-latest.md + href: install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md - name: Interop items: - name: Single-file apps no longer look for native libraries in executable directory From 145d3139af11740c2faf9a06fd597640f47c0027 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 4 Nov 2025 18:07:47 -0800 Subject: [PATCH 6/7] more edits --- .../3.0.0/vscode-dotnet-acquire-no-latest.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md b/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md index f9c4c660ddf55..a423b8e09883a 100644 --- a/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md +++ b/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md @@ -16,25 +16,22 @@ The .NET Install Tool Extension for VS Code provides the `dotnet.acquire` comman ## Previous behavior -Up until version 3.0.0 of the .NET Install Tool (or prerelease version 2.4.1), calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the user was online and did not specify any settings to do otherwise. If that latest runtime wasn't available on the machine, it was installed, and the path to it was returned. +Up until version 3.0.0 of the .NET Install Tool, or prerelease version 2.4.1, calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the user was online and did not specify any settings to do otherwise. If that latest runtime wasn't available on the machine, it was installed, and the path to it was returned. -This runtime is used for C# Dev Kit, C#, and other VS Code extensions to run internal C# code and processes, such as the language server host. +This runtime is used for [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit), C#, and other VS Code extensions, both first and third party, to run internal C# code and processes, such as the language server host. This runtime is generally not used to run user projects, and is a private, user-folder copy on disk. It can be the runtime or aspnetcore runtime. -## New behavior +A similar command, `dotnet.uninstall` exists. Previously, that command uninstalled any .NET runtime or SDK that an extension had requested if no other extensions depended upon that installation. An extension depended on the installation if the extension had requested that version of .NET in the past. A reference count-based mechanism allowed uninstallation when no further dependent extensions of an install remained. -Starting with .NET Install Tool 3.0.0, `dotnet.acquire` no longer always checks for a newer runtime version before returning the path to a runtime that matches the `major.minor`. Instead, the tool: +## New behavior -1. Uses existing runtime installations it made. -1. Checks daily for a new runtime after `runtimeUpdateDelaySeconds` (defaults to 5 minutes). This setting can be changed in the VS Code Extension Settings. -1. After the delay, checks for newer runtime versions and installs the new runtime if needed. -1. After installation, automatically uninstalls all remaining .NET runtimes that aren't *in-use* and aren't the latest patch for a specific `major.minor`, `architecture`, and `mode` (`runtime` or `aspnetcore` runtime) combination. +Starting with version 3.0.0 of the .NET Install Tool, `dotnet.acquire` no longer always checks for a newer runtime version before returning the path to a runtime that matches the `major.minor`. Instead, it uses existing runtime installations it's made and checks daily for a new runtime after `runtimeUpdateDelaySeconds`. The delay setting defaults to 5 minutes and can be changed in the VS Code Extension Settings. After this time, the prior check commences for newer runtime versions, and the new runtime is installed if needed. After this, all remaining .NET runtimes that aren't *in-use* and aren't the latest patch for a specific `major.minor`, `architecture`, and `mode` (runtime or aspnetcore runtime) combo are uninstalled automatically. *In-use* means that the executable path to that .NET runtime install was: -- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or otherwise that has a currently live, running process. Commands include `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. +- Returned by a command through the .NET Install Tool in any session of VS Code, VS Code Insiders, or other VS Code variant that has a currently live, running process. This includes but isn't limited to: `dotnet.acquire`, `dotnet.acquireStatus`, `dotnet.availableInstalls`, and `dotnet.findPath`. - Part of the `PATH` or `DOTNET_ROOT` environment variable in which VS Code is operating. -Additionally, the `dotnet.uninstall` command no longer allows uninstalling an install that's *in-use*. +In addition, `dotnet.uninstall` doesn't uninstall if the install is considered to be *in-use*. This command already rejected uninstalls that were made while the `dotnet.exe` corresponding to that installation folder had a conflicting file handle that demonstrated it was running or in use. Whether it was in use was determined by trying to open the executable with `O_RDONLY` permissions or `FILE_FLAG_NO_BUFFERING` on windows, and by checking for `EBUSY`, `EACCESS`, or processes via `lsof` on Unix. ## Type of breaking change @@ -42,7 +39,7 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -This change speeds up the developer loop by deferring the network call and installation time away from the launch of extensions that utilize .NET. For users in the worst 3% of networks who didn't have their own .NET runtime that matched the requirements of any extension's .NET version, the download time alone created a 9-36 second delay at startup. For the median user, this represented a 287 ms delay. +This change improves performance and management of the .NET runtime. It speeds up the developer loop by deferring the network call and installation time away from the launch of extensions that utilize .NET. For users in the worst 3% of networks who didn't have their own .NET runtime that matched the requirements of any extension's .NET version, the download time alone created a 9-36 second delay at startup. For the median user, this represented a 287 ms delay. ## Recommended action From be568fa79b5c9bead5ecae9848bb27eb26bc615d Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 5 Nov 2025 09:58:25 -0800 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Noah Gilson --- .../install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md b/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md index a423b8e09883a..a6879c8d2e804 100644 --- a/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md +++ b/docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md @@ -16,11 +16,11 @@ The .NET Install Tool Extension for VS Code provides the `dotnet.acquire` comman ## Previous behavior -Up until version 3.0.0 of the .NET Install Tool, or prerelease version 2.4.1, calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the user was online and did not specify any settings to do otherwise. If that latest runtime wasn't available on the machine, it was installed, and the path to it was returned. +Up until version 3.0.0 of the .NET Install Tool, or prerelease version 2.4.1, calling `dotnet.acquire` always triggered a check to see what the latest runtime version was, given the VS Code client was online and didn't specify an existing path to `dotnet`. If that latest runtime wasn't available on the machine, it was installed, and the path to it was returned. -This runtime is used for [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit), C#, and other VS Code extensions, both first and third party, to run internal C# code and processes, such as the language server host. This runtime is generally not used to run user projects, and is a private, user-folder copy on disk. It can be the runtime or aspnetcore runtime. +This runtime is used by [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit), C#, and other VS Code extensions, both first and third party, to run internal .NET code and processes, such as the language server host. This runtime is generally not used to run user projects, and is a private, user-folder copy on disk. It can be the runtime or aspnetcore runtime. -A similar command, `dotnet.uninstall` exists. Previously, that command uninstalled any .NET runtime or SDK that an extension had requested if no other extensions depended upon that installation. An extension depended on the installation if the extension had requested that version of .NET in the past. A reference count-based mechanism allowed uninstallation when no further dependent extensions of an install remained. +A similar command, `dotnet.uninstall` exists. Previously, that command uninstalled any .NET runtime or SDK that an extension had requested, if no other extensions depended upon that installation, and decremented the reference count. An extension depended on the installation if the extension had requested that version of .NET in the past. A reference count-based mechanism allowed uninstallation when no further dependent extensions of an install remained. ## New behavior @@ -58,7 +58,7 @@ Make sure you don't cache or reuse any path from the .NET Install Tool without c Continue to use `dotnet.uninstall` as you did previously to decrement the reference counts of the installs you own. However, this is less vital since uninstallation happens when the older version is replaced with the newer version. -Avoid relying on hard-coded private runtime installations managed by the .NET Install Tool as that isn't the intended purpose of these runtimes. If you must, set the `PATH` or `DOTNET_ROOT` for your VS Code instances such that the install doesn't get cleaned up automatically. +Customers should avoid relying on hard-coded private runtime installations managed by the .NET Install Tool as that isn't the intended purpose of these runtimes. If you must, set the `PATH` or `DOTNET_ROOT` for your VS Code instances such that the install doesn't get cleaned up automatically. ## Affected APIs