Id Member

Unique Identifier

Each top level document in MongoDB contains an _id field that uniquely identifies documents in the collection. This field can be mapped from/to a public property in C# models. By convention public members named Id, id and id will be used as the identifier. MongoDB will ensure to generate a value for your identifier field when inserting documents and deserialize it back your model member during reads.

The identifier member can be of any type but this doesn't mean that MongoDB will be able to automatically generate the value during insertions

Supported MongoDB Id generators

You can use the following types for your Id identifier type:

String

Let's assume that you have a Message class with a string Id public member:

C#

IdMember.cs

var message = new Message {Text = "hello world"};

await messagesCollection.InsertOneAsync(message);

Utils.Log(message.ToBsonDocument());

Message - Faulty

public class Message
{
    public string Id { get; set; }
    public string Text { get; set; }
}

Result

// Id hasn't be recognized by MongoDB 
// as an auto generated property
{
  "_id": null,
  "text": "hello world"
}

When you want to use a string member as an auto generated MongoDB Id member, then just declaring it as a string isn't enough. You need to inform the driver which IdGenerator should use so that can understand if the Id member has been assigned a value or not.

In case you don't do this, the next time you try to insert a document you will get a E11000 duplicate key error collection error

The correct way to use a string Id member as identifier field is the following:

Message

IdMember.cs

public class Message
{
    [BsonId(IdGenerator = typeof(StringObjectIdGenerator))]
    public string Id { get; set; }
    public string Text { get; set; }
}

Custom Id

public class Message
{
    [BsonId(IdGenerator = typeof(StringObjectIdGenerator))]
    public string MyCustomId { get; set; }
    public string Text { get; set; }
}

Result

// _id field gets a generated string
{
  "_id": "5e8e0b39f618356c98297e0c",
  "text": "hello world"
}

In case you want to name your identifier member other than Id, id or _id, make sure you use the [BsonId]attribute on it and MongoDB driver will do the rest

Guid

Guid is one of the most used types for identifying documents and MongoDB fully support them. In fact, in case you use it along with a convention compatible Id member, you don't even need to specify the IdGenerator.

Message

IdMember.cs

public class Message
{
    public Guid Id { get; set; }
    public string Text { get; set; }
}

Custom Id

public class Message
{
    [BsonId(IdGenerator = typeof(GuidGenerator))]
    public Guid MyCustomId { get; set; }
    public string Text { get; set; }
}

Result

{
  "_id": "9bdc79ca-aafb-4a58-a97e-02f199f774b8",
  "text": "hello world"
}

COMB Guid

MongoDB supports generating Guid values using the COMB algorithm and you can use it as follow:

IdMember.cs

public class Message
{
    [BsonId(IdGenerator = typeof(CombGuidGenerator))]
    public Guid MyCustomId { get; set; }
    public string Text { get; set; }
}

ObjectId

MongoDB loves ObjectId ♥️ which is a 12-byte special type for MongoDB which is fast to generate and contains:

• A timestamp value representing the ObjectId's creations (4-byte)

• An auto-incrementing counter (3-byte)

• A random value (5-byte)

In fact, if you try to insert a document in MongoDB in the shell and don't provide any value for the _id field, it will be saved as an ObjectId type

Convention based names with ObjectId type don't require the [BsonId] attribute.

Message

IdMember.cs

public class Message
{
    public ObjectId Id { get; set; }
    public string Text { get; set; }
}

Result

{
  "_id": "5e903c0012193c8ba86bc780",
  "text": "hello world"
}

If you want to use a custom identifier name, just add the [BsonId] attribute. Defining the ObjectIdGenerator is optional.

[BsonId]

public class Message
{
    [BsonId]
    public ObjectId CustomId { get; set; }
    public string Text { get; set; }
}

ObjectIdGenerator

public class Message
{
    [BsonId(IdGenerator = typeof(ObjectIdGenerator))]
    public ObjectId CustomId { get; set; }
    public string Text { get; set; }
}

BsonObjectId

Everything applies for the ObjectId type applies for BsonObjectId as well.

Message

IdMember.cs

public class Message
{
    public BsonObjectId Id { get; set; }
    public string Text { get; set; }
}

Resut

// _id is actually ObjectId("5e8e19fd9ebaad96c89eb225")
// .ToString() will display only the string part
{
  "_id": "5e8e19fd9ebaad96c89eb225",
  "text": "hello world"
}

If you want to use a custom identifier name, just add the [BsonId] attribute. Defining the BsonObjectIdGenerator is optional.

[BsonId]

public class Message
{
    [BsonId]
    public BsonObjectId MyCustomId { get; set; }
    public string Text { get; set; }
}

BsonObjectIdGenerator

public class Message
{
    [BsonId(IdGenerator = typeof(BsonObjectIdGenerator))]
    public BsonObjectId MyCustomId { get; set; }
    public string Text { get; set; }
}

NullIdChecker Generator

In case you want to ensure that the identifier field has been assigned a value before sending the query to MongoDB, you can use the NullIdChecker generator.

Message

public class Message
{
    [BsonId(IdGenerator = typeof(NullIdChecker))]
    public object Id { get; set; }
    public string Text { get; set; }
}

Exception

// The following will throw System.InvalidOperationException: Id cannot be null.
var message = new Message {Text = "hello world"};
await messagesCollection.InsertOneAsync(message);

Trying to insert a document without assigning a value first for an identifier field with NullIdChecker generator will throw System.InvalidOperationException: <field> cannot be null.