Init-only methods: call-once initialization semantics for methods

[Zombach]

Motivation

C# provides init accessors for properties, allowing values to be set only
during object initialization. However, there is no equivalent way to express
"call-once during initialization" semantics for methods.

In practice, developers sometimes need:

• does not naturally map to a property setter,
• requires multiple parameters,
• performs validation or side effects,
• must run exactly once per object instance,
• may involve asynchronous operations.

Today this is typically implemented via private flags and runtime checks,
which is verbose, error-prone, and not discoverable in the type system.

Proposed Feature

Introduce init-only methods, which can be called only during the
object initialization phase and only once per instance.

Example syntax:

public class Person
{
    private string _name;

    public init async Task InitName(string name)
    {
        await Task.Delay(1000);
        _name = name;
    }
}

Use

var p = new Person();
await p.InitName("Alice"); // OK
await p.InitName("Bob");   // Analyzer/Compile-time exception: init method already called

now

But if we want to initialize an object through a method, especially an asynchronous one or one that requires multiple parameters, we end up writing something like:

public class Person
{
    private string _name;
    private bool _initialized;

    public async Task InitNameAsync(string name)
    {
        if (_initialized) throw new InvalidOperationException();
        await Task.Delay(1000);
        _name = name;
        _initialized = true;
    }
}

The problems here are:

• A lot of boilerplate code (_initialized, checks).
• Prone to errors (the check can be forgotten).
• Not reflected in the type system (IDE and analyzers cannot indicate that the method should only be called once).

Interaction with required

• It is unclear whether init-only methods could meaningfully interact with
  the required keyword, given the analyzability constraints of method calls.
• This proposal intentionally does not require such interaction, but it may be
  worth discussing whether a limited form could be considered in the future.

[HaloFour]

Is this pattern so common that requiring a few lines of code per instance is onerous? The fact that this proposal doesn't seem to actually enforce any guardrails on the invocation and instead it just results in a runtime exception seems to tee it up as a pit of failure.

[HaloFour]

Also, see: #6591, which IMO would fit better since it becomes a part of the object creation via initializers.

[Zombach]

Is this pattern so common that requiring a few lines of code per instance is onerous? The fact that this proposal doesn't seem to actually enforce any guardrails on the invocation and instead it just results in a runtime exception seems to tee it up as a pit of failure.

Yes, of course. I meant Analyzer/Compile-time, but I accidentally wrote runtime.

In this case, the compiler or a Roslyn analyzer could detect misuse of init-only methods, such as:

Calling an init-method outside the object initialization phase (after the constructor or after object initializers).

Potentially warning about multiple calls to the same init-method (though full static analysis for async methods may be limited).

So the distinction is:

Analyzer/Compile-time: catches violations before the program runs and can show warnings or errors in the IDE.

Runtime exception: would still occur if the analyzer cannot fully guarantee one-call semantics, especially for async or conditional calls.

This ensures that, ideally, developers get immediate feedback in the IDE, rather than discovering issues only at runtime.

[mattwar]

An init-only method is called a constructor. If you want to do async or any real work in a constructor, use a factory method that calls the constructor at the end.