Records - C# Reference (2023)

Starting with C# 9, use therecordKeyword to define areference typethat provides built-in functionality for encapsulating data. C# 10 allowsrecord classSyntax as a synonym to clarify a reference type andrecord structureset avalue typewith similar functionality. You can create record types with immutable properties using positional parameters or standard property syntax.

The following two examples demonstraterecord(orrecord class) Types of reference:

public record Person(string FirstName, string LastName);

public record Person{ public required string Name { get; inside; } string required public lastname { get; inside; }};

The following two examples demonstraterecord structureValue types:

public record readonly struct Point(double X, double Y, double Z);

public record struct Point{ public double X { get; inside; } audience double Y { get; inside; } public double Z { get; inside; }}

You can also create records with editable properties and fields:

public record Person{ public required string Name { get; Phrase; } string required public lastname { get; Phrase; }};

Record structures can also be mutable, either positional record structures or record structures without positional parameters:

public record structure DataMeasurement(DateTime TakenAt, Double Measurement);

public record struct Point{ public double X { get; Phrase; } audience double Y { get; Phrase; } public double Z { get; Phrase; }}

Although datasets can be mutable, they are primarily intended to support immutable data models. The record type provides the following features:

• Concise syntax for creating a reference type with immutable properties
• Useful built-in behavior for a data-centric reference type:
  • equality of values
  • Short syntax for nondestructive mutation
  • Integrated display formatting
• Support for inheritance hierarchies

The previous examples show some differences between records that are reference types and records that are value types:

• Arecordor onerecord classdeclares a reference type. OClassroomThe keyword is optional, but it can provide clarity for readers. Arecord structuredeclares a value type.
• The position properties areimmutableon arecord classit is aread-only record structure. They aremutableon arecord structure.

The rest of this article covers both.record classErecord structuretypes. Differences are detailed in each section. You must choose between onerecord classit is arecord structuresimilar to the decision between aClassroomit is aStructure. the termrecordused to describe behavior that applies to all record types. Anyrecord structureorrecord classused to describe the unique behavior of struct or class types. Orecordtype was introduced in C# 9;record structuretypes were introduced in C# 10.

Positional syntax for property definition

You can use positional parameters to declare properties of a record and initialize property values ​​when creating an instance:

