Language reference and fundamentals for file based programs (#46900)

* 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.

* Add file-based programs to get started

* Fix host location

And, set +x permissions on hello-world.cs

* Include file based programs in the structure

Include a description and small example of a file based program in the overview of the general structure of a C# program.

* Add file based programs to the command line

Add a brief description of file based programs in the command line section.

* Updates on top level statements

Final edits.

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>
Co-authored-by: David Pine <[email protected]>

* apply feedback.

---------

Co-authored-by: Genevieve Warren <[email protected]>
Co-authored-by: David Pine <[email protected]>

Author: 3 people

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/fundamentals/program-structure/index.md

@@ -1,29 +1,44 @@
 ---
 title: "General Structure of a Program"
 description: Learn about the structure of a C# program by using a skeleton program that contains all the required elements for a program.
-ms.date: 08/01/2024
+ms.date: 06/20/2025
 helpviewer_keywords: 
   - "C# language, program structure"
-ms.assetid: 5ae964a5-0ef0-40fe-88fb-6d1793371d0d
 ---
 # General Structure of a C# Program
 
 C# programs consist of one or more files. Each file contains zero or more namespaces. A namespace contains types such as classes, structs, interfaces, enumerations, and delegates, or other namespaces. The following example is the skeleton of a C# program that contains all of these elements.
 
 :::code language="csharp" source="snippets/toplevel-structure/Program.cs":::
 
-The preceding example uses [*top-level statements*](top-level-statements.md) for the program's entry point. Only one file can have top-level statements. The program's entry point is the first line of program text in that file. In this case, it's the `Console.WriteLine("Hello world!");`.
+The preceding example uses [*top-level statements*](top-level-statements.md) for the program's entry point. Only one file can have top-level statements. The program's entry point is the first text line of program text in that file. In this case, it's the `Console.WriteLine("Hello world!");`.
 You can also create a static method named [`Main`](main-command-line.md) as the program's entry point, as shown in the following example:
 
 :::code language="csharp" source="snippets/structure/Program.cs":::
 
-In that case the program will start in the first line of `Main` method, which is `Console.WriteLine("Hello world!");`
+In that case the program starts in the opening brace of `Main` method, which is `Console.WriteLine("Hello world!");`
+
+## Building and running C# programs
+
+C# is a *compiled* language. In most C# programs, you use the [`dotnet build`](../../../core/tools/dotnet-build.md) command to compile a group of source files into a binary package. Then, you use the [`dotnet run`](../../../core/tools/dotnet-run.md) command to run the program. (You can simplify this process because `dotnet run` compiles the program before running it if necessary.) These tools support a rich language of configuration options and command-line switches. The `dotnet` command line interface (CLI), which is included in the .NET SDK, provides many [tools](../../../core/tools/index.md) to generate and modify C# files.  
+
+Beginning with C# 14 and .NET 10, you can create *file based programs*, which simplifies building and running C# programs. You use the `dotnet run` command to run a program contained in a single `*.cs` file. For example, if the following snippet is stored in a file named `hello-world.cs`, you can run it by typing `dotnet run hello-world.cs`:
+
+:::code language="csharp" source="./snippets/file-based-program/hello-world.cs":::
+
+The first line of the program contains the `#!` sequence for Unix shells. The location of the `dotnet` CLI can vary on different distributions. On any Unix system, if you set the *execute* (`+x`) permission on a C# file, you can run the C# file from the command line:
+
+```bash
+./hello-world.cs
+```
+
+The source for these programs must be a single file, but otherwise all C# syntax is valid. You can use file based programs for small command-line utilities, prototypes, or other experiments. File based programs allow [preprocessor directives](../../language-reference/preprocessor-directives.md#file-based-programs) that configure the build system.
 
 ## Expressions and statements
 
 C# programs are built using *expressions* and *statements*. Expressions produce a value, and statements perform an action:
 
-An *expression* is a combination of values, variables, operators, and method calls that evaluates to a single value. Expressions produce a result and can be used wherever a value is expected. The following examples are expressions:
+An *expression* is a combination of values, variables, operators, and method calls that evaluate to a single value. Expressions produce a result and can be used wherever a value is expected. The following examples are expressions:
 
 - `42` (literal value)
 - `x + y` (arithmetic operation)