Support variables in #:project directives

documentation/general/dotnet-run-file.md

@@ -245,6 +245,16 @@ 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.
 
+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),
+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
+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).
+However, variables at the start can change, so for example `#:project $(ProjectDir)../Lib` is translated to `<ProjectReference Include="../../Lib/Lib.csproj" />` (i.e., the variable is expanded).
+In other directives, all variables are preserved during conversion.
+
 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
 and can do that efficiently by stopping the search when it sees the first "C# token".

src/Cli/dotnet/Commands/Project/Convert/ProjectConvertCommand.cs

@@ -30,7 +30,8 @@ public override int Execute()
 
         // Find directives (this can fail, so do this before creating the target directory).
         var sourceFile = SourceFile.Load(file);
-        var directives = VirtualProjectBuildingCommand.FindDirectives(sourceFile, reportAllErrors: !_force, DiagnosticBag.ThrowOnFirst());
+        var diagnostics = DiagnosticBag.ThrowOnFirst();
+        var directives = VirtualProjectBuildingCommand.FindDirectives(sourceFile, reportAllErrors: !_force, diagnostics);
 
         // Create a project instance for evaluation.
         var projectCollection = new ProjectCollection();
@@ -42,6 +43,11 @@ public override int Execute()
         };
         var projectInstance = command.CreateProjectInstance(projectCollection);
 
+        // Evaluate directives.
+        directives = VirtualProjectBuildingCommand.EvaluateDirectives(projectInstance, directives, sourceFile, diagnostics);
+        command.Directives = directives;
+        projectInstance = command.CreateProjectInstance(projectCollection);
+
         // Find other items to copy over, e.g., default Content items like JSON files in Web apps.
         var includeItems = FindIncludedItems().ToList();
 
