Métodos (Guia de Programação em C#)Methods (C# Programming Guide)

Um método é um bloco de código que contém uma série de instruções.A method is a code block that contains a series of statements. Um programa faz com que as instruções sejam executadas chamando o método e especificando os argumentos de método necessários.A program causes the statements to be executed by calling the method and specifying any required method arguments. No C#, todas as instruções executadas são realizadas no contexto de um método.In C#, every executed instruction is performed in the context of a method. O método Main é o ponto de entrada para todos os aplicativos C# e é chamado pelo CLR (Common Language Runtime) quando o programa é iniciado.The Main method is the entry point for every C# application and it is called by the common language runtime (CLR) when the program is started.

Observação

Este tópico aborda os métodos nomeados.This topic discusses named methods. Para obter informações sobre funções anônimas, consulte Funções anônimas.For information about anonymous functions, see Anonymous Functions.

Assinaturas de MétodoMethod Signatures

Os métodos são declarados em uma classe ou struct especificando o nível de acesso, como public ou private, modificadores opcionais, como abstract ou sealed, o valor retornado, o nome do método e os parâmetros de método.Methods are declared in a class or struct by specifying the access level such as public or private, optional modifiers such as abstract or sealed, the return value, the name of the method, and any method parameters. Juntas, essas partes são a assinatura do método.These parts together are the signature of the method.

Observação

Um tipo de retorno de um método não faz parte da assinatura do método para fins de sobrecarga de método.A return type of a method is not part of the signature of the method for the purposes of method overloading. No entanto, ele faz parte da assinatura do método ao determinar a compatibilidade entre um delegado e o método para o qual ele aponta.However, it is part of the signature of the method when determining the compatibility between a delegate and the method that it points to.

Os parâmetros de método estão entre parênteses e separados por vírgulas.Method parameters are enclosed in parentheses and are separated by commas. Parênteses vazios indicam que o método não requer parâmetros.Empty parentheses indicate that the method requires no parameters. Essa classe contém três métodos:This class contains three methods:

abstract class Motorcycle
{
    // Anyone can call this.
    public void StartEngine() {/* Method statements here */ }

    // Only derived classes can call this.
    protected void AddGas(int gallons) { /* Method statements here */ }

    // Derived classes can override the base class implementation.
    public virtual int Drive(int miles, int speed) { /* Method statements here */ return 1; }

    // Derived classes must implement this.
    public abstract double GetTopSpeed(); 
}

Acesso a métodoMethod Access

Chamar um método em um objeto é como acessar um campo.Calling a method on an object is like accessing a field. Após o nome do objeto, adicione um ponto final, o nome do método e parênteses.After the object name, add a period, the name of the method, and parentheses. Os argumentos são listados dentro dos parênteses e são separados por vírgulas.Arguments are listed within the parentheses, and are separated by commas. Os métodos da classe Motorcycle podem, portanto, ser chamados como no exemplo a seguir:The methods of the Motorcycle class can therefore be called as in the following example:

class TestMotorcycle : Motorcycle
{

    public override double GetTopSpeed()
    {
        return 108.4;
    }

    static void Main()
    {
        
        TestMotorcycle moto = new TestMotorcycle();

        moto.StartEngine();
        moto.AddGas(15);
        moto.Drive(5, 20);
        double speed = moto.GetTopSpeed();
        Console.WriteLine("My top speed is {0}", speed);            
    }
}

Parâmetros de método versus ArgumentsMethod Parameters vs. Arguments

A definição do método especifica os nomes e tipos de quaisquer parâmetros obrigatórios.The method definition specifies the names and types of any parameters that are required. Quando o código de chamada chama o método, ele fornece valores concretos, chamados argumentos, para cada parâmetro.When calling code calls the method, it provides concrete values called arguments for each parameter. Os argumentos devem ser compatíveis com o tipo de parâmetro, mas o nome do argumento (se houver) usado no código de chamada não precisa ser o mesmo que o parâmetro nomeado definido no método.The arguments must be compatible with the parameter type but the argument name (if any) used in the calling code does not have to be the same as the parameter named defined in the method. Por exemplo:For example:

public void Caller()
{
    int numA = 4;
    // Call with an int variable.
    int productA = Square(numA);

    int numB = 32;
    // Call with another int variable.
    int productB = Square(numB);

    // Call with an integer literal.
    int productC = Square(12);

    // Call with an expression that evaulates to int.
    productC = Square(productA * 3);
}

int Square(int i)
{
    // Store input argument in a local variable.
    int input = i;
    return input * input;
}

Passagem por referência versus passagem por valorPassing by Reference vs. Passing by Value

Por padrão, quando um tipo de valor é passado para um método, uma cópia é passada em vez do objeto propriamente dito.By default, when a value type is passed to a method, a copy is passed instead of the object itself. Portanto, alterações no argumento não têm nenhum efeito sobre a cópia original no método de chamada.Therefore, changes to the argument have no effect on the original copy in the calling method. Você pode passar um tipo de valor por referência usando a palavra-chave ref.You can pass a value-type by reference by using the ref keyword. Para obter mais informações, consulte Passando parâmetros de tipo de valor.For more information, see Passing Value-Type Parameters. Para obter uma lista de tipos de valor internos, consulte Tabela de tipos de valor.For a list of built-in value types, see Value Types Table.

Quando um objeto de tipo de referência é passado para um método, uma referência ao objeto é passada.When an object of a reference type is passed to a method, a reference to the object is passed. Ou seja, o método recebe não o objeto em si, mas um argumento que indica o local do objeto.That is, the method receives not the object itself but an argument that indicates the location of the object. Se você alterar um membro do objeto usando essa referência, a alteração será refletida no argumento no método de chamada, ainda que você passe o objeto por valor.If you change a member of the object by using this reference, the change is reflected in the argument in the calling method, even if you pass the object by value.

Crie um tipo de referência usando a palavra-chave class, como mostra o exemplo a seguir.You create a reference type by using the class keyword, as the following example shows.

public class SampleRefType
{
    public int value;
}

Agora, se você passar um objeto com base nesse tipo para um método, uma referência ao objeto será passada.Now, if you pass an object that is based on this type to a method, a reference to the object is passed. O exemplo a seguir passa um objeto do tipo SampleRefType ao método ModifyObject.The following example passes an object of type SampleRefType to method ModifyObject.

public static void TestRefType()
{
    SampleRefType rt = new SampleRefType();
    rt.value = 44;
    ModifyObject(rt);
    Console.WriteLine(rt.value);
}
static void ModifyObject(SampleRefType obj)
{
    obj.value = 33;
}

O exemplo faz essencialmente a mesma coisa que o exemplo anterior, pois ele passa um argumento por valor para um método.The example does essentially the same thing as the previous example in that it passes an argument by value to a method. No entanto, como um tipo de referência é usado, o resultado é diferente.But, because a reference type is used, the result is different. A modificação feita em ModifyObject para o campo value do parâmetro, obj, também altera o campo value do argumento, rt, no método TestRefType.The modification that is made in ModifyObject to the value field of the parameter, obj, also changes the value field of the argument, rt, in the TestRefType method. O método TestRefType exibe 33 como a saída.The TestRefType method displays 33 as the output.

Para obter mais informações sobre como passar tipos de referência por referência e por valor, consulte Passando parâmetros de tipo de referência e Tipos de referência.For more information about how to pass reference types by reference and by value, see Passing Reference-Type Parameters and Reference Types.

Valores de RetornoReturn Values

Os métodos podem retornar um valor para o chamador.Methods can return a value to the caller. Se o tipo de retorno, o tipo listado antes do nome do método, não for void, o método poderá retornar o valor usando a palavra-chave return.If the return type, the type listed before the method name, is not void, the method can return the value by using the return keyword. Uma instrução com a palavra-chave return seguida por uma variável que corresponde ao tipo de retorno retornará esse valor ao chamador do método.A statement with the return keyword followed by a value that matches the return type will return that value to the method caller.

O valor pode ser retornado ao chamador por valor ou, começando com o C# 7.0, por referência.The value can be returned to the caller by value or, starting with C# 7.0, by reference. Valores são retornados ao chamador por referência se a ref palavra-chave é usada na assinatura do método e segue cada palavra-chave return.Values are returned to the caller by reference if the ref keyword is used in the method signature and it follows each return keyword. Por exemplo, a instrução de retorno e a assinatura de método a seguir indicam que o método retorna uma variável chamada estDistance por referência para o chamador.For example, the following method signature and return statement indicate that the method returns a variable names estDistance by reference to the caller.

public ref double GetEstimatedDistance()
{
   return ref estDistance;
}

A palavra-chave return também interrompe a execução do método.The return keyword also stops the execution of the method. Se o tipo de retorno for void, uma instrução return sem um valor ainda será útil para interromper a execução do método.If the return type is void, a return statement without a value is still useful to stop the execution of the method. Sem a palavra-chave return, a execução do método será interrompida quando chegar ao final do bloco de código.Without the return keyword, the method will stop executing when it reaches the end of the code block. Métodos com um tipo de retorno não nulo devem usar a palavra-chave return para retornar um valor.Methods with a non-void return type are required to use the return keyword to return a value. Por exemplo, esses dois métodos usam a palavra-chave return para retornar inteiros:For example, these two methods use the return keyword to return integers:

class SimpleMath
{
    public int AddTwoNumbers(int number1, int number2)
    {
        return number1 + number2;
    }

    public int SquareANumber(int number)
    {
        return number * number;
    }
}

Para usar um valor retornado de um método, o método de chamada pode usar a chamada de método em si em qualquer lugar que um valor do mesmo tipo seria suficiente.To use a value returned from a method, the calling method can use the method call itself anywhere a value of the same type would be sufficient. Você também pode atribuir o valor retornado a uma variável.You can also assign the return value to a variable. Por exemplo, os dois exemplos de código a seguir obtêm a mesma meta:For example, the following two code examples accomplish the same goal:

int result = obj.AddTwoNumbers(1, 2);
result = obj.SquareANumber(result);
// The result is 9.
Console.WriteLine(result);
result = obj.SquareANumber(obj.AddTwoNumbers(1, 2));
// The result is 9.
Console.WriteLine(result);

Usar uma variável local, nesse caso, result, para armazenar um valor é opcional.Using a local variable, in this case, result, to store a value is optional. Isso pode ajudar a legibilidade do código ou pode ser necessário se você precisar armazenar o valor original do argumento para todo o escopo do método.It may help the readability of the code, or it may be necessary if you need to store the original value of the argument for the entire scope of the method.

Para usar o valor retornado de um método por referência, você deve declarar uma variável ref local se você pretende modificar seu valor.To use a value returned by reference from a method, you must declare a ref local variable if you intend to modify its value. Por exemplo, se o método Planet.GetEstimatedDistance retorna um valor Double por referência, você pode defini-lo como uma variável ref local com código semelhante ao seguinte:For example, if the Planet.GetEstimatedDistance method returns a Double value by reference, you can define it as a ref local variable with code like the following:

ref int distance = plant 

Retornar uma matriz multidimensional de um método, M, que modifica o conteúdo da matriz, não é necessário se a função de chamada passou a matriz para M.Returning a multi-dimensional array from a method, M, that modifies the array's contents is not necessary if the calling function passed the array into M. Você pode retornar a matriz resultante de M para um bom estilo ou fluxo funcional de valores, mas isso não é necessário porque o C# passa todos os tipos de referência por valor e o valor de uma referência de matriz é o ponteiro para a matriz.You may return the resulting array from M for good style or functional flow of values, but it is not necessary because C# passes all reference types by value, and the value of an array reference is the pointer to the array. No método M, as alterações do conteúdo da matriz podem ser observadas por qualquer código que tiver uma referência à matriz, conforme mostrado no exemplo a seguir.In the method M, any changes to the array's contents are observable by any code that has a reference to the array, as shown in the following example.

static void Main(string[] args)  
        {  
            int[,] matrix = new int[2, 2];  
            FillMatrix(matrix);  
            // matrix is now full of -1  
        }  

        public static void FillMatrix(int[,] matrix)  
        {  
            for (int i = 0; i < matrix.GetLength(0); i++)  
            {  
                for (int j = 0; j < matrix.GetLength(1); j++)  
                {  
                    matrix[i, j] = -1;  
                }  
            }  
        }  

Para obter mais informações, consulte return.For more information, see return.

Métodos assíncronosAsync Methods

Usando o recurso async, você pode invocar métodos assíncronos sem usar retornos de chamada explícitos ou dividir manualmente seu código entre vários métodos ou expressões lambda.By using the async feature, you can invoke asynchronous methods without using explicit callbacks or manually splitting your code across multiple methods or lambda expressions.

Se marcar um método com o modificador async, você poderá usar o operador await no método.If you mark a method with the async modifier, you can use the await operator in the method. Quando o controle atinge uma expressão await no método assíncrono, ele retorna para o chamador e o progresso no método é suspenso até a tarefa aguardada ser concluída.When control reaches an await expression in the async method, control returns to the caller, and progress in the method is suspended until the awaited task completes. Quando a tarefa for concluída, a execução poderá ser retomada no método.When the task is complete, execution can resume in the method.

Observação

Um método assíncrono retorna para o chamador quando encontra o primeiro objeto esperado que ainda não está completo ou chega ao final do método assíncrono, o que ocorrer primeiro.An async method returns to the caller when either it encounters the first awaited object that’s not yet complete or it gets to the end of the async method, whichever occurs first.

Um método assíncrono pode conter um tipo de retorno Task<TResult>, Task ou nulo.An async method can have a return type of Task<TResult>, Task, or void. O tipo de retorno nulo é usado principalmente para definir manipuladores de eventos, em que um tipo de retorno nulo é necessário.The void return type is used primarily to define event handlers, where a void return type is required. Um método assíncrono que retorna nulo não pode ser aguardado e o chamador de um método de retorno nulo não pode capturar as exceções que esse método gera.An async method that returns void can't be awaited, and the caller of a void-returning method can't catch exceptions that the method throws.

No exemplo a seguir, DelayAsync é um método assíncrono que tem um tipo de retorno de Task<TResult>.In the following example, DelayAsync is an async method that has a return type of Task<TResult>. DelayAsync tem uma instrução return que retorna um número inteiro.DelayAsync has a return statement that returns an integer. Portanto, a declaração do método de Task<int> deve ter um tipo de retorno de DelayAsync.Therefore the method declaration of DelayAsync must have a return type of Task<int>. Como o tipo de retorno é Task<int>, a avaliação da expressão await em DoSomethingAsync produz um inteiro, como a instrução a seguir demonstra: int result = await delayTask.Because the return type is Task<int>, the evaluation of the await expression in DoSomethingAsync produces an integer as the following statement demonstrates: int result = await delayTask.

O método startButton_Click é um exemplo de método assíncrono que tem um tipo de retorno nulo.The startButton_Click method is an example of an async method that has a return type of void. Como DoSomethingAsync é um método assíncrono, a tarefa para a chamada para DoSomethingAsync deve ser colocada em espera, como mostra a seguinte instrução: await DoSomethingAsync();.Because DoSomethingAsync is an async method, the task for the call to DoSomethingAsync must be awaited, as the following statement shows: await DoSomethingAsync();. O método startButton_Click deve ser definido com o modificador async porque o método tem uma expressão await.The startButton_Click method must be defined with the async modifier because the method has an await expression.

// using System.Diagnostics;
// using System.Threading.Tasks;

// This Click event is marked with the async modifier.
private async void startButton_Click(object sender, RoutedEventArgs e)
{
    await DoSomethingAsync();
}

private async Task DoSomethingAsync()
{
    Task<int> delayTask = DelayAsync();
    int result = await delayTask;

    // The previous two statements may be combined into
    // the following statement.
    //int result = await DelayAsync();

    Debug.WriteLine("Result: " + result);
}

private async Task<int> DelayAsync()
{
    await Task.Delay(100);
    return 5;
}

// Output:
//  Result: 5

Um método assíncrono não pode declarar nenhum parâmetro ref ou out, mas pode chamar métodos com tais parâmetros.An async method can't declare any ref or out parameters, but it can call methods that have such parameters.

Para obter mais informações sobre os métodos assíncronos, consulte Programação assíncrona com async e await, Fluxo de controle em programas assíncronos e Tipos de retorno assíncronos.For more information about async methods, see Asynchronous Programming with async and await, Control Flow in Async Programs, and Async Return Types.

Definições de corpo de expressãoExpression Body Definitions

É comum ter definições de método que simplesmente retornam imediatamente com o resultado de uma expressão ou que têm uma única instrução como o corpo do método.It is common to have method definitions that simply return immediately with the result of an expression, or that have a single statement as the body of the method. Há um atalho de sintaxe para definir esses métodos usando =>:There is a syntax shortcut for defining such methods using =>:

public Point Move(int dx, int dy) => new Point(x + dx, y + dy);   
public void Print() => Console.WriteLine(First + " " + Last);  
// Works with operators, properties, and indexers too.  
public static Complex operator +(Complex a, Complex b) => a.Add(b);  
public string Name => First + " " + Last;   
public Customer this[long id] => store.LookupCustomer(id);  

Se o método retornar void ou for um método assíncrono, o corpo do método deverá ser uma expressão de instrução (igual às lambdas).If the method returns void or is an async method, then the body of the method must be a statement expression (same as with lambdas). Para propriedades e indexadores, eles devem ser somente leitura e você não usa a palavra-chave do acessador get.For properties and indexers, they must be read only, and you don't use the get accessor keyword.

IteratorsIterators

Um iterador realiza uma iteração personalizada em uma coleção, como uma lista ou uma matriz.An iterator performs a custom iteration over a collection, such as a list or an array. Um iterador usa a instrução yield return para retornar um elemento de cada vez.An iterator uses the yield return statement to return each element one at a time. Quando uma instrução yield return for alcançada, o local atual no código será lembrado.When a yield return statement is reached, the current location in code is remembered. A execução será reiniciada desse local quando o iterador for chamado na próxima vez.Execution is restarted from that location when the iterator is called the next time.

Você chama um iterador de um código de cliente usando uma instrução foreach.You call an iterator from client code by using a foreach statement.

O tipo de retorno de um iterador pode ser IEnumerable, IEnumerable<T>, IEnumerator ou IEnumerator<T>.The return type of an iterator can be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

Para obter mais informações, consulte Iteradores.For more information, see Iterators.

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

Para obter mais informações, consulte a Especificação da linguagem C#.For more information, see the C# Language Specification. A especificação da linguagem é a fonte definitiva para a sintaxe e o uso de C#.The language specification is the definitive source for C# syntax and usage.

Consulte tambémSee Also

Guia de Programação em C#C# Programming Guide
Classes e StructsClasses and Structs
Modificadores de acessoAccess Modifiers
Classes static e membros de classes staticStatic Classes and Static Class Members
HerançaInheritance
Classes e membros de classes abstract e sealedAbstract and Sealed Classes and Class Members
paramsparams
returnreturn
outout
refref
Passando parâmetrosPassing Parameters