C# 9.0 on the record

Mads Torgersen

Mads

C# 9.0 on the record

It’s official: C# 9.0 is out! Back in May I blogged about the C# 9.0 plans, and the following is an updated version of that post to match what we actually ended up shipping.

With every new version of C# we strive for greater clarity and simplicity in common coding scenarios, and C# 9.0 is no exception. One particular focus this time is supporting terse and immutable representation of data shapes.

Init-only properties

Object initializers are pretty awesome. They give the client of a type a very flexible and readable format for creating an object, and they are especially great for nested object creation where a whole tree of objects is created in one go. Here’s a simple one:

var person = new Person { FirstName = "Mads", LastName = "Torgersen" };

Object initializers also free the type author from writing a lot of construction boilerplate – all they have to do is write some properties!

public class Person
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
}

The one big limitation today is that the properties have to be mutable for object initializers to work: They function by first calling the object’s constructor (the default, parameterless one in this case) and then assigning to the property setters. Init-only properties fix that! They introduce an init accessor that is a variant of the set accessor which can only be called during object initialization:

public class Person
{
    public string? FirstName { get; init; }
    public string? LastName { get; init; }
}

With this declaration, the client code above is still legal, but any subsequent assignment to the FirstName and LastName properties is an error:

var person = new Person { FirstName = "Mads", LastName = "Nielsen" }; // OK
person.LastName = "Torgersen"; // ERROR!

Thus, init-only properties protect the state of the object from mutation once initialization is finished.

Init accessors and readonly fields

Because init accessors can only be called during initialization, they are allowed to mutate readonly fields of the enclosing class, just like you can in a constructor.

public class Person
{
    private readonly string firstName = "<unknown>";
    private readonly string lastName = "<unknown>";
    
    public string FirstName 
    { 
        get => firstName; 
        init => firstName = (value ?? throw new ArgumentNullException(nameof(FirstName)));
    }
    public string LastName 
    { 
        get => lastName; 
        init => lastName = (value ?? throw new ArgumentNullException(nameof(LastName)));
    }
}

Records

At the core of classic object-oriented programming is the idea that an object has strong identity and encapsulates mutable state that evolves over time. C# has always worked great for that, But sometimes you want pretty much the exact opposite, and here C#’s defaults have tended to get in the way, making things very laborious.

If you find yourself wanting the whole object to be immutable and behave like a value, then you should consider declaring it as a record:

public record Person
{
    public string? FirstName { get; init; }
    public string? LastName { get; init; }
}

A record is still a class, but the record keyword imbues it with several additional value-like behaviors. Generally speaking, records are defined by their contents, not their identity. In this regard, records are much closer to structs, but records are still reference types.

While records can be mutable, they are primarily built for better supporting immutable data models.

With-expressions

When working with immutable data, a common pattern is to create new values from existing ones to represent a new state. For instance, if our person were to change their last name we would represent it as a new object that’s a copy of the old one, except with a different last name. This technique is often referred to as non-destructive mutation. Instead of representing the person over time, the record represents the person’s state at a given time. To help with this style of programming, records allow for a new kind of expression; the with-expression:

var person = new Person { FirstName = "Mads", LastName = "Nielsen" };
var otherPerson = person with { LastName = "Torgersen" };

With-expressions use object initializer syntax to state what’s different in the new object from the old object. You can specify multiple properties.

The with-expression works by actually copying the full state of the old object into a new one, then mutating it according to the object initializer. This means that properties must have an init or set accessor to be changed in a with-expression.

Value-based equality

All objects inherit a virtual Equals(object) method from the object class. This is used as the basis for the Object.Equals(object, object) static method when both parameters are non-null. Structs override this to have "value-based equality", comparing each field of the struct by calling Equals on them recursively. Records do the same. This means that in accordance with their "value-ness" two record objects can be equal to one another without being the same object. For instance if we modify the last name of the modified person back again:

var originalPerson = otherPerson with { LastName = "Nielsen" };

