Add #:project directive

documentation/general/dotnet-run-file.md

@@ -161,14 +161,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 System.CommandLine@2.0.0-*
+#:project ../MyLibrary
 ```
 
 The value must be separated from the kind (`package`/`sdk`/`property`) of the directive by whitespace
@@ -182,6 +184,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
@@ -332,8 +337,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
 

src/Cli/dotnet/Commands/CliCommandStrings.resx

@@ -1046,6 +1046,10 @@ Tool '{1}' (version '{2}') was successfully installed. Entry is added to the man
     <value>Minimum expected tests policy violation, tests ran {0}, minimum expected {1}</value>
     <comment>{0}, {1} number of tests</comment>
   </data>
+  <data name="InvalidProjectDirective" xml:space="preserve">
+    <value>The '#:project' directive at '{0}' is invalid: {1}</value>
+    <comment>{0} is the file path and line number. {1} is the inner error message.</comment>
+  </data>
   <data name="MissingDirectiveName" xml:space="preserve">
     <value>Missing name of '{0}' at {1}.</value>
     <comment>{0} is the directive name like 'package' or 'sdk', {1} is the file path and line number.</comment>

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

@@ -58,6 +58,56 @@ internal sealed class VirtualProjectBuildingCommand : CommandBase
         "MSBuild.rsp",
     ];
 
+    internal static readonly string TargetOverrides = """
+          <!--
+            Override targets which don't work with project files that are not present on disk.
+            See https://github.com/NuGet/Home/issues/14148.
+          -->
+
+          <Target Name="_FilterRestoreGraphProjectInputItems"
+                  DependsOnTargets="_LoadRestoreGraphEntryPoints">
+            <!-- No-op, the original output is not needed by the overwritten targets. -->
+          </Target>
+
+          <Target Name="_GetAllRestoreProjectPathItems"
+                  DependsOnTargets="_FilterRestoreGraphProjectInputItems;_GenerateRestoreProjectPathWalk"
+                  Returns="@(_RestoreProjectPathItems)">
+            <!-- Output from dependency _GenerateRestoreProjectPathWalk. -->
+          </Target>
+
+          <Target Name="_GenerateRestoreGraph"
+                  DependsOnTargets="_FilterRestoreGraphProjectInputItems;_GetAllRestoreProjectPathItems;_GenerateRestoreGraphProjectEntry;_GenerateProjectRestoreGraph"
+                  Returns="@(_RestoreGraphEntry)">
+            <!-- Output partly from dependency _GenerateRestoreGraphProjectEntry and _GenerateProjectRestoreGraph. -->
+
+            <ItemGroup>
+              <_GenerateRestoreGraphProjectEntryInput Include="@(_RestoreProjectPathItems)" Exclude="$(MSBuildProjectFullPath)" />
+            </ItemGroup>
+
+            <MSBuild
+                BuildInParallel="$(RestoreBuildInParallel)"
+                Projects="@(_GenerateRestoreGraphProjectEntryInput)"
+                Targets="_GenerateRestoreGraphProjectEntry"
+                Properties="$(_GenerateRestoreGraphProjectEntryInputProperties)">
+
+              <Output
+                  TaskParameter="TargetOutputs"
+                  ItemName="_RestoreGraphEntry" />
+            </MSBuild>
+
+            <MSBuild
+                BuildInParallel="$(RestoreBuildInParallel)"
+                Projects="@(_GenerateRestoreGraphProjectEntryInput)"
+                Targets="_GenerateProjectRestoreGraph"
+                Properties="$(_GenerateRestoreGraphProjectEntryInputProperties)">
+        
+              <Output
+                  TaskParameter="TargetOutputs"
+                  ItemName="_RestoreGraphEntry" />
+            </MSBuild>
+          </Target>
+        """;
+
     private ImmutableArray<CSharpDirective> _directives;
 
     public VirtualProjectBuildingCommand(
@@ -468,6 +518,7 @@ public static void WriteProjectFile(
         var sdkDirectives = directives.OfType<CSharpDirective.Sdk>();
         var propertyDirectives = directives.OfType<CSharpDirective.Property>();
         var packageDirectives = directives.OfType<CSharpDirective.Package>();
+        var projectDirectives = directives.OfType<CSharpDirective.Project>();
 
         string sdkValue = "Microsoft.NET.Sdk";
 
@@ -607,6 +658,25 @@ public static void WriteProjectFile(
             writer.WriteLine("  </ItemGroup>");
         }
 
+        if (projectDirectives.Any())
+        {
+            writer.WriteLine("""
+
+                  <ItemGroup>
+                """);
+
+            foreach (var projectReference in projectDirectives)
+            {
+                writer.WriteLine($"""
+                        <ProjectReference Include="{EscapeValue(projectReference.Name)}" />
+                    """);
+
+                processedDirectives++;
+            }
+
+            writer.WriteLine("  </ItemGroup>");
+        }
+
         Debug.Assert(processedDirectives + directives.OfType<CSharpDirective.Shebang>().Count() == directives.Length);
 
         if (isVirtualProject)
@@ -643,35 +713,8 @@ public static void WriteProjectFile(
                     """);
             }
 
-            writer.WriteLine("""
-
-                  <!--
-                    Override targets which don't work with project files that are not present on disk.
-                    See https://github.com/NuGet/Home/issues/14148.
-                  -->
-
-                  <Target Name="_FilterRestoreGraphProjectInputItems"
-                          DependsOnTargets="_LoadRestoreGraphEntryPoints"
-                          Returns="@(FilteredRestoreGraphProjectInputItems)">
-                    <ItemGroup>
-                      <FilteredRestoreGraphProjectInputItems Include="@(RestoreGraphProjectInputItems)" />
-                    </ItemGroup>
-                  </Target>
-
-                  <Target Name="_GetAllRestoreProjectPathItems"
-                          DependsOnTargets="_FilterRestoreGraphProjectInputItems"
-                          Returns="@(_RestoreProjectPathItems)">
-                    <ItemGroup>
-                      <_RestoreProjectPathItems Include="@(FilteredRestoreGraphProjectInputItems)" />
-                    </ItemGroup>
-                  </Target>
-
-                  <Target Name="_GenerateRestoreGraph"
-                          DependsOnTargets="_FilterRestoreGraphProjectInputItems;_GetAllRestoreProjectPathItems;_GenerateRestoreGraphProjectEntry;_GenerateProjectRestoreGraph"
-                          Returns="@(_RestoreGraphEntry)">
-                    <!-- Output from dependency _GenerateRestoreGraphProjectEntry and _GenerateProjectRestoreGraph -->
-                  </Target>
-                """);
+            writer.WriteLine();
+            writer.WriteLine(TargetOverrides);
         }
 
         writer.WriteLine("""
@@ -943,16 +986,22 @@ private CSharpDirective() { }
             "sdk" => Sdk.Parse(errors, sourceFile, span, directiveKind, directiveText),
             "property" => Property.Parse(errors, sourceFile, span, directiveKind, directiveText),
             "package" => Package.Parse(errors, sourceFile, span, directiveKind, directiveText),
+            "project" => Project.Parse(errors, sourceFile, span, directiveText),
             _ => ReportError<Named>(errors, sourceFile, span, string.Format(CliCommandStrings.UnrecognizedDirective, directiveKind, sourceFile.GetLocationString(span))),
         };
     }
 
     private static T? ReportError<T>(ImmutableArray<SimpleDiagnostic>.Builder? errors, SourceFile sourceFile, TextSpan span, string message, Exception? inner = null)
+    {
+        ReportError(errors, sourceFile, span, message, inner);
+        return default;
+    }
+
+    private static void ReportError(ImmutableArray<SimpleDiagnostic>.Builder? errors, SourceFile sourceFile, TextSpan span, string message, Exception? inner = null)
     {
         if (errors != null)
         {
             errors.Add(new SimpleDiagnostic { Location = sourceFile.GetFileLinePositionSpan(span), Message = message });
-            return default;
         }
         else
         {
@@ -1088,6 +1137,44 @@ private Package() { }
             };
         }
     }
+
+    /// <summary>
+    /// <c>#:project</c> directive.
+    /// </summary>
+    public sealed class Project : Named
+    {
+        private Project() { }
+
+        public static Project Parse(ImmutableArray<SimpleDiagnostic>.Builder? errors, SourceFile sourceFile, TextSpan span, string directiveText)
+        {
+            try
+            {
+                // If the path is a directory like '../lib', transform it to a project file path like '../lib/lib.csproj'.
+                // Also normalize blackslashes to forward slashes to ensure the directive works on all platforms.
+                var sourceDirectory = Path.GetDirectoryName(sourceFile.Path) ?? ".";
+                var resolvedProjectPath = Path.Combine(sourceDirectory, directiveText.Replace('\\', '/'));
+                if (Directory.Exists(resolvedProjectPath))
+                {
+                    var fullFilePath = MsbuildProject.GetProjectFileFromDirectory(resolvedProjectPath).FullName;
+                    directiveText = Path.GetRelativePath(relativeTo: sourceDirectory, fullFilePath);
+                }
+                else if (!File.Exists(resolvedProjectPath))
+                {
+                    throw new GracefulException(CliStrings.CouldNotFindProjectOrDirectory, resolvedProjectPath);
+                }
+            }
+            catch (GracefulException e)
+            {
+                ReportError(errors, sourceFile, span, string.Format(CliCommandStrings.InvalidProjectDirective, sourceFile.GetLocationString(span), e.Message), e);
+            }
+
+            return new Project
+            {
+                Span = span,
+                Name = directiveText,
+            };
+        }
+    }
 }
 
 /// <summary>