C# LINQ

LINQ ("Language Integrated Query", consulta integrada à linguagem) são os métodos que fazem perguntas a qualquer coleção: "quais custam menos de R$ 10?", "qual o total?", "agrupe por categoria". Esta página lista todos os operadores que você vai usar, por grupo, com exemplo e resultado. Para aprender com calma, comece por O que é LINQ; para ver tudo em uso num programa, o projeto Estoque da Lojinha.

Os resultados vêm do programa abaixo, rodado no dotnet 10.0.112 da máquina da Ana (pasta ~/cs/linq, cultura pt-BR) e no editor do guia, que deram a mesma saída. O LINQ está em System.Linq, que o C# já traz sem using.

Atalhos: O programa · Filtrar e projetar · Ordenar · Particionar · Um elemento · Perguntar · Agregar · Agrupar · Conjuntos e junções · Converter e gerar · Sintaxe de consulta · Execução adiada · Quando dá errado · Experimente

O programa de exemplo

Os exemplos usam dois conjuntos: o array n = [5, 3, 8, 1, 9, 2, 8] e uma lista de produtos da lojinha da Ana. A função J só junta o resultado numa linha, com espaços. Cada linha da saída começa com o número que aparece na coluna "Linha" das tabelas:

// linq.cs — um exemplo de cada operador
List<Produto> estoque =
[
    new("Caderno", "Papelaria", 12, 15.90m),
    new("Caneta", "Escrita", 40, 2.50m),
    new("Borracha", "Escrita", 3, 1.75m),
    new("Mochila", "Bolsas", 2, 89.90m),
    new("Lápis", "Escrita", 60, 1.20m),
    new("Papel A4", "Papelaria", 4, 27.50m),
];
int[] n = [5, 3, 8, 1, 9, 2, 8];
static string J<T>(IEnumerable<T> s) => string.Join(" ", s);

Console.WriteLine("-- filtrar e projetar");
Console.WriteLine($"1  {J(n.Where(x => x > 4))} | {J(n.Distinct())} | {J(n.Select(x => x * 10))}");
Console.WriteLine($"2  {J(estoque.Where(p => p.Qtd < 5).Select(p => p.Nome))}");
Console.WriteLine($"3  {J(n.Select((x, i) => $"{i}:{x}"))}");
Console.WriteLine($"4  {J(new[] { "a b", "c d e" }.SelectMany(s => s.Split(' ')))}");
Console.WriteLine($"5  {J(new object[] { 1, "dois", 3.0, 4 }.OfType<int>())} | {J(estoque.DistinctBy(p => p.Categoria).Select(p => p.Nome))}");

Console.WriteLine("-- ordenar");
Console.WriteLine($"6  {J(n.Order())} | {J(n.OrderDescending())} | {J(n.Reverse())}");
Console.WriteLine($"7  {J(estoque.OrderBy(p => p.Preco).Select(p => p.Nome))}");
Console.WriteLine($"8  {J(estoque.OrderBy(p => p.Categoria).ThenByDescending(p => p.Qtd).Select(p => $"{p.Categoria}/{p.Nome}"))}");

Console.WriteLine("-- particionar");
Console.WriteLine($"9  {J(n.Take(3))} | {J(n.Skip(5))} | {J(n.TakeLast(2))} | {J(n.SkipLast(5))} | {J(n.TakeWhile(x => x != 1))} | {J(n.SkipWhile(x => x != 1))}");
Console.WriteLine($"10 {J(n.Chunk(3).Select(c => $"[{J(c)}]"))} | {J(n.Take(2..4))}");

Console.WriteLine("-- elementos");
Console.WriteLine($"11 {n.First()} {n.First(x => x > 5)} {n.Last()} {n.ElementAt(2)} {n.FirstOrDefault(x => x > 100)} {n.FirstOrDefault(x => x > 100, -1)} {n.Single(x => x == 9)}");
Console.WriteLine($"12 [{estoque.FirstOrDefault(p => p.Nome == "Régua")?.Nome ?? "null"}] {J(new int[0].DefaultIfEmpty(7))}");

Console.WriteLine("-- perguntar");
Console.WriteLine($"13 {n.Any()} {n.Any(x => x > 8)} {n.All(x => x > 0)} {n.Contains(8)} {new int[0].Any()} {n.SequenceEqual([5, 3, 8, 1, 9, 2, 8])}");

Console.WriteLine("-- agregar");
Console.WriteLine($"14 {n.Count()} {n.Count(x => x == 8)} {n.Sum()} {n.Min()} {n.Max()} {n.Average():F2}");
Console.WriteLine($"15 {estoque.Sum(p => p.Qtd * p.Preco):C} {estoque.Average(p => p.Preco):C} {estoque.Max(p => p.Preco):C} {estoque.MaxBy(p => p.Preco)!.Nome} {estoque.MinBy(p => p.Qtd)!.Nome}");
Console.WriteLine($"16 {n.Aggregate((a, b) => a * b)} {n.Aggregate(100, (total, x) => total - x)}");

