Merge branch 'main' into wix5

Author: joeloff

.github/copilot-instructions.md

@@ -12,4 +12,7 @@ Output Considerations:
 
 Localization:
 - Avoid modifying .xlf files and instead prompt the user to update them using the `/t:UpdateXlf` target on MSBuild.
-- Consider localizing strings in .resx files when possible.
+- Consider localizing strings in .resx files when possible.
+
+Documentation:
+- Do not manually edit files under documentation/manpages/sdk as these are generated based on documentation and should not be manually modified.

.vsts-ci.yml

@@ -107,7 +107,7 @@ extends:
             templateFolderName: templates-official
             publishTaskPrefix: 1ES.
           runtimeSourceProperties: /p:DotNetRuntimeSourceFeed=https://ci.dot.net/internal /p:DotNetRuntimeSourceFeedKey=$(dotnetbuilds-internal-container-read-token-base64)
-          locBranch: release/9.0.3xx
+          locBranch: main
           # WORKAROUND: BinSkim requires the folder exist prior to scanning.
           preSteps:
           - powershell: New-Item -ItemType Directory -Path $(Build.SourcesDirectory)/artifacts/bin -Force

TemplateEngine.slnf

@@ -1,6 +1,6 @@
 {
   "solution": {
-    "path": "sdk.sln",
+    "path": "sdk.slnx",
     "projects": [
       "test\\TestAssets\\TestPackages\\dotnet-new\\Microsoft.TemplateEngine.TestTemplates.csproj",
       "src\\Cli\\Microsoft.DotNet.Cli.Sln.Internal\\Microsoft.DotNet.Cli.Sln.Internal.csproj",
@@ -21,4 +21,4 @@
       "template_feed\\Microsoft.DotNet.Common.ProjectTemplates.10.0\\Microsoft.DotNet.Common.ProjectTemplates.10.0.csproj"
     ]
   }
-}
+}

containers.slnf

@@ -1,6 +1,6 @@
 {
   "solution": {
-    "path": "sdk.sln",
+    "path": "sdk.slnx",
     "projects": [
       "src\\Cli\\Microsoft.DotNet.Cli.Utils\\Microsoft.DotNet.Cli.Utils.csproj",
       "src\\Cli\\Microsoft.DotNet.InternalAbstractions\\Microsoft.DotNet.InternalAbstractions.csproj",
@@ -13,4 +13,4 @@
       "test\\containerize.UnitTests\\containerize.UnitTests.csproj"
     ]
   }
-}
+}

documentation/general/dotnet-run-file.md

