File based apps document has incorrect shebang recommendation

[jhudsoncedaron]

Type of issue

Code doesn't work

Description

This document: https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps

Reads: #!/usr/bin/env dotnet

Should read #!/usr/bin/env -S dotnet --

I originally thought it was busted in the code due to not finding a working invocation, but no, the one thing I didn't think of works. You can see some of the things I tried and wasted time on here: dotnet/sdk#53810 (comment)

Page URL

https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps

Content source URL

https://github.com/dotnet/docs/blob/main/docs/core/sdk/file-based-apps.md

Document Version Independent Id

d03da876-f782-a111-02b5-b87b2cedad11

Platform Id

bd9ae45e-1b55-0e01-0514-29c5f6c34d94

Article author

gewarren

Metadata

• ID: 646ac25f-6d99-4dfe-e8b3-d7de28a502ae
• PlatformId: bd9ae45e-1b55-0e01-0514-29c5f6c34d94
• Service: dotnet-fundamentals

[jjonescz]

As far as I understand, env -S might not be supported by all systems. Although it would be a slight breaking change, I think we could change dotnet file.cs ...args... to work same as dotnet run --file file.cs -- ...args... and then you could continue using just the simple #!/usr/bin/env dotnet.

[jhudsoncedaron]

@jjonescz : You're right, it is not. But both Linux and Mac OSX have env -S now. (Mac OSX is late to the party; older versions don't have it.)

[adegeo]

I tried reading through the linked discussion but I'm not understanding what's not working exactly. What OS are you using? I just tried a simple app.cs with the shebang and it worked fine, passing or not passing parameters. I tested on WSL Ubuntu 24.04, macOS 26 Tahoe, and Fedora 43.

But to make it clear in the docs, I need to understand where and what the limitation is exactly.

[jhudsoncedaron]

@adegeo : I think it's pretty obvious. If you use #!/usr/bin/env dotnet, some arguments to your script (such as --help) get intercepted by dotnet.

[adegeo]

Ahh thank you, that was the missing piece. When the parameter name matches one used by the dotnet CLI driver, it's consumed.

To accurately describe the problem and doc solution:

Shebang is a shortcut in running the dotnet command and passing the name of the file as a parameter. (technically dotnet then interprets dotnet app.cs as dotnet run app.cs).

Parameters are normally passed through from the command line to the app. However, when the parameter matches one used by the dotnet CLI driver, dotnet consumes the parameter. For example, ./app.cs -hello works fine and -hello is passed to app.cs. If ./app.cs -hello --help is used, the expanded command is dotnet run ./app.cs -hello --help, and dotnet responds to the --help parameter printing out help info about the dotnet run command.

This is only a problem if your app is using a parameter named the same as one of dotnet run's parameters. This probably most common with the --help parameter, it being a standard parameter to get help information.

#!/usr/bin/env -S dotnet -- would fix this issue by ensuring the parameters are passed after -- to force the dotnet CLI driver to use all parameters as parameters for the app. However, the -S parameter may not be supported on the shebang (according to the linked post).

The Shell Execution section of the article needs to be updated. The default shebang used should be #!/usr/bin/env -S dotnet --. Add a note in that section that describes the problem, briefly, and suggest #!/usr/bin/env dotnet as an alternative if -S isn't supported by your shell.