Console.WriteLine("-- agrupar");
foreach (var g in estoque.GroupBy(p => p.Categoria))
{
    Console.WriteLine($"17 {g.Key}: produtos {g.Count()}, unidades {g.Sum(p => p.Qtd)}");
}
Console.WriteLine($"18 {J(estoque.CountBy(p => p.Categoria).Select(kv => $"{kv.Key}={kv.Value}"))}");
Console.WriteLine($"19 {J(estoque.AggregateBy(p => p.Categoria, 0m, (t, p) => t + p.Qtd * p.Preco).Select(kv => $"{kv.Key}={kv.Value}"))}");

Console.WriteLine("-- conjuntos e junções");
int[] a = [1, 2, 3, 4], b = [3, 4, 5];
Console.WriteLine($"20 {J(a.Concat(b))} | {J(a.Union(b))} | {J(a.Intersect(b))} | {J(a.Except(b))}");
Console.WriteLine($"21 {J(a.Zip(b, (x, y) => x + y))} | {J(a.Append(9))} | {J(a.Prepend(0))}");
List<(string Categoria, string Empresa)> fornecedores = [("Papelaria", "Distribuidora Sol"), ("Escrita", "Canetas Brasil")];
var juntos = estoque.Join(fornecedores, p => p.Categoria, f => f.Categoria, (p, f) => $"{p.Nome}<-{f.Empresa}");
Console.WriteLine($"22 {string.Join(", ", juntos)}");
var todos = estoque.LeftJoin(fornecedores, p => p.Categoria, f => f.Categoria, (p, f) => $"{p.Nome}<-{f.Empresa ?? "?"}");
Console.WriteLine($"23 {string.Join(", ", todos)}");
Console.WriteLine($"24 {J(n.Index().Where(t => t.Item == 8).Select(t => t.Index))}");

Console.WriteLine("-- converter e gerar");
Dictionary<string, decimal> precos = estoque.ToDictionary(p => p.Nome, p => p.Preco);
Console.WriteLine($"25 {precos["Mochila"]:C} {n.ToHashSet().Count} {n.ToList().Count} {n.ToArray().Length}");
Console.WriteLine($"26 {J(Enumerable.Range(1, 5))} | {J(Enumerable.Repeat("ha", 3))} | {Enumerable.Empty<int>().Count()}");

record Produto(string Nome, string Categoria, int Qtd, decimal Preco);

$ dotnet run linq.cs
-- filtrar e projetar
1  5 8 9 8 | 5 3 8 1 9 2 | 50 30 80 10 90 20 80
2  Borracha Mochila Papel A4
3  0:5 1:3 2:8 3:1 4:9 5:2 6:8
4  a b c d e
5  1 4 | Caderno Caneta Mochila
-- ordenar
6  1 2 3 5 8 8 9 | 9 8 8 5 3 2 1 | 8 2 9 1 8 3 5
7  Lápis Borracha Caneta Caderno Papel A4 Mochila
8  Bolsas/Mochila Escrita/Lápis Escrita/Caneta Escrita/Borracha Papelaria/Caderno Papelaria/Papel A4
-- particionar
9  5 3 8 | 2 8 | 2 8 | 5 3 | 5 3 8 | 1 9 2 8
10 [5 3 8] [1 9 2] [8] | 8 1
-- elementos
11 5 8 8 8 0 -1 9
12 [null] 7
-- perguntar
13 True True True True False True
-- agregar
14 7 2 36 1 9 5,14
15 R$ 657,85 R$ 23,13 R$ 89,90 Mochila Mochila
16 17280 64
-- agrupar
17 Papelaria: produtos 2, unidades 16
17 Escrita: produtos 3, unidades 103
17 Bolsas: produtos 1, unidades 2
18 Papelaria=2 Escrita=3 Bolsas=1
19 Papelaria=300,80 Escrita=177,25 Bolsas=179,80
-- conjuntos e junções
20 1 2 3 4 3 4 5 | 1 2 3 4 5 | 3 4 | 1 2
21 4 6 8 | 1 2 3 4 9 | 0 1 2 3 4
22 Caderno<-Distribuidora Sol, Caneta<-Canetas Brasil, Borracha<-Canetas Brasil, Lápis<-Canetas Brasil, Papel A4<-Distribuidora Sol
23 Caderno<-Distribuidora Sol, Caneta<-Canetas Brasil, Borracha<-Canetas Brasil, Mochila<-?, Lápis<-Canetas Brasil, Papel A4<-Distribuidora Sol
24 2 6
-- converter e gerar
25 R$ 89,90 6 7 7
26 1 2 3 4 5 | ha ha ha | 0

Quase todos os operadores recebem uma lambda: x => x > 4 lê-se "dado x, diga se x é maior que 4". E quase todos devolvem uma sequência (IEnumerable<T>), por isso dá para encadear: .Where(…).OrderBy(…).Select(…).

Filtrar e projetar

Ordenar

Um segundo OrderBy desfaz o primeiro; para desempatar, é sempre ThenBy. Textos são ordenados como no dicionário (veja string).