@@ -65,6 +65,8 @@ For example, the remaining command-line arguments after the first argument (the
 (except for the arguments recognized by `dotnet run` unless they are after the `--` separator)
 and working directory is not changed (e.g., `cd /x/ && dotnet run /y/file.cs` runs the program in directory `/x/`).
 
+`dotnet path.cs` is a shortcut for `dotnet run path.cs` provided that `path.cs` is a valid [target path](#target-path).
+
 ### Other commands
 
 Commands `dotnet restore file.cs` and `dotnet build file.cs` are needed for IDE support and hence work for file-based programs.
@@ -161,14 +163,16 @@ They are not cleaned immediately because they can be re-used on subsequent runs
 
 It is possible to specify some project metadata via *file-level directives*
 which are [ignored][ignored-directives] by the C# language but recognized by the SDK CLI.
-Directives `sdk`, `package`, and `property` are translated into `<Project Sdk="...">`, `<PackageReference>`, and `<Property>` project elements, respectively.
+Directives `sdk`, `package`, `property`, and `project` are translated into
+`<Project Sdk="...">`, `<PackageReference>`, `<PropertyGroup>`, and `<ProjectReference>` project elements, respectively.
 Other directives result in an error, reserving them for future use.
 
 ```cs
 #:sdk Microsoft.NET.Sdk.Web
 #:property TargetFramework=net11.0
 #:property LangVersion=preview
 #:package [email protected]*
+#:project ../MyLibrary
 ```
 
 The value must be separated from the kind (`package`/`sdk`/`property`) of the directive by whitespace
@@ -182,6 +186,9 @@ The value of `#:property` is split by the separator and injected as `<{0}>{1}</{
 It is an error if no separator appears in the value or if the first part (property name) is empty (the property value is allowed to be empty) or contains invalid characters.
 The value of `#:package` is split by the separator and injected as `<PackageReference Include="{0}" Version="{1}">` (or without the `Version` attribute if there is no separator) in an `<ItemGroup>`.
 It is an error if the first part (package name) is empty (the package version is allowed to be empty, but that results in empty `Version=""`).
+The value of `#:project` is injected as `<ProjectReference Include="{0}" />` in an `<ItemGroup>`.
+If the value points to an existing directory, a project file is found inside that directory and its path is used instead
+(because `ProjectReference` items don't support directory paths).
 
 Because these directives are limited by the C# language to only appear before the first "C# token" and any `#if`,
 dotnet CLI can look for them via a regex or Roslyn lexer without any knowledge of defined conditional symbols
@@ -294,28 +301,24 @@ Also, `InternalsVisibleTo` needs to be added into a C# file as an attribute, or
 
 ### Shebang support
 
-It might be beneficial to also ship `dotnet-run` binary
-(or `dotnet-run-file` that would only work with file-based programs, not project-based ones, perhaps simply named `cs`)
-because some shells do not support multiple command-line arguments in the shebang
+Some shells do not support multiple command-line arguments in the shebang
 which is needed if one wants to use `/usr/bin/env` to find the `dotnet` executable
-(although `-S` argument can be sometimes used to enable multiple argument support):
+(although `-S` argument can be sometimes used to enable multiple argument support),
+so `dotnet file.cs` instead of `dotnet run file.cs` should be used in shebangs:
 
 ```cs
 #!/usr/bin/env dotnet run
 // ^ Might not work in all shells. "dotnet run" might be passed as a single argument to "env".
 ```
 ```cs
-#!/usr/bin/env dotnet-run
+#!/usr/bin/env dotnet
 // ^ Should work in all shells.
 ```
 ```cs
 #!/usr/bin/env -S dotnet run
-// ^ Workaround in some shells.
+// ^ Works in some shells.
 ```
 
-We could also consider making `dotnet file.cs` work because `dotnet file.dll` also works today
-but that would require changes to the native dotnet host.
-
 ### Other possible commands
 
 We can consider supporting other commands like `dotnet pack`, `dotnet watch`,
@@ -332,8 +335,8 @@ We could also add `dotnet compile` command that would be the equivalent of `dotn
 e.g., via `dotnet clean --file-based-program <path-to-entry-point>`
 or `dotnet clean --all-file-based-programs`.
 
-Adding package references via `dotnet package add` could be supported for file-based programs as well,
-i.e., the command would add a `#:package` directive to the top of a `.cs` file.
+Adding references via `dotnet package add`/`dotnet reference add` could be supported for file-based programs as well,
+i.e., the command would add a `#:package`/`#:project` directive to the top of a `.cs` file.
 
 ### Explicit importing
 

documentation/manpages/sdk/dotnet-build-server.1

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "dotnet-build-server" "1" "2025-05-30" "" ".NET Documentation"
+.TH "dotnet-build-server" "1" "2025-06-13" "" ".NET Documentation"
 .hy
 .SH dotnet build-server
 .PP

documentation/manpages/sdk/dotnet-build.1

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "dotnet-build" "1" "2025-05-30" "" ".NET Documentation"
+.TH "dotnet-build" "1" "2025-06-13" "" ".NET Documentation"
 .hy
 .SH dotnet build
 .PP

documentation/manpages/sdk/dotnet-clean.1

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "dotnet-clean" "1" "2025-05-30" "" ".NET Documentation"
+.TH "dotnet-clean" "1" "2025-06-13" "" ".NET Documentation"
 .hy
 .SH dotnet clean
 .PP

documentation/manpages/sdk/dotnet-dev-certs.1

@@ -15,7 +15,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "dotnet-dev-certs" "1" "2025-05-30" "" ".NET Documentation"
+.TH "dotnet-dev-certs" "1" "2025-06-13" "" ".NET Documentation"
 .hy
 .SH dotnet dev-certs
 .PP

documentation/manpages/sdk/dotnet-environment-variables.7

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "dotnet-environment-variables" "7" "2025-05-30" "" ".NET Documentation"
+.TH "dotnet-environment-variables" "7" "2025-06-13" "" ".NET Documentation"
 .hy
 .SH NAME
 .PP