Compartilhar via

Nome e argumentos Opcional (guia de programação de C#)

  • Artigo

Visual C# 2010apresenta os argumentos nomeados e opcionais. Argumentos nomeados permitem que você especificar um argumento para um determinado parâmetro associando-se o argumento com o nome do parâmetro, em vez de fazê-lo com a posição do parâmetro na lista de parâmetros. Argumentos opcionais permitem que você omitir argumentos para alguns parâmetros. Ambas as técnicas podem ser usadas com métodos, indexadores, construtores e delegados.

Ao usar argumentos nomeados e opcionais, os argumentos são avaliados na ordem em que aparecem na lista do argumento, não na lista de parâmetro.

Parâmetros nomeados e opcionais, quando usados em conjunto, permitem que você fornecer argumentos para apenas alguns parâmetros de uma lista de parâmetros opcionais. Esse recurso facilita bastante a chamadas para interfaces de COM, como, por exemplo, as APIs de automação de Microsoft Office.

Argumentos nomeados

Argumentos nomeados liberá-lo da necessidade de memorizar ou consultar a ordem dos parâmetros em listas de parâmetros de métodos chamados. O parâmetro para cada argumento pode ser especificado por nome de parâmetro. Por exemplo, uma função que calcula o índice de massa corporal (IMC) pode ser chamado da forma padrão enviando argumentos de peso e altura por posição, na ordem definida pela função.

CalculateBMI(123, 64);

Se não lembrar a ordem dos parâmetros, mas você sabe que seus nomes, você pode enviar os argumentos em qualquer ordem, peso a primeira ou a altura primeiro.

CalculateBMI(weight: 123, height: 64);

CalculateBMI(height: 64, weight: 123);

Argumentos nomeados também melhoram a legibilidade do código, identificando o que representa cada argumento.

Um argumento nomeado pode seguir argumentos posicionais, conforme mostrado aqui.

CalculateBMI(123, height: 64);

No entanto, um argumento posicional não pode seguir um argumento nomeado. A instrução a seguir faz com que um erro do compilador.

//CalculateBMI(weight: 123, 64);

Exemplo

O código a seguir implementa os exemplos desta seção.

class NamedExample
{
    static void Main(string[] args)
    {
        // The method can be called in the normal way, by using positional arguments.
        Console.WriteLine(CalculateBMI(123, 64));

        // Named arguments can be supplied for the parameters in either order.
        Console.WriteLine(CalculateBMI(weight: 123, height: 64));
        Console.WriteLine(CalculateBMI(height: 64, weight: 123));

        // Positional arguments cannot follow named arguments.
        // The following statement causes a compiler error.
        //Console.WriteLine(CalculateBMI(weight: 123, 64));

        // Named arguments can follow positional arguments.
        Console.WriteLine(CalculateBMI(123, height: 64));
    }

    static int CalculateBMI(int weight, int height)
    {
        return (weight * 703) / (height * height);
    }
}

Argumentos opcionais

A definição de um método, construtor, indexador ou representante pode especificar que os seus parâmetros são necessários ou que eles são opcionais. Qualquer chamada deve fornecer argumentos para todos os parâmetros necessários, mas pode omitir argumentos para os parâmetros opcionais.

Cada parâmetro opcional tem um valor padrão como parte de sua definição. Se nenhum argumento for enviado para esse parâmetro, o valor padrão é usado. Valores padrão devem ser constantes.

Parâmetros opcionais são definidos no final da lista de parâmetros, após quaisquer parâmetros necessários. Se o chamador fornece um argumento para qualquer um de uma sucessão de parâmetros opcionais, ele deve fornecer argumentos para todos os parâmetros opcionais de anteriores. Separados por ponto-e-vírgula lacunas na lista de argumentos não são suportadas. Por exemplo, no código a seguir, método de instância ExampleMethod é definido com um obrigatório e dois parâmetros opcionais.

public void ExampleMethod(int required, string optionalstr = "default string",
    int optionalint = 10)

A seguinte chamada para ExampleMethod causa um erro do compilador, como um argumento foi fornecido para o terceiro parâmetro, mas não para o segundo.

//anExample.ExampleMethod(3, ,4);

No entanto, se você souber o nome do terceiro parâmetro, você pode usar um argumento nomeado para realizar a tarefa.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense usa colchetes para indicar os parâmetros opcionais, conforme mostrado na ilustração a seguir.

Parâmetros opcionais em ExampleMethod

Informações rápidas do IntelliSense para o método ExampleMethod.

ObservaçãoObservação

Também é possível declarar parâmetros opcionais usando o.NET OptionalAttribute classe. OptionalAttributeparâmetros não exigem um valor padrão.

Exemplo

No exemplo a seguir, o construtor para ExampleClass possui um parâmetro é opcional. Método de instância ExampleMethod tem um parâmetro obrigatório, requirede dois parâmetros opcionais, optionalstr e optionalint. O código de Main mostra as diferentes maneiras nas quais o construtor e o método podem ser chamados.

namespace OptionalNamespace
{
    class OptionalExample
    {
        static void Main(string[] args)
        {
            // Instance anExample does not send an argument for the constructor's
            // optional parameter.
            ExampleClass anExample = new ExampleClass();
            anExample.ExampleMethod(1, "One", 1);
            anExample.ExampleMethod(2, "Two");
            anExample.ExampleMethod(3);

            // Instance anotherExample sends an argument for the constructor's
            // optional parameter.
            ExampleClass anotherExample = new ExampleClass("Provided name");
            anotherExample.ExampleMethod(1, "One", 1);
            anotherExample.ExampleMethod(2, "Two");
            anotherExample.ExampleMethod(3);

            // The following statements produce compiler errors.

            // An argument must be supplied for the first parameter, and it
            // must be an integer.
            //anExample.ExampleMethod("One", 1);
            //anExample.ExampleMethod();

            // You cannot leave a gap in the provided arguments. 
            //anExample.ExampleMethod(3, ,4);
            //anExample.ExampleMethod(3, 4);

            // You can use a named parameter to make the previous 
            // statement work.
            anExample.ExampleMethod(3, optionalint: 4);
        }
    }

    class ExampleClass
    {
        private string _name;

        // Because the parameter for the constructor, name, has a default
        // value assigned to it, it is optional.
        public ExampleClass(string name = "Default name")
        {
            _name = name;
        }

        // The first parameter, required, has no default value assigned
        // to it. Therefore, it is not optional. Both optionalstr and 
        // optionalint have default values assigned to them. They are optional.
        public void ExampleMethod(int required, string optionalstr = "default string",
            int optionalint = 10)
        {
            Console.WriteLine("{0}: {1}, {2}, and {3}.", _name, required, optionalstr,
                optionalint);
        }
    }

    // The output from this example is the following:
    // Default name: 1, One, and 1.
    // Default name: 2, Two, and 10.
    // Default name: 3, default string, and 10.
    // Provided name: 1, One, and 1.
    // Provided name: 2, Two, and 10.
    // Provided name: 3, default string, and 10.
    // Default name: 3, default string, and 4.

}

Interfaces COM

Argumentos nomeados e opcionais, juntamente com suporte para objetos dinâmicos e outros aperfeiçoamentos, melhoram a interoperabilidade com as APIs de COM, como, por exemplo, APIs de automação do Office.

Por exemplo, o AutoFormatação método no Excel de Microsoft Office intervalo interface tem sete parâmetros, os quais são opcionais. Esses parâmetros são mostrados na ilustração a seguir.

Parâmetros de AutoFormatação

Informações rápidas do IntelliSense para o método AutoFormat.

C# 3.0 e versões anteriores, um argumento é necessário para cada parâmetro, conforme mostrado no exemplo a seguir.

// In C# 3.0 and earlier versions, you need to supply an argument for
// every parameter. The following call specifies a value for the first
// parameter, and sends a placeholder value for the other six. The
// default values are used for those parameters.
var excelApp = new Microsoft.Office.Interop.Excel.Application();
excelApp.Workbooks.Add();
excelApp.Visible = true;

var myFormat = 
    Microsoft.Office.Interop.Excel.XlRangeAutoFormat.xlRangeAutoFormatAccounting1;

excelApp.get_Range("A1", "B4").AutoFormat(myFormat, Type.Missing, 
    Type.Missing, Type.Missing, Type.Missing, Type.Missing, Type.Missing);

No entanto, você pode simplificar bastante a chamada para AutoFormat usando os argumentos nomeados e opcionais, introduzidos no C# 4.0. Nome e argumentos opcionais permitem que você omita o argumento para um parâmetro opcional, se não quiser alterar o valor do parâmetro padrão. A chamada a seguir, é especificado um valor de apenas um dos sete parâmetros.

// The following code shows the same call to AutoFormat in C# 4.0. Only
// the argument for which you want to provide a specific value is listed.
excelApp.Range["A1", "B4"].AutoFormat( Format: myFormat );

Para mais informações e um exemplo, consulte How to: Chamada de uso e argumentos Opcional no Office (guia de programação C#) de programação. e How to: Objetos de interoperabilidade do Office Access usando recursos visuais C# 2010 (guia de programação C#).

Resolução de Sobrecarregamento

Uso de argumentos nomeados e opcionais afeta a resolução de sobrecarga das seguintes maneiras:

  • Um método, indexador ou construtor é um candidato para execução, se cada um de seus parâmetros é opcional ou corresponde, por nome ou posição, para um único argumento da instrução de chamada, e esse argumento pode ser convertido para o tipo do parâmetro.

  • Se houver mais de um candidato, regras de resolução de sobrecarga para conversões preferenciais são aplicadas para os argumentos que são explicitamente especificados. Argumentos omitidos para parâmetros opcionais são ignorados.

  • Se dois candidatos são considerados igualmente bom, a preferência vai para um candidato que não tem parâmetros opcionais para os quais argumentos foram omitidos na chamada. Esta é uma conseqüência da preferência geral na resolução de sobrecarga para candidatos que têm menos parâmetros.

Especificação da linguagem C#

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

Consulte também

Tarefas

How to: Chamada de uso e argumentos Opcional no Office (guia de programação C#) de programação.

Referência

Using Constructors (C# Programming Guide)

Usando os indexadores (guia de programação de C#)

Outros recursos

Usando o Tipo dinâmico (guia de programação C#)