mongodb driver c#语法

译：（原文地址：http://www.mamicode.com/info-detail-1400017.html）

驱动程序引入了一些与filters、updates、projections、sorts和index keys的规范相关的类型,这些类型在整个API中使用.

大部分的定义需要buliders来帮助创建对象。每个bulider都有一个泛型类型参数TDocument，它表示您正在使用的文档类型。它几乎总是与IMongoCollection中使用的通用TDocument参数相匹配。

Fields

FieldDefinition<TDocument> 和FieldDefinition<TDocument>用来定义一个Field对象。它们是隐式可转换的字符串，因此您可以简单地传递您想要的字段名。例如，要使用名为“fn”的字段，使用BsonDocument的TDocument，执行以下操作:

FieldDefinition<BsonDocument> field = "fn";

但是，如果您使用的是一个映射类，那么我们就需要定义一个与属性名相等的字符串。如下例所示：给一个Person类

class Person
{
    [BsonElement("fn")]
    public string FirstName { get; set; }

    [BsonElement("ln")]
    public string LastName { get; set; }
}

因为我们知道类型为Person,我们可以提供属性名“FirstName”，并且"fn"依然可以被使用。

FieldDefinition<Person> field = "FirstName";

注意： 我们未验证所提供的字符串是否作为映射字段存在，所以仍然可以提供未映射的字段:

FieldDefinition<Person> field = "fn";

输出的字段名就仅是fn，而非映射字段

Filters

FiltersDefinition<TDocument>定义一个filter,它是由json字符串或者BsonDocument转换而来。

FilterDefinition<BsonDocument> filter = "{ x: 1 }";
// or
FilterDefinition<BsonDocument> filter = new BsonDocument("x", 1);

上边两种方式都定义了同一个filter{x:1}

FilterDefinitionBuilder<TDocument>提供了一种类型安全的API，用于构建简单和复杂的MongoDB查询。

例如，构建一个filter：{x:10,y:{$lt:20}}，下边的调用时等价的：

var builder = Builders<BsonDocument>.Filter;
var filter = builder.Eq("x", 10) & builder.Lt("y", 20);

注意：&运算符是重载的。

如下例：

创建一个类：

class Widget
{
    [BsonElement("x")]
    public int X { get; set; }

    [BsonElement("y")]
    public int Y { get; set; }
}
var builder = Builders<Widget>.Filter;
var filter = builder.Eq(widget => widget.X, 10) & builder.Lt(widget => widget.Y, 20);

这样做的好处是编译期运行安全，并且，你也可以进行重构。

另外，那你也可以使用field名来进行代替：

var filter = builder.Eq("X", 10) & builder.Lt("Y", 20);

// or

var filter = builder.Eq("x", 10) & builder.Lt("y", 20);

Array Operators
When using entities with properties or fields that serialize to arrays, you can use the methods prefixed with “Any” to compare the entire array against a single item.

Given the following class:

public class Post
{
    public IEnumerable<string> Tags { get; set; }
}
To see if any of the tags equals “mongodb”:

var filter = Builders<Post>.Filter.AnyEq(x => x.Tags, "mongodb");

// This will NOT compile:
// var filter = Builders<Post>.Filter.Eq(x => x.Tags, "mongodb");
Pipelines
A pipeline definition defines an entire aggregation pipeline. It is implicitly convertible from a List<BsonDocument>, a BsonDocument, a List<IPipelineStageDefinition> , and a IPipelineStageDefinition[].

For example:

PipelineDefinition pipeline = new BsonDocument[] 
{
    new BsonDocument { { "$match", new BsonDocument("x", 1) } },
    new BsonDocument { { "$sort", new BsonDocument("y", 1) } }
};
NOTE
There is no builder for a PipelineDefinition. In most cases, the IAggregateFluent<TDocument> interface would be used which is returned from the IMongoCollection<TDocument>.Aggregate method.

Projections
There are two forms of a projection definition: one where the type of the projection is known, ProjectionDefinition<TDocument, TProjection>, and one where the type of the projection is not yet known, ProjectionDefinition<TDocument>. The latter, while implicitly convertible to the first, is merely used as a building block. The high-level APIs that take a projection will always take the former. This is because, when determining how to handle a projection client-side, it is not enough to know what fields and transformations will take place. It also requires that we know how to interpret the projected shape as a .NET type. Since the driver allows you to work with custom classes, it is imperative that any projection also include the “interpretation instructions” for projecting into a custom class.

Each projection definition is implicity convertible from both a JSON string as well as a BsonDocument.

ProjectionDefinition<BsonDocument> projection = "{ x: 1 }";

// or

ProjectionDefinition<BsonDocument> projection = new BsonDocument("x", 1);
Both of these will render the projection { x: 1 }.

Projection Definition Builder
See the tests for examples.

The ProjectionDefinitionBuilder<TDocument> exists to make it easier to build up projections in MongoDB’s syntax. For the projection { x: 1, y: 1, _id: 0 }:

var projection = Builders<BsonDocument>.Projection.Include("x").Include("y").Exclude("_id");
Using the Widget class:

class Widget
{
    public ObjectId Id { get; set; }

    [BsonElement("x")]
    public int X { get; set; }

    [BsonElement("y")]
    public int Y { get; set; }
}
We can render the same projection in a couple of ways:

var projection = Builders<Widget>.Projection.Include("X").Include("Y").Exclude("Id");

// or

var projection = Builders<Widget>.Projection.Include("x").Include("y").Exclude("_id");

// or

var projection = Builders<Widget>.Projection.Include(x => x.X).Include(x => x.Y).Exclude(x => x.Id);

// or