We would now have ReferenceEquals(person, originalPerson) = false (they aren’t the same object) but Equals(person, originalPerson) = true (they have the same value). Along with the value-based Equals there’s also a value-based GetHashCode() override to go along with it. Additionally, records implement IEquatable<T> and overload the == and != operators, so that the value-based behavior shows up consistently across all those different equality mechanisms.

Value equality and mutability don’t always mesh well. One problem is that changing values could cause the result of GetHashCode to change over time, which is unfortunate if the object is stored in a hash table! We don’t disallow mutable records, but we discourage them unless you have thought through the consequences!

Inheritance

Records can inherit from other records:

public record Student : Person
{
    public int ID;
}

With-expressions and value equality work well with record inheritance, in that they take the whole runtime object into account, not just the type that it’s statically known by. Say that I create a Student but store it in a Person variable:

Person student = new Student { FirstName = "Mads", LastName = "Nielsen", ID = 129 };

A with-expression will still copy the whole object and keep the runtime type:

var otherStudent = student with { LastName = "Torgersen" };
WriteLine(otherStudent is Student); // true

In the same manner, value equality makes sure the two objects have the same runtime type, and then compares all their state:

Person similarStudent = new Student { FirstName = "Mads", LastName = "Nielsen", ID = 130 };
WriteLine(student != similarStudent); //true, since ID's are different

Positional records

Sometimes it’s useful to have a more positional approach to a record, where its contents are given via constructor arguments, and can be extracted with positional deconstruction. It’s perfectly possible to specify your own constructor and deconstructor in a record:

public record Person 
{ 
    public string FirstName { get; init; } 
    public string LastName { get; init; }
    public Person(string firstName, string lastName) 
      => (FirstName, LastName) = (firstName, lastName);
    public void Deconstruct(out string firstName, out string lastName) 
      => (firstName, lastName) = (FirstName, LastName);
}

But there’s a much shorter syntax for expressing exactly the same thing (modulo casing of parameter names):

public record Person(string FirstName, string LastName);

This declares the public init-only auto-properties and the constructor and the deconstructor, so that you can write:

var person = new Person("Mads", "Torgersen"); // positional construction
var (f, l) = person;                        // positional deconstruction

If you don’t like the generated auto-property you can define your own property of the same name instead, and the generated constructor and deconstructor will just use that one. In this case, the parameter is in scope for you to use for initialization. Say, for instance, that you’d rather have the FirstName be a protected property:

public record Person(string FirstName, string LastName)
{
    protected string FirstName { get; init; } = FirstName; 
}

A positional record can call a base constructor like this:

public record Student(string FirstName, string LastName, int ID) : Person(FirstName, LastName);

Top-level programs

Writing a simple program in C# requires a remarkable amount of boilerplate code:

using System;
class Program
{
    static void Main()
    {
        Console.WriteLine("Hello World!");
    }
}

This is not only overwhelming for language beginners, but clutters up the code and adds levels of indentation. In C# 9.0 you can just write your main program at the top level instead:

using System;

Console.WriteLine("Hello World!");

Any statement is allowed. The program has to occur after the usings and before any type or namespace declarations in the file, and you can only do this in one file, just as you can have only one Main method today. If you want to return a status code you can do that. If you want to await things you can do that. And if you want to access command line arguments, args is available as a "magic" parameter.

using static System.Console;
using System.Threading.Tasks;

WriteLine(args[0]);
await Task.Delay(1000);
return 0;

Local functions are a form of statement and are also allowed in the top level program. It is an error to call them from anywhere outside of the top level statement section.

Improved pattern matching

Several new kinds of patterns have been added in C# 9.0. Let’s look at them in the context of this code snippet from the pattern matching tutorial:

public static decimal CalculateToll(object vehicle) =>
    vehicle switch
    {
       ...
       
        DeliveryTruck t when t.GrossWeightClass > 5000 => 10.00m + 5.00m,
        DeliveryTruck t when t.GrossWeightClass < 3000 => 10.00m - 2.00m,
        DeliveryTruck _ => 10.00m,

        _ => throw new ArgumentException("Not a known vehicle type", nameof(vehicle))
    };

Simple type patterns