Particionar

Skip e Take juntos fazem paginação: a página p (do 0), com 10 por página, é .Skip(p * 10).Take(10). Aula: Filtrar e Projetar.

Um elemento só

Regra prática: quando "não achar" é normal (busca pelo que o usuário digitou), use FirstOrDefault e confira o null. Aula: Filtrar e Projetar.

Perguntar (devolvem bool)

Para saber se há itens, Any() é melhor que Count() > 0: ele para no primeiro. Aula: Agregar.

Agregar (um valor no fim)

Aula: Agregar (Count, Sum, Average).

Agrupar

As pilhas do GroupBy saem na ordem em que cada chave apareceu pela primeira vez.

Conjuntos e junções

Antes do .NET 10, o LeftJoin era escrito com GroupJoin + SelectMany + DefaultIfEmpty, uma receita que você ainda vai ver em código mais antigo. Aula: Juntar (Join).

Converter e gerar

Sintaxe de consulta

O LINQ tem uma segunda forma de escrever, parecida com SQL. O compilador transforma uma na outra: o programa é o mesmo.

// consulta.cs — a mesma pergunta nas duas sintaxes
int[] notas = [7, 4, 9, 5, 10, 6];

var metodos = notas.Where(n => n >= 6).OrderByDescending(n => n).Select(n => $"nota {n}");

var consulta = from n in notas
               where n >= 6
               orderby n descending
               select $"nota {n}";

Console.WriteLine(string.Join(", ", metodos));
Console.WriteLine(string.Join(", ", consulta));

$ dotnet run consulta.cs
nota 10, nota 9, nota 7, nota 6
nota 10, nota 9, nota 7, nota 6

O guia usa a forma com métodos: ela é a mais comum e tem todos os operadores (Take, Count, MaxBy… não existem na sintaxe de consulta). Aula: O que é LINQ.

Execução adiada

Uma consulta como notas.Where(…) não calcula nada na hora: ela guarda a "receita", e a receita roda a cada vez que alguém percorre o resultado (com foreach, Count(), ToList()…).

// adiada.cs — a consulta roda quando é percorrida
List<int> notas = [7, 4, 9];
var aprovados = notas.Where(n => n >= 6);
var foto = notas.Where(n => n >= 6).ToList();
notas.Add(10);
Console.WriteLine($"consulta: {aprovados.Count()}  |  ToList: {foto.Count}");

$ dotnet run adiada.cs
consulta: 3  |  ToList: 2

Se você vai percorrer o resultado várias vezes, ou a coleção pode mudar, termine com .ToList(). Exemplo completo no projeto Estoque.

Quando dá errado

Experimente

List<Produto> estoque =
[
    new("Caderno", 15.90m),
    new("Caneta", 2.50m),
    new("Borracha", 1.75m),
    new("Mochila", 89.90m),
    new("Lápis", 1.20m),
    new("Papel A4", 27.50m),
];

// Os 3 mais caros, do mais caro para o mais barato
var maisCaros = estoque.Take(3).Select(p => p.Nome);
Console.WriteLine(string.Join(", ", maisCaros));

record Produto(string Nome, decimal Preco);

List<Produto> estoque =
[
    new("Caderno", 15.90m),
    new("Caneta", 2.50m),
    new("Borracha", 1.75m),
    new("Mochila", 89.90m),
    new("Lápis", 1.20m),
    new("Papel A4", 27.50m),
];

// Os 3 mais caros, do mais caro para o mais barato
var maisCaros = estoque.OrderByDescending(p => p.Preco).Take(3).Select(p => p.Nome);
Console.WriteLine(string.Join(", ", maisCaros));

record Produto(string Nome, decimal Preco);

int[] notas = [7, 4, 9, 5, 10, 6, 8];
Console.WriteLine(string.Join(" ", notas.Where(x => x >= 6)));
Console.WriteLine(string.Join(" ", notas.Order()));
Console.WriteLine($"Média: {notas.Average():F1}");
Console.WriteLine($"Aprovados: {notas.Count(x => x >= 6)} de {notas.Length}");
Console.WriteLine($"Maior: {notas.Max()}, menor: {notas.Min()}");
Console.WriteLine(notas.Any(x => x == 10) ? "Alguém tirou 10!" : "Ninguém tirou 10.");

Resumo

• Filtrar: Where. Transformar: Select, SelectMany. Ordenar: OrderBy + ThenBy. Pedaços: Take, Skip, Chunk.
• Um item: First/FirstOrDefault, Single, Last. Sim ou não: Any, All, Contains.
• Contas: Count, Sum, Average, Min, Max, MinBy/MaxBy, Aggregate.
• Grupos: GroupBy (g.Key), CountBy e AggregateBy (.NET 9). Junções: Join e, no .NET 10, LeftJoin/RightJoin.
• As consultas são adiadas: rodam quando percorridas. ToList() guarda o resultado do momento.
• First, Single, Average e Max numa sequência vazia lançam InvalidOperationException.