var projection = Builders<Widget>.Projection.Expression(x => new { X = x.X, Y = x.Y });
This last projection where we’ve used the Expression method is subtly different as is explained below, and its return type is a (ProjectionDefinition<TDocument, TProjection>) as opposed to the others which return a (ProjectionDefinition<TDocument>).

Lambda Expressions
The driver supports using expression trees to render projections. The same expression tree will sometimes render differently when used in a Find operation versus when used in an Aggregate operation. Inherently, a lambda expression contains all the information necessary to form both the projection on the server as well as the client-side result and requires no further information.

Find
See the tests for examples.

When a Find projection is defined using a lambda expression, it is run client-side. The driver inspects the lambda expression to determine which fields are referenced and automatically constructs a server-side projection to return only those fields.

Given the following class:

class Widget
{
    public ObjectId Id { get; set; }

    [BsonElement("x")]
    public int X { get; set; }

    [BsonElement("y")]
    public int Y { get; set; }
}
The following lambda expressions will all result in the projection { x: 1, y: 1, _id: 0 }. This is because we inspect the expression tree to discover all the fields that are used and tell the server to include them. We then run the lambda expression client-side. As such, Find projections support virtually the entire breadth of the C# language.

var projection = Builders<Widget>.Projection.Expression(x => new { X = x.X, Y = x.Y });

var projection = Builders<Widget>.Projection.Expression(x => new { Sum = x.X + x.Y });

var projection = Builders<Widget>.Projection.Expression(x => new { Avg = (x.X + x.Y) / 2 });

var projection = Builders<Widget>.Projection.Expression(x => (x.X + x.Y) / 2);
The _id field is excluded automatically when we know for certain that it isn’t necessary, as is the case in all the above examples.

Aggregate
See the tests for examples.

When an aggregate projection is defined using a lambda expression, a majority of the aggregation expression operators are supported and translated. Unlike a project for Find, no part of the lambda expression is run client-side. This means that all expressions in a projection for the Aggregation Framework must be expressible on the server.

Grouping
See the tests for examples.

A projection is also used when performing grouping in the Aggregation Framework. In addition to the expression operators used in an aggregate projection, the aggregation accumulator operators are also supported.

Sorts
SortDefinition<TDocument> defines how to render a valid sort document. It is implicity convertible from both a JSON string as well as a BsonDocument.

SortDefinition<BsonDocument> sort = "{ x: 1 }";

// or

SortDefinition<BsonDocument> sort = new BsonDocument("x", 1);
Both of these will render the sort { x: 1 }.

Sort Definition Builder
See the tests for examples.

The SortDefinitionBuilder<TDocument> provides a type-safe API for building up MongoDB sort syntax.

For example, to build up the sort { x: 1, y: -1 }, do the following:

var builder = Builders<BsonDocument>.Sort;
var sort = builder.Ascending("x").Descending("y");
Given the following class:

class Widget
{
    [BsonElement("x")]
    public int X { get; set; }

    [BsonElement("y")]
    public int Y { get; set; }
}
We can achieve the same result in the typed variant:

var builder = Builders<Widget>.Sort;
var sort = builder.Ascending(x => x.X).Descending(x => x.Y);

// or

var sort = builder.Ascending("X").Descending("Y");

// or

var sort = builder.Ascending("x").Descending("y");
Updates
UpdateDefinition<TDocument> defines how to render a valid update document. It is implicity convertible from both a JSON string as well as a BsonDocument.

// invocation
UpdateDefinition<BsonDocument> update = "{ $set: { x: 1 } }";

// or

UpdateDefinition<BsonDocument> update = new BsonDocument("$set", new BsonDocument("x", 1));
Both of these will render the update { $set: { x: 1 } }.

Update Definition Builder
See the tests for examples.

The UpdateDefinitionBuilder<TDocument> provides a type-safe API for building the MongoDB update specification.

For example, to build up the update { $set: { x: 1, y: 3 }, $inc: { z: 1 } }, do the following:

var builder = Builders<BsonDocument>.Update;
var update = builder.Set("x", 1).Set("y", 3).Inc("z", 1);
Given the following class:

class Widget
{
    [BsonElement("x")]
    public int X { get; set; }

    [BsonElement("y")]
    public int Y { get; set; }

    [BsonElement("z")]
    public int Z { get; set; }
}
We can achieve the same result in a typed variant:

var builder = Builders<Widget>.Update;
var update = builder.Set(widget => widget.X, 1).Set(widget => widget.Y, 3).Inc(widget => widget.Z, 1);

// or

var update = builder.Set("X", 1).Set("Y", 3).Inc("Z", 1);

// or

var update = builder.Set("x", 1).Set("y", 3).Inc("z", 1);
Index Keys
IndexKeysDefinition<TDocument> defines the keys for index. It is implicity convertible from both a JSON string as well as a BsonDocument.

IndexKeysDefinition<BsonDocument> keys = "{ x: 1 }";

// or

IndexKeysDefinition<BsonDocument> keys = new BsonDocument("x", 1);
Both of these will render the keys { x: 1 }.

Index Keys Definition Builder
See the tests for examples.

The IndexKeysDefinitionBuilder<TDocument> provides a type-safe API to build an index keys definition.

For example, to build up the keys { x: 1, y: -1 }, do the following:

var builder = Builders<BsonDocument>.IndexKeys;
var keys = builder.Ascending("x").Descending("y");
Given the following class:

class Widget
{
    [BsonElement("x")]
    public int X { get; set; }

    [BsonElement("y")]
    public int Y { get; set; }
}
We can achieve the same result in the typed variant:

var builder = Builders<Widget>.IndexKeys;
var keys = builder.Ascending(x => x.X).Descending(x => x.Y);

// or

var keys = builder.Ascending("X").Descending("Y");

// or

var keys = builder.Ascending("x").Descending("y");