.CS File Format – Lexical structure

XML documentation comments

A /// or /** comment placed directly before a type or member is an XML documentation comment (annex D). With the GenerateDocumentationFile project property or the -doc option, the compiler collects these into a .xml file. It checks that the text is well-formed XML and that cref and param references resolve, and warns if they do not.

/// <summary>Returns the larger of two values.</summary>
/// <param name="a">The first value.</param>
/// <param name="b">The second value.</param>
/// <returns><paramref name="a"/> if it is not smaller, otherwise <paramref name="b"/>.</returns>
/// <seealso cref="Math.Max(int, int)"/>
public static int Larger(int a, int b) => a >= b ? a : b;

These are the tags recommended by the standard (annex D.3). The compiler checks only the ones marked:

A cref is written to the output file as an ID string whose first character gives the kind of element: N namespace, T type, F field, P property or indexer, M method, E event, and ! for an error.

Unicode escapes

A Unicode escape is \uXXXX or \UXXXXXXXX with four or eight hexadecimal digits (clause 6.4.2). Unlike in Java, escapes are not replaced before tokenising. They are processed only in identifiers, character literals and regular string literals. Elsewhere they have no meaning, so one cannot write a keyword or a brace with an escape. Only one level is decoded: "\u005Cu005C" is \u005C as text, not a backslash.

The @ prefix

The prefix @ lets a keyword be used as an identifier, which is useful when calling code from other languages: int @class = 1;. The @ is not part of the name, so @foo and foo are the same identifier. The prefix is also allowed on a word that is not a keyword, though that is poor style.

The underscore

_ is an ordinary identifier. In some positions it is instead a discard: _ = Compute();, out _, and patterns. See Variables.

Contextual keywords

These words are keywords only in certain places. Everywhere else they are ordinary identifiers, so old code that uses them as names still compiles. New keywords are almost always added this way. Since C# 11 the compiler warns when a type name is all lower-case ASCII, because such names may become keywords.

The specification also treats Cdecl, Stdcall, Thiscall and Fastcall as contextual, in function pointer declarations. Writing @await uses a contextual keyword as an identifier, just as with reserved keywords. Unlike ordinary identifiers, a contextual keyword cannot contain Unicode escapes when it is used as a keyword.

Integer literals

There are no octal literals: a leading zero means nothing, so 010 is ten.

• Digit separators (C# 7.0) are underscores between digits, any number of them: 1_000_000, 0xFFFF_FFFF. C# 7.2 also allows one after the prefix, 0x_FF. They may not be at the start or end of the digits.
• Use L rather than l, which looks like 1; the compiler warns about l.
• 2147483648 (2³¹) with no suffix, written directly after unary minus, gives int.MinValue; likewise 9223372036854775808 (2⁶³) with no suffix or L gives long.MinValue. A value that fits no type is an error.

Real literals

• Digits are required after a decimal point: 1.3F is a real literal, 1.F is not. .5 and 1e10 are real literals. 1f, 1d and 1m are real literals without a point.
• There is no hexadecimal real literal.
• Digit separators work here too: 3.141_593.
• float and double values use IEC 60559 round to nearest, with ties to even. A literal too large for its type is a compile-time error, so a real literal never produces infinity; a non-zero literal may round to zero. A decimal literal is rounded to the nearest value with banker’s rounding, and keeps the scale written unless rounded, so 2.900m is the value 2.9 with a scale of 3.
• A real literal cannot produce infinity or NaN. Use double.PositiveInfinity and double.NaN.

Character literals

A character literal is one character or one escape sequence in single quotes. It holds one UTF-16 code unit, so a character beyond U+FFFF cannot be written as a char literal; a string or a surrogate pair must be used instead.

Escape sequences

\x takes as many digits as it can, up to four, so "\x1E2" is a single character (U+01E2), not U+001E then "2". Using \u avoids this surprise. A backslash before any other character is an error. There is no octal escape.

String literals

Each kind of string literal below is a string. Equal literals in the same assembly refer to the same string instance (clause 6.4.5.6). Add u8 to make a UTF-8 literal instead (see below).

string path = @"C:\Users\Example";
string text = @"First line
second line, ""quoted""";

double pi = 3.14159;
$"pi is {pi:F2}";              // "pi is 3.14"
$"[{42,6}] [{42,-6}]";         // "[    42] [42    ]"
$"{{ literal braces }} {pi}";  // "{ literal braces } 3.14159"
$"{(pi > 3 ? "big" : "small")}";  // conditional in parentheses

{ interpolation_expression [, alignment] [: format_string] }

var single = """This is "raw" and \ is just a backslash.""";

var xml = """
    <element attr="content">
        <body/>
    </element>
    """;
// "<element attr=\"content\">\n    <body/>\n</element>"

var more = """"
    The text contains """ three quotes.
    """";

int n = 1;
var json = $$"""
    {
        "value": {{n}}
    }
    """;