Cláusula Aggregate (Visual Basic)

Aplica uma ou mais funções agregadas a uma coleção.

Aggregate element [As type] In collection _
  [, element2 [As type2] In collection2, [...]]
  [ clause ]
  Into expressionList

Partes

Termo	Definição
element	Obrigatório. Variável usada para iterar através dos elementos da coleção.
type	Opcional. O tipo de element. Se nenhum tipo for especificado, o tipo de element é inferido de collection.
collection	Obrigatório. Refere-se a coleção sobre a qual operar.
clause	Opcional. Uma ou mais cláusulas de consulta, como uma cláusula Where, para refinar o resultado da consulta para aplicar a cláusula ou cláusulas agregadas.
expressionList	Obrigatório. Uma ou mais expressões delimitadas por vírgulas que identifiquem uma função agregada para aplicar à coleção. Você pode aplicar um alias para uma função agregada para especificar um nome de membro para o resultado da consulta. Se nenhum alias for fornecido, o nome da função agregada é usado. Para obter exemplos, consulte a seção sobre funções agregadas mais à frente neste tópico.

Comentários

A cláusula Aggregate pode ser usada para incluir funções agregadas em suas consultas. Funções agregadas executam verificações e cálculos sobre um conjunto de valores e retornam um único valor. Você pode acessar o valor calculado usando um membro do tipo do resultado da consulta. As funções agregadas padrão que você pode usar são as funções All, Any, Average, Count, LongCount, Max, Min e Sum. Essas funções são familiares para os desenvolvedores que estão familiarizados com agregados em SQL. Elas são descritas na seção a seguir deste tópico.

O resultado de uma função agregada é incluído no resultado da consulta como um campo do tipo do resultado da consulta. Você pode fornecer um alias para o resultado da função agregada para especificar o nome do membro do tipo do resultado da consulta que conterá o valor agregado. Se nenhum alias for fornecido, o nome da função agregada é usado.

A cláusula Aggregate pode começar uma consulta, ou pode ser incluída como uma cláusula adicional em uma consulta. Se a cláusula Aggregate começar uma consulta, o resultado é um valor único que é o resultado da função agregada especificada na cláusula Into. Se mais de uma função agregada for especificada na cláusula Into, a consulta retorna um único tipo com uma propriedade separada para fazer referência ao resultado de cada função agregada na cláusula Into. Se a cláusula Aggregate é incluída como uma cláusula adicional em uma consulta, o tipo retornado na coleção de consultas terá uma propriedade separada para referenciar o resultado de cada função agregada na cláusula Into.

Funções Agregadas

A lista a seguir descreve as funções agregadas padrão que podem ser usadas com a cláusula Aggregate.

