POCO

読み取り専用プロパティを直列化

プロパティが読み取り専用の場合、オートマッパーはそのプロパティを直列化用のクラス マップに含めません。クラス マップにプロパティを含めるようにオートマッパーを強制するには、 [BsonElement] 属性をプロパティに適用します。

次のコード例では、Clothing クラスの Upc プロパティに [BsonElement] 属性を適用します。Upc には、get メソッドはありますが、 set メソッドがないため、読み取り専用プロパティです。

public class Clothing
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    public bool InStock { get; set; }
    public double Price { get; set; }
    public List<string> ColorSelection { get; set; }
    [BsonElement]
    public int Upc { get; }
}

次の例に示すように、クラスマップを登録するときに読み取り専用プロパティを追加することもできます。

BsonClassMap.RegisterClassMap<Clothing>(classMap =>
{
    classMap.AutoMap();
    classMap.MapProperty(c => c.Upc);
});

フィールド名を設定

ドライバーは、同じフィールド名と大文字小文字を使用して、POCO プロパティを BSON フィールドに直列化します。プロパティを別の名前で保存するには、[BsonElement()] 属性を使用します。次のコードは、House クラスの YearBuilt プロパティを、直列化された BSON ドキュメントの year_built フィールドにマッピングします。

public class House
{
    public Guid Id { get; set; }
    [BsonElement("year_built")]
    public int YearBuilt { get; set; }
}

C# クラスを定義するときはパスカルケースの命名規則を使用するのが一般的ですが、[BsonElement()] 属性を使用すると、MongoDB コレクションで別の命名規則またはカスタム命名規則を選択できます。

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);

型表現を選択する

C# プロパティを特定の BSON 型に直列化するには、 [BsonRepresentation()] 属性を使用します。これは、C# プリミティブ型が指定された BSON 型に変換可能な場合にのみ機能します。次のコード例では、C# で char として定義されている YearBuilt プロパティが BSON Int32 型として直列化されています。

public class House
{
    public Guid Id { get; set; }
    [BsonRepresentation(BsonType.Int32)]
    public char YearBuilt { get; set; }
}

有効な型変換の詳細については、「C# 変換の仕様」を参照してください。

フィールドの順序を設定

ドライバーは、POCO で指定された順序でプロパティを BSON フィールドに直列化します。既存のスキーマと一致するようにプロパティをカスタム順序で保存するには、[BsonElement()] 属性に Order という名前のパラメーターを指定できます。次のコード例では、ドライバーは Style プロパティの後に YearBuilt プロパティを保存します。

public class House
{
    public Guid Id { get; set; }
    [BsonElement(Order = 2)]
    public int YearBuilt { get; set; }
    [BsonElement(Order = 1)]
    public string Style { get; set; }
}

明示的に Order が指定されていないプロパティの場合、ドライバーは Order が明示的に指定されているプロパティの後に、デフォルトの順序でそれらを直列化します。

Idプロパティの識別

デフォルトでは、ドライバーは Id、id、または _id という名前のパブリック プロパティを BSONの _id フィールドにマッピングします。_id フィールドにマッピングするプロパティを明示的に選択するには、[BsonId()] 属性を使用します。次のコード例は、Identifier プロパティを _id フィールドにマッピングします。

public class House
{
    [BsonId]
    public string Identifier { get; set; }
}

空のフィールドを省略

デフォルトでは、ドライバーは未定義のプロパティを null 値を持つフィールドとして直列化します。直列化の際に未定義のプロパティを無視するには、[BsonIgnore] 属性を使用します。次のコードは、YearBuilt プロパティが未定義の場合にドライバーが直列化しないようにする方法を示しています。

public class House
{
    public Guid Id { get; set; }
    [BsonIgnore]
    public int YearBuilt { get; set; }
    public string Style { get; set; }
}

デフォルト値をカスタマイズ

C# では、プロパティには値を割り当てるまでデフォルト値が設定されます。デフォルト値は、プロパティのデータ型によって異なります。たとえば、参照型プロパティのデフォルト値は null です。

