Primary constructor no C#: o que muda na inicialização

O que é o primary constructor no C#

O primary constructor chegou às classes e structs no C# 12 e continua disponível no C# 14, que acompanha o .NET 10, a versão LTS atual. Com ele, os parâmetros do construtor ficam declarados ao lado do nome do tipo e permanecem visíveis em todo o corpo da classe.

Antes, esse recurso existia apenas em records. Agora, qualquer classe comum pode declarar seus parâmetros dessa forma.

// Construtor tradicional
public class OrderService
{
    private readonly IOrderRepository repository;

    public OrderService(IOrderRepository repository)
    {
        this.repository = repository;
    }

    public Order? GetById(Guid id) => repository.Find(id);
}

// O mesmo serviço com primary constructor
public class OrderService(IOrderRepository repository)
{
    public Order? GetById(Guid id) => repository.Find(id);
}

Por isso, muita gente trata o primary constructor como simples açúcar sintático. Na maior parte do tempo, de fato, as duas versões se comportam da mesma forma.

Contudo, existe um cenário em que elas divergem. Ele envolve herança, membros virtuais e a ordem em que o runtime monta o objeto.

O problema: um membro virtual no construtor da base

O exemplo a seguir vem do artigo de Steven Giesel, que serviu de base para este texto. Ele parte de uma classe abstrata que executa algum trabalho no próprio construtor.

abstract class Base
{
    protected Base(Func<int?> check)
    {
        // A base lê um membro virtual antes da classe derivada terminar de construir
        Console.WriteLine($"{GetType().Name}: check() = {check()}, Message = {Message}");
    }

    protected abstract string Message { get; }
}

class Regular : Base
{
    private readonly int? count;

    public Regular(int? count) : base(() => count)
    {
        // Esta atribuição só roda depois que o construtor da base termina
        this.count = count;
    }

    protected override string Message => $"count = {count?.ToString() ?? "null"}";
}

class Primary(int? count) : Base(() => count)
{
    protected override string Message => $"count = {count?.ToString() ?? "null"}";
}

O resultado da execução

Para comparar, basta instanciar as duas classes com o mesmo valor.

new Regular(3);
new Primary(3);

A saída, no entanto, mostra uma diferença clara.

Regular: check() = 3, Message = count = null
Primary: check() = 3, Message = count = 3

Nas duas classes, a lambda check() devolve o valor 3. Por outro lado, a propriedade Message mostra null na classe Regular e 3 na classe com primary constructor.

Em outras palavras, as duas versões não são equivalentes. Para entender o motivo, é preciso olhar o código que o compilador realmente gera.

O que o compilador gera para o primary constructor

O compilador do C# transforma a sintaxe de alto nível em um código mais simples antes de emitir IL. Ferramentas como o ILSpy ou o sharplab.io mostram essa versão rebaixada, também conhecida como lowered code.

public Regular(int? count)
{
    // A lambda captura o parâmetro em uma closure (display class)
    var obj = new <>c__DisplayClass1_0();
    obj.count = count;

    // A base executa aqui, antes de o campo receber o valor
    base..ctor(new Func<int?>(obj.<.ctor>b__0));

    // O campo só recebe o valor depois que a base retorna
    this.count = obj.count;
}

public Primary(int? count)
{
    // O campo oculto recebe o valor antes de chamar a base
    <count>P = count;
    base..ctor(new Func<int?>(<.ctor>b__0_0));
}

Como inspecionar o código gerado pelo primary constructor

Você não precisa confiar apenas na explicação. Com poucos passos, dá para confirmar a ordem de atribuição no seu próprio código.

No sharplab.io, cole as classes no painel da esquerda e escolha a saída em C# no painel da direita. A ferramenta mostra o construtor rebaixado, com os campos ocultos e a chamada explícita à base.

Já no ILSpy, abra o assembly compilado e escolha uma versão antiga da linguagem nas opções de descompilação. Assim, o descompilador exibe o construtor sem a sintaxe de alto nível, e a posição da chamada base..ctor fica evidente.

Em ambos os casos, observe dois pontos. Primeiro, onde fica a atribuição do campo em relação à chamada da base; depois, se existe um campo oculto com o sufixo P no nome.

Esse hábito vale para qualquer recurso novo da linguagem. Em geral, o código rebaixado responde em segundos dúvidas que levariam horas de depuração.

A ordem de inicialização de objetos no C#

Esse comportamento não é um acaso. Na prática, o primary constructor segue a mesma regra dos inicializadores de campo, que também rodam antes de base(...).

Segundo o guia de programação do C# sobre construtores, a criação de uma instância segue esta sequência:

1. O runtime zera todos os campos de instância.
2. Os inicializadores de campo do tipo derivado executam.
3. Os inicializadores de campo do tipo base executam.
4. O construtor da base executa.
5. O corpo do construtor derivado executa.

Assim, um campo com inicializador já tem valor quando o construtor da base roda. Por outro lado, uma atribuição dentro do corpo do construtor só acontece no último passo.

O diagrama resume a diferença. Na classe Regular, a base executa no meio do caminho, quando o campo ainda vale null.

Enquanto isso, na classe Primary, o campo oculto já carrega o valor no momento em que a base começa a trabalhar. Ou seja, o primary constructor se comporta como um inicializador de campo, e não como uma atribuição no corpo do construtor.

O caso real do bUnit

O exemplo didático parece artificial, mas o problema surgiu em uma biblioteca real. No bUnit, a ferramenta de testes para componentes Blazor, o construtor base do WaitForHelper inicia um timer.

Quando esse timer dispara, o código lê a propriedade virtual TimeoutErrorMessage. Dessa forma, a leitura do membro virtual acontece em outra thread, possivelmente antes de o construtor derivado terminar.