@@ -166,21 +172,56 @@ void CopyFile(string source, string target)
 
         ImmutableArray<CSharpDirective> UpdateDirectives(ImmutableArray<CSharpDirective> directives)
         {
+            var sourceDirectory = Path.GetDirectoryName(file)!;
+
             var result = ImmutableArray.CreateBuilder<CSharpDirective>(directives.Length);
 
             foreach (var directive in directives)
             {
-                // Fixup relative project reference paths (they need to be relative to the output directory instead of the source directory).
-                if (directive is CSharpDirective.Project project &&
-                    !Path.IsPathFullyQualified(project.Name))
-                {
-                    var modified = project.WithName(Path.GetRelativePath(relativeTo: targetDirectory, path: project.Name));
-                    result.Add(modified);
-                }
-                else
+                // Fixup relative project reference paths (they need to be relative to the output directory instead of the source directory,
+                // and preserve MSBuild interpolation variables like `$(..)`
+                // while also pointing to the project file rather than a directory).
+                if (directive is CSharpDirective.Project project)
                 {
-                    result.Add(directive);
+                    if (Path.IsPathFullyQualified(project.Name))
+                    {
+                        // If the path is absolute and has no `$(..)` vars, just keep it.
+                        if (project.UnresolvedName == project.OriginalName)
+                        {
+                            result.Add(project);
+                            continue;
+                        }
+
+                        // If the path is absolute and it *starts* with some `$(..)` vars,
+                        // turn it into a relative path (it might be in the form `$(ProjectDir)/../Lib`
+                        // and we don't want that to be turned into an absolute path in the converted project).
+                        //
+                        // If the path is absolute but the `$(..)` vars are *inside* of it (like `C:\$(..)\Lib`),
+                        // instead of at the start, we can keep those vars, i.e., skip this `if` block.
+                        //
+                        // The `OriginalName` is absolute if there are no `$(..)` vars at the start.
+                        if (!Path.IsPathFullyQualified(project.OriginalName))
+                        {
+                            project = project.WithName(Path.GetRelativePath(relativeTo: targetDirectory, path: project.Name));
+                            result.Add(project);
+                            continue;
+                        }
+                    }
+
+                    // If the original path is to a directory, just append the resolved file name
+                    // but preserve the variables from the original, e.g., `../$(..)/Directory/Project.csproj`.
+                    if (Directory.Exists(Path.Combine(sourceDirectory, project.UnresolvedName)))
+                    {
+                        var projectFileName = Path.GetFileName(project.Name);
+                        project = project.WithName(Path.Join(project.OriginalName, projectFileName));
+                    }
+
+                    project = project.WithName(Path.GetRelativePath(relativeTo: targetDirectory, path: Path.Combine(sourceDirectory, project.Name)));
+                    result.Add(project);
+                    continue;
                 }
+
+                result.Add(directive);
             }
 
             return result.DrainToImmutable();

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

@@ -6,6 +6,7 @@
 using System.Collections.Immutable;
 using System.Collections.ObjectModel;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Security;
 using System.Text.Json;
 using System.Text.Json.Serialization;
@@ -164,14 +165,26 @@ public VirtualProjectBuildingCommand(
     /// </summary>
     public bool NoWriteBuildMarkers { get; init; }
 
+    private SourceFile EntryPointSourceFile
+    {
+        get
+        {
+            if (field == default)
+            {
+                field = SourceFile.Load(EntryPointFileFullPath);
+            }
+
+            return field;
+        }
+    }
+
     public ImmutableArray<CSharpDirective> Directives
     {
         get
         {
             if (field.IsDefault)
             {
-                var sourceFile = SourceFile.Load(EntryPointFileFullPath);
-                field = FindDirectives(sourceFile, reportAllErrors: false, DiagnosticBag.ThrowOnFirst());
+                field = FindDirectives(EntryPointSourceFile, reportAllErrors: false, DiagnosticBag.ThrowOnFirst());
                 Debug.Assert(!field.IsDefault);
             }
 
@@ -1049,6 +1062,23 @@ public ProjectInstance CreateProjectInstance(ProjectCollection projectCollection
     private ProjectInstance CreateProjectInstance(
         ProjectCollection projectCollection,
         Action<IDictionary<string, string>>? addGlobalProperties)
+    {
+        var project = CreateProjectInstance(projectCollection, Directives, addGlobalProperties);
+
+        var directives = EvaluateDirectives(project, Directives, EntryPointSourceFile, DiagnosticBag.ThrowOnFirst());
+        if (directives != Directives)
+        {
+            Directives = directives;
+            project = CreateProjectInstance(projectCollection, directives, addGlobalProperties);
+        }
+
+        return project;
+    }
+
+    private ProjectInstance CreateProjectInstance(
+        ProjectCollection projectCollection,
+        ImmutableArray<CSharpDirective> directives,
+        Action<IDictionary<string, string>>? addGlobalProperties)
     {
         var projectRoot = CreateProjectRootElement(projectCollection);
 
@@ -1071,7 +1101,7 @@ ProjectRootElement CreateProjectRootElement(ProjectCollection projectCollection)
             var projectFileWriter = new StringWriter();
             WriteProjectFile(
                 projectFileWriter,
-                Directives,
+                directives,
                 isVirtualProject: true,
                 targetFilePath: EntryPointFileFullPath,
                 artifactsPath: ArtifactsPath,
@@ -1611,6 +1641,30 @@ static bool Fill(ref WhiteSpaceInfo info, in SyntaxTriviaList triviaList, int in
         }
     }
 
+    /// <summary>
+    /// If there are any <c>#:project</c> <paramref name="directives"/>, expand <c>$()</c> in them and then resolve the project paths.
+    /// </summary>
+    public static ImmutableArray<CSharpDirective> EvaluateDirectives(
+        ProjectInstance? project,
+        ImmutableArray<CSharpDirective> directives,
+        SourceFile sourceFile,
+        DiagnosticBag diagnostics)
+    {
+        if (directives.OfType<CSharpDirective.Project>().Any())
+        {
+            return directives
+                .Select(d => d is CSharpDirective.Project p
+                    ? (project is null
+                        ? p
+                        : p.WithName(project.ExpandString(p.Name)))
+                       .ResolveProjectPath(sourceFile, diagnostics)
+                    : d)
+                .ToImmutableArray();
+        }
+
+        return directives;
+    }
+
     public static SourceText? RemoveDirectivesFromFile(ImmutableArray<CSharpDirective> directives, SourceText text)
     {
         if (directives.Length == 0)
@@ -1897,8 +1951,31 @@ public sealed class Package(in ParseInfo info) : Named(info)
     /// <summary>
     /// <c>#:project</c> directive.
     /// </summary>
-    public sealed class Project(in ParseInfo info) : Named(info)
+    public sealed class Project : Named
     {
+        [SetsRequiredMembers]
+        public Project(in ParseInfo info, string name) : base(info)
+        {
+            Name = name;
+            OriginalName = name;
+            UnresolvedName = name;
+        }
+
+        /// <summary>
+        /// Preserved across <see cref="WithName"/> calls.
+        /// </summary>
+        public string OriginalName { get; init; }
+
+        /// <summary>
+        /// Preserved across <see cref="ResolveProjectPath"/> calls.
+        /// </summary>
+        /// <remarks>
+        /// When MSBuild <c>$(..)</c> vars are expanded via <see cref="WithName"/>,
+        /// the <see cref="UnresolvedName"/> will be expanded, but not resolved
+        /// (i.e., can be pointing to project directory or file).
+        /// </remarks>
+        public string UnresolvedName { get; init; }
+
         public static new Project? Parse(in ParseContext context)
         {
             var directiveText = context.DirectiveText;
@@ -1908,11 +1985,32 @@ public sealed class Project(in ParseInfo info) : Named(info)
                 return context.Diagnostics.AddError<Project?>(context.SourceFile, context.Info.Span, string.Format(CliCommandStrings.MissingDirectiveName, directiveKind));
             }
 
+            return new Project(context.Info, directiveText);
+        }
+
+        public Project WithName(string name, bool preserveUnresolvedName = false)
+        {
+            return name == Name && (preserveUnresolvedName || UnresolvedName == name)
+                ? this
+                : new Project(Info, name)
+                {
+                    OriginalName = OriginalName,
+                    UnresolvedName = preserveUnresolvedName ? UnresolvedName : name,
+                };
+        }
+
+        /// <summary>
+        /// If the directive points to a directory, returns a new directive pointing to the corresponding project file.
+        /// </summary>
+        public Project ResolveProjectPath(SourceFile sourceFile, DiagnosticBag diagnostics)
+        {
+            var directiveText = Name;
+
             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(context.SourceFile.Path) ?? ".";
+                // Also normalize backslashes 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))
                 {
@@ -1930,18 +2028,10 @@ public sealed class Project(in ParseInfo info) : Named(info)
             }
             catch (GracefulException e)
             {
-                context.Diagnostics.AddError(context.SourceFile, context.Info.Span, string.Format(CliCommandStrings.InvalidProjectDirective, e.Message), e);
+                diagnostics.AddError(sourceFile, Info.Span, string.Format(CliCommandStrings.InvalidProjectDirective, e.Message), e);
             }
 
-            return new Project(context.Info)
-            {
-                Name = directiveText,
-            };
-        }
-
-        public Project WithName(string name)
-        {
-            return new Project(Info) { Name = name };
+            return WithName(directiveText, preserveUnresolvedName: true);
         }
 
         public override string ToString() => $"#:project {Name}";