Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update ignored directives proposal after LDM #9215

Merged
merged 2 commits into from
Mar 14, 2025
Merged

Update ignored directives proposal after LDM #9215

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be5fac5
Update ignored directives proposal after LDM
jjonescz Mar 13, 2025
b89f2d1
Use `=` instead of `/` in the examples
jjonescz Mar 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 21 additions & 38 deletions proposals/ignored-directives.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,16 @@ Champion issue: <https://github.com/dotnet/csharplang/issues/3507>

## Summary

Add `#` directives to be used by tooling, but ignored by the language.
Add `#:` directive prefix to be used by tooling, but ignored by the language.

```cs
#!/usr/bin/dotnet run
#sdk Microsoft.NET.Sdk.Web
#package Microsoft.AspNetCore.OpenApi 9.0.2

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Builder();

app.MapGet("/", () => new { Message = "Hello, World!" })
.WithName("HelloWorld");
#:sdk Microsoft.NET.Sdk.Web
#:property TargetFramework=net11.0
#:property LangVersion=preview
#:package System.CommandLine=2.0.0-*

app.Run();
Console.WriteLine("Hello, World!");
```

## Motivation
Expand Down Expand Up @@ -51,8 +44,7 @@ PP_Ignored

PP_IgnoredToken
: '!'
| 'package'
| 'sdk'
| ':'
;
```

Expand All @@ -70,37 +62,34 @@ e.g., Roslyn will report an error if these directives are present in a file comp
(and tooling will remove these directives when migrating file-based programs to project-based programs).
That error should not be reported for the `#!` directive, it can be placed on any file because it might invoke some other tool than `dotnet run`.

Similarly, the compiler or SDK should still error/warn on unrecognized directives to "reserve" them for future use by the official .NET tooling.

<!--
## Drawbacks
-->

## Alternatives

### One ignored prefix
### Separate directives instead of one ignored prefix

Reusing an existing syntax form or introducing just a single new ignored prefix
would allow tooling to introduce new directives without needing to change the language spec.
However, we do not anticipate needing to add many directives.
- For `dotnet run file.cs` specifically, we aim to add only as few directives as possible,
and for anything more advanced, project-based programs should be used instead
(we don't want to have two ways to configure everything).
- In any case, it seems good if new directives are discussed and approved by the language design team
We could add each ignored directive to the language instead of introducing one ignored prefix.
- For `dotnet run file.cs` specifically, we might want to add only as few directives as possible,
and for anything more advanced, recommend users to eject to project-based programs instead
(i.e., avoid having two ways to configure everything).
- In any case, it might be good if new directives are discussed and approved by the language design team
since they are part of the overall C# language experience.

On the other hand, with one ignored prefix, we could allow file-based programs to specify any project metadata:

```cs
#!/usr/bin/dotnet run
#:sdk Microsoft.NET.Sdk.Web
#:property TargetFramework/net11.0
#:property LangVersion/preview
#:package System.CommandLine/2.0.0-*
#sdk Microsoft.NET.Sdk.Web
#property TargetFramework=net11.0
#property LangVersion=preview
#package System.CommandLine=2.0.0-*
#something // unrecognized directives would still be required by the language spec to be an error

Console.WriteLine("Hello, World!");
```

The compiler or SDK should still error/warn on unrecognized directives to "reserve" them for future use by the official .NET tooling.

### Other syntax forms

Other syntax forms could be used except for shebang which shells recognize only by `#!`.
Expand All @@ -125,7 +114,7 @@ However, the naming of the directive is less clear.

#### Sigil

We could reserve one sigil prefix (e.g., `#!`/`#@`/`#$`/`#:`) for any directives that should be ignored by the language.
We could reserve another sigil prefix (e.g., `#!`/`#@`/`#$`) for any directives that should be ignored by the language.
Note that `#!` would be interpreted as shebang by shells if it is at the first line of the file.

```cs
Expand All @@ -147,12 +136,6 @@ Documentation XML comments are more verbose and we would need to ensure they do
/// <package name="Microsoft.CodeAnalysis" version="4.14.0" />
```

## Open questions

### More directives

We can consider also `#tfm`.

<!--
## Links
-->
Expand Down