Operações com construtores

Visão geral

Neste guia, você pode aprender sobre as classes auxiliares, ou construtores, que o .NET/C# Driver fornece para criar tipos usados em suas operações. A utilização de construtores ajuda você a identificar erros no tempo de compilação e evitá-los no tempo de execução. Este guia fornece informações sobre classes de construtores que você pode usar para as seguintes tarefas:

• Criar uma definição de filtro

• Criar uma projeção

• Definir uma ordem de classificação

• Definir uma operação de atualização

• Selecionar chaves de índice

Leia este guia se quiser saber mais sobre como construir definições e sintaxe usando construtores.

Classe de amostra

Os exemplos de código neste guia demonstram como você pode usar os construtores para criar tipos para interagir com documentos na coleção de amostra plants.flowers. Os documentos nesta coleção são modelados pela seguinte classe Flower:

public class Flower
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    public string Category { get; set; }
    public double Price { get; set; }
    public List<string> Season { get; set; }
    public double Stock { get; set; }
    public string Description { get; set; }
}

Cada classe de construtor usa um parâmetro de tipo genérico TDocument, que representa o tipo de documento com o qual você está trabalhando. Neste guia, a classe Flower é o tipo de documento utilizado em cada exemplo de classe de construtor.

Construir um filtro

A classe FilterDefinitionBuilder fornece uma interface de tipo seguro para criar query. Suponha que você queira fazer query em sua coleção para documentos que correspondam aos seguintes critérios:

• Price valor do campo inferior a 20

• Category o valor do campo é "Perennial"

Use construtores para criar a definição de filtro com a variante digitada:

var builder = Builders<Flower>.Filter;
var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial");

Usar o formulário variante digitado fornece segurança em tempo de compilação. Além disso, seu IDE pode fornecer suporte à refatoração.

Opcionalmente, você pode usar nomes de campo baseados em cadeias de caracteres para criar o filtro:

var builder = Builders<Flower>.Filter;
var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial");

var builder = Builders<Flower>.Filter;
var filter = builder.AnyEq(f => f.Season, "winter");

Criar uma projeção

A classe ProjectionDefinitionBuilder oferece uma interface segura por tipo para definir uma projeção. Suponha que você queira criar uma projeção nos campos Name e Price, mas excluir o campo Id.

Use construtores para criar a definição de projeção com a variante digitada:

var builder = Builders<Flower>.Projection;
var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id);

Você também pode usar nomes de campos baseados em string para definir a projeção:

var builder = Builders<Flower>.Projection;
var projection = builder.Include("Name").Include("Price").Exclude("Id");

Finalmente, você pode utilizar o método Expression() para definir a projeção:

var builder = Builders<Flower>.Projection;
var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price });

Esta definição tem um tipo de retorno de ProjectionDefinition<TDocument, TProjection> enquanto os outros retornam um ProjectionDefinition<TDocument>.

var builder = Builders<Flower>.Projection;
var projection = builder.Expression(f => new { Profit = f.Price * f.Stock });

Definir uma classificação

A classe SortDefinitionBuilder fornece uma interface segura por tipo para construir sintaxe de classificação. Suponha que você deseja definir uma classificação com a seguinte ordem:

• Subindo Price

• Descendo Category

Use construtores para criar a definição de classificação com a variante digitada:

var builder = Builders<Flower>.Sort;
var sort = builder.Ascending(f => f.Price).Descending(f => f.Category);

Como alternativa, você pode usar nomes de campo baseados em strings para definir a classificação:

var builder = Builders<Flower>.Sort;
var sort = builder.Ascending("Price").Descending("Category");

Definir uma atualização

A classe UpdateDefinitionBuilder fornece uma interface de tipo seguro para criar uma especificação de atualização. Suponha que você deseja criar uma especificação de atualização com os seguintes critérios:

• Criar o novo campo SunRequirement

• Multiplique o valor de campo Price por 0,9

Use construtores para criar a especificação de atualização com a variante digitada:

var builder = Builders<Flower>.Update;
var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9);

Alternativamente, você pode usar nomes de campos baseados em string para definir a atualização:

var builder = Builders<Flower>.Update;
var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9);

Definir chaves de índice

A classe IndexKeysDefinitionBuilder oferece uma interface segura por tipo para definir chaves de índice. Suponha que você queira selecionar Category como uma chave de índice ascendente.

Use construtores para selecionar a chave de índice com a variante digitada:

var builder = Builders<Flower>.IndexKeys;
var keys = builder.Ascending(f => f.Category);

Como alternativa, você pode usar nomes de campo baseados em strings para selecionar a chave de índice:

var builder = Builders<BsonDocument>.IndexKeys;
var keys = builder.Ascending("Category");

A classe IndexKeysDefinitionBuilder também fornece métodos para construir um índice curinga. Você pode criar um índice curinga utilizando All field paths ou A single field path, neste caso utilizando Category:

var builder = Builders<Flower>.IndexKeys;
var keys = builder.Wildcard();

var builder = Builders<Flower>.IndexKeys;
// Using the typed variant
var keys = builder.Wildcard(f => f.Category);
// Using string-based field names
var keys = builder.Wildcard("Category");

Para obter mais informações sobre como utilizar índices curinga, consulte Índices curinga.

Criar um pipeline de agregação

A classe PipelineDefinitionBuilder fornece uma interface segura para definir um aggregation pipeline. Um pipeline de agregação é uma série de estágios usados para transformar um documento. Suponha que você queira criar um pipeline que execute as seguintes operações:

• Corresponde a todos os documentos com "spring" no campo Season

• Classifica os resultados pelo campo Category

• Agrupa os documentos por categoria e mostra o preço médio e o total disponível para todos os documentos nessa categoria

Use PipelineDefinitionBuilder turmas para criar o pipeline:

var sortBuilder = Builders<Flower>.Sort.Ascending(f => f.Category);
var matchFilter = Builders<Flower>.Filter.AnyEq(f => f.Season, "spring");
var pipeline = new EmptyPipelineDefinition<Flower>()
    .Match(matchFilter)
    .Sort(sortBuilder)
    .Group(f => f.Category,
           g => new
              {
                 name = g.Key,
                 avgPrice = g.Average(f => f.Price),
                 totalAvailable = g.Sum(f => f.Stock)
               }
          );

O exemplo anterior cria o seguinte pipeline:

[{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }]

Você pode adicionar estágios ao seu pipeline que não têm métodos seguros de tipo correspondentes na interface PipelineDefinitionBuilder entregando sua consulta como BsonDocument ao método AppendStage().

var pipeline = new EmptyPipelineDefinition<BsonDocument>().AppendStage<BsonDocument, BsonDocument, BsonDocument>("{ $set: { field1: '$field2' } }");

Para saber mais sobre o Pipeline de Agregação, consulte a página de manual do servidor de Pipeline de Agregação .

Construir uma Consulta de Pesquisa Atlas

A classe Search fornece uma interface de tipo seguro para criar um estágio de pipeline $search.

Para aprender como construir consultas de pesquisa com a classe Search, consulte Pesquisa Atlas.

Informações adicionais

Encontre exemplos executáveis utilizando construtores para várias operações em Exemplos de Uso.