[automated] Merge branch 'release/10.0.4xx' => 'main'

.github/copilot-instructions.md

@@ -22,9 +22,10 @@ Testing:
   - Examples:
     - `dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~ItShowsTheAppropriateMessageToTheUser"`
     - `dotnet exec artifacts/bin/redist/Debug/dotnet.Tests.dll -method "*ItShowsTheAppropriateMessageToTheUser*"`
+- For incremental test runs of `dotnet.Tests` (avoids slow full `build.cmd`), use the `incremental-test` skill.
 - To test CLI command changes:
   - Build the redist SDK: `./build.sh` from repo root
-  - Create a dogfood environment: `source eng/dogfood.sh` 
+  - Create a dogfood environment: `source eng/dogfood.sh`
   - Test commands in the dogfood shell (e.g., `dnx --help`, `dotnet tool install --help`)
   - The dogfood script sets up PATH and environment to use the newly built SDK
 

.github/skills/AGENTS.md

@@ -0,0 +1,24 @@
+# Agent Skills
+
+When creating skills, follow:
+- Agent skills specification: https://agentskills.io/specification.md
+- Best practices: https://agentskills.io/skill-creation/best-practices.md
+
+## Structure
+
+```
+.github/skills/skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+├── assets/           # Optional: templates, resources
+└── ...               # Any additional files or directories
+```
+
+## Quick Checklist
+
+- [ ] Run `dotnet .github/skills/ValidateSkill.cs <skill-dir>` to validate format.
+- [ ] `description` describes what the skill does and when to use it. Skill body does not include "When to use this skill".
+- [ ] Skill does not explain things the agent already knows. Focus on what's specific to the task at hand.
+- [ ] Deterministic processes use scripts (for example, to fetch and format data from an API).
+- [ ] Scripts use PowerShell or .NET file-based apps, not bash.

.github/skills/ValidateSkill.cs

