Warn for missing shebang by jjonescz · Pull Request #53614 · dotnet/sdk

jjonescz · 2026-03-27T12:26:29Z

Copilot

Pull request overview

This PR introduces a new analyzer warning (CA2266) and code fix to help IDEs reliably identify the entry point in multi-file file-based programs by requiring a #! shebang on the entry-point file, and wires up the SDK to provide the entry point file path to analyzers.

Changes:

Add CA2266 analyzer + code fix for missing shebang in multi-file file-based programs (based on EntryPointFilePath).
Plumb EntryPointFilePath through the file-based virtual project and generated editorconfig so analyzers can identify the entry point.
Add SDK/integration tests, analyzer unit tests, docs, and resource/localization updates for the new rule.

Reviewed changes

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

Show a summary per file

File	Description
test/dotnet.Tests/CommandTests/Run/RunFileTests.cs	Adds an end-to-end `dotnet run Program.cs` test validating CA2266 behavior (only for `#:include` entry points missing a shebang) and updates expected virtual project content.
src/Microsoft.DotNet.ProjectTools/VirtualProjectBuilder.cs	Adds `<EntryPointFilePath>` to the generated virtual project so the entry point path can be surfaced to analyzers.
src/Microsoft.CodeAnalysis.NetAnalyzers/tests/Microsoft.CodeAnalysis.NetAnalyzers.UnitTests/Microsoft.NetCore.Analyzers/Usage/MissingShebangInFileBasedProgramTests.cs	Adds analyzer/codefix unit tests for CA2266.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Utilities/Compiler/Options/MSBuildPropertyOptionNames.cs	Adds `EntryPointFilePath` to the known MSBuild property option names.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Utilities/Compiler/DiagnosticCategoryAndIdRanges.txt	Extends the Usage range to include CA2266.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.zh-Hant.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.zh-Hans.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.tr.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.ru.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.pt-BR.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.pl.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.ko.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.ja.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.it.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.fr.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.es.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.de.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/xlf/MicrosoftNetCoreAnalyzersResources.cs.xlf	Adds new localized resource entries for CA2266 strings (pending translation).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/MissingShebangInFileBasedProgram.cs	Introduces the shared diagnostic descriptor for CA2266.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/MissingShebangInFileBasedProgram.Fixer.cs	Adds the shared abstract code fix provider base for CA2266.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/MicrosoftNetCoreAnalyzersResources.resx	Adds CA2266 title/message/description and code fix title strings.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/AnalyzerReleases.Unshipped.md	Registers CA2266 as a new unshipped rule.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers.sarif	Adds CA2266 metadata to the SARIF rule set.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers.md	Adds documentation entry for CA2266.
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.CSharp.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/CSharpMissingShebangInFileBasedProgram.cs	Implements the C# analyzer logic for CA2266 (checks entry point tree for shebang; reports only when multiple non-generated trees exist).
src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.CSharp.NetAnalyzers/Microsoft.NetCore.Analyzers/Usage/CSharpMissingShebangInFileBasedProgram.Fixer.cs	Implements the C# code fix to prepend `#!/usr/bin/env dotnet` with appropriate EOL.
src/Cli/dotnet/Commands/Run/CSharpCompilerCommand.Generated.cs	Exposes `EntryPointFilePath` to analyzers via generated editorconfig build_property.
documentation/general/dotnet-run-file.md	Documents the new `EntryPointFilePath` exposure and the CA2266 behavior for multi-file file-based programs.

jasonmalinowski · 2026-03-30T23:04:36Z

