Instrução Function (Visual Basic)Function Statement (Visual Basic)

Declara o nome, os parâmetros e o código que definem um Function procedimento.Declares the name, parameters, and code that define a Function procedure.

SyntaxSyntax

[ <attributelist> ] [ accessmodifier ] [ proceduremodifiers ] [ Shared ] [ Shadows ] [ Async | Iterator ]
Function name [ (Of typeparamlist) ] [ (parameterlist) ] [ As returntype ] [ Implements implementslist | Handles eventlist ]
    [ statements ]
    [ Exit Function ]
    [ statements ]
End Function

PartesParts

  • attributelist

    Opcional.Optional. Consulte a lista de atributos.See Attribute List.

  • accessmodifier

    Opcional.Optional. Pode ser um dos seguintes:Can be one of the following:

    Consulte níveis de acesso em Visual Basic.See Access levels in Visual Basic.

  • proceduremodifiers

    Opcional.Optional. Pode ser um dos seguintes:Can be one of the following:

  • Shared

    Opcional.Optional. Consulte compartilhado.See Shared.

  • Shadows

    Opcional.Optional. Consulte Shadows.See Shadows.

  • Async

    Opcional.Optional. Consulte Async.See Async.

  • Iterator

    Opcional.Optional. Consulte iterador.See Iterator.

  • name

    Obrigatório.Required. Nome do procedimento.Name of the procedure. Consulte nomes de elementos declarados.See Declared Element Names.

  • typeparamlist

    Opcional.Optional. Lista de parâmetros de tipo para um procedimento genérico.List of type parameters for a generic procedure. Consulte lista de tipos.See Type List.

  • parameterlist

    Opcional.Optional. Lista de nomes de variáveis locais que representam os parâmetros deste procedimento.List of local variable names representing the parameters of this procedure. Consulte a lista de parâmetros.See Parameter List.

  • returntype

    Obrigatório se Option Strict for On .Required if Option Strict is On. Tipo de dados do valor retornado por este procedimento.Data type of the value returned by this procedure.

  • Implements

    Opcional.Optional. Indica que este procedimento implementa um ou mais Function procedimentos, cada um definido em uma interface implementada por este procedimento que contém a classe ou a estrutura.Indicates that this procedure implements one or more Function procedures, each one defined in an interface implemented by this procedure's containing class or structure. Consulte a instrução Implements.See Implements Statement.

  • implementslist

    Necessário se Implements for fornecido.Required if Implements is supplied. Lista de Function procedimentos que estão sendo implementados.List of Function procedures being implemented.

    implementedprocedure [ , implementedprocedure ... ]

    Cada implementedprocedure uma tem a seguinte sintaxe e partes:Each implementedprocedure has the following syntax and parts:

    interface.definedname

    PartePart DescriçãoDescription
    interface Obrigatórios.Required. Nome de uma interface implementada por este procedimento que contém a classe ou a estrutura.Name of an interface implemented by this procedure's containing class or structure.
    definedname Obrigatório.Required. Nome pelo qual o procedimento é definido interface .Name by which the procedure is defined in interface.
  • Handles

    Opcional.Optional. Indica que esse procedimento pode manipular um ou mais eventos específicos.Indicates that this procedure can handle one or more specific events. Consulte identificadores.See Handles.

  • eventlist

    Necessário se Handles for fornecido.Required if Handles is supplied. Lista de eventos que este procedimento manipula.List of events this procedure handles.

    eventspecifier [ , eventspecifier ... ]

    Cada eventspecifier uma tem a seguinte sintaxe e partes:Each eventspecifier has the following syntax and parts:

    eventvariable.event

    PartePart DescriçãoDescription
    eventvariable Obrigatórios.Required. Variável de objeto declarada com o tipo de dados da classe ou estrutura que gera o evento.Object variable declared with the data type of the class or structure that raises the event.
    event Obrigatório.Required. Nome do evento que este procedimento manipula.Name of the event this procedure handles.
  • statements

    Opcional.Optional. Bloco de instruções a serem executadas neste procedimento.Block of statements to be executed within this procedure.

  • End Function

    Encerra a definição deste procedimento.Terminates the definition of this procedure.