@@ -0,0 +1,103 @@
+#!/usr/bin/env dotnet
+#:property ManagePackageVersionsCentrally=false
+#:property PublishAot=false
+#:package YamlDotNet@16.3.0
+
+using YamlDotNet.Serialization;
+using System.Text.RegularExpressions;
+
+if (args.Length == 0)
+{
+    Console.Error.WriteLine("Usage: dotnet ValidateSkill.cs <path-to-skill-directory>");
+    return 1;
+}
+
+string skillDir = Path.GetFullPath(args[0]);
+string skillName = Path.GetFileName(Path.TrimEndingDirectorySeparator(skillDir));
+string skillFile = Path.Combine(skillDir, "SKILL.md");
+
+// SKILL.md must exist in the skill directory
+if (!File.Exists(skillFile))
+{
+    Console.Error.WriteLine($"SKILL.md not found in {skillDir}");
+    return 1;
+}
+
+string text = File.ReadAllText(skillFile);
+
+// SKILL.md must begin with YAML frontmatter delimited by ---
+if (!text.StartsWith("---"))
+{
+    Console.Error.WriteLine("No YAML frontmatter found.");
+    return 1;
+}
+
+Match frontmatterMatch = Regex.Match(
+    text,
+    @"\A---\r?\n(?<yaml>.*?)(?:\r?\n)---(?:\r?\n|$)",
+    RegexOptions.Singleline);
+if (!frontmatterMatch.Success)
+{
+    Console.Error.WriteLine("Unterminated YAML frontmatter.");
+    return 1;
+}
+
+string yaml = frontmatterMatch.Groups["yaml"].Value.Trim();
+
+IDeserializer deserializer = new DeserializerBuilder().Build();
+Dictionary<string, object> frontmatter = deserializer.Deserialize<Dictionary<string, object>>(yaml);
+
+// name is required
+if (!frontmatter.TryGetValue("name", out object? nameValue) || nameValue is not string frontmatterName)
+{
+    Console.Error.WriteLine("Frontmatter missing 'name' field.");
+    return 1;
+}
+
+// name must be 1-64 characters
+if (frontmatterName.Length == 0 || frontmatterName.Length > 64)
+{
+    Console.Error.WriteLine($"Name is {frontmatterName.Length} chars (must be 1-64).");
+    return 1;
+}
+
+// name: lowercase alphanumeric and hyphens only, no leading/trailing/consecutive hyphens
+if (!Regex.IsMatch(frontmatterName, @"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+    || frontmatterName.Contains("--"))
+{
+    Console.Error.WriteLine($"Invalid name '{frontmatterName}'. Must be lowercase letters, numbers, and hyphens only. Must not start/end with a hyphen or contain consecutive hyphens.");
+    return 1;
+}
+
+// name must match the parent directory name
+if (!string.Equals(skillName, frontmatterName, StringComparison.Ordinal))
+{
+    Console.Error.WriteLine($"Name mismatch: directory is '{skillName}' but SKILL.md name is '{frontmatterName}'.");
+    return 1;
+}
+
+// description is required
+if (!frontmatter.TryGetValue("description", out object? descValue) || descValue is not string description)
+{
+    Console.Error.WriteLine("Frontmatter missing 'description' field.");
+    return 1;
+}
+
+// description must be 1-1024 characters
+if (description.Length == 0 || description.Length > 1024)
+{
+    Console.Error.WriteLine($"Description is {description.Length} chars (must be 1-1024).");
+    return 1;
+}
+
+// Keep SKILL.md under 500 lines; move detailed content to references/ or scripts/
+// See "Progressive Disclosure" at https://agentskills.io/specification.md
+int lineCount = text.Split('\n').Length;
+if (lineCount > 500)
+{
+    Console.Error.WriteLine($"SKILL.md is {lineCount} lines (max 500). See \"Progressive Disclosure\" at https://agentskills.io/specification.md");
+    return 1;
+}
+
+Console.WriteLine($"Skill '{frontmatterName}' is valid.");
+return 0;

.github/skills/incremental-test/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: incremental-test
+description: >-
+  Run dotnet.Tests incrementally without a full build.cmd rebuild. Use after
+  modifying source code in SDK projects to quickly build only changed projects,
+  deploy their outputs into the redist SDK layout, and run tests against them.
+---
+
+# Incremental Test Runner for dotnet.Tests
+
+## Prerequisites
+
+- A full build must have been completed at least once (via `build.cmd` or `build.sh`) so that the redist SDK layout exists at `artifacts\bin\redist\Debug\dotnet\sdk\<version>\`.
+- The repo-local `.dotnet` SDK must match the version expected by the test projects. If the runtime or SDK version is out of date (e.g., test build fails with a missing framework error), run `.\restore.cmd` (or `./restore.sh` on macOS/Linux) to download the correct SDK into `.dotnet`.
+- This workflow uses Windows/PowerShell commands and paths. On macOS/Linux, substitute forward slashes and use `cp` instead of `Copy-Item`.
+
+## Workflow
+
+### Step 1: Identify modified projects
+
+Determine which projects have been modified. Use context from:
+- The files you just edited in this session.
+- Or `git status`/`git diff` to find changed `.cs` files and map them to their `.csproj` projects.
+
+### Step 2: Build modified projects
+
+Build each modified project individually using the repo-local dotnet:
+
+```
+.\.dotnet\dotnet build <path-to-project.csproj> -c Debug
+```
+
+For example:
+```
+.\.dotnet\dotnet build src\Cli\Microsoft.DotNet.Cli.Utils\Microsoft.DotNet.Cli.Utils.csproj -c Debug
+```
+
+If the `dotnet` CLI project itself was modified, build it:
+```
+.\.dotnet\dotnet build src\Cli\dotnet\dotnet.csproj -c Debug
+```
+
+### Step 3: Copy output DLLs to the redist SDK layout
+
+Discover the SDK version directory name:
+```powershell
+$sdkVersion = (Get-ChildItem artifacts\bin\redist\Debug\dotnet\sdk -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1).Name
+```
+
+For each modified project, copy its output DLL (and any satellite assemblies) from the project's build output to the redist SDK directory:
+
+```
+Source: artifacts\bin\<ProjectName>\Debug\net10.0\<AssemblyName>.dll
+Target: artifacts\bin\redist\Debug\dotnet\sdk\<version>\
+```
+
+For example:
+```powershell
+Copy-Item artifacts\bin\Microsoft.DotNet.ProjectTools\Debug\net10.0\Microsoft.DotNet.ProjectTools.dll artifacts\bin\redist\Debug\dotnet\sdk\$sdkVersion\
+Copy-Item artifacts\bin\Microsoft.DotNet.Cli.Utils\Debug\net10.0\Microsoft.DotNet.Cli.Utils.dll artifacts\bin\redist\Debug\dotnet\sdk\$sdkVersion\
+```
+
+The `dotnet` project is special — it builds into `artifacts\bin\dotnet\Debug\net10.0\` and its `dotnet.dll` must be copied to the SDK directory:
+```powershell
+Copy-Item artifacts\bin\dotnet\Debug\net10.0\dotnet.dll artifacts\bin\redist\Debug\dotnet\sdk\$sdkVersion\
+```
+
+**Important notes:**
+- For typical incremental edits, only copy DLLs that are **already present** in the target directory. If your change introduces a new shipped assembly or moves assemblies, you will need a full `build.cmd`/`build.sh` to update the layout correctly.
+- Some projects multi-target (e.g., `net10.0` and `net472`). Always use the `net10.0` output.
+- If localization resource DLLs were changed (in subdirectories like `cs\`, `de\`, etc.), copy those too.
+
+### Step 4: Build the test project (if test code was modified)
+
+The test project `test\dotnet.Tests\dotnet.Tests.csproj` outputs directly to `artifacts\bin\redist\Debug\` (via `TestHostFolder`), so just build it:
+
+```
+.\.dotnet\dotnet build test\dotnet.Tests\dotnet.Tests.csproj
+```
+
+### Step 5: Run the tests
+
+Run specific tests:
+```
+.\.dotnet\dotnet exec artifacts\bin\redist\Debug\dotnet.Tests.dll -method "*TestMethodName*"
+```
+
+Or run filtered tests via `dotnet test`:
+```
+.\.dotnet\dotnet test test\dotnet.Tests\dotnet.Tests.csproj --no-build --filter "Name~TestMethodName"
+```
+
+## Common project paths
+
+| Assembly | Project Path |
+|---|---|
+| `dotnet.dll` | `src\Cli\dotnet\dotnet.csproj` |
+| `Microsoft.DotNet.Cli.Utils.dll` | `src\Cli\Microsoft.DotNet.Cli.Utils\Microsoft.DotNet.Cli.Utils.csproj` |
+| `Microsoft.DotNet.Cli.Definitions.dll` | `src\Cli\Microsoft.DotNet.Cli.Definitions\Microsoft.DotNet.Cli.Definitions.csproj` |
+| `Microsoft.DotNet.Cli.CoreUtils.dll` | `src\Cli\Microsoft.DotNet.Cli.CoreUtils\Microsoft.DotNet.Cli.CoreUtils.csproj` |
+| `Microsoft.DotNet.Configurer.dll` | `src\Cli\Microsoft.DotNet.Configurer\Microsoft.DotNet.Configurer.csproj` |
+| `Microsoft.DotNet.ProjectTools.dll` | `src\Microsoft.DotNet.ProjectTools\Microsoft.DotNet.ProjectTools.csproj` |
+| `Microsoft.DotNet.NativeWrapper.dll` | `src\Resolvers\Microsoft.DotNet.NativeWrapper\Microsoft.DotNet.NativeWrapper.csproj` |
+| `Microsoft.DotNet.TemplateLocator.dll` | `src\Microsoft.DotNet.TemplateLocator\Microsoft.DotNet.TemplateLocator.csproj` |
+| `Microsoft.DotNet.InternalAbstractions.dll` | `src\Cli\Microsoft.DotNet.InternalAbstractions\Microsoft.DotNet.InternalAbstractions.csproj` |
+| `dotnet.Tests.dll` | `test\dotnet.Tests\dotnet.Tests.csproj` |

.github/skills~d4df2c00059096f30eabafe83ba1722cf97d8ecd

@@ -0,0 +1 @@
+D:/code/dotnet-sdk/.claude/skills/

documentation/general/dotnet-run-file.md

@@ -52,6 +52,8 @@ Additionally, the implicit project file has the following customizations:
     string? directoryPath = AppContext.GetData("EntryPointFileDirectoryPath") as string;
     ```
 
+  - `EntryPointFilePath` property is set to the entry-point file path and is made visible to analyzers via `CompilerVisibleProperty`.
+
   - `FileBasedProgram` property is set to `true` and can be used by SDK targets to detect file-based apps.
 
   - `DisableDefaultItemsInProjectFolder` property is set to `true` which results in `EnableDefaultItems=false` by default
@@ -110,8 +112,8 @@ If a dash (`-`) is given instead of the target path (i.e., `dotnet run -`), the
 In this case, the current working directory is not used to search for other files (launch profiles, other sources in case of multi-file apps);
 the compilation consists solely of the single file read from the standard input.
 However, the current working directory is still used as the working directory for building and executing the program.
-To reference projects relative to the current working directory (instead of relative to the temporary directory the file is isolated in),
-you can use something like `#:project $(MSBuildStartupDirectory)/relative/path`.
+To reference projects or files relative to the current working directory (instead of relative to the temporary directory the file is isolated in),
+you can use something like `#:project $(MSBuildStartupDirectory)/relative/path` or `#:ref $(MSBuildStartupDirectory)/relative/lib.cs`.
 
 `dotnet path.cs` is a shortcut for `dotnet run --file path.cs` provided that `path.cs` is a valid [target path](#target-path) (`dotnet -` is currently not supported)
 and it is not a DLL path, built-in command, or a NuGet tool (e.g., `dotnet watch` invokes the `dotnet-watch` tool
@@ -165,7 +167,7 @@ removes current user's `dotnet run` build outputs that haven't been used in 30 d
 They are not cleaned immediately because they can be re-used on subsequent runs for better performance.
 The automatic cleanup can be disabled by environment variable `DOTNET_CLI_DISABLE_FILE_BASED_APP_ARTIFACTS_AUTOMATIC_CLEANUP=true`,
 but other parameters of the automatic cleanup are currently not configurable.
-The same cleanup can be performed manually via command `dotnet clean-file-based-app-artifacts`.
+The same cleanup can be performed manually via command `dotnet clean file-based-apps`.
 
 ## Directives for project metadata
 
@@ -178,11 +180,12 @@ which are [ignored][ignored-directives] by the C# language but recognized by the
 #:property LangVersion=preview
 #:package System.CommandLine@2.0.0-*
 #:project ../MyLibrary
+#:ref ../lib/lib.cs
 #:include ./**/*.cs
 ```
 
 Each directive has a kind (e.g., `package`), a name (e.g., `System.CommandLine`), a separator (e.g., `@`), and a value (e.g., the package version).
-The value is required for `#:property`, optional for `#:package`/`#:sdk`, and disallowed for `#:project`/`#:include`.  
+The value is required for `#:property`, optional for `#:package`/`#:sdk`, and disallowed for `#:project`/`#:ref`/`#:include`.  
 
 The name must be separated from the kind of the directive by whitespace
 and any leading and trailing white space is not considered part of the name and value.
@@ -209,6 +212,26 @@ The directives are processed as follows:
   (because `ProjectReference` items don't support directory paths).
   An error is reported if zero or more than one projects are found in the directory, just like `dotnet reference add` would do.
 
+- Each `#:ref` references another `.cs` file as a separate project reference.
+  A virtual project is created for the referenced file (e.g., `lib.cs` produces a virtual `lib.cs.csproj`),
+  and a `<ProjectReference Include="lib.cs.csproj" />` is injected in an `<ItemGroup>`.
+  It is an error if the name is empty or if the referenced file does not exist.
+  Unlike `#:project`, `#:ref` points to a `.cs` file (not a `.csproj` file or directory).
+
+  The referenced file is itself a file-based program with its own virtual project (defaulting to `OutputType=Exe`).
+  Library files without an entry point should use `#:property OutputType=Library` to avoid compilation errors.
+  Because the referenced file is compiled as a separate assembly, internal members of the referenced file are not accessible from the referencing file.
+  The `#:ref` directive is transitive: a referenced file can itself contain `#:ref` directives (or any other directives).
+
+  Relative paths are resolved relative to the file containing the directive.
+  MSBuild variables (like `$(MSBuildProjectDirectory)`) can be used in the path.
+
+  During [conversion](#grow-up), each `#:ref` directive creates a separate library project in a sibling directory
+  and a corresponding `<ProjectReference>` entry is added to the converted project.
+  The conversion is recursive: any `#:ref` directives in the referenced files are also converted in the same way.
+
+  This directive is currently gated under a feature flag that can be enabled by setting the MSBuild property `ExperimentalFileBasedProgramEnableRefDirective=true`.
+
 - Each `#:include` is injected as `<{1} Include="{0}" />` in an `<ItemGroup>`
   where `{0}` is the directive's value and `{1}` is determined by its extension.
   The mapping can be customized by setting the MSBuild property `FileBasedProgramsItemMapping`
@@ -228,9 +251,9 @@ The directives are processed as follows:
 - Other directive kinds result in an error, reserving them for future use.
 
 Directive values support MSBuild variables (like `$(..)`) normally as they are translated literally and left to MSBuild engine to process.
-However, in `#:project` directives, variables might not be preserved during [grow up](#grow-up),
+However, in `#:project` and `#:ref` directives, variables might not be preserved during [grow up](#grow-up),
 because there is additional processing of those directives that makes it technically challenging to preserve variables in all cases
-(project directive values need to be resolved to be relative to the target directory
+(project and ref directive values need to be resolved to be relative to the target directory
 and also to point to a project file rather than a directory).
 Note that it is not expected that variables inside the path change their meaning during the conversion,
 so for example `#:project ../$(LibName)` is translated to `<ProjectReference Include="../../$(LibName)/Lib.csproj" />` (i.e., the variable is preserved).
@@ -270,6 +293,11 @@ Along with `#:`, the language also ignores `#!` which could be then used for [sh
 Console.WriteLine("Hello");
 ```
 
+When a file-based program uses [`#:include`](#multiple-files) directives to include additional files,
+the entry point file should start with `#!` to clearly distinguish it from included files.
+This helps IDEs to properly handle multi-file scenarios and discover entry points.
+The analyzer **CA2266** reports a warning if the entry point file is missing the shebang line in this scenario.
+
 ## Implementation
 
 The build is performed using MSBuild APIs on in-memory project files.

src/Cli/Microsoft.DotNet.Cli.Definitions/Commands/Hidden/List/ListCommandDefinition.cs

@@ -20,7 +20,7 @@ public static Argument<string> CreateSlnOrProjectArgument(string name, string de
             Arity = ArgumentArity.ZeroOrOne
         }.DefaultToCurrentDirectory();
 
-    public readonly Argument<string> SlnOrProjectArgument = CreateSlnOrProjectArgument(CommandDefinitionStrings.SolutionOrProjectArgumentName, CommandDefinitionStrings.SolutionOrProjectArgumentDescription);
+    public readonly Argument<string> SlnOrProjectOrFileArgument = CreateSlnOrProjectArgument(CommandDefinitionStrings.SolutionOrProjectOrFileArgumentName, CommandDefinitionStrings.SolutionOrProjectOrFileArgumentDescription);
 
     public readonly ListPackageCommandDefinition PackageCommand = new();
     public readonly ListReferenceCommandDefinition ReferenceCommand = new();
@@ -31,7 +31,7 @@ public ListCommandDefinition()
         Hidden = true;
         this.DocsLink = Link;
 
-        Arguments.Add(SlnOrProjectArgument);
+        Arguments.Add(SlnOrProjectOrFileArgument);
         Subcommands.Add(PackageCommand);
         Subcommands.Add(ReferenceCommand);
     }

src/Cli/Microsoft.DotNet.Cli.Definitions/Commands/Hidden/List/ListPackageCommandDefinition.cs

@@ -12,6 +12,6 @@ internal sealed class ListPackageCommandDefinition() : PackageListCommandDefinit
 
     public ListCommandDefinition Parent => (ListCommandDefinition)Parents.Single();
 
-    public override string? GetFileOrDirectory(ParseResult parseResult)
-        => parseResult.GetValue(Parent.SlnOrProjectArgument);
+    public override Argument<string>? GetProjectOrFileArgument()
+        => Parent.SlnOrProjectOrFileArgument;
 }

src/Cli/Microsoft.DotNet.Cli.Definitions/Commands/Hidden/List/ListReferenceCommandDefinition.cs

@@ -19,7 +19,7 @@ public ListReferenceCommandDefinition() : base(Name)
     public ListCommandDefinition Parent => (ListCommandDefinition)Parents.Single();
 
     internal override string? GetFileOrDirectory(ParseResult parseResult)
-        => parseResult.GetValue(Parent.SlnOrProjectArgument);
+        => parseResult.GetValue(Parent.SlnOrProjectOrFileArgument);
 }
 
 internal abstract class ListReferenceCommandDefinitionBase : Command