File-level directives: allow quoting and additional properties by jjonescz · Pull Request #55592 · dotnet/sdk

jjonescz · 2026-08-04T12:32:16Z

Resolves #52399.
Resolves #49367.
Docs: dotnet/docs#55352

azure-pipelines · 2026-08-04T12:32:34Z

Azure Pipelines: Successfully started running 2 pipeline(s). 1 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Pull request overview

This PR updates file-based program #: directive parsing/emission to support double-quoted values (for whitespace) and additional MSBuild item metadata on #:package, #:project, and #:ref, and adds a new analyzer (CA2267) to help migrate legacy unquoted-whitespace directives.

Changes:

Extend file-level directive parsing to support quoted values and trailing Name=Value metadata, and emit metadata into generated MSBuild items.
Add/expand CLI and conversion tests for quoting and metadata round-tripping.
Introduce CA2267 (“Prefer quoted file-based program directive values”) with code fix, plus documentation/resource updates.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/dotnet.Tests/CommandTests/Run/RunFileTests_Directives.cs	Adds E2E coverage for `#:ref` metadata emitted into `<ProjectReference>`.
test/dotnet.Tests/CommandTests/Run/FileBasedAppSourceEditorTests.cs	Tests directive editing/round-tripping with metadata and quoting.
test/dotnet.Tests/CommandTests/Project/Convert/DotnetProjectConvertTests.cs	Adds conversion tests for quoting/metadata and updates escaping/whitespace expectations.
src/Microsoft.CodeAnalysis.NetAnalyzers/tests/Microsoft.CodeAnalysis.NetAnalyzers.UnitTests/Microsoft.NetCore.Analyzers/Usage/PreferQuotedFileBasedProgramDirectiveTests.cs	New unit tests for CA2267 analyzer + fixer.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Utilities/Compiler/DiagnosticCategoryAndIdRanges.txt	Extends Usage ID range to include CA2267.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.zh-Hant.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.zh-Hans.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.tr.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.ru.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.pt-BR.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.pl.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.ko.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.ja.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.it.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.fr.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.es.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.de.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.cs.xlf	Adds localized entries for new CA2267 strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/PreferQuotedFileBasedProgramDirective.Fixer.cs	Adds shared fixer base for CA2267.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/PreferQuotedFileBasedProgramDirective.cs	Adds shared diagnostic descriptor for CA2267.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/MicrosoftNetCoreAnalyzersResources.resx	Adds CA2267 resource strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/AnalyzerReleases.Unshipped.md	Registers CA2267 in unshipped analyzer list.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers.sarif.template	Adds CA2267 to SARIF template metadata.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers.md	Adds generated documentation entry for CA2267.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.CSharp.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/FileBasedProgramDirectiveQuoting.cs	Adds shared quoting detection/rewrite logic for analyzer/fixer.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.CSharp.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/CSharpPreferQuotedFileBasedProgramDirective.Fixer.cs	Implements C# code fix for CA2267.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.CSharp.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/CSharpPreferQuotedFileBasedProgramDirective.cs	Implements C# analyzer for CA2267.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.zh-Hant.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.zh-Hans.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.tr.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.ru.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.pt-BR.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.pl.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.ko.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.ja.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.it.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.fr.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.es.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.de.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/xlf/FileBasedProgramsResources.cs.xlf	Adds localized CLI strings for new directive parsing errors.
src/Cli/Microsoft.DotNet.FileBasedPrograms/VirtualProjectBuilder.cs	Emits directive metadata as child elements on generated MSBuild items.
src/Cli/Microsoft.DotNet.FileBasedPrograms/InternalAPI.Unshipped.txt	Tracks new internal API surface for directive metadata properties.
src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs	Implements tokenization, quoted values, and metadata parsing for directives.
src/Cli/Microsoft.DotNet.FileBasedPrograms/FileBasedProgramsResources.resx	Adds/updates directive parsing error messages.
src/Cli/dotnet/Commands/Project/Convert/ProjectConvertCommand.cs	Preserves `#:ref` metadata when converting to a project.
documentation/general/dotnet-run-file.md	Documents quoting rules, legacy behavior, and new metadata support.

Suppressed comments (1)

src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs:565

Metadata element names are emitted directly into the generated project file. XmlConvert.VerifyName allows ':' (QName) which can yield invalid MSBuild XML without an xmlns declaration. Use VerifyNCName here to ensure generated elements are always safe.

            try
            {
                name = XmlConvert.VerifyName(name);
            }

Copilot

Pull request overview

Copilot reviewed 46 out of 46 changed files in this pull request and generated 1 comment.

Suppressed comments (5)

src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs:366