ComentáriosRemarks

Todo o código executável deve estar dentro de um procedimento.All executable code must be inside a procedure. Cada procedimento, por sua vez, é declarado dentro de uma classe, uma estrutura ou um módulo que é chamado de classe, estrutura ou módulo que o contém.Each procedure, in turn, is declared within a class, a structure, or a module that is referred to as the containing class, structure, or module.

Para retornar um valor para o código de chamada, use um Function procedimento; caso contrário, use um Sub procedimento.To return a value to the calling code, use a Function procedure; otherwise, use a Sub procedure.

Definindo uma funçãoDefining a Function

Você pode definir um Function procedimento somente no nível do módulo.You can define a Function procedure only at the module level. Portanto, o contexto de declaração para uma função deve ser uma classe, uma estrutura, um módulo ou uma interface e não pode ser um arquivo de origem, um namespace, um procedimento ou um bloco.Therefore, the declaration context for a function must be a class, a structure, a module, or an interface and can't be a source file, a namespace, a procedure, or a block. Para obter mais informações, consulte Contextos de declaração e níveis de acesso padrão.For more information, see Declaration Contexts and Default Access Levels.

Function os procedimentos assumem como padrão o acesso público.Function procedures default to public access. Você pode ajustar seus níveis de acesso com os modificadores de acesso.You can adjust their access levels with the access modifiers.

Um Function procedimento pode declarar o tipo de dados do valor que o procedimento retorna.A Function procedure can declare the data type of the value that the procedure returns. Você pode especificar qualquer tipo de dados ou o nome de uma enumeração, uma estrutura, uma classe ou uma interface.You can specify any data type or the name of an enumeration, a structure, a class, or an interface. Se você não especificar o returntype parâmetro, o procedimento retornará Object .If you don't specify the returntype parameter, the procedure returns Object.

Se esse procedimento usar a Implements palavra-chave, a classe ou estrutura que a contém também deverá ter uma Implements instrução que imediatamente segue sua Class Structure instrução or.If this procedure uses the Implements keyword, the containing class or structure must also have an Implements statement that immediately follows its Class or Structure statement. A Implements instrução deve incluir cada interface especificada em implementslist .The Implements statement must include each interface that's specified in implementslist. No entanto, o nome pelo qual uma interface define o Function (in definedname ) não precisa corresponder ao nome desse procedimento (em name ).However, the name by which an interface defines the Function (in definedname) doesn't need to match the name of this procedure (in name).

Observação

Você pode usar expressões lambda para definir expressões de função embutidas.You can use lambda expressions to define function expressions inline. Para obter mais informações, consulte expressão de função e expressões lambda.For more information, see Function Expression and Lambda Expressions.

Retornando de uma funçãoReturning from a Function

Quando o Function procedimento retorna ao código de chamada, a execução continua com a instrução que segue a instrução que chamou o procedimento.When the Function procedure returns to the calling code, execution continues with the statement that follows the statement that called the procedure.

Para retornar um valor de uma função, você pode atribuir o valor ao nome da função ou incluí-lo em uma Return instrução.To return a value from a function, you can either assign the value to the function name or include it in a Return statement.

A Return instrução atribui simultaneamente o valor de retorno e sai da função, como mostra o exemplo a seguir.The Return statement simultaneously assigns the return value and exits the function, as the following example shows.

Function MyFunction(ByVal j As Integer) As Double
    Return 3.87 * j
End Function

O exemplo a seguir atribui o valor de retorno ao nome da função myFunction e, em seguida, usa a Exit Function instrução a ser retornada.The following example assigns the return value to the function name myFunction and then uses the Exit Function statement to return.

Function MyFunction(ByVal j As Integer) As Double
    MyFunction = 3.87 * j
    Exit Function
End Function

As Exit Function Return instruções e causam uma saída imediata de um Function procedimento.The Exit Function and Return statements cause an immediate exit from a Function procedure. Qualquer número de Exit Function Return instruções and pode aparecer em qualquer lugar no procedimento, e você pode misturar Exit Function e Return demonstrativos.Any number of Exit Function and Return statements can appear anywhere in the procedure, and you can mix Exit Function and Return statements.