プロパティに別のデフォルト値を指定するには、プロパティに [BsonDefaultValue()] 属性を適用し、任意のデフォルト値を引数として渡します。

次のコード例では、[BsonDefaultValue()] 属性を YearBuilt プロパティに適用します。このプロパティに値が割り当てられるまで、その値は 1900 です。

public class House
{
    public Guid Id { get; set; }
    [BsonDefaultValue(1900)]
    public int YearBuilt { get; set; }
}

次の例に示すように、クラスマップを登録するときに、プロパティに別のデフォルト値を指定することもできます。

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.YearBuilt).SetDefaultValue(1900);
});

デフォルトでは、.NET/C# ドライバーは、デフォルト値を持つプロパティを含む、すべてのプロパティを直列化します。デフォルト値を持つプロパティを無視するようにドライバーに指定するには、[BsonIgnoreIfDefault] 属性を使用します。

次のコード例では、[BsonIgnoreIfDefault] 属性を YearBuilt プロパティに適用します。このプロパティの値がそのデータ型のデフォルト（int プロパティの場合は 0）の場合、ドライバーはそれを直列化しません。

public class House
{
    public Guid Id { get; set; }
    [BsonIgnoreIfDefault]
    public int YearBuilt { get; set; }
}

次の例に示すように、クラスマップを登録するときに、デフォルト値を含むプロパティを無視するようにドライバーに指示することもできます。

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.YearBuilt).SetIgnoreIfDefault(true);
});

このデフォルト値が含まれている場合は、プロパティに別のデフォルト値を指定することも、そのプロパティを無視するようにドライバーに指示することもできます。これを行うには、次のコード例に示すように、プロパティに [BsonDefaultValue()] 属性と [BsonIgnoreIfDefault] 属性の両方を適用します。

public class House
{
    public Guid Id { get; set; }
    [BsonDefaultValue(1900)]
    [BsonIgnoreIfDefault]
    public int YearBuilt { get; set; }
}

前のコード例では、次の直列化動作を設定しています。

• YearBuilt プロパティに値が割り当てられていない場合は、指定されたデフォルト値 1900 が設定されます。

• このプロパティのデフォルト値は 1900 であるため、プロパティがこの値を持つ場合、ドライバーはプロパティを無視します。

ID ジェネレータを指定

MongoDB コレクション内のすべてのドキュメントにはユニークな ID が必要です。オブジェクトをコレクションに直列化する際、Id プロパティがそのデータ型のデフォルト値を持つ場合、.NET/C# ドライバーはそれを直列化しません。代わりに、ドライバーはプロパティのユニークな ID 値を生成します。

Id プロパティの型が Guid、ObjectId、または string の場合、ドライバーは独自に ID 値を生成できます。Id プロパティが他のデータ型の場合、ドライバーが値を生成するために使用する IIdGenerator 型を指定する必要があります。IIdGenerator 型を指定するには、プロパティに [BsonId(IdGenerator)] 属性を適用し、IIdGenerator 型を引数として渡します。

.NET/C# ドライバーには以下の IIdGenerator 型があります。

次のコード例では、House クラスの Id プロパティにデフォルト値（null）が含まれている場合、ドライバーは COMB アルゴリズムを使用して直列化中にユニークな値を生成します。

public class House
{
    [BsonId(IdGenerator = typeof(CombGuidGenerator))]
    public Guid Id { get; set; }
}

次の例に示すように、クラスマップを登録する際に IIdGenerator 型を指定することもできます。

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapIdMember(h => h.Id).SetIdGenerator(CombGuidGenerator.Instance);
});

BsonSerializer.RegisterIdGenerator(
  typeof(Guid),
  CombGuidGenerator.Instance
);

.NET/C# ドライバーには、Id プロパティを検証し、ID が無効な場合に例外をスローする IIdGenerator 型も含まれています。次の表に、これらの型を示します。

次のコード例では、House クラスの Id プロパティにデフォルト値（null）が含まれている場合、ドライバーは例外をスローします。

public class House
{
    [BsonId(IdGenerator = typeof(NullIdChecker))]
    public Guid Id { get; set; }
}

DateTime 直列化をカスタマイズ

