객체 모델 - .NET SDK
이 페이지의 내용
객체 모델 만들기
Realm 클래스는 Realm 스키마를 정의하는 일반 C# 클래스입니다.
중요
상속
모든 Realm 객체는 IRealmObject, IEmbeddedObject 또는 IAsymmetricObject 인터페이스에서 상속되며 partial 클래스로 선언되어야 합니다.
10.18.0 이전의 .NET SDK 버전에서는 객체는 RealmObject, EmbeddedObject 또는 AsymmetricObject 기본 클래스에서 파생됩니다. Realm 모델 정의에 대한 이 접근 방식은 계속 지원되지만 null 허용 여부 주석 과 같은 새로운 기능은 포함되지 않습니다. 향후 SDK 릴리스에서는 기본 클래스가 더 이상 사용되지 않습니다. 새로 작성하는 모든 클래스에 인터페이스를 사용해야 하며 기존 클래스의 마이그레이션을 고려해야 합니다.
참고
클래스 이름은 최대 57자의 UTF-8 문자로 제한됩니다.
객체 스키마
객체 스키마는 Realm 객체의 속성과 관계를 정의하는 구성 객체입니다. Realm 클라이언트 애플리케이션은 네이티브 클래스로 구현된 객체 스키마를 정의하며, 이때 객체 스키마를 사용하는 해당 언어를 사용합니다.
객체 스키마는 각 속성의 데이터 유형, 속성이 필요한지 여부와 같은 객체 속성에 대한 제약 조건을 지정합니다. 스키마는 또한 영역의 객체 유형 간의 관계를 정의할 수 있습니다.
모든 앱에는 해당 애플리케이션의 영역에 포함될 수 있는 각 객체 유형에 대한 객체 스키마 목록으로 구성된 App Services 스키마가 있습니다. Realm은 영역의 모든 객체가 해당 객체 유형의 스키마를 준수하도록 보장하고 객체가 생성, 수정 또는 삭제될 때마다 객체의 유효성을 검사합니다.
속성 주석
스키마 속성은 RealmObject의 표준 C# 속성입니다. Realm이 특정 속성을 처리하는 방법을 더 세밀하게 정의하기 위해 사용할 수 있는 몇 가지 속성 주석이 있습니다.
기본 키
기본 키는 객체를 고유하게 식별하는 속성입니다. 다음 유형(또는 null 허용 대응 항목)을 사용하여 기본 키를 생성할 수 있습니다.
ObjectIdUUIDstringcharbyteshortintlong
객체 스키마 의 일부로 객체 유형의 단일 속성 에 기본 키를 정의할 수 있습니다. Realm은 기본 키 속성을 자동으로 인덱싱하므로 기본 키를 기반으로 객체를 효율적으로 읽고 수정할 수 있습니다.
객체 유형에 기본 키가 있는 경우 해당 유형의 모든 객체에는 영역에 있는 동일한 유형의 객체와 비교했을 때 고유한 값을 갖는 기본 키 속성이 포함되어야 합니다.
참고
속성을 기본 키로 할당한 후에는 변경할 수 없습니다.
다음 예에서는 객체 스키마에서 기본 키를 지정하는 방법을 보여줍니다.
public partial class Dog : IRealmObject { [] public string Name { get; set; } public int Age { get; set; } public Person? Owner { get; set; } }
Indexes
인덱스는 Realm에서 쿼리 시간을 크게 개선합니다. 인덱스가 없으면 Realm은 컬렉션의 모든 문서를 검색하여 주어진 쿼리와 일치하는 문서를 선택합니다. 그러나 쿼리에 적용 가능한 인덱스가 있는 경우 Realm은 해당 인덱스를 사용하여 검사해야 하는 문서 수를 제한합니다.
다음 유형으로 속성을 인덱싱할 수 있습니다.
boolbyteshortintlongDateTimeOffsetcharstringObjectIdUUID
참고
인덱스를 추가하면 쓰기 시간이 약간 느려지고 스토리지 및 메모리 오버헤드가 늘어나지만, 일부 쿼리의 속도가 빨라질 수 있습니다. 인덱스는 영역 파일의 공간을 차지하므로 속성에 인덱스를 추가하면 영역 파일이 사용하는 디스크 공간이 늘어납니다. 각 인덱스 항목은 최소 12바이트입니다.
속성을 인덱싱하려면 Indexed 속성을 사용합니다. Indexed 속성을 사용하면 IndexType 열거형을 사용하여 속성의 인덱스 유형을 지정할 수 있습니다. 다음 예제에는 Name 속성에 대한 기본("일반") 인덱스가 있습니다.
public partial class Person : IRealmObject { [] public string Name { get; set; } [] public string Biography { get; set; } }
참고
인덱스를 생성하면 Atlas 컬렉션이 아닌 로컬 영역에 인덱스가 생성됩니다. Atlas 컬렉션을 직접 쿼리해야 하고 성능을 개선하려면 인덱스 만들기, 보기, 삭제 및 숨기기를 참조하세요.
전체 텍스트 검색 인덱스
Realm은 표준 인덱스 외에도 string 속성에 대한 FTS(Full-Text Search) 인덱스를 지원합니다. 표준 인덱스 유무에 관계없이 문자열 필드를 쿼리할 수 있지만 FTS 인덱스를 사용하면 여러 단어와 구문를 검색하고 나머지는 제외할 수 있습니다.
전체 텍스트 인덱스 쿼리에 대한 자세한 내용은 Full Text Search(LINQ) 및 Full Text Search(RQL)을 참조하세요.
FTS 속성을 인덱싱하려면 IndexType.FullText 열거형과 함께 Indexed 속성을 사용합니다. 다음 예제에는 Biography 속성에 대한 FullText 인덱스가 있습니다.
public partial class Person : IRealmObject { [] public string Name { get; set; } [] public string Biography { get; set; } }
기본 필드 값
내장된 언어 기능을 사용하여 속성에 기본값을 지정할 수 있습니다. C#에서는 속성 선언의 기본 형식에 기본값을 할당할 수 있습니다. 컬렉션에 기본값을 설정할 수는 없습니다. 단, 기본값을 null!로 설정하는 경우는 예외입니다. 컬렉션을 null!로 설정하더라도 컬렉션은 항상 처음 액세스할 때 초기화되므로 null이 되지 않습니다.
public partial class Person : IRealmObject { public string Name { get; set; } = "foo"; public IList<PhoneNumber> PhoneNumbers { get; } = null!; }
참고
기본값 및 null 허용 여부
기본값은 새로 만든 객체가 null 값을 포함할 수 없도록 하지만(기본값 null 을 지정하지 않는 한), 속성의 null 허용 여부에는 영향을 주지 않습니다. null을 허용하지 않는 속성을 만들려면 필수 속성을 참조하세요.
속성 무시
모델의 속성을 영역에 저장하지 않으려면 해당 속성을 무시하면 됩니다. 속성이 자동 구현되지 않았거나 설정자가 없는 경우에는 기본적으로 무시됩니다.
Ignored 속성을 사용하여 Realm 객체 모델에서 속성을 무시합니다.
// Rather than store an Image in Realm, // store the path to the Image... public string ThumbnailPath { get; set; } // ...and the Image itself can be // in-memory when the app is running: [] public Image? Thumbnail { get; set; }
속성 이름 바꾸기
기본적으로 Realm은 모델 클래스에 정의된 이름을 사용하여 내부적으로 속성을 나타냅니다. 다음과 같은 이유로 이 동작을 변경하고 싶을 수도 있습니다.
이름 지정 규칙이 서로 다른 플랫폼에서 더 쉽게 작업하고자 하는 경우.
마이그레이션을 강제하지 않고 .NET에서 속성 이름을 변경하고자 하는 경우.
모델 클래스에 사용된 이름과 다른 내부 이름을 선택하면 다음과 같은 의미가 있습니다.
마이그레이션에서는 클래스 및 속성을 생성할 때 내부 이름을 사용해야 합니다.
보고된 스키마 오류는 내부 이름을 사용합니다.
[MapTo] 속성을 사용하여 속성의 이름을 바꿉니다.
public partial class Person : IRealmObject { [] public string Name { get; set; } }
클래스 이름 바꾸기
기본적으로 Realm은 모델 클래스에 정의된 이름을 사용하여 내부적으로 클래스를 나타냅니다. 다음과 같은 이유로 이 동작을 변경하고 싶을 수도 있습니다:
서로 다른 네임스페이스에서 동일한 단순한 이름을 가진 여러 모델 클래스를 지원하고자 하는 경우.
이름 지정 규칙이 서로 다른 플랫폼에서 더 쉽게 작업하고자 하는 경우.
클래스 이름이 Realm에서 지정한 57자 제한보다 긴 경우.
마이그레이션을 강제하지 않고 .NET에서 클래스 이름을 변경하고자 하는 경우.
[MapTo] 속성을 사용하여 클래스 이름을 변경합니다.
[] public partial class Person : IRealmObject { public string Name { get; set; } }
사용자 지정 설정자
Realm은 사용자 지정 설정자가 있는 속성을 저장하지 않습니다. 사용자 지정 설정자를 사용하려면 속성값을 비공개 속성에 저장한 다음, 사용자 지정 설정자를 사용하여 해당 값을 공개 속성에 매핑합니다. Realm은 비공개 속성을 저장하지만, 사용자는 공개 속성을 통해 해당 값을 수정합니다. 다음 코드에서 비공개 email 속성은 영역에 저장되지만 유효성 검사를 제공하는 공개 Email 속성은 유지되지 않습니다.
// This property will be stored in the Realm private string email { get; set; } // Custom validation of the email property. // This property is *not* stored in Realm. public string Email { get { return email; } set { if (!value.Contains("@")) throw new Exception("Invalid email address"); email = value; } }
비정형 데이터 정의
버전 12.2.0에 추가 되었습니다.
SDK 버전 12.2.0 부터 RealmValue 속성 내에 혼합 데이터 컬렉션을 저장 수 있습니다. 이 기능 을 사용하면 엄격한 데이터 모델 을 정의하지 않고도 JSON 또는 MongoDB 문서와 같은 복잡한 데이터 구조를 모델링할 수 있습니다.
구조화되지 않은 데이터 는 예상 스키마 를 쉽게 준수하지 않는 데이터로, 개별 데이터 클래스를 모델링하기가 어렵거나 비실용적입니다. 예를 예시 앱 에 매우 가변적인 데이터나 런타임에 구조를 알 수 없는 동적 데이터가 있을 수 있습니다.
컬렉션을 혼합 속성 에 저장하면 Device Sync 사용 시 성능 동기화를 포함하여 기능을 희생하지 않고도 유연성을 확보할 수 있습니다. 혼합되지 않은 컬렉션 과 동일한 방식으로 작업할 수 있습니다.
혼합 컬렉션을 최대 100 수준까지 중첩할 수 있습니다.
혼합 컬렉션의 변경React 을 쿼리 하고 이에 대응할 수 있습니다.
개별 혼합 컬렉션 요소를 찾고 업데이트 할 수 있습니다.
그러나 혼합된 컬렉션에 데이터를 저장하는 것은 구조화된 스키마 를 사용하거나 JSON blob을 단일 string 속성 으로 직렬화하는 것보다 성능이 떨어집니다.
앱 에서 구조화되지 않은 데이터를 모델링하려면 스키마 에서 적절한 속성을 RealmValue 유형으로 정의합니다. 그런 다음 이러한 RealmValue 속성을 RealmValue 요소의 목록 또는 사전 으로 설정하다 수 있습니다. RealmValue 은(는) 설정하다 이나 내장된 객체 를 나타낼 수 없습니다 .
팁
유형을 알 수 없지만 각 값에 고유 식별자가 있는 경우 혼합 데이터 유형의 맵을 사용합니다.
유형을 알 수 없지만 객체의 순서가 의미 있는 경우 혼합 데이터 유형 목록을 사용합니다.
Realm 스키마에서 클래스 생략
기본적으로 애플리케이션의 Realm 스키마에는 IRealmObject 또는 IEmbeddedObject를 구현하는 모든 클래스가 포함됩니다. Realm 스키마에 이러한 클래스의 하위 집합만 포함하려는 경우 원하는 특정 클래스를 포함하도록 구성을 업데이트할 수 있습니다.
// Declare your schema partial class LoneClass : IRealmObject { public string Name { get; set; } } class AnotherClass { private void SetUpMyRealmConfig() { // Define your config with a single class var config = new RealmConfiguration("RealmWithOneClass.realm"); config.Schema = new[] { typeof(LoneClass) }; // Or, specify multiple classes to use in the Realm config.Schema = new[] { typeof(Dog), typeof(Cat) }; } }
필수 및 선택 속성
C# 에서 int 및 과 같은 값 형식은 bool 암시적으로 null이 아닙니다. 그러나 물음표(?) 표기법을 사용하여 선택사항으로 설정할 수 있습니다.
C# 8.0부터 null 허용 참조 형식이 도입되었습니다. 프로젝트에서 C# 8.0 이상을 사용하는 경우 string 및 byte[]와 같은 참조 유형을 ?를 사용하여 null 허용으로 선언할 수도 있습니다.
참고
.NET 6.0 부터는 새 프로젝트에 대해 기본적으로 null 허용 컨텍스트가 활성화됩니다. 이전 프로젝트의 경우 수동으로 활성화할 수 있습니다. 자세한 내용은 https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/nullable-reference-types#setting-the-nullable-context를 참조하세요.
Realm .NET SDK는 null 허용 인식 컨텍스트를 완벽하게 지원하며 null 허용을 사용하여 속성이 필수인지 선택 사항인지 결정합니다. SDK에는 다음과 같은 규칙이 있습니다.
Realm은 null 허용으로 지정하지 않을 경우 값 및 참조 유형 속성이 모두 필요하다고 가정합니다.
?를 사용하여 null 허용으로 지정하면 Realm은 이를 선택 사항으로 간주합니다.Realm 객체 유형인 속성을 null 허용으로 선언해야 합니다.
컬렉션(목록, 세트, 역링크, 사전)은 null 허용으로 선언할 수 없지만, 해당 매개변수는 다음 규칙에 따라 null을 허용할 수 있습니다.
모든 유형의 컬렉션에 대해 매개 변수가 기본 형식(값 또는 참조 유형)인 경우 필수이거나 null을 허용할 수 있습니다.
목록, 세트 및 역링크의 매개 변수가 Realm 객체인 경우 해당 매개 변수는 null을 허용할 수 없습니다.
Realm 객체의 값 타입을 가진 사전의 경우 값 타입 매개 변수를 반드시 null 허용으로 선언 해야 합니다.
다음 코드 스니펫은 이러한 규칙을 보여줍니다.
public partial class Person : IRealmObject { /* Reference Types */ public string NonNullableName { get; set; } public string? NullableName { get; set; } public byte[] NonNullableArray { get; set; } public byte[]? NullableArray { get; set; } /* Value Types */ public int NonNullableInt { get; set; } public int? NullableInt { get; set; } /* Realm Objects */ public Dog? NullableDog { get; set; } // public Dog NonNullableDog { get; set; } // Compile-time error /* Collections of Primitives */ public IList<int> IntListWithNonNullableValues { get; } public IList<int?> IntListWithNullableValues { get; } // public IList<int>? NullableListOfInts { get; } // Compile-time error /* Collections of Realm Objects */ public IList<Dog> ListOfNonNullableObjects { get; } // public IList<Dog>? NullableListOfObjects { get; } // Compile-time error // public IList<Dog?> ListOfNullableObjects { get; } // Compile-time error public ISet<Dog> SetOfNonNullableObjects { get; } // public ISet<Dog>? NullableSetOfObjects { get; } // Compile-time error // public ISet<Dog?> SetOfNullableObjects { get; } // Compile-time error public IDictionary<string, Dog?> DictionaryOfNullableObjects { get; } // public IDictionary<string, Dog> DictionaryOfNonNullableObjects { get; } // Compile-time error // public IDictionary<string, Dog>? NullableDictionaryOfObjects { get; } // Compile-time error [] public IQueryable<Dog> MyDogs { get; } // [Backlink(nameof(Dog.People))] // public IQueryable<Dog?> MyDogs { get; } // Compile-time error }
참고
이전 스키마 유형 정의(클래스가 RealmObject 기본 클래스에서 파생됨)를 사용하거나 null 허용 여부를 활성화하지 않은 경우, 필수 string 및 byte[] 에 대해 [필수] 속성을 사용해야 합니다. 속성.
null 허용 여부 무시
Realm 객체에서 속성의 null 허용 여부를 더 유연하게 정의하는 것이 좋습니다. realm.ignore_objects_nullability = true 전역 구성 파일 에서 를 설정하면 됩니다.
realm.ignore_objects_nullability를 활성화하면 Realm 객체 컬렉션을 포함한 Realm 객체 속성에서 null 허용 여부 주석이 무시됩니다.