Localizar e query dados de entidade com LINQ

Dados de amostra

Os exemplos neste guia usam a coleção planets do banco de dados sample_guides . Os documentos nesta coleção utilizam a seguinte classe Planet como um modelo:

public class Planet
{
    public ObjectId _id { get; set; }
    public string name { get; set; } = null!;
    public int orderFromSun { get; set; }
    public bool hasRings { get; set; }
}

Essa coleção é dos conjuntos de dados de amostra fornecidos pelo Atlas. Consulte o guia Início rápido para saber como criar um cluster MongoDB gratuito e carregar esses dados de amostra.

Encontre uma única entidade

O método FirstOrDefault() retorna a primeira entidade que encontra na sua collection que corresponda aos critérios de pesquisa e retorna null se nenhuma entidade correspondente for encontrada.

O código a seguir usa o método FirstOrDefault() para localizar um planeta com o campo name de "Mercury" de um DBSet chamado Planets e imprime o nome do planeta no console:

var planet = db.Planets.FirstOrDefault(p => p.name == "Mercury");
Console.WriteLine(planet?.name);

Encontrar múltiplas entidades

Você pode utilizar o método Where() para recuperar múltiplas entidades de sua collection. Where() retorna todas as entidades que correspondem aos critérios de pesquisa.

O código a seguir usa o método Where() para encontrar todos os planetas que têm o campo hasRings definido como true e imprime os nomes dos planetas no console.

var planets = db.Planets.Where(p => p.hasRings);
foreach (var p in planets)
{
    Console.WriteLine(p.name);
}

Executar query de uma propriedade de sombra

Uma propriedade shadow é uma propriedade que não está definida em sua classe de entidade .NET, mas está incluída no modelo Entity Framework e mapeada para campos no banco de dados. Você pode usar propriedades de sombra para query ou acompanhar dados em seus documentos sem expô-los como uma propriedade em sua entidade.

Para fazer referência a uma propriedade de sombra em uma query LINQ, chame o método EF.Property<T>() e passe o nome da propriedade configurada como um argumento. O argumento de tipo genérico deve corresponder ao tipo de dados da propriedade shadow .

Por exemplo, a classe Planet não define uma propriedade para o campo mainAtmosphere. Para configurar este campo como uma propriedade de sombra, chame o método Property<T>() no método OnModelCreating() de PlanetDbContext, como mostrado no seguinte exemplo:

public class PlanetDbContext : DbContext
{
    public DbSet<Planet> Planets { get; init; } = null!;
    public static PlanetDbContext Create(IMongoDatabase database) =>
        new(new DbContextOptionsBuilder<PlanetDbContext>()
            .UseMongoDB(database.Client, database.DatabaseNamespace.DatabaseName)
            .Options);
    public PlanetDbContext(DbContextOptions options)
        : base(options)
    {
    }
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.Entity<Planet>().ToCollection("planets");
        modelBuilder.Entity<Planet>().Property<string[]>("mainAtmosphere");
    }
}

A chamada para modelBuilder.Entity<Planet>().Property<string[]>("mainAtmosphere") instrui a framework a incluir mainAtmosphere no modelo e mapeá-lo para um campo string[] no MongoDB.

O código a seguir usa o método EF.Property<string[]>() para localizar todos os planetas que têm uma propriedade shadow mainAtmosphere não vazia e imprime os nomes dos planetas no console:

var planets = db.Planets.Where(
    p => EF.Property<string[]>(p, "mainAtmosphere").Length > 0);
foreach (var p in planets)
{
    Console.WriteLine(p.name);
}

Mql.Exists

O método Mql.Exists() combina documentos que contêm o campo especificado, incluindo documentos em que o valor de campo é null.

O código a seguir usa o método Mql.Exists() para encontrar todos os planetas que têm o campo hasRings e imprime os nomes dos planetas no console:

var planetNames = db.Planets
    .Where(p => Mql.Exists(p.hasRings))
    .Select(p => p.name);
foreach (var name in planetNames)
{
    Console.WriteLine(name);
}

Mql.IsMissing

O método Mql.IsMissing() corresponde a documentos que não contêm o campo especificado.

O código a seguir usa o método Mql.IsMissing() para encontrar todos os planetas que não têm o campo hasRings e imprime os nomes dos planetas no console:

var planetNames = db.Planets
    .Where(p => Mql.IsMissing(p.hasRings))
    .Select(p => p.name);
foreach (var name in planetNames)
{
    Console.WriteLine(name);
}

Mql.IsNullOrMissing

O método Mql.IsNullOrMissing() corresponde a documentos em que o campo especificado está ausente ou tem um valor null.

O código a seguir usa o método Mql.IsNullOrMissing() para encontrar todos os planetas onde o campo hasRings está ausente ou null e imprime os nomes dos planetas no console:

var planetNames = db.Planets
    .Where(p => Mql.IsNullOrMissing(p.hasRings))
    .Select(p => p.name);
