8 lines
6.5 KiB
TypeScript
8 lines
6.5 KiB
TypeScript
/**
|
|
* Comprehensive information for the AI agent about the .NET Install Tool extension.
|
|
* This explains settings, architecture, installation types, and useful tricks.
|
|
*
|
|
* Extracted into its own file to keep LanguageModelTools.ts focused on tool logic.
|
|
*/
|
|
export declare const settingsInfoContent = "\n# .NET Install Tool - Guide\n\n## Overview\nThe .NET Install Tool is a VS Code extension that manages .NET installations. It serves two distinct purposes:\n1. **For VS Code Extensions**: Automatically installs .NET runtimes that other extensions (C#, C# DevKit, Unity, Bicep, etc.) need to run their internal components\n2. **For Users**: Provides commands to find and install .NET SDKs system-wide for development\n\n---\n\n## Installation Types\n\n### LOCAL (Extension-Managed) Runtime Installs\n- Small, isolated .NET runtime installs stored in VS Code's extension data folder\n- NOT on the system PATH, NOT visible via `dotnet --list-runtimes`\n- Used solely by VS Code extensions to run their internal components\n- Auto-managed; users rarely need to interact with these\n- The extension's uninstall list ONLY shows these local installs for runtimes\n\n### GLOBAL/Admin SDK Installs (system-wide)\n- System-wide .NET SDK installs (includes runtimes)\n- Typical Locations: Windows: `%ProgramFiles%\\dotnet` (admin required) | macOS: `/usr/local/share/dotnet` (.pkg) | Linux: `/usr/lib/dotnet` or `/usr/share/dotnet` (package manager; officially supported: Ubuntu + RHEL; community distros may work; WSL is not supported)\n\n- Requires administrator/sudo privileges; users must accept elevation prompts\n- IS on the system PATH after installation\n- Visible via `dotnet --list-sdks` and `dotnet --list-runtimes`\n- Use \"Install .NET SDK System-Wide\" command for this\n\n---\n\n## existingDotnetPath Setting (Commonly Misunderstood)\n\n### What It Does\nControls which .NET runtime VS Code **extensions** use to run their internal components.\n\n### What It Does NOT Do\n- Does NOT change what .NET the user's code runs on\n- Does NOT affect `dotnet build` or `dotnet run` commands\n- Does NOT change a project's target framework\n\n### When Users Need This\n- Extensions fail to start with \"could not find .NET runtime\" errors\n- Corporate/restricted environments where the extension cannot auto-download .NET\n- Air-gapped machines without internet or PowerShell script execution restrictions\n- User wants extensions to use a specific pre-installed .NET version\n\n**IMPORTANT:** If a user wants to pin which SDK their PROJECT uses (for `dotnet build`, `dotnet run`, etc.), existingDotnetPath is the WRONG setting. They should use `global.json` instead \u2014 see the \"I want to use a local/repo-specific SDK\" scenario below.\n\nSetting names and formats:\n- `dotnetAcquisitionExtension.existingDotnetPath` \u2014 per-extension:\n```json\n[{ \"extensionId\": \"ms-dotnettools.csharp\", \"path\": \"C:\\\\Program Files\\\\dotnet\\\\dotnet.exe\" }]\n```\n- `dotnetAcquisitionExtension.sharedExistingDotnetPath` \u2014 all extensions:\n```json\n\"C:\\\\Program Files\\\\dotnet\\\\dotnet.exe\"\n```\n\n---\n\n## How to See What's Installed\n\n**Extension-Managed Local Installs:** Run the \"Uninstall .NET\" command \u2014 the dropdown shows all extension-managed installs.\n\n**System-Wide Global Installs:** Run `dotnet --list-sdks` and `dotnet --list-runtimes` in terminal, or use the listInstalledVersions tool.\n\n**listInstalledVersions Tool:** Calls `dotnet.availableInstalls` to scan SDKs/runtimes for a given dotnet executable. If no path provided, it uses PATH (typically global install). Returns version, architecture, and directory for each install.\n\n---\n\n## Uninstall Notes\n\n- The uninstall list only shows extension-managed installs, not system-wide ones\n- **Trick:** To uninstall a global SDK not in the list, first install the SAME version via the extension (this registers it), then it appears in the uninstall list\n- Global SDK uninstall requires the same admin/elevated privileges as installing\n\n---\n\n## Version Selection\n\nCheck `global.json` first \u2014 if present, install `sdk.version` (respecting rollForward). Otherwise, latest LTS.\n\nSDK and runtime share major.minor but differ in patch:\n\n| SDK | Includes Runtime |\n|---------|-----------------|\n| 8.0.100 | 8.0.0 |\n| 8.0.204 | 8.0.4 |\n\nInstalling an SDK always includes the corresponding runtime.\n\n---\n\n## global.json paths (.NET 10+)\n\nFor repo-local SDK resolution, use the `paths` property in global.json:\n```json\n{\n \"sdk\": {\n \"version\": \"10.0.100\",\n \"paths\": [\".dotnet\", \"$host$\"]\n }\n}\n```\n- First matching SDK wins\n- Only works with SDK commands (`dotnet run`, `dotnet build`), NOT with native apphost\n- The host `dotnet` must be .NET 10+\n- Ref: https://learn.microsoft.com/dotnet/core/tools/global-json#paths\n\n---\n\n## Common Scenarios\n\n- **\"I want to develop .NET applications\"** - Install an SDK globally via \"Install .NET SDK System-Wide.\" This provides the `dotnet` CLI for build, run, test, and publish.\n- **\"I want a local/repo-specific SDK (not global)\"** - Use the `paths` property in global.json (.NET 10+ required) \u2014 see section above. DO NOT use existingDotnetPath.\n- **\"C# extension won't start / can't find .NET\"** \u2192 Check `dotnet --info` in terminal. If missing, install SDK globally. If a RUNTIME is installed but not detected, set existingDotnetPath or sharedExistingDotnetPath.\n- **\"Extension installed .NET but I can't use it in terminal\"** - Extension-managed runtimes are LOCAL and not on PATH. For terminal/CLI usage, install globally.\n- **\"I want to use a different .NET version for my project\"** - NOT existingDotnetPath. Create `global.json` in the project root or install the desired SDK globally.\n- **\"Which dotnet does the C# extension use?\"** - Use the findDotNetPath tool. It searches in order: existingDotnetPath setting - PATH - DOTNET_ROOT - extension-managed local installs.\n\n---\n\n## Additional Settings\n\n- **installTimeoutValue**: Seconds to wait for downloads (default: 600). Increase for slow connections.\n- **proxyUrl**: HTTP proxy URL for corporate firewalls.\n\n---\n\n## .NET Hives Architecture\n.NET supports multiple installation \"hives\" (locations). Extension-managed local installs do not conflict with global system installs.\n- The `dotnet` executable typically only sees installs in its own folder\n- `dotnet.findPath` shows which hive extensions like C# DevKit will use\n- `dotnet.availableInstalls` lists installs in a specific hive when given an executable path\n";
|