Previously, a type pattern needs to declare an identifier when the type matches – even if that identifier is a discard _, as in DeliveryTruck _ above. But now you can just write the type:

DeliveryTruck => 10.00m,

Relational patterns

C# 9.0 introduces patterns corresponding to the relational operators <, <= and so on. So you can now write the DeliveryTruck part of the above pattern as a nested switch expression:

DeliveryTruck t when t.GrossWeightClass switch
{
    > 5000 => 10.00m + 5.00m,
    < 3000 => 10.00m - 2.00m,
    _ => 10.00m,
},

Here > 5000 and < 3000 are relational patterns.

Logical patterns

Finally you can combine patterns with logical operators and, or and not, spelled out as words to avoid confusion with the operators used in expressions. For instance, the cases of the nested switch above could be put into ascending order like this:

DeliveryTruck t when t.GrossWeightClass switch
{
    < 3000 => 10.00m - 2.00m,
    >= 3000 and <= 5000 => 10.00m,
    > 5000 => 10.00m + 5.00m,
},

The middle case there uses and to combine two relational patterns and form a pattern representing an interval. A common use of the not pattern will be applying it to the null constant pattern, as in not null. For instance we can split the handling of unknown cases depending on whether they are null:

not null => throw new ArgumentException($"Not a known vehicle type: {vehicle}", nameof(vehicle)),
null => throw new ArgumentNullException(nameof(vehicle))

Also not is going to be convenient in if-conditions containing is-expressions where, instead of unwieldy double parentheses:

if (!(e is Customer)) { ... }

You can just say

if (e is not Customer) { ... }

And in fact, in an is not expression like that we allow you to name the Customer for subsequent use:

if (e is not Customer c) { throw ... } // if this branch throws or returns...
var n = c.FirstName; // ... c is definitely assigned here

Target-typed new expressions

"Target typing" is a term we use for when an expression gets its type from the context of where it’s being used. For instance null and lambda expressions are always target typed.

new expressions in C# have always required a type to be specified (except for implicitly typed array expressions). In C# 9.0 you can leave out the type if there’s a clear type that the expression is being assigned to.

Point p = new (3, 5);

This is particularly nice when you have a lot of repetition, such as in an array or object initializer:

Point[] ps = { new (1, 2), new (5, 2), new (5, -3), new (1, -3) }; 

Covariant returns

It’s sometimes useful to express that a method override in a derived class has a more specific return type than the declaration in the base type. C# 9.0 allows that:

abstract class Animal
{
    public abstract Food GetFood();
    ...
}
class Tiger : Animal
{
    public override Meat GetFood() => ...;
}

And much more…

The best place to check out the full set of C# 9.0 features is the "What’s new in C# 9.0" docs page.

66 comments