.NET/C# ドライバーが DateTime プロパティを直列化する方法をカスタマイズするには、[BsonDateTimeOptions()] 属性を使用し、任意の設定を引数として指定します。

DateTime プロパティが日付のみを表す場合は、[BsonDateTimeOptions(DateOnly = true)] 属性を適用できます。これを実施すると、ドライバーは値に対してタイムゾーンの変換を行いません。

次のコード例では、PatientRecord クラスは DateOfBirth プロパティに DateTime を使用します。[BsonDateTimeOptions(DateOnly = true)] 属性は、プロパティに日付のみが含まれていることを示します。

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateTimeOptions(DateOnly = true)]
    public DateTime DateOfBirth { get; set; }
}

[BsonDateTimeOptions()] 属性を使用して、DateTime プロパティの DateTimeKind を指定することもできます。次のコード例では、PatientRecord クラスに DateTime 型の AppointmentTime プロパティがあります。[BsonDateTimeOptions(Kind = DateTimeKind.Local)] 属性は、プロパティの値の時間コンポーネントがローカル時間であることを示します。ドライバーがこのプロパティを直列化する際、時刻を UTC に変換します。これは MongoDB に保存される時刻の標準形式です。

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateTimeOptions(Kind = DateTimeKind.Local)]
    public DateTime AppointmentTime { get; set; }
}

クラスマップを登録するときに、前述の DateTime オプションの 1 つまたは両方を指定することもできます。

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(p => p.DateOfBirth)
      .SetSerializer(new DateTimeSerializer(dateOnly: true));
   classMap.MapMember(p => p.AppointmentTime)
      .SetSerializer(new DateTimeSerializer(DateTimeKind.Local));
});

辞書の直列化をカスタマイズ

DictionaryRepresentation 列挙型は、.NET/C# ドライバーが Dictionary インスタンスを直列化できる形式を定義します。この列挙型には、次のノードが含まれます。

• Document:（デフォルト）ドライバーは Dictionary を BsonDocument に直列化します。辞書内の各エントリは、名前がエントリのキーと等しく、値がエントリの値と等しい値を持つ BsonElement です。この表現を使用できるのは、辞書内のすべてのキーが有効な BsonElement 名でもある文字列の場合のみです。

• ArrayOfArrays: ドライバーは辞書を BsonArray に直列化します。辞書内の各エントリは、エントリのキーとエントリの値を含む、ネストされた 2 要素のBsonArray です。

• ArrayOfDocuments: ドライバーは辞書を BsonArray に直列化します。辞書内の各エントリは { k : key, v : value } という形式の BsonDocument がネストされています。キーと値には要素名がタグ付けされているので、ArrayOfArrays よりも直感的にこの形式でクエリを実行できます。

次のコード例では、RoomSizes プロパティは、家一軒の各部屋とその大きさを含む辞書となっています。[BsonDictionaryOptions()] 属性は、.NET/C# ドライバーに対して、このプロパティを BsonArray オブジェクトに直列化し、辞書の各エントリを { k : "<room>", v : <size> } 形式の BsonDocument に直列化するように指示します。

public class House
{
    public Guid Id { get; set; }
    [BsonDictionaryOptions(DictionaryRepresentation.ArrayOfDocuments)]
    public Dictionary<string, float> RoomSizes { get; set; }
}

次の例に示すように、クラスマップを登録する際に、辞書の直列化形式を指定することもできます。

BsonClassMap.RegisterClassMap<House>(classMap =>
{
    classMap.AutoMap();
    classMAp.MapMember(h => h.RoomSizes)
      .SetSerializer(new DictionaryInterfaceImplementerSerializer<Dictionary<string, float>>
      (DictionaryRepresentation.ArrayOfDocuments));
});

API ドキュメント

このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。

• [BsonElement()]

• [BsonRepresentation()]

• [BsonId()]

• [BsonIgnore()]

• [BsonDefaultValue()]

• [BsonIgnoreIfDefault]

• [BsonDateTimeOptions()]

• [BsonDictionaryOptions()]

• ConventionPack

• InsertOne()