Propriedades (Guia de Programação em C#)Properties (C# Programming Guide)

Uma propriedade é um membro que oferece um mecanismo flexível para ler, gravar ou calcular o valor de um campo particular.A property is a member that provides a flexible mechanism to read, write, or compute the value of a private field. As propriedades podem ser usadas como se fossem membros de dados públicos, mas na verdade elas são métodos realmente especiais chamados acessadores.Properties can be used as if they are public data members, but they are actually special methods called accessors. Isso permite que os dados sejam acessados facilmente e ainda ajuda a promover a segurança e a flexibilidade dos métodos.This enables data to be accessed easily and still helps promote the safety and flexibility of methods.

Visão geral das propriedadesProperties overview

  • As propriedades permitem que uma classe exponha uma forma pública de obter e definir valores, enquanto oculta o código de implementação ou de verificação.Properties enable a class to expose a public way of getting and setting values, while hiding implementation or verification code.

  • Um acessador de propriedade get é usado para retornar o valor da propriedade e um acessador de propriedade set é usado para atribuir um novo valor.A get property accessor is used to return the property value, and a set property accessor is used to assign a new value. Esses acessadores podem ter diferentes níveis de acesso.These accessors can have different access levels. Para obter mais informações, consulte Restringindo a acessibilidade aos acessadores.For more information, see Restricting Accessor Accessibility.

  • A palavra-chave value é usada para definir o valor que está sendo atribuído pelo acessador set.The value keyword is used to define the value being assigned by the set accessor.

  • As propriedades podem ser de leitura/gravação (elas têm um acessador get e set), somente leitura (elas têm um acessador get, mas nenhum set) ou somente gravação (elas têm um acessador set, mas nenhum get).Properties can be read-write (they have both a get and a set accessor), read-only (they have a get accessor but no set accessor), or write-only (they have a set accessor, but no get accessor). As propriedades somente gravação são raras e são mais comumente usadas para restringir o acesso a dados confidenciais.Write-only properties are rare and are most commonly used to restrict access to sensitive data.

  • As propriedades simples que não exigem nenhum código de acessador personalizado podem ser implementadas como definições de corpo da expressão ou como propriedades autoimplementadas.Simple properties that require no custom accessor code can be implemented either as expression body definitions or as auto-implemented properties.

Propriedades com campos de suporteProperties with backing fields

Um padrão básico para implementar uma propriedade envolve o uso de um campo de suporte particular da propriedade para definir e recuperar o valor da propriedade.One basic pattern for implementing a property involves using a private backing field for setting and retrieving the property value. O acessador get retorna o valor do campo particular e o acessador set pode realizar alguma validação de dados antes de atribuir um valor ao campo particular.The get accessor returns the value of the private field, and the set accessor may perform some data validation before assigning a value to the private field. Os dois acessadores também podem realizar alguma conversão ou cálculo nos dados antes de eles serem armazenados ou retornados.Both accessors may also perform some conversion or computation on the data before it is stored or returned.

O exemplo a seguir ilustra esse padrão.The following example illustrates this pattern. Neste exemplo, a classe TimePeriod representa um intervalo de tempo.In this example, the TimePeriod class represents an interval of time. Internamente, a classe armazena o intervalo de tempo em segundos em um campo particular chamado seconds.Internally, the class stores the time interval in seconds in a private field named seconds. Uma propriedade de leitura/gravação chamada Hours permite que o cliente especifique o intervalo de tempo em horas.A read-write property named Hours allows the customer to specify the time interval in hours. Tanto o acessador get quanto o set executam a conversão necessária entre horas e segundos.Both the get and the set accessors perform the necessary conversion between hours and seconds. Além disso, o acessador set valida os dados e gera um ArgumentOutOfRangeException se o número de horas é inválido.In addition, the set accessor validates the data and throws an ArgumentOutOfRangeException if the number of hours is invalid.

using System;

class TimePeriod
{
   private double seconds;

   public double Hours
   {
       get { return seconds / 3600; }
       set { 
          if (value < 0 || value > 24)
             throw new ArgumentOutOfRangeException(
                   $"{nameof(value)} must be between 0 and 24.");

          seconds = value * 3600; 
       }
   }
}

class Program
{
   static void Main()
   {
       TimePeriod t = new TimePeriod();
       // The property assignment causes the 'set' accessor to be called.
       t.Hours = 24;

       // Retrieving the property causes the 'get' accessor to be called.
       Console.WriteLine($"Time in hours: {t.Hours}");
   }
}
// The example displays the following output:
//    Time in hours: 24

Definições de corpo de expressãoExpression body definitions

Os acessadores de propriedade geralmente consistem em instruções de linha única que simplesmente atribuem ou retornam o resultado de uma expressão.Property accessors often consist of single-line statements that just assign or return the result of an expression. Você pode implementar essas propriedades como membros aptos para expressão.You can implement these properties as expression-bodied members. As definições de corpo da expressão consistem no símbolo => seguido pela expressão à qual atribuir ou recuperar da propriedade.Expression body definitions consist of the => symbol followed by the expression to assign to or retrieve from the property.

A partir do C#6, as propriedades somente leitura podem implementar o acessador get como um membro apto para expressão.Starting with C# 6, read-only properties can implement the get accessor as an expression-bodied member. Nesse caso, nem a palavra-chave do acessador get nem a palavra-chave return é usada.In this case, neither the get accessor keyword nor the return keyword is used. O exemplo a seguir implementa a propriedade Name somente leitura como um membro apto para expressão.The following example implements the read-only Name property as an expression-bodied member.

using System;

public class Person
{
   private string firstName;
   private string lastName;
   
   public Person(string first, string last)
   {
      firstName = first;
      lastName = last;
   }

   public string Name => $"{firstName} {lastName}";   
}

public class Example
{
   public static void Main()
   {
      var person = new Person("Isabelle", "Butts");
      Console.WriteLine(person.Name);
   }
}
// The example displays the following output:
//      Isabelle Butts

A partir do C# 7, os acessadores get e set podem ser implementados como membros aptos para expressão.Starting with C# 7, both the get and the set accessor can be implemented as expression-bodied members. Nesse caso, as palavras-chave get e set devem estar presentes.In this case, the get and set keywords must be present. O exemplo a seguir ilustra o uso de definições de corpo de expressão para ambos os acessadores.The following example illustrates the use of expression body definitions for both accessors. Observe que a palavra-chave return não é usada com o acessador get.Note that the return keyword is not used with the get accessor.

using System;

public class SaleItem
{
   string name;
   decimal cost;
   
   public SaleItem(string name, decimal cost)
   {
      this.name = name;
      this.cost = cost;
   }

   public string Name 
   {
      get => name;
      set => name = value;
   }

   public decimal Price
   {
      get => cost;
      set => cost = value; 
   }
}

class Program
{
   static void Main(string[] args)
   {
      var item = new SaleItem("Shoes", 19.95m);
      Console.WriteLine($"{item.Name}: sells for {item.Price:C2}");
   }
}
// The example displays output like the following:
//       Shoes: sells for $19.95



Propriedades autoimplementadasAuto-implemented properties

Em alguns casos, os acessadores get e set da propriedade apenas atribuem um valor ou recuperam um valor de um campo de suporte sem incluir nenhuma lógica adicional.In some cases, property get and set accessors just assign a value to or retrieve a value from a backing field without including any additional logic. Usando propriedades autoimplementadas, você pode simplificar o código enquanto o compilador C# fornece de forma transparente o campo de suporte para você.By using auto-implemented properties, you can simplify your code while having the C# compiler transparently provide the backing field for you.

Se uma propriedade tiver tanto um acessador get quanto um set, ambos deverão ser autoimplementados.If a property has both a get and a set accessor, both must be auto-implemented. Você define uma propriedade autoimplementada usando as palavras-chave get e set sem fornecer qualquer implementação.You define an auto-implemented property by using the get and set keywords without providing any implementation. O exemplo a seguir repete o anterior, exceto que Name e Price são propriedades autoimplementadas.The following example repeats the previous one, except that Name and Price are auto-implemented properties. Observe que o exemplo também remove o construtor parametrizado, para que os objetos SaleItem agora sejam inicializados com uma chamada para o construtor padrão e um inicializador de objeto.Note that the example also removes the parameterized constructor, so that SaleItem objects are now initialized with a call to the default constructor and an object initializer.

using System;

public class SaleItem
{
   public string Name 
   { get; set; }

   public decimal Price
   { get; set; }
}

class Program
{
   static void Main(string[] args)
   {
      var item = new SaleItem{ Name = "Shoes", Price = 19.95m };
      Console.WriteLine($"{item.Name}: sells for {item.Price:C2}");
   }
}
// The example displays output like the following:
//       Shoes: sells for $19.95



Especificação da Linguagem C#C# Language Specification

Para obter mais informações, consulte a Especificação da linguagem C#. A especificação da linguagem é a fonte definitiva para a sintaxe e o uso de C#.

Consulte tambémSee also

Guia de Programação em C#C# Programming Guide
Usando propriedadesUsing Properties
IndexadoresIndexers
Palavra-chave get get keyword
Palavra-chave setset keyword