Leave a comment

  • Avatar
    Bruno Boucard

    I have a question regarding the record feature.

    I adapted my code for my immutable types (Value Object in Domain-Driven Design).

    public sealed record SeatsRequested
    {
        public const int MinRequested = 1;
        public const int MaxRequested = 20;
    
        public int Count { get; }
    
        public SeatsRequested(int seatRequestCount)
        {
            if (seatRequestCount  MaxRequested)
                throw new ArgumentException(
                    $"{nameof(seatRequestCount)}({seatRequestCount}) should be between {MinRequested} and {MaxRequested}");
    
            Count = seatRequestCount;
        }
    
        public bool IsMatch(IReadOnlyCollection seats)
        {
            return seats.Count == Count;
        }
    }

    But do you have a plan when the record type contains some collections:

    public sealed record Coach
    {
        private readonly List _seats;
        public IReadOnlyCollection Seats => _seats;
        private string Name { get; }
    
        private int NumberOfReservedSeats
        {
            get { return Seats.Count(s => !s.IsAvailable()); }
        }
    
        public Coach(string name) : this(name, new List())
        {
        }
    
        public Coach(string name, List seats)
        {
            Name = name;
            _seats = seats;
        }
    
        // DDD Pattern: Closure Of Operation
        public Coach AddSeat(Seat seat)
        {
            return new Coach(seat.CoachName, new List(Seats) {seat});
        }
    
        public ReservationAttempt BuildReservationAttempt(TrainId trainId, SeatsRequested seatsRequested)
        {
            var availableSeats = Seats.Where(s => s.IsAvailable()).Take(seatsRequested.Count).ToList();
            return seatsRequested.IsMatch(availableSeats)
                ? new ReservationAttempt(trainId, seatsRequested, availableSeats)
                : new ReservationAttemptFailure(trainId, seatsRequested);
        }
    
        public bool DoesNotExceedOverallCapacity(SeatsRequested seatsRequested)
        {
            return NumberOfReservedSeats + seatsRequested.Count <=
                   Math.Floor(CapacityThresholdPolicy.ForCoach * Seats.Count);
        }
    }
  • Avatar
    James Lonero

    I thought C# was completely an object oriented language. With the new Top-level program statements, its starting to look like Javescript or old Basic. That’s too bad since its starting to look less like a professional engineering language. Part of being an OOP is that it is highly structured for the professional engineer.

    • Mads Torgersen
      Mads TorgersenMicrosoft employee

      The first object-oriented programming language, Simula-67, allowed anything to be declared at any level, just like its “host language” Algol-68. They were no less highly structured, just less rigid.

      Many modern programming languages dispense with more of the ceremony and limitations that used to be par for the cause. In C# we are happy to do the same, where we can. It doesn’t make the language less structured, just less restrictive and syntax heavy.

  • Iuri Brindeiro
    Iuri Brindeiro

    There is some how a way to prevent the default behavior of with-expression for specific properties without having to rewrite the whole protected constructor?
    I mean, if I have a private property that need to be set with a specific value whenever I create a new instance of that record. What should I do in that case? Should I override the whole protected constructor called by the with-expression?

  • Avatar
    Lorenzo Maiorfi

    Hi. I have an issue with logical pattern matching sample with nested switch, that is, making reference to sample classes in Microsoft Docs tutorial, the commented-out pattern does not compile (error CS1003: Syntax error, ‘=>’ expected and error CS1525: Invalid expression term ‘,’):

    public static decimal CalculateToll(object vehicle) =>
                    vehicle switch
                    {
                        /*CommercialRegistration.DeliveryTruck dt when dt.GrossWeightClass switch
                        {
                            > 5000 => 10.00m + 5.00m,
                             10.00m - 2.00m,
                            _ => 10.00m
                        },*/
                        LiveryRegistration.Taxi _ => 5.00m,
                        CommercialRegistration.DeliveryTruck dt when dt.GrossWeightClass > 5000 => 10.00m + 5.00m,
                        CommercialRegistration.DeliveryTruck dt when dt.GrossWeightClass  10.00m - 2.00m,
                        CommercialRegistration.DeliveryTruck _ => 10.00m,
                        null => throw new ArgumentNullException(nameof(vehicle)),
                        _ => throw new ArgumentException("Not a known vehicle type", nameof(vehicle))
                    };

    What is wrong with that?

    Thanks!

  • Avatar
    Károly Ozsvárt

    About Target-typed new expressions: I found a better way creating (specifically) Point objects. This assumes you have access to the type’s source , because you need an implicit operator for casting from an (int x, int y) tuple (or float, double, whatever) to a Point.
    If you do that, the followings are possible:

    Point p = (3, 5);
    Point[] ps = { (1, 2), (5, 2), (5, -3), (1, -3) };

    This is just for the Point example, I know “target-typed new expressions” are a lot more and I am happy about it.

    (I wanted to give another example but that includes generic arguments and the blogging engine messed it up… Please fix it!
    I click “code”, insert a generic dictionary where the value is a list of integers, and you see this (List type parameters DISAPPEAR after hitting submit):

    Dictionary<string, List> values = null;

    )

  • Avatar
    Andriy Savin

    As init-only properties seem to have regular setters decorated with System.Runtime.CompilerServices.IsExternalInit attribute, how do they behave with other languages not aware of this feature? Is it possible to break the rules by setting an init-only property after object initialization from, say, VB.NET?