POCO

읽기 전용 속성 직렬화

속성이 읽기 전용인 경우 자동 매퍼는 직렬화를 위해 클래스 맵에 해당 속성을 포함하지 않습니다. 자동 매퍼가 클래스 맵에 속성을 포함하도록 하려면 해당 속성에 [BsonElement] 특성을 적용합니다.

다음 코드 예시에서는 [BsonElement] 특성을 Clothing 클래스의 Upc 속성에 적용합니다. 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가 없는 경우 드라이버는 명시적 값이 있는 속성 다음에 해당 속성을 기본 순서로 직렬화합니다.

Id 속성 식별

기본적으로 드라이버는 Id, id 또는 _id라는 공용 속성을 BSON _id 필드에 매핑합니다. _id 필드에 매핑할 속성을 명시적으로 선택하려면 [BsonId()] 특성을 사용합니다. 다음 코드 샘플에서는 Identifier 속성을 _id 필드에 매핑합니다.

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

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

public class House
{
   public Guid Id { get; set; }
}

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

public class House
{
   [BsonRepresentation(BsonType.ObjectId)]
   public string Id { get; set; }
}

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

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

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

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

public class House
{
    [BsonId(IdGenerator = typeof(NullIdChecker))]
    public Guid Id { 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이 속성의 기본값이므로 드라이버는 이 값이 있는 경우 속성을 무시합니다.

날짜/시간 직렬화 사용자 지정

.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)] 특성은 속성 값의 시간 구성 요소가 현지 시간임을 나타냅니다. 드라이버는 이 속성을 직렬화할 때 시간을 MongoDB에 저장된 표준 시간 형식인 UTC로 변환합니다.

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

클래스 맵을 등록할 때 이전 DateTime 옵션 중 하나 또는 둘 다를 지정할 수도 있습니다.

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 인스턴스를 직렬화할 수 있는 형식을 정의합니다. 이 열거형에는 다음 노드가 포함됩니다.

• 문서: (기본값) 드라이버는 Dictionary를 BsonDocument로 직렬화합니다. 사전의 각 항목은 항목 키와 이름이 같고 값이 항목 값과 같은 BsonElement입니다. 사전의 모든 키가 유효한 BsonElement 이름이기도 한 문자열인 경우에만 이 표현을 사용할 수 있습니다.

• ArrayOfArrays: 드라이버가 사전을 BsonArray로 직렬화합니다. 사전의 각 항목은 항목 키와 항목 값을 포함하는 중첩된 두 요소로 구성된 BsonArray입니다.

• ArrayOfDocuments: 드라이버는 사전을 BsonArray로 직렬화합니다. 사전의 각 항목은 { k : key, v : value } 형식의 중첩된 BsonDocument입니다. 키와 값에 요소 이름이 태그되어 있으므로 이 형식은 ArrayOfArrays보다 더 직관적으로 쿼리할 수 있습니다.

다음 코드 예시에서 RoomSizes 속성은 집의 각 방과 해당 크기를 포함하는 사전입니다. [BsonDictionaryOptions()] 특성은 이 속성을 BsonArray 객체로, 사전의 각 항목을 { k : "<room>", v : <size> } 형식의 BsonDocument로 직렬화하도록 .NET/C# 드라이버에 지시합니다.

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()