.CS File Format – Preprocessor

Rules for every directive

• A directive starts with #, which must be the first non-white-space character on its line. White space may separate the # from the name: # if DEBUG is valid.
• A directive takes up a whole line and cannot be split across lines.
• A single-line comment (//) may end a directive line. Delimited comments (/* */) are not allowed on it.
• Names are case-sensitive.
• Directives are not tokens. They are separate from the grammar, so they may appear in the middle of a declaration or expression, on lines of their own.

Defining symbols

#define identifier
#undef identifier

A conditional compilation symbol is defined or undefined. #define and #undef must come before the first token of the file. They apply from that point to the end of the file, so a symbol set in one file has no effect on another. A symbol may be defined more than once, and it may be undefined when it was never defined; neither is an error (clause 6.5.4).

The DefineConstants project property (-define option) defines symbols for every file. In one file #undef still removes it. The symbols true and false cannot be defined.

Conditional compilation

#if expression
    code
#elif expression
    code
#else
    code
#endif

Each of these directives is a line of its own, and they nest. The compiler compiles the section of the first condition that is true, or the #else section if none is. All other sections are skipped: their text is not turned into tokens, but the directives in them are still checked and nesting still counts, so an inner #if needs its #endif even in a skipped section.

#define VERBOSE

#if DEBUG && !VERBOSE
    Console.WriteLine("debug");
#elif (DEBUG == true) || VERBOSE
    Console.WriteLine("verbose");
#else
    Console.WriteLine("quiet");
#endif

Diagnostics

#error text
#warning text

These stop or warn the compilation at this point, with the text after the directive name as the message. #error reports CS1029. #warning reports CS1030. The text is not parsed, so it need not be quoted, and the whole line is the message.

The compiler treats #error version specially. It reports CS8304, with a message naming the compiler and language versions in use, which is the quickest way to find out what a project is compiled with.

#if !NET8_0_OR_GREATER
#error This code needs .NET 8 or later.
#endif

#warning Remove this workaround before release.

Regions

#region [text]
#endregion [text]

#region and #endregion mark a block that editors can fold. They have no effect on compiled code. They must be paired and may nest. A region may not overlap an #if block, but one may be fully inside the other. Any text after the directive is a name for the region.

#region Helpers
private static int Twice(int x) => x * 2;
#endregion

Line numbers

#line changes the line numbers and file names that the compiler reports. Code generators use it to point error messages back at the original source.

In the span form, the start and end are the line and column in the original file. The optional offset gives the column of the next line that maps to the first column of the span.

  _builder.Add("Time: ");
#line (2, 6) - (2, 27) 15 "page.razor"
  _builder.Add(DateTime.Now);

Nullable context

#nullable (C# 8) sets the two flags of the nullable context: the annotation flag decides whether ? on a reference type has effect, and the warning flag decides whether nullable warnings are given. A directive applies from its line to the next directive or the end of the file. It overrides the project’s Nullable setting.

The project property Nullable takes the values enable, disable, warnings and annotations. If it is not set, the default is disable. Files marked as generated (see File structure) start disabled regardless of the project, and can opt in with a directive.

Pragmas

#pragma pragma-name pragma-arguments

#pragma gives the compiler instructions for the file. The two pragmas below are recognised; the compiler warns about any other.

#pragma warning disable [warning-list]
#pragma warning restore [warning-list]

#pragma warning disable 414, CS3021
[CLSCompliant(false)]
public class C { int i = 1; }
#pragma warning restore CS3021

#pragma checksum "filename" "{guid}" "checksum-bytes"

File-based app directives

From the .NET 10 SDK, a single C# file can be built and run with no project file (see File structure). The C# compiler ignores any directive starting with #! or #:. The SDK reads them, and they produce warnings in a normal project build.