Com o construtor clássico, se o timer disparasse antes do corpo do construtor derivado, a mensagem de erro saía errada. Ela dizia que a busca não encontrou nenhum elemento, quando deveria dizer que não encontrou exatamente os elementos esperados.

Com o primary constructor, o valor já estava no campo oculto antes de a base iniciar o timer. Portanto, a mensagem passou a refletir a configuração correta em qualquer cenário de corrida.

Esse caso mostra por que vale entender o código gerado. Uma troca que parece puramente estética mudou o comportamento observável de uma biblioteca.

Cuidados ao usar primary constructor

O primary constructor resolve o problema da ordem, mas traz suas próprias armadilhas. Duas delas merecem atenção especial.

class Counter(int count)
{
    public void Reset()
    {
        // Compila sem erro: o parâmetro capturado é mutável
        count = 0;
    }

    public int Current => count;
}

class Primary(int? count) : Base(() => count)
{
    // O inicializador roda antes de base(...), então a base já enxerga o valor
    private readonly int? count = count;

    protected override string Message => $"count = {count?.ToString() ?? "null"}";
}

class Account(decimal balance)
{
    // Cópia 1: o campo explícito
    private readonly decimal initialBalance = balance;

    // Cópia 2: o parâmetro capturado no campo oculto
    public decimal Available => balance;
}

Como evitar o problema na classe base

O primary constructor contorna o sintoma, mas a causa continua na classe base. Afinal, qualquer classe derivada que ainda use construtor tradicional vai cair na mesma armadilha.

Por isso, quando você controla a base, a solução mais robusta é eliminar a leitura virtual durante a construção. Uma forma simples consiste em receber o dado necessário como parâmetro.

abstract class Base
{
    protected Base(Func<int?> check, string message)
    {
        // A base recebe a mensagem pronta, sem consultar um membro virtual
        Console.WriteLine($"{GetType().Name}: check() = {check()}, Message = {message}");
    }
}

class Regular : Base
{
    public Regular(int? count)
        : base(() => count, $"count = {count?.ToString() ?? "null"}")
    {
    }
}

Dessa forma, a classe derivada calcula o valor antes de chamar a base, e a ordem de inicialização deixa de importar. O mesmo raciocínio vale para timers e callbacks: a base só deve iniciar trabalho assíncrono quando o objeto estiver completo.

Outra alternativa é mover a lógica para um método explícito, como Start ou Initialize, chamado depois da construção. Embora exija uma linha a mais de quem consome a classe, essa abordagem torna o ciclo de vida previsível.

Quando a base pertence a uma biblioteca de terceiros, no entanto, você não tem essas opções. Nesse caso, o primary constructor ou um inicializador de campo readonly passam a ser as saídas mais práticas.

Quando migrar para primary constructor

Na maioria dos serviços, a troca é segura e deixa o código mais limpo. Classes que apenas recebem dependências por injeção, sem herança relevante, raramente mudam de comportamento.

No entanto, vale revisar com mais cuidado alguns cenários:

• Classes que herdam de uma base cujo construtor chama membros virtuais ou abstratos.
• Bases que iniciam timers, tasks, threads ou assinaturas de eventos no construtor.
• Tipos que dependem de readonly para garantir a imutabilidade do estado.
• Código que usa o mesmo parâmetro em inicializadores e em membros ao mesmo tempo.

Nesses casos, a migração para primary constructor pode corrigir um bug escondido, como aconteceu no bUnit. Também pode, em outro contexto, alterar um comportamento do qual algum teste dependia.

Por isso, trate a mudança como uma alteração de comportamento, e não como formatação. Rode os testes, observe os avisos do compilador e, quando houver dúvida, abra o código rebaixado no sharplab.io.

Para quem está consolidando a base de herança, encapsulamento e polimorfismo, o curso Fundamentos da Orientação a Objetos do balta.io ajuda a entender por que a ordem de construção importa tanto.

Conclusão sobre o primary constructor

O primary constructor é mais do que açúcar sintático. Quando um membro usa o parâmetro, o compilador o captura em um campo oculto e faz a atribuição antes de chamar o construtor da base.

Já o construtor tradicional atribui o campo no corpo, depois que a base retorna. Assim, qualquer leitura virtual feita pela base enxerga o valor padrão, e não o valor recebido.

Na prática, isso significa que o primary constructor se alinha aos inicializadores de campo. Essa ordem resolveu um problema real no bUnit e pode resolver problemas parecidos no seu código.

Ainda assim, o campo gerado não é readonly, e o uso duplicado do parâmetro gera duas cópias e o aviso CS9124. Conhecer esses detalhes permite usar o recurso com segurança e escolher a forma certa para cada classe.

FAQ

O primary constructor é apenas açúcar sintático?

Não totalmente. Quando um membro da classe usa o parâmetro, o compilador o guarda em um campo oculto e atribui esse campo antes de chamar o construtor da base.

Em qual versão do C# o primary constructor surgiu para classes?

O recurso chegou às classes e structs no C# 12, junto com o .NET 8. Antes, ele existia apenas em records.

O parâmetro de um primary constructor é readonly?

Não. O campo gerado pelo compilador é mutável, então você pode reatribuir o parâmetro dentro da classe.

Como garantir imutabilidade com primary constructor?

Declare um campo readonly com inicializador, como private readonly int? count = count;. Esse inicializador também roda antes do construtor da base.

O que significa o aviso CS9124?

Ele indica que o mesmo parâmetro foi capturado no estado do tipo e também usado para inicializar um campo, uma propriedade ou um evento, gerando duas cópias do valor.

Chamar membros virtuais no construtor é uma boa prática?

Não. A classe derivada ainda não terminou de inicializar, então o membro sobrescrito pode ler valores padrão.