foreach (var name in planetNames)
{
    Console.WriteLine(name);
}

Limite o número de resultados

Use o método Take() para especificar um número máximo de entidades a retornar de uma query.

O código a seguir usa o método Take() para retornar os primeiros 3 planetas da coleção Planets:

var planetList = db.Planets.Take(3);
foreach (var p in planetList)
{
    Console.WriteLine(p.name);
}

Ignorar resultados

Use o método Skip() para especificar um número de entidades a serem ignoradas antes de retornar os resultados de uma query.

O código a seguir usa os métodos OrderBy() e Skip() para ignorar os primeiros 5 planetas (ordenados por orderFromSun) e retornar os planetas restantes:

var planetList = db.Planets.OrderBy(p => p.orderFromSun).Skip(5);
foreach (var p in planetList)
{
    Console.WriteLine(p.name);
}

Contar

O exemplo seguinte utiliza o método Count() para contar o número de elementos na collection Planets:

var planetCount = db.Planets.Count();
Console.WriteLine("Planet Count: " + planetCount);

O exemplo seguinte utiliza o método Count() para contar o número de elementos na coleção Planets que têm um campo hasRings configurado para true:

var planetCountWithRings = db.Planets.Count(p => p.hasRings);
Console.WriteLine("Planet Count with Rings: " + planetCountWithRings);

LongCount

O exemplo seguinte utiliza o método LongCount() para contar o número de elementos na coleção Planets e retorna o resultado como um long:

var planetCountLong = db.Planets.LongCount();
Console.WriteLine("Long Planet Count: " + planetCountLong);

O exemplo seguinte utiliza o método LongCount() para contar o número de elementos na coleção Planets que têm um campo hasRings configurado para true e retorna o resultado como long:

var planetCountLongWithRings = db.Planets.LongCount(p => p.hasRings);
Console.WriteLine("Long Planet Count with Rings: " + planetCountLongWithRings);

Any

O exemplo seguinte utiliza o método Any() para verificar se algum elemento na coleção Planets tem um campo hasRings configurado para true:

var results = db.Planets.Any(p => p.hasRings);
Console.WriteLine("Planet with Rings: " + results);

Máx

O exemplo seguinte utiliza o método Max() para localizar o valor máximo do campo orderFromSun na collection Planets:

var furthestPlanet = db.Planets.Max(p => p.orderFromSun);
Console.WriteLine("Furthest Planet: " + furthestPlanet);

Min

O exemplo seguinte utiliza o método Min() para localizar o valor mínimo do campo orderFromSun na collection Planets:

var closestPlanet = db.Planets.Min(p => p.orderFromSun);
Console.WriteLine("Closest Planet: " + closestPlanet);

Soma

O exemplo a seguir utiliza o método Sum() para localizar a soma do campo orderFromSun na coleção Planets:

var totalOrderFromSun = db.Planets.Sum(p => p.orderFromSun);
Console.WriteLine("Total Order From Sun: " + totalOrderFromSun);

Média

O exemplo seguinte utiliza o método Average() para localizar o valor médio do campo orderFromSun na collection Planets:

var averageOrderFromSun = db.Planets.Average(p => p.orderFromSun);
Console.WriteLine("Average Order From Sun: " + averageOrderFromSun);

Habilitar registro de dados confidenciais

O provedor registra o texto completo da query MQL somente quando o registro de dados confidenciais está ativado. Se você não ativar o registro de dados confidenciais, os logs de query poderão omitir valores. Para ativar o registro de dados confidenciais, chame o método EnableSensitiveDataLogging() do seu objeto DbContextOptionsBuilder, conforme o exemplo a seguir:

var mongoClient = new MongoClient("<connection string URI>");
var dbContextOptions =
    new DbContextOptionsBuilder<MyDbContext>()
        .UseMongoDB(mongoClient, "sample_guides")
        .LogTo(Console.WriteLine)
        .EnableSensitiveDataLogging()
        .Options;
var db = new MyDbContext(dbContextOptions);

Convenções de serialização personalizadas

Se você registrar convenções de serialização BSON personalizadas no MongoClient, como a nomenclatura de campo camel-case, essas convenções poderão alterar os nomes de campo armazenados no MongoDB para que eles sejam diferentes dos nomes de propriedade em seu modelo de entidade. O provedor EF Core usa nomes de propriedade de entidade para gerar MQL, portanto, uma incompatibilidade pode fazer com que as query direcionem os campos errados e ignorem quaisquer índices nesses campos. Quando os nomes de campo armazenados diferem dos nomes de propriedade da entidade, você pode mapear explicitamente uma propriedade para o nome de campo armazenado em OnModelCreating() usando HasElementName(), conforme mostrado no exemplo a seguir:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder);
    modelBuilder.Entity<Planet>()
        .Property(p => p.name)
        .HasElementName("name");
}