Token.ContainsDiagnostics is not specific to unterminated quotes; it will also be true for invalid escape sequences (e.g. "\q"). Reporting UnterminatedQuoteInDirective for all diagnostics can mislead users. Distinguish the unterminated-quote case (missing closing ") from other invalid string literal diagnostics and use InvalidQuoteInDirective for the latter.

                var token = SyntaxFactory.ParseToken(text, offset: i);
                if (token.ContainsDiagnostics)
                {
                    context.ReportError(FileBasedProgramsResources.UnterminatedQuoteInDirective);
                    return null;

src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs:572

Metadata names are emitted as XML element names. XmlConvert.VerifyName permits ':' (QName), which can yield invalid MSBuild XML when written as <a:b> without a namespace binding. Prefer XmlConvert.VerifyNCName here to prevent generating malformed project files.

            try
            {
                name = XmlConvert.VerifyName(name);
            }
            catch (XmlException ex)

src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs:563

ParseMetadata treats tokens like "=value" as valid because it only checks separatorIndex < 0. XmlConvert.VerifyName("") will throw, which can surface as an unhandled exception instead of a directive parse error. Treat separatorIndex <= 0 as invalid metadata and report InvalidDirectiveMetadata.

            var separatorIndex = token.IndexOf('=');
            if (separatorIndex < 0)
            {
                context.ReportError(string.Format(FileBasedProgramsResources.InvalidDirectiveMetadata, token));
                return null;

src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs:984

Ref.Metadata is left uninitialized (default ImmutableArray), unlike Package/Project which default to Empty. Default ImmutableArray can throw on common operations and forces callers to handle IsDefault. Initialize to ImmutableArray.Empty for consistency and safer consumption.

        public ImmutableArray<(string Name, string Value)> Metadata { get; init; }

test/dotnet.Tests/CommandTests/Run/RunFileTests_Directives.cs:350

The new RefDirective_Metadata test summary claims it validates that trailing #:ref metadata is emitted into the generated , but the test only asserts the app output. If metadata emission regresses (metadata dropped), the build/run would likely still succeed and this test would not fail. Add an assertion that inspects the generated virtual project and verifies test and a b c are present under the ProjectReference.

Copilot

Pull request overview

Copilot reviewed 48 out of 48 changed files in this pull request and generated 1 comment.

azure-pipelines · 2026-08-10T11:50:35Z

Azure Pipelines: Successfully started running 2 pipeline(s). 1 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

tannergooding · 2026-08-10T14:26:38Z

+
+namespace Microsoft.NetCore.Analyzers.Usage
+{
+    public abstract class PreferQuotedFileBasedProgramDirectiveFixer : CodeFixProvider


nit: Is this correct?

We changed nearly every other analyzer over to the SyntaxEditorBasedCodeFixProvider to ensure that all the hookups and handling are correct and done consistently, as well as ensuring that none of the issues with BatchFixer surface up.

The fixes that are being done for file-based program directives are a bit simpler, likely with no concern over nesting; but the lack of other features like supported fix-all scopes. ordering, etc should generally still be impactful

tannergooding · 2026-08-10T14:32:39Z

+    /// <summary>
+    /// Validates that <paramref name="name"/> is a valid XML NCName, the constraint MSBuild applies to
+    /// property and item-metadata names (an NCName additionally disallows the ':' that a plain XML name
+    /// permits). Returns <see langword="true"/> when valid; otherwise returns <see langword="false"/> and
+    /// sets <paramref name="errorMessage"/> to the underlying validation-failure message.
+    /// </summary>
+    public static bool IsValidMSBuildName(string name, out string? errorMessage)


There are some reserved MSBuild names like Identity that will cause the build to fail with

"Identity" is a reserved item metadata, and cannot be redefined as a custom metadata on the item. The build failed.

Is that something we have the capability of testing/filtering for?

In a similar vein, we're allowing cases like #:package Name@1.0 Version=2.0 which will have the latter override what we emit for the former. Feels like a likely bug if a user writes something like that; so perhaps such names should also be warned on.

Also duplicates where last one wins, so a user can write Prop=a Prop=b and then not understand that Prop=a is "overwritten"

tannergooding · 2026-08-10T14:45:01Z

+                        continue;
+                    }
+
+                    if (!FileBasedProgramDirectiveQuoting.TryGetQuotedForm(kind, value, out _))


This is causing it to bail and not report a diagnostic and seems to mismatch with how the SDK parsing works, right?

consider #:package Name@1.0 Property which hits the legacy path, so we won't get a diagnostic (because we cannot give a fix) even though the user should ideally be made aware they have something on the legacy pattern

tannergooding · 2026-08-10T14:48:12Z

+|-|-|
+|Category|Usage|
+|Enabled|True|
+|Severity|Warning|


Is warning the right severity here? The old form can be used correctly, its just harder and more error prone.

Is the justification that the old form is essentially deprecated or similar?

tannergooding · 2026-08-10T14:55:30Z

+{
+    // Characters that are not allowed in a directive or metadata name because they would be confused
+    // with a separator: whitespace, '@', '=', '/'.
+    private static readonly Regex s_disallowedNameCharacters = new("""[\s@=/]""", RegexOptions.Compiled);


Do we expect this to be frequent enough that Compiled is worthwhile? I'd expect compilations to last a very small amount of time and be thrown away, so we'd either want a source generated version or just the standard interpreted; otherwise we may be paying more for the regex compilation than the work we're actually doing (which is a handful of single lines, most of which are likely small)

tannergooding · 2026-08-10T14:59:18Z

+        [TestMethod]
+        public async Task MultipleDirectives_AllFixedAsync()
+        {
+            await new VerifyCS.Test


nit: We should have NumberOfFixAllIterations = 1 here. Nothing about this change should require 2 passes and so that ensures we're actually invoking FixAll and having it done as expected perf wise

tannergooding · 2026-08-10T14:59:58Z

+namespace Microsoft.NetCore.Analyzers.Usage.UnitTests
+{
+    [TestClass]
+    public class PreferQuotedFileBasedProgramDirectiveTests


We don't have any tests covering trivia preservation

tannergooding · 2026-08-10T15:01:07Z

+                async ct =>
+                {
+                    var text = await context.Document.GetTextAsync(ct).ConfigureAwait(false);
+                    return context.Document.WithText(text.Replace(triviaSpan, newDirectiveText));


This is going to reload the document for each individual fix in a multi-fix scenario, right?

That's why we have SyntaxEditorBasedCodeFixProvider instead to help force down the path that allows actually batching it all in a single pass?

jjonescz added 5 commits July 27, 2026 16:39

File-level directives: allow quoting and additional properties

2222f39

Simplify

7e135a6

Merge branch 'main' into 52399-sprint-directive-properties

34578d2

Support #:ref

341b944

Allow legacy unquoted forms

7366b31

jjonescz added the Area-run-file Items related to the "dotnet run <file>" effort label Aug 4, 2026

jjonescz added 2 commits August 4, 2026 15:02

Analyze non-entry-point files too

e1b1c1f

Revert unnecessary changes

d468556

jjonescz requested a review from Copilot August 6, 2026 13:33

Copilot started reviewing on behalf of jjonescz August 6, 2026 13:33 View session

Copilot AI reviewed Aug 6, 2026

View reviewed changes

Comment thread src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs Outdated

Comment thread src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs Outdated

Comment thread src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs

jjonescz added 2 commits August 6, 2026 16:26

Use roslyn lexer

d24bb6a

Add metadata name to the error message

4a410fe

jjonescz requested a review from Copilot August 6, 2026 14:48

Copilot started reviewing on behalf of jjonescz August 6, 2026 14:49 View session

Copilot AI reviewed Aug 6, 2026

View reviewed changes

Comment thread src/Cli/Microsoft.DotNet.FileBasedPrograms/FileLevelDirectiveHelpers.cs Outdated

jjonescz added 8 commits August 6, 2026 17:10

Propagate roslyn errors

264b0ee

Clarify raw string literal error

3cfff2b

Encapsulate name verification

f54f08f

Improve code

41afd00

Share logic

7d17d59

Turn it into a warning

ccf2f4a

Handle empty metadata name

7b3e283

Remove unnecessary test

65c983f

jjonescz requested a review from Copilot August 7, 2026 15:11

Copilot started reviewing on behalf of jjonescz August 7, 2026 15:12 View session

Copilot AI reviewed Aug 7, 2026

View reviewed changes

Comment thread src/Cli/Microsoft.DotNet.FileBasedPrograms/FileBasedProgramDirectiveValueHelpers.cs

Test directives that don't support metadata

c957743

jjonescz mentioned this pull request Aug 10, 2026

Add CA2267: Quote whitespace in file-based program directive values dotnet/docs#55352

Draft

Merge branch 'main' into 52399-sprint-directive-properties

bd8a5b0

jjonescz requested a review from a team August 10, 2026 11:50

jjonescz marked this pull request as ready for review August 10, 2026 11:50

jjonescz requested review from a team as code owners August 10, 2026 11:50

tannergooding reviewed Aug 10, 2026

View reviewed changes

Uh oh!

Conversation

jjonescz commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azure-pipelines Bot commented Aug 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

azure-pipelines Bot commented Aug 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jjonescz commented Aug 4, 2026 •

edited

Loading