Allow skipping project fallback with file-based run

documentation/general/dotnet-run-file.md

@@ -78,6 +78,7 @@ The file-based build and run kicks in only when:
 - if the target file exists, and has the `.cs` file extension or contents that start with `#!`.
 
 Otherwise, project-based `dotnet run` fallback is used and you might get an error like "Couldn't find a project to run."
+You can explicitly use the `--file` option to avoid the fallback behavior.
 
 File-based programs are processed by `dotnet run` equivalently to project-based programs unless specified otherwise in this document.
 For example, the remaining command-line arguments after the first argument (the target path) are passed through to the target app
@@ -88,7 +89,7 @@ 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.
 
-`dotnet path.cs` is a shortcut for `dotnet run path.cs` provided that `path.cs` is a valid [target path](#target-path) (`dotnet -` is currently not supported).
+`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).
 
 ### Other commands
 
@@ -303,7 +304,7 @@ would need to search for a file-based program in the current directory instead o
 
 We could add a universal option that works with both project-based and file-based programs,
 like `dotnet run --directory ./dir/`. For inspiration, `dotnet test` also has a `--directory` option.
-Furthermore, users might expect there to be a `--file` option, as well. Both could be unified as `--path`.
+We already have a `--file` option. Both could be unified as `--path`.
 
 If we want to also support [multi-entry-point scenarios](#multiple-entry-points),
 we might need an option like `dotnet run --entry ./dir/name` which would work for both `./dir/name.cs` and `./dir/name/name.csproj`.

src/Cli/dotnet/Commands/CliCommandStrings.resx

@@ -671,6 +671,12 @@ dotnet.config is a name don't translate.</comment>
   <data name="CommandOptionProjectHelpName" xml:space="preserve">
     <value>PROJECT_PATH</value>
   </data>
+  <data name="CommandOptionFileDescription" xml:space="preserve">
+    <value>The path to the file-based app to run (can be also passed as the first argument if there is no project in the current directory).</value>
+  </data>
+  <data name="CommandOptionFileHelpName" xml:space="preserve">
+    <value>FILE_PATH</value>
+  </data>
   <data name="Commands" xml:space="preserve">
     <value>SDK commands</value>
   </data>

src/Cli/dotnet/Commands/Run/RunCommand.cs

@@ -445,8 +445,16 @@ private static void ThrowUnableToRunError(ProjectInstance project)
                     project.GetPropertyValue("OutputType")));
     }
 
-    private static string? DiscoverProjectFilePath(string? projectFileOrDirectoryPath, bool readCodeFromStdin, ref string[] args, out string? entryPointFilePath)
+    private static string? DiscoverProjectFilePath(string? filePath, string? projectFileOrDirectoryPath, bool readCodeFromStdin, ref string[] args, out string? entryPointFilePath)
     {
+        // If `--file` is explicitly specified, just use that.
+        if (filePath != null)
+        {
+            Debug.Assert(projectFileOrDirectoryPath == null);
+            entryPointFilePath = Path.GetFullPath(filePath);
+            return null;
+        }
+
         bool emptyProjectOption = false;
         if (string.IsNullOrWhiteSpace(projectFileOrDirectoryPath))
         {
@@ -547,9 +555,20 @@ public static RunCommand FromParseResult(ParseResult parseResult)
                 .Any(static t => t is { Type: TokenType.Argument, Value: "-" });
 
         string? projectOption = parseResult.GetValue(RunCommandParser.ProjectOption);
+        string? fileOption = parseResult.GetValue(RunCommandParser.FileOption);
+
+        if (projectOption != null && fileOption != null)
+        {
+            throw new GracefulException(CliCommandStrings.InvalidOptionCombination, RunCommandParser.ProjectOption.Name, RunCommandParser.FileOption.Name);
+        }
 
         string[] args = [.. nonBinLogArgs];
-        string? projectFilePath = DiscoverProjectFilePath(projectOption, readCodeFromStdin, ref args, out string? entryPointFilePath);
+        string? projectFilePath = DiscoverProjectFilePath(
+            filePath: fileOption,
+            projectFileOrDirectoryPath: projectOption,
+            readCodeFromStdin: readCodeFromStdin,
+            ref args,
+            out string? entryPointFilePath);
 
         bool noBuild = parseResult.HasOption(RunCommandParser.NoBuildOption);
 

src/Cli/dotnet/Commands/Run/RunCommandParser.cs

@@ -23,6 +23,12 @@ internal static class RunCommandParser
         HelpName = CliCommandStrings.CommandOptionProjectHelpName
     };
 
+    public static readonly Option<string> FileOption = new("--file")
+    {
+        Description = CliCommandStrings.CommandOptionFileDescription,
+        HelpName = CliCommandStrings.CommandOptionFileHelpName,
+    };
+
     public static readonly Option<ReadOnlyDictionary<string, string>?> PropertyOption = CommonOptions.PropertiesOption;
 
     public static readonly Option<string> LaunchProfileOption = new("--launch-profile", "-lp")
@@ -85,6 +91,7 @@ private static Command ConstructCommand()
         command.Options.Add(FrameworkOption);
         command.Options.Add(RuntimeOption);
         command.Options.Add(ProjectOption);
+        command.Options.Add(FileOption);
         command.Options.Add(PropertyOption);
         command.Options.Add(LaunchProfileOption);
         command.Options.Add(NoLaunchProfileOption);