Função	Descrição
All	Retorna true se todos os elementos na coleção satisfazem uma condição especificada; caso contrário, retorna false. A seguir, há um exemplo: Dim customerList1 = Aggregate order In orders Into AllOrdersOver100 = All(order.Total >= 100)
Any	Retorna true se qualquer elemento da coleção satisfazem uma condição especificada; caso contrário, retorna false. A seguir, há um exemplo: Dim customerList2 = From cust In customers Aggregate order In cust.Orders Into AnyOrderOver500 = Any(order.Total >= 500)
Average	Calcula a média de todos os elementos da coleção, ou calcula uma expressão fornecida para todos os elementos na coleção. A seguir, há um exemplo: Dim customerOrderAverage = Aggregate order In orders Into Average(order.Total)
Count	Conta o número de elementos na coleção. Você pode fornecer uma expressão Boolean opcional para contar somente o número de elementos da coleção que satisfazem a uma condição. A seguir, há um exemplo: Dim customerOrderAfter1996 = From cust In customers Aggregate order In cust.Orders Into Count(order.OrderDate > #12/31/1996#)
Group	Refere-se aos resultados da consulta que são agrupados como resultado de uma cláusula Group By ou Group Join. A função Group é válida somente na cláusula Into de uma cláusula Group By ou Group Join. Para mais informações e um exemplo, consulte Cláusula Group By (Visual Basic) e Cláusula Join Group (Visual Basic).
LongCount	Conta o número de elementos na coleção. Você pode fornecer uma expressão Boolean opcional para contar somente o número de elementos da coleção que satisfazem a uma condição. Retorna o resultado como um Long. Para obter um exemplo, consulte a função agregada Count.
Max	Calcula o valor máximo da coleção, ou calcula uma expressão fornecida para todos os elementos na coleção. A seguir, há um exemplo: Dim customerMaxOrder = Aggregate order In orders Into MaxOrder = Max(order.Total)
Min	Calcula o valor mínimo da coleção, ou calcula uma expressão fornecida para todos os elementos na coleção. A seguir, há um exemplo: Dim customerMinOrder = From cust In customers Aggregate order In cust.Orders Into MinOrder = Min(order.Total)
Sum	Calcula a soma de todos os elementos da coleção, ou calcula uma expressão fornecida para todos os elementos na coleção. A seguir, há um exemplo: Dim customerTotals = From cust In customers Aggregate order In cust.Orders Into Sum(order.Total)

Exemplo

O exemplo de código a seguir mostra como usar a cláusula Aggregate para aplicar uma função agregada a um resultado de consulta.

Public Sub AggregateSample()
  Dim customers = GetCustomerList()

  Dim customerOrderTotal =
      From cust In customers
      Aggregate order In cust.Orders
      Into Sum(order.Total), MaxOrder = Max(order.Total),
      MinOrder = Min(order.Total), Avg = Average(order.Total)

  For Each customer In customerOrderTotal
    Console.WriteLine(customer.cust.CompanyName & vbCrLf &
                     vbTab & "Sum = " & customer.Sum & vbCrLf &
                     vbTab & "Min = " & customer.MinOrder & vbCrLf &
                     vbTab & "Max = " & customer.MaxOrder & vbCrLf &
                     vbTab & "Avg = " & customer.Avg.ToString("#.##"))
  Next 
End Sub

Criando funções agregadas definidas pelo usuário

Você pode incluir suas próprias funções agregadas personalizadas em uma expressão de consulta adicionando métodos de extensão ao tipo IEnumerable. O método personalizado pode então executar um cálculo ou operação na coleção enumerável que referenciou sua função agregada. Para obter mais informações sobre estes métodos de extensão, consulte Métodos de extensão (Visual Basic).

Por exemplo, o exemplo de código a seguir mostra uma função agregada personalizada que calcula o valor mediano de uma coleção de números. Há duas sobrecargas do método de extensão Median. A primeira sobrecarga aceita, como entrada, uma coleção do tipo IEnumerable(Of Double). Se a função agregada Median for chamada para um campo de consulta do tipo Double, esse método será chamado. A segunda sobrecarga do método Median pode ser passada a qualquer tipo genérico. A sobrecarga genérica do método Median leva um segundo parâmetro que faz referência a expressão lambda Func(Of T, Double) para projetar um valor para um tipo (de uma coleção) como o valor correspondente do tipo Double. Ele então delega o cálculo do valor mediano para a outra sobrecarga do método Median. Para obter mais informações sobre expressões lambda, consulte Expressões lambda (Visual Basic).

Imports System.Runtime.CompilerServices

Module UserDefinedAggregates

    ' Calculate the median value for a collection of type Double.
    <Extension()>
    Function Median(ByVal values As IEnumerable(Of Double)) As Double 
        If values.Count = 0 Then 
            Throw New InvalidOperationException("Cannot compute median for an empty set.")
        End If 

        Dim sortedList = From number In values
                         Order By number

        Dim medianValue As Double 

        Dim itemIndex = CInt(Int(sortedList.Count / 2))

        If sortedList.Count Mod 2 = 0 Then 
            ' Even number of items in list.
            medianValue = ((sortedList(itemIndex) + sortedList(itemIndex - 1)) / 2)
        Else 
            ' Odd number of items in list.
            medianValue = sortedList(itemIndex)
        End If 

        Return medianValue
    End Function 

    ' "Cast" the collection of generic items as type Double and call the  
    ' Median() method to calculate the median value.
    <Extension()>
    Function Median(Of T)(ByVal values As IEnumerable(Of T),
                          ByVal selector As Func(Of T, Double)) As Double 
        Return (From element In values Select selector(element)).Median()
    End Function 

End Module

O exemplo de código a seguir mostra exemplos de consultas que chamam a função agregada Median em uma coleção do tipo Integer e uma coleção do tipo Double. A consulta que chama a função agregada Median na coleção do tipo Double chama a sobrecarga do método Median que aceita, como entrada, uma coleção do tipo Double. A consulta que chama a função agregada Median na coleção do tipo Integer chama a sobrecarga genérica do método Median.

Module Module1

    Sub Main()
        Dim numbers1 = {1, 2, 3, 4, 5}

        Dim query1 = Aggregate num In numbers1 Into Median(num)

        Console.WriteLine("Median = " & query1)

        Dim numbers2 = {1.9, 2, 8, 4, 5.7, 6, 7.2, 0}

        Dim query2 = Aggregate num In numbers2 Into Median()

        Console.WriteLine("Median = " & query2)
    End Sub 

End Module

Consulte também

Referência

Cláusula Select (Visual Basic)

Cláusula From (Visual Basic)

Cláusula Where (Visual Basic)

Cláusula Group By (Visual Basic)

Conceitos

Introdução a LINQ no Visual Basic

Outros recursos

Consultas (Visual Basic)