.CS File Format – File structure

Encoding and line endings

A .cs file is plain text. The standard requires every compiler to accept UTF-8 and allows it to accept other encodings. The Microsoft compiler first tries to read each file as UTF-8. A file in another encoding that uses characters beyond 7-bit ASCII needs the CodePage option (-codepage), which applies to every file in the compilation.

The file is turned into a sequence of Unicode characters, then into lines, tokens and directives (clause 6.1). These line terminators are all accepted, and a file may mix them:

Two changes are made at the end of the file, before it is split into tokens (clause 6.3.2). If the last character is Control-Z (U+001A), it is deleted. If the file is not empty and does not already end in a line terminator, a carriage return is added, so that the last line is always terminated.

Compilation units

A compilation unit is made of the parts below, in this order. Each part is optional. This grammar is simplified from clauses 14.2, 14.5 and 14.6:

CompilationUnit:
    {ExternAliasDirective}
    {GlobalUsingDirective}
    {UsingDirective}
    {GlobalAttributeSection}
    {Statement}
    {NamespaceMemberDeclaration}

Unlike Java, C# has no one-public-type rule and no link between names and folders. A file may declare any number of public types with any names, and may declare several namespaces. Preprocessor directives may appear between these parts, in lines of their own; see Preprocessor.

// Example.cs
extern alias Legacy;                 // extern aliases first

global using System.Text;            // then global usings
using System;                        // then using directives
using Legacy::Old.Api;

[assembly: CLSCompliant(true)]       // then global attributes

namespace Example;                   // file-scoped namespace

public class First { }
public class Second { }              // any number of public types

Using directives

A using directive makes names from elsewhere available without qualification (clause 14.6). It has no effect on what is linked into the program; the project’s references do that. All using directives in a compilation unit or a namespace must come before any members.

• A using namespace directive imports the types of that namespace only. It does not import nested namespaces, so using System; does not bring in System.IO.
• An alias is visible only in the compilation unit or namespace that declares it. It may name a constructed generic type, using L = System.Collections.Generic.List<int>;, but it cannot take type parameters of its own.
• From C# 12 an alias may name any type, including tuples, arrays, pointers and nullable value types: using Point = (int X, int Y);. A pointer alias needs using unsafe.
• Using directives inside a namespace declaration apply only there.
• A name that two imported namespaces both supply is an error only where it is used.

global using System.Text;
global using Json = System.Text.Json.JsonSerializer;
global using static System.Console;

File-scoped namespaces

A file-scoped namespace (C# 10) is written namespace Name;. All the types in the file belong to it, with no extra braces or indentation. See Namespaces for the full rules. A file may have only one, it must precede every type in the file, and it cannot be used alongside top-level statements or block-scoped namespaces.

namespace Shop.Billing;

public class Invoice { }

Top-level statements

Since C# 9, one file in a program may hold statements directly in the compilation unit, with no Main method (clause 7.1.3). The compiler turns them into the program’s entry point.

using System.Text;

StringBuilder builder = new();
foreach (var arg in args)
    builder.AppendLine(arg);
Console.WriteLine(builder.ToString());
return 0;

class Helper { }        // types and namespaces go after the statements

• Only one file in a project may have top-level statements. The project cannot have another entry point, and the StartupObject option (-main) cannot be used.
• Using directives come first in that file. Types and namespaces come after the statements.
• The statements are in the global namespace.
• The contextual keyword args names the command-line arguments as a string[]. It is never null; it is empty when there are no arguments.
• Local variables and local functions declared in the statements belong to the generated method, not to any type.

The signature of the generated entry point depends on what the statements contain:

A program written the older way has a static Main method in a class. It may take string[] or nothing, and may return void, int, Task or Task<int> (clause 7.1).

File-based apps

From the .NET 10 SDK a single .cs file can be run with no project file: dotnet run file.cs, or dotnet file.cs, and it may hold directives for the build, placed at the top of the file. The C# compiler ignores these directives; the build tools read them. They are listed on the Preprocessor page.

#!/usr/bin/env -S dotnet --
#:package Spectre.Console@*

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

Partial files

A type may be split across several declarations, usually in several files, by marking each declaration partial (C# 2, clause 15.2.7). The compiler treats all the parts as one declaration. Designers and source generators use this to keep generated code apart from hand-written code.

// Order.cs
public partial class Order
{
    public decimal Total { get; }
    partial void OnCreated();
}

// Order.Generated.cs
public partial class Order : ISerializable
{
    partial void OnCreated() { }
}

• All parts must carry partial and be in the same assembly, module and namespace, with the same name and the same type parameters.
• partial can be used on classes, structs, interfaces and records. It must come immediately before class, struct, interface or record.
• Modifiers, attributes, base interfaces and members from every part are combined. A part may repeat a modifier, but parts cannot contradict each other.
• A class has at most one base class, which may be named in more than one part if all name the same one.

Partial members let one part declare a member and another implement it; see Classes for partial methods, properties, indexers, events and constructors.

File-local types

The file modifier (C# 11) limits a type to the file that declares it. Other files can declare a type with the same name without conflict. It is meant mainly for source generators.

file class Helper
{
    public static void Log(string text) => Console.WriteLine(text);
}

A file-local type must be a top-level type, not nested, and cannot be partial across different files. It cannot appear in the public signature of a type that is not itself file-local.

File names and projects

The language places no rules on file names. By convention a file is named after the type it holds, so Invoice is in Invoice.cs, and the folders follow the namespaces. Program.cs usually holds the entry point. A project normally compiles every **/*.cs file below its folder; the .csproj project file only lists exceptions.

Some file names mark a file as generated code. The compiler applies a disabled nullable context to these, and analysers commonly treat them differently:

• names starting with TemporaryGeneratedFile_
• names ending in .designer.cs, .generated.cs, .g.cs or .g.i.cs
• files with <auto-generated> or <auto-generated/> in a comment that is the first element of the file
• files with generated_code = true in .editorconfig

The language version a file is compiled with comes from the project, not the file: the <LangVersion> property sets it, and the default depends on the target framework. See Versions.