Se você usar Exit Function sem atribuir um valor ao name , o procedimento retornará o valor padrão para o tipo de dados especificado em returntype .If you use Exit Function without assigning a value to name, the procedure returns the default value for the data type that's specified in returntype. Se returntype não for especificado, o procedimento retornará Nothing , que é o valor padrão para Object .If returntype isn't specified, the procedure returns Nothing, which is the default value for Object.

Chamando uma FunçãoCalling a Function

Você chama um Function procedimento usando o nome do procedimento, seguido pela lista de argumentos entre parênteses, em uma expressão.You call a Function procedure by using the procedure name, followed by the argument list in parentheses, in an expression. Você pode omitir os parênteses somente se não estiver fornecendo nenhum argumento.You can omit the parentheses only if you aren't supplying any arguments. No entanto, seu código será mais legível se você sempre incluir os parênteses.However, your code is more readable if you always include the parentheses.

Você chama um Function procedimento da mesma maneira que chama qualquer função de biblioteca, como Sqrt , Cos ou ChrW .You call a Function procedure the same way that you call any library function such as Sqrt, Cos, or ChrW.

Você também pode chamar uma função usando a Call palavra-chave.You can also call a function by using the Call keyword. Nesse caso, o valor de retorno é ignorado.In that case, the return value is ignored. O uso da Call palavra-chave não é recomendado na maioria dos casos.Use of the Call keyword isn't recommended in most cases. Para obter mais informações, consulte Call Statement.For more information, see Call Statement.

Às vezes, Visual Basic reorganiza as expressões aritméticas para aumentar a eficiência interna.Visual Basic sometimes rearranges arithmetic expressions to increase internal efficiency. Por esse motivo, você não deve usar um Function procedimento em uma expressão aritmética quando a função altera o valor de variáveis na mesma expressão.For that reason, you shouldn't use a Function procedure in an arithmetic expression when the function changes the value of variables in the same expression.

Funções assíncronasAsync Functions

O recurso Async permite invocar funções assíncronas sem usar retornos de chamada explícitos ou dividir manualmente seu código em várias funções ou expressões lambda.The Async feature allows you to invoke asynchronous functions without using explicit callbacks or manually splitting your code across multiple functions or lambda expressions.

Se você marcar uma função com o modificador Async , poderá usar o operador Await na função.If you mark a function with the Async modifier, you can use the Await operator in the function. Quando o controle alcança uma Await expressão na Async função, o controle retorna ao chamador e o progresso na função é suspenso até que a tarefa esperada seja concluída.When control reaches an Await expression in the Async function, control returns to the caller, and progress in the function is suspended until the awaited task completes. Quando a tarefa for concluída, a execução poderá ser retomada na função.When the task is complete, execution can resume in the function.

Observação

Um Async procedimento retorna ao chamador quando ele encontra o primeiro objeto esperado que ainda não está completo, ou chega ao final do Async procedimento, o que ocorrer primeiro.An Async procedure 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 procedure, whichever occurs first.

Uma Async função pode ter um tipo de retorno de Task<TResult> ou Task .An Async function can have a return type of Task<TResult> or Task. Um exemplo de uma Async função que tem um tipo de retorno Task<TResult> é fornecido abaixo.An example of an Async function that has a return type of Task<TResult> is provided below.

Uma Async função não pode declarar parâmetros ByRef .An Async function cannot declare any ByRef parameters.

Uma instrução sub também pode ser marcada com o Async modificador.A Sub Statement can also be marked with the Async modifier. Isso é usado principalmente para manipuladores de eventos, em que um valor não pode ser retornado.This is primarily used for event handlers, where a value cannot be returned. Um Async Sub procedimento não pode ser aguardado e o chamador de um Async Sub procedimento não pode capturar exceções que são geradas pelo Sub procedimento.An Async Sub procedure can't be awaited, and the caller of an Async Sub procedure can't catch exceptions that are thrown by the Sub procedure.

Para obter mais informações sobre as Async funções, consulte programação assíncrona com Async e Await, fluxo de controle em programas assíncronose tipos de retorno assíncronos.For more information about Async functions, see Asynchronous Programming with Async and Await, Control Flow in Async Programs, and Async Return Types.

