What are nested types in C#? Explain how a nested class differs from a Java inner class, what it can access in the outer type, default accessibility, and when nested types are a good or a bad design choice.

1. Representation in metadata

Nested types are stored with a NestedClass table entry linking them to their enclosing type. Their full metadata name uses +: MyApp.Order+Line (that's what you see in Type.FullName, stack traces and reflection). In C# source you write Order.Line. typeof(Order.Line).IsNested is true; DeclaringType returns Order.

2. Accessibility checks

The CLR enforces accessibility, and nested types are considered "inside" their enclosing type for private access. That's why a nested class can access private fields of the outer type — the access check treats the nested type's code as part of the outer type. For nested-in-generic types, Outer<int>.Inner and Outer<string>.Inner are distinct types.

3. Private constructors and closed hierarchies

public abstract class Shape
{
    private Shape() { }
    public sealed class Circle(double r) : Shape { public double R { get; } = r; }
    public sealed class Square(double s) : Shape { public double S { get; } = s; }
}

Because the base constructor is private, only nested types can call it, so the set of subclasses is fixed. Pattern matching still requires a discard arm (the compiler doesn't treat the hierarchy as closed), but the design communicates and enforces closure. Some analysers and libraries (e.g. Dunet, OneOf) build on similar patterns.

4. Nested types and generics

public class Cache<TKey, TValue>
{
    private sealed class Entry { public TValue Value = default!; public DateTimeOffset Expires; }
    private readonly Dictionary<TKey, Entry> _entries = new();
}

Entry automatically uses TValue. Each closed generic gets its own Entry type. This is neat for private helpers; for public nested types in generic classes, callers must write Cache<string, int>.Entry, which is clunky.

5. BCL examples

• List<T>.Enumerator, Dictionary<TKey,TValue>.KeyCollection — public nested types tightly coupled to their outer type (exposed for performance and foreach pattern binding).
• Environment.SpecialFolder — a nested enum.
• HttpClientHandler internals use many private nested helpers.

The guidelines allow public nested types when they're rarely referenced by name or tightly bound to the outer type (enumerators), and discourage them for commonly used types.

6. Nested types vs file-scoped types

C# 11's file access modifier (file class Helper) restricts a top-level type to its source file — another way to hide helpers without nesting, especially useful for source generators to avoid name collisions. Use nesting when the helper needs the outer type's private members; use file when it just needs to be invisible elsewhere.

Try it yourself

1. Print typeof(Order.Line).FullName and observe the +.
2. Access a private field of the outer type from a nested class, then try the reverse.
3. Build a closed result hierarchy with a private base constructor and try to derive from it outside.
4. Replace a private nested helper with a file-scoped class and compare.

public sealed class RateLimiter(int permits)
{
    private int _available = permits;
    private readonly Lock _lock = new();      // System.Threading.Lock (.NET 9+)

    public IDisposable? TryAcquire()
    {
        lock (_lock)
        {
            if (_available == 0) return null;
            _available--;
            return new Lease(this);              // callers only see IDisposable
        }
    }

    // Private nested type: an implementation detail that can change freely
    private sealed class Lease(RateLimiter owner) : IDisposable
    {
        private int _disposed;
        public void Dispose()
        {
            if (Interlocked.Exchange(ref _disposed, 1) == 1) return;
            lock (owner._lock) owner._available++;   // reads outer PRIVATE fields
        }
    }
}

// Generic outer type: nested type uses outer type parameters
public sealed class LruCache<TKey, TValue>(int capacity) where TKey : notnull
{
    private sealed class Node(TKey key, TValue value)
    {
        public TKey Key { get; } = key;
        public TValue Value { get; set; } = value;
    }
    private readonly Dictionary<TKey, LinkedListNode<Node>> _map = new(capacity);
    private readonly LinkedList<Node> _order = new();
}