public record Person(string FirstName, string LastName); public static void Main(){ Person person = new("Nancy", "Davolio"); Console WriteLine(Pessoa); // Output: Person { First Name = Nancy, Last Name = Davolio } }

If you use positional syntax for the property definition, the compiler will output the following:

• An automatically implemented public property for each positional parameter provided in the record declaration.
  • Forrecordtypes andread-only record structuretype: onenur initProperty.
  • Forrecord structureTypes: A read/write property.
• A primary constructor whose parameters match the positional parameters in the record declaration.
• For record structure types, a parameterless constructor that sets each field to its default value.
• Adeconstructmethod with aoutside ofParameters for each positional parameter specified in the record declaration. The method deconstructs the defined properties using positional syntax; it ignores properties defined using standard property syntax.

You might want to add attributes to each of these elements that the compiler creates from the record definition. You can add aMetato any attribute applied to location record properties. The following example applies toSystem.Text.Json.Serialization.JsonPropertyNameAttributeto each property ofPersonrecord. OProperty:target indicates that the attribute is applied to the property generated by the compiler. Other values ​​areCampo:to apply the attribute to the field, andParameter:to apply the attribute to the parameter.

/// <summary>/// Person Record Type /// </summary>/// <param name="FirstName">First Name</param>/// <param name="LastName">Last Name< /param>/ // <notes>/// The person type is a location record that contains /// the first and last name properties. These /// properties are mapped to JSON elements "firstName" and "lastName" if /// they have been serialized or deserialized./// </remarks>Public record Person([property: JsonPropertyName("firstName")] string FirstName , [ Property: JsonPropertyName("lastName")]string LastName);

The previous example also shows how to create XML documentation comments for the dataset. You can add those<param>tag to add documentation for the primary parameters of the constructor.

If the generated self-implemented property definition is not what you want, you can define your own property with the same name. For example, you might want to change accessibility or mutability, or provide an implementation forto receiveorPhraseaccessor. If you declare the property in your source, you must initialize it from the record's positional parameter. If your property is an automatically implemented property, you must initialize it. If you add a background field to your source, you must initialize the background field. The generated destructor uses your property definition. For example, the following example declares theFirst nameElast name, last nameProperties of a position recordpublic, but restricts themI WENTposition parameter tootrainee. You can use this syntax for records and record structure types.

public record Person(string FirstName, string LastName, string Id){ internal string Id { get; inside; } = ID;}public static void Main(){ Person person = new("Nancy", "Davolio", "12345"); Console.WriteLine(person.Name); //Output: Nancy}

A record type need not declare positional properties. You can declare a record without positional properties, and you can declare other fields and properties, as in the following example:

registro público Pessoa(string FirstName, string LastName){ public string[] PhoneNumbers { get; dentro; } = Array.Empty<string>();};

If you define properties using standard property syntax but omit the access modifier, the properties are impliedPrivate.

immutability

Aposition recordit is apositional read-only record structureDeclare initialization-only properties. APosition record structuredeclare read/write properties. You can override any of these defaults as shown in the previous section.

Immutability can be useful when you need a data-centric type that is thread safe or when you depend on a hash code in a hash table to stay the same. However, immutability is not appropriate for all data scenarios.Entity Framework-Kernfor example, it does not support updating with immutable entity types.

Initialization-only properties, regardless of whether they were created from positional parameters (record class, Eread-only record structure) or by specificationinsideaccessors, hasshallow immutability. After initialization, you cannot change the value of value type properties or the reference of reference type properties. However, data referenced by a reference type property can be modified. The following example shows that the contents of an immutable property of the reference type (in this case, an array) is mutable:

öffentlicher Datensatz Person(string FirstName, string LastName, string[] PhoneNumbers);public static void Main(){ Person person = new("Nancy", "Davolio", new string[1] { "555-1234" }); Console.WriteLine(pessoa.PhoneNumbers[0]); // Número de telefone: 555-1234 person.PhoneNumbers[0] = "555-6789"; Console.WriteLine(pessoa.PhoneNumbers[0]); // Ausgabe: 555-6789}

The unique functions of record types are implemented through methods synthesized by the compiler, and none of these methods break immutability by changing the state of the object. Unless otherwise noted, synthesized procedures are generated torecord,record structure, Eread-only record structureExplanations.

equality of values

Unless you override or override equality methods, the type you declare determines how equality is defined:

• ForClassroomTypes are two objects the same if they refer to the same object in memory.
• ForStructureTypes Two objects are equal if they are of the same type and store the same values.
• Forrecordspecies, includingrecord structureEread-only record structure, two objects are equal if they are of the same type and store the same values.

The definition of equality for arecord structureis the same as for aStructure. The difference is that for aStructure, the implementation is thereValueType.Equals(Object)and depends on reflection. For datasets, the implementation is synthesized by the compiler and uses the declared data members.

Reference equality is required for some data models. For example,Entity Framework-Kernrelies on equality of reference to ensure that only one instance of an entity type is used for a conceptually unique entity. Because of this, records and record structures are not appropriate for use as entity types in Entity Framework Core.

The following example illustrates the value equality of record types:

registro público Person(string FirstName, string LastName, string[] PhoneNumbers); public static void Main(){ var phoneNumbers = new string[2]; Pessoa pessoa1 = new("Nancy", "Davolio", phoneNumbers); Pessoa pessoa2 = new("Nancy", "Davolio", phoneNumbers); Console.WriteLine(pessoa1 == pessoa2); // Output: True person1.PhoneNumbers[0] = "555-1234"; Console.WriteLine(pessoa1 == pessoa2); // output: True Console.WriteLine(ReferenceEquals(person1, person2)); // saída: falso}

To implement value equality, the compiler synthesizes several methods, including:

• A rewrite ofObject.Equals(Objekt). It is an error if the override is explicitly declared.

  This method serves as the basis forObject.Equals(object, object)static method if both parameters are not null.

• Avirtual, orsealed,Same (R? other)WoRis the record type. Implemented this methodIEquatable<T>. This method can be declared explicitly.

• If the record type is derived from a base record typeBase,Same (base? other). It is an error if the override is explicitly declared. If you provide your own implementation ofSame (R? other), provide an implementation ofGetHashCodeAlso.

• A rewrite ofObject.GetHashCode(). This method can be declared explicitly.

• Operator Overrides==E!=. It is an error if operators are explicitly declared.

• If the record type is derived from a base record type,protected substitution Type EqualityContract { get; };. This property can be declared explicitly. For more information, seeEquality in inheritance hierarchies.

If a record type has a method that matches the signature of a synthesized method that can be declared explicitly, the compiler will not synthesize that method.

nondestructive mutation

If you need to copy an instance with some modifications, you cancomto achieve the expressionnondestructive mutation. AcomExpression creates a new record instance that is a copy of an existing record instance by modifying certain properties and fields. you useobject initializerSyntax to specify the values ​​to be changed, according to the following example:

registro público Pessoa(string FirstName, string LastName){ public string[] PhoneNumbers { get; dentro; }}public static void Main(){ Person person1 = new("Nancy", "Davolio") {PhoneNumbers = new string[1] }; Console WriteLine (pessoa1); // Output: Person { FirstName = Nancy, LastName = Davolio, PhoneNumbers = System.String[] } Person person2 = person1 with { FirstName = "John" }; Console WriteLine (pessoa2); // Output: Person { FirstName = John, LastName = Davolio, PhoneNumbers = System.String[] } Console.WriteLine(person1 == person2); // Output: False person2 = person1 with { PhoneNumbers = new string[1] }; Console WriteLine (pessoa2); // Output: Person { FirstName = Nancy, LastName = Davolio, PhoneNumbers = System.String[] } Console.WriteLine(person1 == person2); // Saída: Pessoa2 errada = pessoa1 com { }; Console.WriteLine(pessoa1 == pessoa2); // saída: verdadeiro}

OcomThe expression can specify positional or constructed properties using standard property syntax. Non-positional properties must have ainsideorPhraseAccessor to change in onecomExpression.

The result of acomexpression is ashallow copy, which means that for a reference property, only the reference to an instance is copied. Both the original record and the copy end with a reference to the same instance.

To implement this function, for examplerecord classtypes, the compiler synthesizes a clone method and a copy constructor. The virtual clone method returns a new record initialized by the copy constructor. If you use acom-expression, the compiler creates code that calls the clone method and then sets the properties specified in thecomExpression.

If you need different copy behavior, you can write your own copy constructor in arecord class. If you do, the compiler will not synthesize any. make your builderPrivateif the record issealed, otherwise doprotected. The compiler does not synthesize a copy constructor forrecord structuretypes. You can write one, but the compiler doesn't generate calls to itcomexpressions. the values ​​ofrecord structureare copied in the order.

You cannot override the clone method and you cannot create a member by nameCloneon each record type. The actual name of the clone method is generated by the compiler.

Integrated display formatting

Record types have a generated compilerto sequencemethod that displays the names and values ​​of properties and public fields. Oto sequenceThe method returns a string in the following format:

<record type name> { <property name> = <value>, <property name> = <value>, ...}

The string that is produced for<Wert>is the string returned byto sequence()for the type of property. In the example belowchildren's namesit is aSystem.Array, Woto sequenceReturnsSystem.String[]:

Pessoa { FirstName = Nancy, LastName = Davolio, ChildNames = System.String[] }

To implement this function inrecord classtypes, the compiler synthesizes a virtualPrintMembersmethod and ato sequenceto replace. Inrecord structureGuys, this member isPrivate.Oto sequenceReplace created aStringBuilderObject with the name of the type followed by an opening square bracket. he callsPrintMembersto add property names and values, and then add the closing square bracket. The following example shows code similar to the content of the synthesized replacement:

substituição pública string ToString(){ StringBuilder stringBuilder = new StringBuilder(); stringBuilder.Append("Lehrer"); // Name eingeben stringBuilder.Append(" { "); if (PrintMembers(stringBuilder)) { stringBuilder.Append(" "); } stringBuilder.Append("}"); return stringBuilder.ToString();}

You can provide your own implementation ofPrintMembersor theto sequenceto replace. Examples can be found inFormatting PrintMembers in Derived Datasetssection later in this article. In C# 10 and later, your implementation ofto sequencecan contain thesealedModifier that prevents the compiler from synthesizing ato sequenceImplementation for all derived datasets. You can do this to create a consistent representation of strings in a hierarchy ofrecordtypes. (The derived records still have aPrintMembersMethod generated for all derived properties.)

state

This section only applies torecord classThe type.

A record can inherit from another record. However, a record cannot inherit from a class, and a class cannot inherit from a record.

Positional parameters in derived record types

The derived record declares positional parameters for all parameters in the base record's primary constructor. The base record declares and initializes these properties. The derived dataset does not hide them, but just creates and initializes properties for parameters that are not declared in its base dataset.

The following example illustrates inheritance using positional property syntax:

abstract public record Person(string FirstName, string LastName);public record Teacher(string FirstName, string LastName, int Grade): Person(FirstName, LastName);public static void Main(){ Person Teacher = new Teacher("Nancy", "Davólio", 3); Console.WriteLine(professor); // Output: Teacher { First Name = Nancy, Last Name = Davolio, Class = 3 }}

Equality in inheritance hierarchies

This section applies torecord classguys, but norecord structuretypes. For two registry variables to be equal, the runtime type must be the same. The types of the container variables can be different. Inherited equality comparison is illustrated in the following code example:

abstract public record Person(string FirstName, string LastName); public record Teacher(string FirstName, string LastName, int Grade): Person(FirstName, LastName); public record Student(string FirstName, string LastName, int Grade): Person(FirstName , LastName);public static void Main(){ Person Teacher = new Teacher("Nancy", "Davolio", 3); Person student = new Student("Nancy", "Davolio", 3); Console.WriteLine(teacher == student); // Output: False Student student2 = new Student("Nancy", "Davolio", 3); Console.WriteLine(Student2 == Student); // output: true}

In the example, all variables are declared asPerson, even if the instance is a type derived from bothStudentorLehrer. Instances have the same properties and the same property values. Butstudent == teacherReturnsINCORRECTalthough both arePerson-Type variables andstudent == student2ReturnsTRUEalthough one is onePersonvariable and one is oneStudentVariable. The equality test depends on the runtime type of the actual object, not the declared type of the variable.

To implement this behavior, the compiler synthesizes aequality contractProperty returning aTypeObject corresponding to the record type. Oequality contractallows equality methods to compare the type of objects at runtime when checking equality. If the base type of a record isObject, this property isvirtual. If the base type is another record type, this property will be an override. If the record type issealed, this property is effectivesealedbecause the guy issealed.

When comparing two instances of a derived type, the synthesized equality methods compare all properties of the base type and the derived type for equality. the synthesizedGetHashCodemethod uses theGetHashCodemethod of all properties and fields declared in the base type and derived record type.

comExpressions in Derived Datasets

The result of acomexpression has the same runtime type as the expression's operand. All runtime type properties are copied, but you can only set compile-time type properties, as the following example shows:

conjunto de dados público Point(int X, int Y) { public int Zbase { get; Frase; }}; conjunto de dados público NamedPoint(string Name, int X, int Y) : Point(X, Y){ public int Zderived { get; Frase; }}; public static void Main() { Point p1 = new NamedPoint( "A", 1, 2) { Zbase = 3, Zderived = 4 }; Ponto p2 = p1 com { X = 5, Y = 6, Zbase = 7 }; // Não é possível definir Name ou Zderived Console.WriteLine(p2 is NamedPoint); // Output: True Console.WriteLine(p2); // Output: NamedPoint { X = 5, Y = 6, Zbase = 7, Name = A, Zderived = 4 } Ponto p3 = (NamedPoint)p1 with { Name = "B", X = 5, Y = 6, Zbase = 7, Zderivado = 8 }; Console.WriteLine(p3); // Output: NamedPoint { X = 5, Y = 6, Zbase = 7, Name = B, Zderived = 8 }}

PrintMembersFormatting in Derived Datasets

the synthesizedPrintMembersThe method of a derived record type calls the base implementation. The result is that all properties and public fields of derived and base types are included in theto sequenceoutput as shown in the following example:

abstract public record Person(string FirstName, string LastName); registro público Teacher(string FirstName, string LastName, int Grade): Person(FirstName, LastName); registro público Student(string FirstName, string LastName, int Grade): Person(FirstName , Sobrenome);public static void Main(){ Pessoa Professor = new Professor("Nancy", "Davolio", 3); Console.WriteLine(professor); // Output: Teacher { First Name = Nancy, Last Name = Davolio, Class = 3 }}

You can provide your own implementation ofPrintMembersMethod. In this case, use the following signature:

• ForsealedRegistration originating fromObject(does not declare a base record):private bool PrintMembers (Construtor StringBuilder);
• ForsealedRecord derived from another record (note that the delimiter type issealed, then the method is effectivesealed):override protected bool PrintMembers (StringBuilder constructor);
• For a record that is notsealedand derives from the object:bool virtual protegido PrintMembers(construtor StringBuilder);
• For a record that is notsealedand comes from another dataset:protected override bool PrintMembers(StringBuilder constructor);

Here is a code example replacing the synthesizedPrintMembersMethods, one for a record type derived from Object and one for a record type derived from another record:

registro abstrato público Pessoa(string FirstName, string LastName, string[] PhoneNumbers){ protected virtual bool PrintMembers(StringBuilder stringBuilder) { stringBuilder.Append($"FirstName = {FirstName}, LastName = {LastName}, "); stringBuilder.Append($"PhoneNumber1 = {PhoneNumbers[0]}, PhoneNumber2 = {PhoneNumbers[1]}"); gib true zurück; }}Public record Teacher(string FirstName, string LastName, string[] PhoneNumbers, int Grade): Person(FirstName, LastName, PhoneNumbers){ protected override bool PrintMembers(StringBuilder stringBuilder) { if (base.PrintMembers(stringBuilder)) { stringBuilder .Anexar(", "); }; stringBuilder.Append($"Nota = {Nota}"); gib true zurück; }};public static void Main(){ Person Teacher = new Teacher("Nancy", "Davolio", new string[2] { "555-1234", "555-6789" }, 3); Console.WriteLine (Lehrer); // Ausgabe: Teacher { FirstName = Nancy, LastName = Davolio, PhoneNumber1 = 555-1234, PhoneNumber2 = 555-6789, Grade = 3 }}

Destructor behavior on derived datasets

Odeconstructmethod of a derived record returns the values ​​of all positional properties of the compile-time type. If the variable type is a base record, only the base record properties are deconstructed unless the object is converted to the derived type. The following example shows calling a destructor on a derived record.

abstract public record Person(string FirstName, string LastName); registro público Teacher(string FirstName, string LastName, int Grade): Person(FirstName, LastName); registro público Student(string FirstName, string LastName, int Grade): Person(FirstName , Sobrenome);public static void Main(){ Pessoa Professor = new Professor("Nancy", "Davolio", 3); var (nome, sobrenome) = professor; // Não desconstrói a nota Console.WriteLine($"{firstName}, {lastName}");// Output: Nancy, Davolio var (fName, lName, grade) = (Teacher)teacher; Console.WriteLine($"{fName}, {lName}, {grau}");// Output: Nancy, Davolio, 3}

General Restrictions

There are no generic constraints that require a type to be a record. The records meet the requirementsClassroomorStructureObligation. To define a restriction on a specific hierarchy of record types, define the restriction on the base record as you would for a base class. For more information, seeRestrictions on type parameters.

C# language specification

For more information, seeKlassenSection ofC# language specification.

For more information about features introduced in C# 9 and later, see the following Feature Suggestion Notes:

• records
• Init-only SetterName
• Income Covariance

See too

• C# Reference
• Design guidelines - choose between class and structure
• Project Guidelines - Structural Project
• The C# Type System
• with expression