+                    Interlocked.CompareExchange(ref pendingDiagnostic, location.CreateDiagnostic(Rule), null);
+                });
+
+                context.RegisterCompilationEndAction(context =>


CompilationEnd we don't run in the IDE as live diagnostics; I'm not sure if that's problematic for your scenarios or not. This might be rewritable to some code that would just look at the initial compilation and find the tree that matches the entry point file path, and then you could move the reporting of the diagnostic to when nonGeneratedTreeCount == 2. Somebody else might have a better idea here too...

Thanks, I haven't realized CompilationEnd doesn't run in IDE. Changed.

jasonmalinowski · 2026-03-30T23:05:32Z

    string? directoryPath = AppContext.GetData("EntryPointFileDirectoryPath") as string;
    ```

+  - `EntryPointFilePath` property is set to the entry-point file path and is made visible to analyzers via `CompilerVisibleProperty`.


There's a part of me that really feels like this should be something more like a CompilationOption rather than just being passed along as an MSBuild property but I'm not really sure what we'd actually gain with that.

Well, we have the feature flag FileBasedProgram (which causes roslyn to allow #: and #! directives). We could pass the entry point file path as its value I guess. Feature flags are part of parse options. But I also don't know what we'd gain with that.

csc has the -main switch today, but, it takes a type name, not a file path..

-main:<type> Specify the type that contains the entry point (ignore all other possible entry points) (Short form: -m)

I think that using a compiler-visible msbuild property is the right notch on the dial for the time being.

jasonmalinowski · 2026-03-30T23:09:13Z

+                }
+            }
+
+            return Environment.NewLine;


We should have a better answer for this, since there's still .editorconfig settings and the editor to use here as a hint. Looks like for the file header fix we do this:
https://github.com/dotnet/roslyn/blob/106890564f33f6642b625e99bed73b3e9a15244e/src/Analyzers/Core/CodeFixes/FileHeaders/AbstractFileHeaderCodeFixProvider.cs#L48-L50

@JoeRobich or @akhera99 any ideas here?

I want to say you can annotate the node and it will be formatted when applied.

Here it is

https://github.com/dotnet/roslyn/blob/106890564f33f6642b625e99bed73b3e9a15244e/src/Workspaces/Core/Portable/Formatting/Formatter.cs#L26-L29

I want to say you can annotate the node and it will be formatted when applied.

It doesn't look like that's happening for newlines inside a trivia like this though.

Looks like for the file header fix we do this:

Updated to do a similar thing here.

jasonmalinowski · 2026-03-30T23:13:44Z

+                    var eol = GetEndOfLine(root.SyntaxTree.GetText());
+                    var shebangTrivia = SyntaxFactory.ParseLeadingTrivia("#!/usr/bin/env dotnet" + eol);
+                    var firstToken = root.GetFirstToken(includeZeroWidth: true);
+                    var newFirstToken = firstToken.WithLeadingTrivia(shebangTrivia.AddRange(firstToken.LeadingTrivia));


Where should this go relative to copyright headers?

#! always needs to be first otherwise it wouldn't be recognized by shells. I remember we already discussed this and the copyright header analyzers should be already handling #! correctly.

jasonmalinowski · 2026-03-30T23:15:49Z

+                {
+                    Interlocked.Increment(ref nonGeneratedTreeCount);
+
+                    if (!context.Tree.FilePath.Equals(entryPointFilePath, StringComparison.OrdinalIgnoreCase))


The "IgnoreCase" here may be problematic on Linux/Mac, since file names are case sensitive there.

I guess the file names should be consistent since they come from the same tooling so we can just use Ordinal everywhere.

jjonescz · 2026-04-01T08:40:30Z

+        /// the <c>generated_code</c> analyzer config option,
+        /// common file name patterns, and <c>&lt;auto-generated&gt;</c> comment headers.
+        /// </summary>
+        private static bool IsGeneratedCode(SyntaxTree tree, AnalyzerConfigOptionsProvider optionsProvider)


I don't like hardcoding this knowledge here, but don't know how to better do this.

At first I thought: just indicate that the analyzer shouldn't run on generated code, and see if you get called back for a given syntax tree or not. But I think that doesn't work, since it would need the "compilation end" callback to run.

I think copying the implementation like you did is the best we can do for now.

I would recommend adding a permalink here to the location in Roslyn this was based on though.

RikkiGibson · 2026-04-07T22:52:02Z

+                }
+
+                // Only report when there are multiple non-generated files
+                // (i.e., #:include directives are used).


I guess this has the effect of also detecting when a Directory.Build.props adds a compile item? Is that right?

I think if it is a goal to handle that case, then, it should have a test

RikkiGibson · 2026-04-07T22:56:04Z

+                    }
+
+                    var root = context.Tree.GetRoot(context.CancellationToken);
+                    if (root.GetLeadingTrivia().Any(SyntaxKind.ShebangDirectiveTrivia))


Are we counting on the fact that if the #! appears somewhere besides position 0, then the compiler reports an error?

Yes, I'll add a test to demonstrate.

RikkiGibson · 2026-04-08T01:59:52Z


+## [CA2266](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2266): File-based program entry point should start with '#!'
+
+When a file-based program consists of multiple files, the entry point file should start with a shebang ('#!') line to clearly distinguish it from other included files.


It occurs to me that we may also want this when #:project or #:ref are used, so that find all references on symbols in the referenced projects works properly.

However, I don't wish to block on that.

Good idea, but I think that can be implemented as a follow up (filed #53749), since this PR should unblock us removing the experimental opt-in from #:include, so it'd be good to merge just that part first.

RikkiGibson

Overall LGTM just had some minor comments.

333fred · 2026-04-08T23:08:26Z

+                    ExpectedDiagnostics =
+                    {
+                        new DiagnosticResult(MissingShebangInFileBasedProgram.Rule).WithLocation("Test0.cs", 1, 1),
+                        // Preprocessor directives must appear as the first non-whitespace character on a line


Do we have a tracking bug somewhere for this nonsensical error? #! is the first non-whitespace character on its line, that's not the issue.

Filed dotnet/roslyn#83111, thanks.

jjonescz · 2026-04-09T09:10:45Z

/ba-g unrelated test failures, same as in #53759

Warn for missing shebang

0fe80a0

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

jjonescz added 8 commits March 27, 2026 14:04

Update doc and sarif files

a3d03da

Fixup

3e41a04

Change namespace to Usage

75365b8

Document EntryPointFilePath

f924d63

Add fixer

e44e29d

Fixup

e9f6254

Remove tmp file

39f4c95

Improve tests

162a08a

jjonescz marked this pull request as ready for review March 28, 2026 13:30

jjonescz requested a review from a team as a code owner March 28, 2026 13:30

Copilot AI review requested due to automatic review settings March 28, 2026 13:30

Copilot started reviewing on behalf of jjonescz March 28, 2026 13:31 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

Comment thread ...alyzers.UnitTests/Microsoft.NetCore.Analyzers/Usage/MissingShebangInFileBasedProgramTests.cs

jjonescz requested a review from a team March 28, 2026 13:36

build-analysis Bot mentioned this pull request Mar 28, 2026

dotnet-watch tests failing #40006

Open

jasonmalinowski reviewed Mar 30, 2026

View reviewed changes

jjonescz added 2 commits March 31, 2026 15:36

Improve code

e5e3765

Fix checking generated code

df349de

jjonescz commented Apr 1, 2026

View reviewed changes

jjonescz requested review from JoeRobich, RikkiGibson and jasonmalinowski April 7, 2026 11:54

Enable the warning in .NET 10

4ae6b42

This was referenced Apr 7, 2026

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

[android-arm64] The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#6408

Open

RikkiGibson reviewed Apr 7, 2026

View reviewed changes

RikkiGibson reviewed Apr 8, 2026

View reviewed changes

Comment thread ...alyzers.UnitTests/Microsoft.NetCore.Analyzers/Usage/MissingShebangInFileBasedProgramTests.cs

RikkiGibson reviewed Apr 8, 2026

View reviewed changes

jjonescz mentioned this pull request Apr 8, 2026

Require #! for more file-based app scenarios #53749

Open

2 tasks

jjonescz added 4 commits April 8, 2026 12:16

Extend tests and docs

8f30601

Fixup tests

481d4ed

Fixup convert tests

54e9b4f

Make pre-existing test more resilient

1657410

RikkiGibson approved these changes Apr 8, 2026

View reviewed changes

333fred approved these changes Apr 8, 2026

View reviewed changes

jjonescz mentioned this pull request Apr 9, 2026

Misleading error for #! not being on the first line and column dotnet/roslyn#83111

Closed

Copilot AI mentioned this pull request Apr 9, 2026

Fix misleading error when #! appears anywhere other than the start of the file dotnet/roslyn#83112

Merged

jjonescz merged commit 815727a into dotnet:release/10.0.3xx Apr 9, 2026
25 of 28 checks passed

jjonescz deleted the sprint-shebang-warn-2 branch April 9, 2026 09:11

dotnet-maestro Bot mentioned this pull request Apr 9, 2026

[release/10.0.3xx] Source code updates from dotnet/sdk dotnet/dotnet#5946

Merged

jjonescz mentioned this pull request Apr 22, 2026

[automated] Merge branch 'release/10.0.4xx' => 'main' #54004

Closed


		## [CA2266](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2266): File-based program entry point should start with '#!'

		When a file-based program consists of multiple files, the entry point file should start with a shebang ('#!') line to clearly distinguish it from other included files.

Conversation

jjonescz commented Mar 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

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!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RikkiGibson Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

Uh oh!

RikkiGibson left a comment

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!

jjonescz commented Apr 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jjonescz Mar 31, 2026 •

edited

Loading

RikkiGibson Mar 31, 2026 •

edited

Loading