modificador necessário (Referência de C#)

O required modificador indica que o campo ou a propriedade à qual ele se aplica deve ser inicializado por um inicializador de objeto. Qualquer expressão que inicialize uma nova instância do tipo deve inicializar todos os membros necessários. O required modificador está disponível a partir do C# 11.

A linguagem C# faz referência a documentos da versão mais recentemente lançada da linguagem C#. Ele também contém a documentação inicial para funcionalidades em pré-visualizações públicas para o próximo lançamento do idioma.

A documentação identifica qualquer recurso introduzido pela primeira vez nas três últimas versões do idioma ou nas versões prévias públicas atuais.

Dica

Para descobrir quando um recurso foi introduzido pela primeira vez em C#, consulte o artigo sobre o histórico de versão da linguagem C#.

Usando o modificador, os required desenvolvedores podem criar tipos em que as propriedades ou campos devem ser inicializados corretamente, mas ainda permitir a inicialização por meio de inicializadores de objeto. Várias regras garantem esse comportamento:

• Aplique o required modificador a campos e propriedades declaradas e structclass tipos, incluindo record e record struct tipos. Você não pode aplicar o required modificador a membros de um interface.
• Você não pode marcar implementações de interface explícitas como required. Você não pode defini-los em inicializadores de objeto.
• Você deve inicializar os membros necessários, mas pode inicializá-los para null. Se o tipo for um tipo de referência não anulável, o compilador emitirá um aviso se você inicializar o membro para null. O compilador emitirá um erro se o membro não for inicializado de forma alguma.
• Os membros necessários devem ser pelo menos tão visíveis quanto seu tipo de contenção. Por exemplo, uma classe public não pode conter um campo required que é protected. Além disso, as propriedades necessárias devem ter setters (acessadoresset ou init) que sejam pelo menos tão visíveis quanto os tipos que os contêm. O código que cria uma instância não pode definir membros que não estão acessíveis.
• Classes derivadas não podem ocultar um membro required declarado na classe base. Ocultar um membro necessário impede que os chamadores usem inicializadores de objeto para ele. Além disso, os tipos derivados que substituem uma propriedade necessária devem incluir o modificador required. O tipo derivado não pode remover o estado required. Tipos derivados podem adicionar o modificador required ao substituir uma propriedade.
• Você não pode usar um tipo com nenhum required membro como um argumento de tipo quando o parâmetro de tipo inclui a new() restrição. O compilador não pode impor que todos os membros necessários sejam inicializados no código genérico.
• Você não pode usar o required modificador na declaração para parâmetros posicionais em um registro. Você pode adicionar uma declaração explícita para uma propriedade posicional que inclua o modificador required.

Alguns tipos, como registros posicionais, usam um construtor primário para inicializar propriedades posicionais. Se qualquer uma dessas propriedades incluir o modificador required, o construtor primário adicionará o atributo SetsRequiredMembers. Esse atributo indica que o construtor primário inicializa todos os membros necessários. Você pode escrever seu próprio construtor com o atributo System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute. No entanto, o compilador não verifica se esses construtores inicializam todos os membros necessários. Em vez disso, o atributo afirma ao compilador que o construtor inicializa todos os membros necessários. O atributo SetsRequiredMembers adiciona estas regras aos construtores:

• Um construtor que se encadeia a outro construtor anotado com o atributo SetsRequiredMembers, this()ou base(), também deve incluir o atributo SetsRequiredMembers. Isso garante que os chamadores possam usar corretamente todos os constructos apropriados.
• Constructos de cópia gerados para tipos record têm o atributo SetsRequiredMembers aplicado se qualquer um dos membros for required.

Aviso

O SetsRequiredMembers atributo desabilita as verificações do compilador de que todos os required membros são inicializados quando um objeto é criado. Use-o com cuidado.

O código a seguir mostra uma hierarquia de classe que usa o modificador de required para as propriedades FirstName e LastName:

public class Person
{
    public Person() { }

    [SetsRequiredMembers]
    public Person(string firstName, string lastName) =>
        (FirstName, LastName) = (firstName, lastName);

    public required string FirstName { get; init; }
    public required string LastName { get; init; }

    public int? Age { get; set; }
}

public class Student : Person
{
    public Student() : base()
    {
    }

    [SetsRequiredMembers]
    public Student(string firstName, string lastName) :
        base(firstName, lastName)
    {
    }

    public double GPA { get; set; }
}

Para obter mais informações sobre os membros necessários, consulte a especificação do recurso C#11 – Membros necessários.