In C# 11 and later, what does the file modifier restrict on a type, and why do source generators declare their helper types with it?
answer
- narrower than internal
- one source file, not one assembly
- same name in two files, no clash
- never in a wider type's signature
basics
~20 sA type declared with the file modifier (C# 11) is visible only inside the source file that declares it. Two files can each declare a file-local Formatter without a name clash, which is why source generators use it for helper types.
solid answer
~40 s`file class Formatter` makes the type **file-local**: code in other source files of the same assembly cannot name it and gets CS0246 as if it did not exist. Several files may declare their own file-local type with the same name, and lookup inside a file prefers its own file-local type. `file` is not an access modifier and cannot be combined with one (CS9052); it is allowed only on top-level types (CS9054). A file-local type cannot appear in the signature of a non-file-local type (CS9051) or be its base class (CS9053), though a public class may implement a file-local interface. Generators emit helpers this way so they never collide with user code or with each other.
code
csharp · 16 linesvar report = new ReportBuilder();
Console.WriteLine(report.Build());
Console.WriteLine(typeof(Formatter).IsPublic);
file static class Formatter // visible only in this source file
{
public static string Cents(int cents) => $"{cents / 100}.{cents % 100:D2}";
}
file interface IRendered { string Kind { get; } }
public class ReportBuilder : IRendered // a public type may implement a file-local interface
{
public string Build() => $"{((IRendered)this).Kind}: {Formatter.Cents(1250)}";
string IRendered.Kind => "invoice";
}go deeper
Recall that file (C# 11) limits a top-level type to its own source file, and that it is narrower than internal.
Explain the CS9051 and CS9053 rules as the same leak check that drives CS0050, and why same-file lookup preference matters to generators.
Use file-local types in generator output and for single-use helpers, and know they are compile-time scoping only: reflection still sees them.
Set a rule for generated code: helpers file-local, nothing a user might name; it keeps generator upgrades from breaking consumers who bound to accidental internals.
## What `file` adds to the access levels Before C# 11 the narrowest scope a top-level type could have was `internal`: the whole assembly. C# 11 added the **`file` modifier**, which shrinks a top-level type's visibility to **the single source file** that declares it. The compiler accepts it from C# 11 on (the feature is listed under C# 11 in the compiler's feature table). ```csharp file static class Formatter { public static string Cents(int cents) => $"{cents / 100}.{cents % 100:D2}"; } ``` Code in the same file uses `Formatter` normally. Code in any other file of the project reports CS0246 ("The type or namespace name 'Formatter' could not be found"), exactly as if the type did not exist. ## Why source generators want it A **source generator** adds files to a compilation. Its helper types used to be `internal`, which meant they shared the assembly's namespace with the user's code and with other generators' output. A generator that emitted `internal static class Formatter` could collide with a user's own `Formatter`, or with the same generator's output for another class. File-local types remove that risk: - every file may declare its own `file class Formatter`, and these are distinct types; - **member lookup prefers a file-local type declared in the same file** over a type with the same name in another file, so the generator's code always binds to its own helper; - users never see the helper in IntelliSense or depend on it by accident. Hand-written code can use `file` the same way, for a tiny helper that exists to serve one class. ## The rules the compiler enforces | Rule | Diagnostic | |---|---| | `file` cannot be combined with `public`, `internal` or any other access modifier | CS9052 | | `file` is allowed only on top-level types, never on nested types | CS9054 | | A file-local type cannot appear in a member signature of a non-file-local type | CS9051 (with CS0050 or CS0051) | | A non-file-local type cannot derive from a file-local type | CS9053 (with CS0060) | | A file-local type cannot be used in a `global using static` directive | CS9055 | | Types and aliases cannot be named `file` | CS9056 | Points that surprise people: - `file` is **not** classified as an accessibility modifier. The type's accessibility is the default `internal`; `file` is an extra scope restriction on top. - A **public class may implement a file-local interface**. The implementation is fine; an explicit implementation can only be called from the declaring file, because only that file can name the interface for the cast. - Types nested inside a file-local type are file-local too. ## What it compiles to The proposal leaves the metadata name implementation-defined and expects `internal` accessibility with an unspeakable generated name. The 10.0.401 compiler emits names shaped like `<AuditLog>F…__Formatter`, mixing the file name and a hash, and `typeof(Formatter).IsPublic` reports `False`. Two consequences: 1. Reflection can still find the type, so `file` is a compile-time scoping tool, not a security boundary. 2. Code that searches for the type by a hard-coded metadata name is fragile; `typeof(Formatter)` inside the file is the reliable handle. ## Compared with the other ways to hide a helper | Declaration | Who can name it | Can two copies share a name? | |---|---|---| | `internal class Formatter` | every file in the assembly, plus friend assemblies | no, one per namespace in the assembly | | `private class Formatter` nested in `ReportBuilder` | only `ReportBuilder` and its nested types | yes, in different containing types | | `file class Formatter` | only its own source file | yes, one per file | A nested private class gives the same isolation but ties the helper to one containing type and lengthens that type's declaration. A file-local type keeps the helper beside the code that uses it without making it a member of anything. ## When to reach for it - Generated helper types, attribute types and extension classes that exist only to support one generated file. - A private helper you would otherwise nest inside a class, when nesting would clutter that class. - Not for anything another file needs: if two files must share a helper, it is an `internal` type.
- Can a public C# class implement a file-local interface, and who can call the implementation?Yes. A public class may implement a `file interface` implicitly or explicitly. Implicit implementations are ordinary public members anyone can call on the class. An explicit implementation is reachable only by casting to the interface, and only the declaring file can name that interface, so in practice only that file calls it.
- Does a file-local type hide the class from reflection?No. The compiler emits it as an ordinary internal type with a generated, unspeakable name, so `Assembly.GetTypes()` still returns it. The `file` modifier controls which source code can name the type at compile time; it does not protect it at run time.
- Says file can be combined with internal to mean file-and-assembly scope.
- Thinks a file-local type can be nested inside another class.
- Believes file-local types are invisible to reflection at run time.
- Says two files declaring the same file-local name cause a duplicate-type error.
- Thinks a public method may return a file-local type.