Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Primary Constructors: Syntax, Scope, and Pitfalls

How C# 12 primary constructors work on classes and structs, what the compiler generates, and the property, capture, and validation pitfalls that surprise teams.

~4 min readC#
#C##Primary Constructors#C# 12#Records
C# primary constructor parameters captured into a glowing class container

A primary constructor in C# 12 lets a class or struct declare its constructor parameters in the type header and use them anywhere in the type body, without writing a constructor, assigning fields, or repeating parameter names. The parameters are not properties: unless you declare a property yourself, nothing is exposed to callers.

Syntax

csharp
public class Person(string name, int age) { public string Name { get; } = name; public int Age { get; } = age; public string Describe() => $"{Name} ({Age})"; }

The parameter list lives between the type name and the base list or body. Everything else - attributes, sealed, generics, interfaces, base class arguments - keeps its usual position.

csharp
public sealed class UserService(ILogger<UserService> logger, IUserStore store) : ServiceBase(logger), IUserService { public Task<User?> FindAsync(Guid id) => store.FindAsync(id); }

What the compiler actually generates

A primary constructor parameter is a parameter, not a member. When a member of the type refers to it, the compiler emits a hidden private field to hold the value and rewrites the member to read that field. If the parameter is only used in field or property initializers, no field is generated at all.

DeclarationPublic property generatedValue stored on the instanceTypical use
class C(int x) used only in an initializerNoNoFeeding a field or base call
class C(int x) used in a methodNoYes, hidden fieldDependency injection, helpers
record R(int X)Yes, public int X { get; init; }Yes, backing fieldData carriers
struct S(int x) used in a methodNoYes, field in the struct layoutSmall value types

That table is the whole difference between records and classes here. record turns positional parameters into public init-only properties and adds value equality, ToString, and with. A class with a primary constructor adds none of that: it only removes boilerplate.

Deep dive: where primary constructors change behaviour

1. There is no property, so there is no person.Name

The most common surprise after the first refactor is a compile error at the call site.

csharp
public class Person(string name) { public string Greet() => $"Hello, {name}"; } var p = new Person("Ada"); Console.WriteLine(p.Greet()); // works Console.WriteLine(p.Name); // CS1061: no member 'Name'

If a caller needs the value, declare the property explicitly. Primary constructors shorten the constructor, they do not create the surface area.

csharp
public class Person(string name, int age) { public string Name { get; } = name; public int Age { get; } = age; }

2. Capture is invisible, and it changes the object's layout

A parameter used by an instance method becomes a field, which means the instance now carries that value whether or not you intended to store it. For classes this is only a small allocation difference. For structs it is a layout change that affects copying and default.

csharp
public struct Money(decimal amount, string currency) { public string Format() => $"{amount:0.00} {currency}"; // captures both } var m = default(Money); // amount = 0, currency = null Console.WriteLine(m.Format()); // prints "0.00 " - null is legal here

Every Money value now contains a decimal and a reference. Passing it around copies both. For large structs, declare the capture explicitly as a field and pass it to the constructor, or make the type a readonly struct so the intent is clear.

3. Validation has no constructor body to live in

A primary constructor has no body, so validation must happen in an initializer expression, in an explicitly declared property, or in a factory method.

csharp
public class EmailAddress(string value) { private readonly string _value = !string.IsNullOrWhiteSpace(value) && value.Contains('@') ? value : throw new ArgumentException("Invalid email address.", nameof(value)); public string Value => _value; public override string ToString() => _value; }

The alternative is an explicit property with an initializer that performs the same check. What you should not do is expose the raw parameter and validate somewhere else: with a primary constructor, there is exactly one place where the object is constructed, and that is where the invariant belongs.

4. Shadowing between parameter and member

A primary constructor parameter stays in scope for the whole type body. If a property or field has the same name, the parameter wins inside members, and this. is required to reach the member.

csharp
public class Order(string id) { public string Id { get; } = id; public string Label() { // id here is the captured parameter, not the property return id.ToUpperInvariant(); } public string IdFromProperty() => this.Id; // explicit member access }

Keep parameter and member names distinct (value and _value, or id and Id) to make the intent obvious. Note also that the compiler reports CS9113 - "parameter is unread" - when a primary constructor parameter is never used, which usually means a half-finished refactor.

5. Chaining and this(...)

When a class declares a primary constructor, every other constructor must chain to it. You cannot have an independent parameterless constructor that skips it.

csharp
public class Connection(string host, int port) { public Connection() : this("localhost", 5432) { } public Connection(string host) : this(host, 5432) { } }

For structs the same rule applies: every other constructor chains with this(...) and must leave every field definitely assigned, including any hidden field created by capture.

Common mistakes

  • Expecting properties from a class primary constructor. Only records generate them. Declare public string Name { get; } = name; yourself.
  • Assuming the parameter disappears. Any member that reads it forces a hidden field, which shows up in the type's size and in serialized diagnostics. For structs, that changes copying cost.
  • Using primary constructors for mutable state. There is no constructor body to establish invariants, and the generated field is not something you can mark readonly. Prefer initializing an explicit readonly field or property.
  • Forgetting this. under shadowing. A parameter with the same name as a property silently takes precedence inside methods.
  • Leaving captured parameters that nothing uses. CS9113 is a warning, not an error, so unused injection points can survive review unnoticed.
  • Replacing records with classes to "simplify". You lose value equality, ToString, with, and deconstruction. If the type is a data carrier, a record is usually the better shape.
  • Ignoring ref struct and readonly constraints. A readonly struct with a primary constructor captures into readonly fields; a non-readonly struct does not, so the same code copies differently.
  • Dropping the base call. A primary constructor does not call base() implicitly when the base type has no parameterless constructor; pass the argument in the base list.

The short version: a primary constructor is a parameter list with a lifetime, not a property generator. Use it to remove constructor boilerplate in services and controllers, declare properties when callers need the data, and keep invariants in readonly fields that you initialize from the parameters.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.