publish spec and add preprocessor reference

First commit: Publish the C# speclet for ignored preprocessor directives, and make the updates for the ignored directives used for file based programs.

Author: BillWagner

docfx.json

@@ -61,7 +61,8 @@
                     "partial-events-and-constructors.md",
                     "null-conditional-assignment.md",
                     "extensions.md",
-                    "user-defined-compound-assignment.md"
+                    "user-defined-compound-assignment.md",
+                    "ignored-directives.md"
                 ],
                 "src": "_csharplang/proposals",
                 "dest": "csharp/language-reference/proposals",
@@ -533,7 +534,7 @@
                 "_csharplang/proposals/csharp-11.0/*.md": "09/30/2022",
                 "_csharplang/proposals/csharp-12.0/*.md": "08/15/2023",
                 "_csharplang/proposals/csharp-13.0/*.md": "10/31/2024",
-                "_csharplang/proposals/*.md": "04/08/2025",
+                "_csharplang/proposals/*.md": "06/19/2025",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "11/08/2022",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "11/08/2023",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "11/09/2024",
@@ -713,6 +714,7 @@
                 "_csharplang/proposals/null-conditional-assignment.md": "Null conditional assignment",
                 "_csharplang/proposals/extensions.md": "Extension members",
                 "_csharplang/proposals/user-defined-compound-assignment.md": "User-defined compound assignment",
+                "_csharplang/proposals/ignored-directives.md": "Ignored preprocessor directives",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "C# compiler breaking changes since C# 10",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "C# compiler breaking changes since C# 11",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "C# compiler breaking changes since C# 12",
@@ -838,6 +840,7 @@
                 "_csharplang/proposals/null-conditional-assignment.md": "This proposal allows the null conditional operator to be used for the destination of assignment expressions. This allows you to assign a value to a property or field only if the left side is not null.",
                 "_csharplang/proposals/extensions.md": "This proposal enables new kinds of extension members. These new extension members support extension properties, extension static members, including extension operators.",
                 "_csharplang/proposals/user-defined-compound-assignment.md": "This proposal introduces user-defined compound assignment operators. Developers can override compound assignment, increment, and decrement operators.",
+                "_csharplang/proposals/ignored-directives.md": "This proposal allows a source file to include ignored directives. In most cases, ignored directives are used for file based programs, for example `#!`",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "Learn about any breaking changes since the initial release of C# 10 and included in C# 11",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "Learn about any breaking changes since the initial release of C# 11 and included in C# 12",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "Learn about any breaking changes since the initial release of C# 12 and included in C# 13",

docs/csharp/language-reference/preprocessor-directives.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn the different C# preprocessor directives that control conditional compilation, warnings, nullable analysis, and more"
 title: "Preprocessor directives"
-ms.date: 01/14/2025
+ms.date: 06/19/2025
 f1_keywords:
   - "cs.preprocessor"
   - "#nullable"
@@ -20,6 +20,10 @@ f1_keywords:
   - "#pragma warning"
   - "#pragma checksum"
   - "defaultline_CSharpKeyword"
+  - "#!"
+  - "#:sdk"
+  - "#:property"
+  - "#:package"
 helpviewer_keywords:
   - "preprocessor directives [C#]"
   - "keywords [C#], preprocessor directives"
@@ -43,6 +47,63 @@ helpviewer_keywords:
 
 Although the compiler doesn't have a separate preprocessor, the directives described in this section are processed as if there were one. You use them to help in conditional compilation. Unlike C and C++ directives, you can't use these directives to create macros. A preprocessor directive must be the only instruction on a line.
 
+## File based programs
+
+*File based programs* are programs that are compiled and run using `dotnet run Program.cs` (or any `*.cs` file). The C# compiler ignores these preprocessor directives, but the build system parses them to produce the output. These directives generate warnings when encountered in a project-based compilation.
+
+The C# compiler ignores any preprocessor directive that starts with `#:` or `#!`.
+
+The `#!` preprocessor directive enables unix shells to directly execute a C# file using `dotnet run`. For example:
+
+```csharp
+#!/usr/bin/dotnet run
+Console.WriteLine("Hello");
+```
+
+The preceding code snippet informs a unix shell to execute the file using `/usr/bin/dotnet run`. The `#!` line must be the first line in the file, and the following tokens are the program to run. You need to enable the *execute* (`x`) permission on the C# file for that feature.
+
+The `#:` directives that are used in file based programs include:
+
+- `#:sdk`:
+
+  The first instance specifies the value for the `<Project Sdk="value" />` node. Subsequent instances specify `<Sdk Name="value" Version="version" />` node. The version can be omitted. For example:
+
+  ```csharp
+  #:sdk Microsoft.NET.Sdk.Web
+  ```
+
+- `#:property`:
+
+  Instances of `#:property` are translated into property elements in a `<PropertyGroup>`. A token of the form `Name=value` must follow the `property` token. The following are valid `property` tokens:
+
+  ```csharp
+  #:property TargetFramework=net11.0
+  #:property LangVersion=preview
+  ```
+
+  The preceding two properties are translated into:
+
+  ```xml
+  <TargetFramework>net11.0</TargetFramework>
+  <LangVersion>preview</LangVersion>
+  ```
+
+- `#:package`:
+
+  Instances `#:package` are translated into `PackageReference` elements to include NuGet packages with the specified version to your file. For example:
+
+  ```csharp
+  #:package [email protected]*
+  ```
+
+  The preceding preprocessor token is translated into:
+
+  ```xml
+  <PackageReference Include="System.CommandLine" Version="2.0.0-*">
+  ```
+  
+Tools can add new tokens following the `#:` convention.
+
 ## Nullable context
 
 The `#nullable` preprocessor directive sets the *annotations* and *warning* flags in the  *nullable context*. This directive controls whether nullable annotations have effect, and whether nullability warnings are given. Each flag is either *disabled* or *enabled*.

docs/csharp/specification/toc.yml

@@ -79,6 +79,8 @@ items:
       href: ../../../_csharplang/proposals/csharp-10.0/enhanced-line-directives.md
     - name: "Escape sequence '\\e'"
       href: ../../../_csharplang/proposals/csharp-13.0/esc-escape-sequence.md
+    - name: "Ignored directives"
+      href: ../../../_csharplang/proposals/ignored-directives.md
   - name: Basic concepts
     items:
     - name: Top-level statements