Document breaking change: dotnet.acquire API no longer always downloads latest

[Copilot]

The .NET Install Tool v3.0.0 changed dotnet.acquire behavior from always checking for latest runtime to using existing installations with periodic updates.

Changes

• New documentation: docs/core/compatibility/extensions/10.0/vscode-dotnet-acquire-no-latest.md
  • Documents behavioral change in dotnet.acquire and dotnet.uninstall APIs
  • Explains new periodic update mechanism (daily checks after configurable delay, default 5min)
  • Defines 'in-use' semantics for runtime lifecycle management
  • Provides forceUpdate: true workaround for forcing latest version
• TOC and index updates: Added entries to toc.yml and 10.0.md

Key behavioral changes

Before v3.0.0: Always checked for latest runtime version on each call
After v3.0.0: Reuses existing installations, checks daily after runtimeUpdateDelaySeconds

Example usage:

// Force check for latest runtime (not generally recommended)
const path = (await vscode.commands.executeCommand<IDotnetAcquireResult>(
    'dotnet.acquire',
    { version: '9.0', requestingExtensionId, forceUpdate: true }
)).dotnetPath;

Performance impact: Eliminates 287ms median delay (up to 9-36s for slowest 3% of networks)

Fixes #<issue_number>

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: dotnet.acquire API for VS Code No Longer Always Downloads Latest</issue_title>
<issue_description>### Description

As implemented in dotnet/vscode-dotnet-runtime#2420 and described in dotnet/vscode-dotnet-runtime#2359, The .NET Install Tool Extension (https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscode-dotnet-runtime) for VS Code Extension Developers provides the VS Code command dotnet.acquire to install a .NET runtime given a major.minor, amongst other information such as an architecture. Some of the commands are documented at https://github.com/dotnet/vscode-dotnet-runtime/blob/main/Documentation/commands.md.

Example of how a VS Code Extension may install the runtime using our extension:
const dotnetRuntimePath = (await vscode.commands.executeCommand<IDotnetAcquireResult>('dotnet.acquire', { version: '9.0', 'requestingExtensionId'})).dotnetPath;

The commands for dotnet.acquire and dotnet.uninstall were both changed. dotnet.acquire no longer downloads the latest runtime each time and will instead periodically manage, update, and uninstall runtime versions. dotnet.uninstall will no longer allow uninstalling an install that is 'in-use' which is defined below.

Version

Other (please put exact version in description textbox)

Previous behavior

Up until version 3.0.0 of the .NET Install Tool, or pre-release version 2.4.1, calling dotnet.acquire would always trigger 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#DevKit, C#, and other VS Code extensions, both first and third party, to run internal C# code/processes, such as the language server host. This runtime is generally not used to run the users specific project, and is a private, user-folder copy on disk. It may be the runtime or aspnetcore runtime.

A similar command, dotnet.uninstall exists and is also documented above. That command would uninstall any dotnet runtime or SDK that an extension had requested if no other extensions depended upon that installation. By depend on, we mean that an extension had requested that version of .NET in the past. This was a reference count-based mechanism to allow uninstallation when no further dependent extensions of an install remained.

New behavior

As part of a change to improve performance and management of the .NET Runtime:

1. dotnet.acquire will no longer always check for a newer runtime version before returning path to a runtime that matches the major.minor. It will instead use existing runtime installations it's made and check daily for a new runtime after runtimeUpdateDelaySeconds, which defaults to 5 minutes. This is a setting that can be changed in the VS Code Extension Settings. After this time, the prior check will commence for newer runtime versions, and the new runtime will be installed if needed. After this, 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]) combo will be uninstalled automatically.

   'in-use' means that the executable path to that .NET runtime install was:

   a. Returned by a command through the .NET Install Tool in any session of vscode, vscode 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.

   b. Part of the PATH or DOTNET_ROOT environment variable in which VS Code is operating within.

2. dotnet.uninstall will not 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/in-use. This 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

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

This speeds up the developer loop by deferring the network call and installation time away from the launch of extensions that util...

• Fixes [Breaking change]: dotnet.acquire API for VS Code No Longer Always Downloads Latest #49127

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/10.0.md	Breaking changes in .NET 10
docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md	dotnet.acquire API for VS Code no longer always downloads latest
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull Request Overview

This PR documents a breaking change in the .NET Install Tool for VS Code Extension version 3.0.0, which modifies the behavior of the dotnet.acquire API command to optimize startup performance by deferring runtime version checks.

Key changes:

• Adds new breaking change documentation for the .NET Install Tool's dotnet.acquire API behavior modification
• Updates the table of contents and .NET 10 compatibility index to include the new breaking change entry

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/core/compatibility/install-tool/3.0.0/vscode-dotnet-acquire-no-latest.md	New breaking change documentation describing behavior changes in dotnet.acquire API
docs/core/compatibility/toc.yml	Adds new "Install tool" section with link to the breaking change article
docs/core/compatibility/10.0.md	Adds new "Install tool" section in the .NET 10 compatibility index table

[gewarren]

I'm good with the warning. It doesn't like the folder name 3.0.0 but we've named folders based on versions like that for a long time.

[BillWagner]

This LGTM @gewarren

We should fix the one warning though.

[BillWagner]

It looks like the warning is coming from the folder name. That should be addressed.

[gewarren]

Thanks for the review @BillWagner. Can you take a look at my comment at #49618 (comment) and see if you agree?