Funções de iteradorIterator Functions

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

Você chama um iterador do código do cliente usando um para cada... Próxima instrução.You call an iterator from client code by using a For Each…Next statement.

O tipo de retorno de uma função de iterador pode ser IEnumerable , IEnumerable<T> , IEnumerator ou IEnumerator<T> .The return type of an iterator function can be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

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

ExemploExample

O exemplo a seguir usa a Function instrução para declarar o nome, os parâmetros e o código que formam o corpo de um Function procedimento.The following example uses the Function statement to declare the name, parameters, and code that form the body of a Function procedure. O ParamArray modificador permite que a função aceite um número variável de argumentos.The ParamArray modifier enables the function to accept a variable number of arguments.

Public Function CalcSum(ByVal ParamArray args() As Double) As Double
    CalcSum = 0
    If args.Length <= 0 Then Exit Function
    For i As Integer = 0 To UBound(args, 1)
        CalcSum += args(i)
    Next i
End Function

ExemploExample

O exemplo a seguir invoca a função declarada no exemplo anterior.The following example invokes the function declared in the preceding example.

Module Module1

    Sub Main()
        ' In the following function call, CalcSum's local variables 
        ' are assigned the following values: args(0) = 4, args(1) = 3, 
        ' and so on. The displayed sum is 10.
        Dim returnedValue As Double = CalcSum(4, 3, 2, 1)
        Console.WriteLine("Sum: " & returnedValue)
        ' Parameter args accepts zero or more arguments. The sum 
        ' displayed by the following statements is 0.
        returnedValue = CalcSum()
        Console.WriteLine("Sum: " & returnedValue)
    End Sub

    Public Function CalcSum(ByVal ParamArray args() As Double) As Double
        CalcSum = 0
        If args.Length <= 0 Then Exit Function
        For i As Integer = 0 To UBound(args, 1)
            CalcSum += args(i)
        Next i
    End Function

End Module

ExemploExample

No exemplo a seguir, DelayAsync é um Async Function que tem um tipo de retorno de Task<TResult> .In the following example, DelayAsync is an Async Function 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 de função de DelayAsync precisa ter um tipo de retorno de Task(Of Integer) .Therefore the function declaration of DelayAsync needs to have a return type of Task(Of Integer). Como o tipo de retorno é Task(Of Integer) , a avaliação da Await expressão em DoSomethingAsync produz um inteiro.Because the return type is Task(Of Integer), the evaluation of the Await expression in DoSomethingAsync produces an integer. Isso é demonstrado nesta instrução: Dim result As Integer = Await delayTask .This is demonstrated in this statement: Dim result As Integer = Await delayTask.

O startButton_Click procedimento é um exemplo de um Async Sub procedimento.The startButton_Click procedure is an example of an Async Sub procedure. Como DoSomethingAsync é uma Async função, a tarefa para a chamada DoSomethingAsync deve ser esperada, como demonstra a seguinte instrução: Await DoSomethingAsync() .Because DoSomethingAsync is an Async function, the task for the call to DoSomethingAsync must be awaited, as the following statement demonstrates: Await DoSomethingAsync(). O startButton_Click Sub procedimento deve ser definido com o Async modificador porque ele tem uma Await expressão.The startButton_Click Sub procedure must be defined with the Async modifier because it has an Await expression.

' Imports System.Diagnostics
' Imports System.Threading.Tasks

' This Click event is marked with the Async modifier.
Private Async Sub startButton_Click(sender As Object, e As RoutedEventArgs) Handles startButton.Click
    Await DoSomethingAsync()
End Sub

Private Async Function DoSomethingAsync() As Task
    Dim delayTask As Task(Of Integer) = DelayAsync()
    Dim result As Integer = Await delayTask

    ' The previous two statements may be combined into
    ' the following statement.
    ' Dim result As Integer = Await DelayAsync()

    Debug.WriteLine("Result: " & result)
End Function

Private Async Function DelayAsync() As Task(Of Integer)
    Await Task.Delay(100)
    Return 5
End Function

'  Output:
'   Result: 5

Consulte tambémSee also