Muokkaa

Jaa

readonly (C# Reference)

  • Artikkeli

The readonly keyword is a modifier that can be used in five contexts:

  • In a field declaration, readonly indicates that assignment to the field can only occur as part of the declaration or in a constructor in the same class. A readonly field can be assigned and reassigned multiple times within the field declaration and constructor.

    A readonly field can't be assigned after the constructor exits. This rule has different implications for value types and reference types:

    • Because value types directly contain their data, a field that is a readonly value type is immutable.
    • Because reference types contain a reference to their data, a field that is a readonly reference type must always refer to the same object. That object might not be immutable. The readonly modifier prevents replacing the field value with a different instance of the reference type. However, the modifier doesn't prevent the instance data of the field from being modified through the read-only field.

    Warning

    An externally visible type that contains an externally visible read-only field that is a mutable reference type may be a security vulnerability and may trigger warning CA2104 : "Do not declare read only mutable reference types."

  • In a readonly struct type definition, readonly indicates that the structure type is immutable. For more information, see the readonly struct section of the Structure types article.

  • In an instance member declaration within a structure type, readonly indicates that an instance member doesn't modify the state of the structure. For more information, see the readonly instance members section of the Structure types article.

  • In a ref readonly method return, the readonly modifier indicates that method returns a reference and writes aren't allowed to that reference.

Readonly field example

In this example, the value of the field year can't be changed in the method ChangeYear, even though it was assigned a value in the class constructor:

class Age
{
    private readonly int _year;
    Age(int year)
    {
        _year = year;
    }
    void ChangeYear()
    {
        //_year = 1967; // Compile error if uncommented.
    }
}

You can assign a value to a readonly field only in the following contexts:

  • When the variable is initialized in the declaration, for example:

    public readonly int y = 5;

  • In an instance constructor of the class that contains the instance field declaration.

  • In the static constructor of the class that contains the static field declaration.

These constructor contexts are also the only contexts in which it's valid to pass a readonly field as an out or ref parameter.

Note

The readonly keyword is different from the const keyword. A const field can only be initialized at the declaration of the field. A readonly field can be assigned multiple times in the field declaration and in any constructor. Therefore, readonly fields can have different values depending on the constructor used. Also, while a const field is a compile-time constant, the readonly field can be used for run-time constants as in the following example:

public static readonly uint timeStamp = (uint)DateTime.Now.Ticks;

public class SamplePoint
{
    public int x;
    // Initialize a readonly field
    public readonly int y = 25;
    public readonly int z;

    public SamplePoint()
    {
        // Initialize a readonly instance field
        z = 24;
    }

    public SamplePoint(int p1, int p2, int p3)
    {
        x = p1;
        y = p2;
        z = p3;
    }

    public static void Main()
    {
        SamplePoint p1 = new SamplePoint(11, 21, 32);   // OK
        Console.WriteLine($"p1: x={p1.x}, y={p1.y}, z={p1.z}");
        SamplePoint p2 = new SamplePoint();
        p2.x = 55;   // OK
        Console.WriteLine($"p2: x={p2.x}, y={p2.y}, z={p2.z}");
    }
    /*
     Output:
        p1: x=11, y=21, z=32
        p2: x=55, y=25, z=24
    */
}

In the preceding example, if you use a statement like the following example:

p2.y = 66;        // Error

you get the compiler error message:

A readonly field cannot be assigned to (except in a constructor or a variable initializer)

Readonly instance members

You can also use the readonly modifier to declare that an instance member doesn't modify the state of a struct.

public readonly double Sum()
{
    return X + Y;
}

Note

In the case of a read/write property, you can add the readonly modifier to the get accessor. Some get accessors may perform a calculation and cache the result, rather than simply returning the value of a private field. Adding the readonly modifier to the get accessor guarantees that the get accessor doesn't modify the internal state of the object by caching any result.

You can find more examples in the readonly instance members section of the Structure types article.

Ref readonly return example

The readonly modifier on a ref return indicates that the returned reference can't be modified. The following example returns a reference to the origin. It uses the readonly modifier to indicate that callers can't modify the origin:

private static readonly SamplePoint s_origin = new SamplePoint(0, 0, 0);
public static ref readonly SamplePoint Origin => ref s_origin;

The type returned doesn't need to be a readonly struct. Any type that can be returned by ref can be returned by ref readonly.

Readonly ref readonly return example

A ref readonly return can also be used with readonly instance members on struct types:

public struct ReadonlyRefReadonlyExample
{
    private int _data;

    public readonly ref readonly int ReadonlyRefReadonly(ref int reference)
    {
        // _data = 1; // Compile error if uncommented.
        return ref reference;
    }
}

The method essentially returns a readonly reference together with the instance member (in this case a method) being readonly (not able to modify any instance fields).

C# language specification

For more information, see the C# Language Specification. The language specification is the definitive source for C# syntax and usage.

You can also see the language specification proposals:

See also