Classes e métodos partial (Guia de Programação em C#)

É possível dividir a definição de uma classe, um struct, uma interface ou um método em dois ou mais arquivos de origem. Cada arquivo de origem contém uma seção da definição de tipo ou método e todas as partes são combinadas quando o aplicativo é compilado.

Classes parciais

Há várias situações em que a divisão de uma definição de classe é desejável:

• Declarar uma classe em arquivos separados permite que vários programadores trabalhem nela ao mesmo tempo.
• Você pode adicionar código à classe sem precisar recriar o arquivo de origem que inclui a origem gerada automaticamente. O Visual Studio usa essa abordagem quando cria Windows Forms, código de wrapper de serviço Web e assim por diante. Você pode criar código que usa essas classes sem precisar modificar o arquivo que o Visual Studio cria.
• Os geradores de origem podem gerar funcionalidade extra em uma classe.

Para dividir uma definição de classe, use o modificador de palavra-chave parcial . Na prática, cada classe parcial é normalmente definida em um arquivo separado, facilitando o gerenciamento e a expansão da classe ao longo do tempo.

O exemplo a seguir Employee demonstra como a classe pode ser dividida em dois arquivos: Employee_Part1.cs e Employee_Part2.cs.

// This is in Employee_Part1.cs
public partial class Employee
{
    public void DoWork()
    {
        Console.WriteLine("Employee is working.");
    }
}

// This is in Employee_Part2.cs
public partial class Employee
{
    public void GoToLunch()
    {
        Console.WriteLine("Employee is at lunch.");
    }
}

//Main program demonstrating the Employee class usage
public class Program
{
    public static void Main()
    {
        Employee emp = new Employee();
        emp.DoWork();
        emp.GoToLunch();
    }
}

// Expected Output:
// Employee is working.
// Employee is at lunch.

A palavra-chave partial indica que outras partes da classe, struct ou interface podem ser definidas no namespace. Todas as partes devem usar a palavra-chave partial. Todas as partes devem estar disponíveis em tempo de compilação para formar o tipo final. Todas as partes devem ter a mesma acessibilidade, tais como public, private e assim por diante.

Se alguma parte for declarada como abstrata, o tipo inteiro será considerado abstrato. Se alguma parte for declarada como lacrada, o tipo inteiro será considerado lacrado. Se alguma parte declarar um tipo base, o tipo inteiro herda dessa classe.

Todas as partes que especificam uma classe base devem concordar, mas partes que omitem uma classe base ainda herdam o tipo base. As partes podem especificar diferentes interfaces base e o tipo final implementa todas as interfaces listadas por todas as declarações parciais. Qualquer membro de classe, struct ou interface declarado em uma definição parcial está disponível para todas as outras partes. O tipo final é a combinação de todas as partes em tempo de compilação.

Observação

O modificador partial não está disponível em declarações de enumeração ou delegados.

O exemplo a seguir mostra que os tipos aninhados podem ser parciais, mesmo que o tipo em que estão aninhados não seja parcial.

class Container
{
    partial class Nested
    {
        void Test() { }
    }

    partial class Nested
    {
        void Test2() { }
    }
}

Em tempo de compilação, atributos de definições de tipo parcial são mesclados. Por exemplo, considere as declarações a seguir:

[SerializableAttribute]
partial class Moon { }

[ObsoleteAttribute]
partial class Moon { }

Elas são equivalentes às seguintes declarações:

[SerializableAttribute]
[ObsoleteAttribute]
class Moon { }

Os itens a seguir são mesclados de todas as definições de tipo parcial:

• Comentários XML. No entanto, se ambas as declarações de um membro parcial incluírem comentários, apenas os comentários do membro de implementação serão incluídos.
• interfaces
• atributos de parâmetro de tipo genérico
• atributos class
• membros

Por exemplo, considere as declarações a seguir:

partial class Earth : Planet, IRotate { }
partial class Earth : IRevolve { }

Elas são equivalentes às seguintes declarações:

class Earth : Planet, IRotate, IRevolve { }

Restrições

Há várias regras a seguir quando você está trabalhando com definições parciais de classe:

• Todas as definições de tipo parcial que devem ser partes do mesmo tipo devem ser modificadas com partial. Por exemplo, as seguintes declarações de classe geram um erro:

  public partial class A { }
  //public class A { }  // Error, must also be marked partial
  

• O modificador partial só pode aparecer imediatamente antes da palavra-chave class, struct ou interface.
• Tipos parciais aninhados são permitidos em definições de tipo parcial, conforme ilustrado no exemplo a seguir:

  partial class ClassWithNestedClass
  {
      partial class NestedClass { }
  }
  
  partial class ClassWithNestedClass
  {
      partial class NestedClass { }
  }
  

• Todas as definições de tipo parcial que devem ser partes do mesmo tipo devem ser definidas no mesmo assembly e no mesmo módulo (arquivo .dll ou .exe). Definições parciais não podem abranger vários módulos.
• O nome de classe e os parâmetros de tipo genérico devem corresponder em todas as definições de tipo parcial. Tipos genéricos podem ser parciais. Cada declaração parcial deve usar os mesmos nomes de parâmetro na mesma ordem.
• As seguintes palavras-chave em uma definição de tipo parcial são opcionais, mas, se estiverem presentes em uma definição de tipo parcial, é preciso que esteja especificada em outra definição parcial para o mesmo tipo:
  • public
  • private
  • protected
  • interno
  • abstract
  • sealed
  • classe base
  • modificador new (partes aninhadas)
  • restrições genéricas

Para obter mais informações, consulte Restrições a parâmetros de tipo.

Exemplos

No exemplo a seguir, os campos e o Coords construtor da classe são declarados em uma definição de classe parcial (Coords_Part1.cs) e o método é declarado PrintCoords em outra definição de classe parcial (Coords_Part2.cs). Essa separação demonstra como as classes parciais podem ser divididas em vários arquivos para facilitar a manutenção.

 // This is in Coords_Part1.cs
 public partial class Coords
 {
     private int x;
     private int y;

     public Coords(int x, int y)
     {
         this.x = x;
         this.y = y;
     }
 }

 // This is in Coords_Part2.cs
 public partial class Coords
 {
     public void PrintCoords()
     {
         Console.WriteLine("Coords: {0},{1}", x, y);
     }
 }

// Main program demonstrating the Coords class usage
 class TestCoords
 {
     static void Main()
     {
         Coords myCoords = new Coords(10, 15);
         myCoords.PrintCoords();

         // Keep the console window open in debug mode.
         Console.WriteLine("Press any key to exit.");
         Console.ReadKey();
     }
 }
 // Output: Coords: 10,15

O exemplo a seguir mostra que você também pode desenvolver interfaces e structs parciais.

partial interface ITest
{
    void Interface_Test();
}

partial interface ITest
{
    void Interface_Test2();
}

partial struct S1
{
    void Struct_Test() { }
}

partial struct S1
{
    void Struct_Test2() { }
}

Membros parciais

Uma classe ou struct parcial pode conter um membro parcial. Uma parte da classe contém a assinatura do membro. Uma implementação pode ser definida na mesma parte ou em outra parte.

Uma implementação não é necessária para um método parcial quando a assinatura obedece às seguintes regras:

• A declaração não inclui modificadores de acesso. O método tem acesso private por padrão.
• O tipo de retorno é void.
• Nenhum dos parâmetros tem o modificador out.
• A declaração do método não pode incluir nenhum dos seguintes modificadores:
  • virtual
  • override
  • sealed
  • new
  • extern

O método e todas as chamadas para o método são removidos no momento da compilação quando não há nenhuma implementação.

Qualquer método que não esteja em conformidade com todas essas restrições, incluindo propriedades e indexadores, deve fornecer uma implementação. Essa implementação pode ser fornecida por um gerador de origem. Propriedades parciais não podem ser implementadas usando propriedades implementadas automaticamente. O compilador não pode distinguir entre uma propriedade implementada automaticamente e a declaração de declaração de uma propriedade parcial.

A partir do C# 13, a declaração de implementação de uma propriedade parcial pode usar propriedades com suporte de campo para definir a declaração de implementação. Uma propriedade com suporte de campo fornece uma sintaxe concisa em que a palavra-chave acessa field o campo de suporte sintetizado do compilador para a propriedade. Por exemplo, você pode escrever o seguinte:

// in file1.cs
public partial class PropertyBag
{
    // Defining declaration
    public partial int MyProperty { get; set; }
}

// In file2.cs
public partial class PropertyBag
{
    // Defining declaration
    public partial int MyProperty { get => field; set; }
}

Você pode usar field no get acessador ou set em ambos.

Importante

A field palavra-chave é um recurso de visualização no C# 13. Você deve estar usando o .NET 9 e definir seu <LangVersion> elemento como preview no arquivo de projeto para usar a field palavra-chave contextual.

Você deve ter cuidado ao usar o recurso de field palavra-chave em uma classe que tenha um campo chamado field. A nova field palavra-chave sombreia um campo nomeado field no escopo de um acessador de propriedade. Você pode alterar o nome da field variável ou usar o @ token para fazer referência ao field identificador como @field. Você pode saber mais lendo a especificação do recurso para a field palavra-chave.

Métodos parciais permitem que o implementador de uma parte de uma classe declare um membro. O implementador de outra parte da classe pode definir esse membro. Há dois cenários em que essa separação é útil: modelos que geram código clichê e geradores de origem.

• Código do modelo: o modelo reserva um nome de método e uma assinatura para que o código gerado possa chamar o método. Esses métodos seguem as restrições que permitem a um desenvolvedor decidir se quer implementar o método. Se o método não for implementado, o compilador removerá a assinatura do método e todas as chamadas para o método. As chamadas para o método, incluindo qualquer resultado que ocorreria da avaliação de argumentos nas chamadas, não têm efeito em tempo de execução. Portanto, qualquer código na classe parcial pode usar livremente um método parcial, mesmo que a implementação não seja fornecida. Nenhum erro de tempo de compilação ou em tempo de execução resulta se o método for chamado, mas não implementado.
• Geradores de origem: os geradores de origem fornecem uma implementação para membros. O desenvolvedor humano pode adicionar a declaração de membro (geralmente com atributos lidos pelo gerador de origem). O desenvolvedor pode gravar um código que chama esses membros. O gerador de origem é executado durante a compilação e fornece a implementação. Nesse cenário, as restrições para membros parciais que nem sempre são implementadas geralmente não são seguidas.

// Definition in file1.cs
partial void OnNameChanged();

// Implementation in file2.cs
partial void OnNameChanged()
{
  // method body
}

• As declarações de membro parcial devem começar com a palavra-chave contextual partial.
• As assinaturas de membro parcial em ambas as partes do tipo parcial devem ser correspondentes.
• Métodos de membros podem ter modificadores static e unsafe.
• Membros parciais podem ser genéricos. As restrições devem ser as mesmas na declaração de método de definição e implementação. Os nomes de parâmetro e de parâmetro de tipo não precisam ser os mesmos na declaração de implementação e de definição.
• Você pode criar um delegado para um método parcial definido e implementado, mas não para um método parcial que não tenha uma implementação.

Especificação da Linguagem C#

Para obter mais informações, confira Tipos parciais e Métodos parciais na Especificação da Linguagem C#. A especificação da linguagem é a fonte definitiva para a sintaxe e o uso de C#. Os novos recursos para métodos parciais são definidos na especificação do recurso.

Confira também

• Classes
• Tipos de estrutura
• Interfaces
• parcial (tipo)