엔터티 속성

아티클
10/05/2023

모델의 각 엔터티 형식에는 EF Core가 데이터베이스에서 읽고 쓰는 속성 집합이 있습니다. 관계형 데이터베이스를 사용하는 경우 엔터티 속성은 테이블 열에 매핑됩니다.

포함 및 제외된 속성

규칙에 따라 getter 및 setter가 있는 모든 공용 속성이 모델에 포함됩니다.

특정 속성은 다음과 같이 제외할 수 있습니다.

데이터 주석
Fluent API

public class Blog
{
    public int BlogId { get; set; }
    public string Url { get; set; }

    [NotMapped]
    public DateTime LoadedFromDatabase { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Ignore(b => b.LoadedFromDatabase);
}

열 이름

규칙에 따라 관계형 데이터베이스를 사용하는 경우 엔터티 속성은 속성과 이름이 같은 테이블 열에 매핑됩니다.

다른 이름으로 열을 구성하려는 경우 다음 코드 조각으로 구성할 수 있습니다.

데이터 주석
Fluent API

public class Blog
{
    [Column("blog_id")]
    public int BlogId { get; set; }

    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.BlogId)
        .HasColumnName("blog_id");
}

열 데이터 형식

관계형 데이터베이스를 사용하는 경우 데이터베이스 공급자는 속성의 .NET 형식을 기반으로 데이터 형식을 선택합니다. 또한 구성된 최대 길이, 속성이 기본 키의 일부인지 여부 등과 같은 다른 메타데이터도 고려합니다.

예를 들어 SQL Server는 DateTime 속성을 datetime2(7) 열에 매핑하고 string 속성을 nvarchar(max) 열에(또는 키로 사용되는 속성의 경우 nvarchar(450)에) 매핑합니다.

열에 대한 정확한 데이터 형식을 지정하도록 열을 구성할 수도 있습니다. 예를 들어 다음 코드는 Url을 최대 길이가 200인 유니코드가 아닌 문자열로 구성하고 Rating을 5의 전체 자릿수 및 2의 배율을 가진 10진수로 구성합니다.

데이터 주석
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [Column(TypeName = "varchar(200)")]
    public string Url { get; set; }

    [Column(TypeName = "decimal(5, 2)")]
    public decimal Rating { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>(
        eb =>
        {
            eb.Property(b => b.Url).HasColumnType("varchar(200)");
            eb.Property(b => b.Rating).HasColumnType("decimal(5, 2)");
        });
}

최대 길이

최대 길이를 구성하면 데이터베이스 공급자에게 지정된 속성에 대해 선택할 적절한 열 데이터 형식에 대한 힌트를 제공합니다. 최대 길이는 string 및 byte[]와 같은 배열 데이터 형식에만 적용됩니다.

참고 항목

Entity Framework는 공급자에게 데이터를 전달하기 전에 최대 길이의 유효성 검사를 수행하지 않습니다. 적절한 경우 유효성을 검사하는 것은 공급자 또는 데이터 저장소의 입니다. 예를 들어 SQL Server 대상으로 지정할 때 최대 길이를 초과하면 기본 열의 데이터 형식이 초과 데이터를 저장할 수 없으므로 예외가 발생합니다.

다음 예제에서 최대 길이를 500으로 구성하면 형식 nvarchar(500)의 열이 SQL Server에 생성됩니다.

데이터 주석
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [MaxLength(500)]
    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .HasMaxLength(500);
}

정밀도 및 규모

일부 관계형 데이터 형식은 정밀도 및 배율 패싯을 지원합니다. 이러한 값은 저장할 수 있는 값과 열에 필요한 스토리지 양을 제어합니다. 전체 자릿수 및 크기 조정을 지원하는 데이터 형식은 데이터베이스에 따라 다르지만 대부분의 데이터베이스 decimal 및 DateTime 형식에서는 이러한 패싯을 지원합니다. decimal 속성의 경우 전체 자릿수는 열에 포함될 값을 표현하는 데 필요한 최대 자릿수를 정의하고 소수 자릿수는 필요한 최대 소수 자릿수를 정의합니다. DateTime 속성의 경우 전체 자릿수는 초의 분수를 표현하는 데 필요한 최대 자릿수를 정의하며 소수 자릿수는 사용되지 않습니다.

참고 항목

Entity Framework는 데이터를 공급자에게 전달하기 전에 정밀도 또는 배율의 유효성을 검사하지 않습니다. 적절한 유효성을 검사하는 것은 공급자 또는 데이터 저장소에 달려 있습니다. 예를 들어 SQL Server 대상으로 지정할 때 데이터 형식 datetime의 열은 전체 자릿수를 설정할 수 없는 반면, datetime2의 전체 자릿수는 0에서 7 사이일 수 있습니다.

다음 예제에서는 전체 자릿수가 14이고 소수 자릿수 2인 Score 속성을 구성하면 SQL Server에서 decimal(14,2) 형식의 열이 생성되고 LastUpdated 속성을 전체 자릿수 3으로 구성하면 datetime2(3) 형식 열이 생성됩니다.

데이터 주석
Fluent API

public class Blog
{
    public int BlogId { get; set; }
    [Precision(14, 2)]
    public decimal Score { get; set; }
    [Precision(3)]
    public DateTime LastUpdated { get; set; }
}

소수 자릿수는 먼저 정밀도를 정의하지 않고 정의되지 않으므로 소수 자릿수를 정의하기 위한 데이터 주석은 [Precision(precision, scale)]입니다.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Score)
        .HasPrecision(14, 2);

    modelBuilder.Entity<Blog>()
        .Property(b => b.LastUpdated)
        .HasPrecision(3);
}

소수 자릿수는 먼저 정밀도를 정의하지 않고 정의되지 않으므로 소수 자릿수를 정의하기 위한 Fluent API는 HasPrecision(precision, scale)입니다.

Unicode

일부 관계형 데이터베이스에서는 유니코드 및 유니코드가 아닌 텍스트 데이터를 나타내는 다양한 형식이 있습니다. 예를 들어 SQL Server에서 nvarchar(x)는 UTF-16의 유니코드 데이터를 나타내는 데 사용되고 varchar(x)는 유니코드가 아닌 데이터를 나타내는 데 사용됩니다(하지만 SQL Server UTF-8 지원의 참고 사항 참조). 이 개념을 지원하지 않는 데이터베이스의 경우 이 개념을 구성해도 아무런 효과가 없습니다.

텍스트 속성은 기본적으로 유니코드로 구성됩니다. 다음과 같이 열을 유니코드가 아닌 열로 구성할 수 있습니다.

데이터 주석
Fluent API

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }

    [Unicode(false)]
    [MaxLength(22)]
    public string Isbn { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Book>()
        .Property(b => b.Isbn)
        .IsUnicode(false);
}

필수 및 선택 속성

null을 포함하는 것이 유효한 경우 속성은 선택 사항으로 간주됩니다. null이 속성에 할당할 유효한 값이 아닌 경우 필수 속성으로 간주됩니다. 관계형 데이터베이스 스키마에 매핑할 때 필수 속성은 null 허용이 아닌 열로 만들어지고 선택적 속성은 null 허용 열로 만들어집니다.

규칙

규칙에 따라 .NET 형식에 null을 포함할 수 있는 속성은 선택 사항으로 구성되는 반면 .NET 형식에 null을 포함할 수 없는 속성은 필요에 따라 구성됩니다. 예를 들어 .NET 값 형식(int, decimal, bool 등)이 있는 모든 속성은 필요에 따라 구성되고 null 허용 .NET 값 형식(int?, decimal?, bool? 등)이 있는 모든 속성은 선택 사항으로 구성됩니다.

C# 8에서는 NRT(null 허용 참조 형식)라는 새로운 기능을 도입하여 참조 형식에 주석을 추가할 수 있도록 하여 null을 포함하는 것이 유효한지 여부를 나타냅니다. 이 기능은 새 프로젝트 템플릿에서 기본적으로 사용하도록 설정되지만 명시적으로 옵트인하지 않는 한 기존 프로젝트에서는 사용하지 않도록 유지됩니다. null 허용 참조 형식은 다음과 같은 방식으로 EF Core의 동작에 영향을 미칩니다.

null 허용 참조 형식을 사용하지 않도록 설정하면 .NET 참조 형식이 있는 모든 속성은 규칙에 따라 선택 사항으로 구성됩니다(예: string).
null 허용 참조 형식을 사용하도록 설정하면 속성은 .NET 형식의 C# null 허용 여부를 기반으로 구성됩니다. string?는 선택 사항으로 구성되지만 string은 필요에 따라 구성됩니다.

다음 예제에서는 null 허용 참조 기능을 사용하지 않도록 설정하고 사용하도록 설정한 필수 및 선택적 속성이 있는 엔터티 형식을 보여 줍니다.

NRT 없음(기본값)
NRT 있음

public class CustomerWithoutNullableReferenceTypes
{
    public int Id { get; set; }

    [Required] // Data annotations needed to configure as required
    public string FirstName { get; set; }

    [Required] // Data annotations needed to configure as required
    public string LastName { get; set; }

    public string MiddleName { get; set; } // Optional by convention
}

public class Customer
{
    public int Id { get; set; }
    public string FirstName { get; set; } // Required by convention
    public string LastName { get; set; } // Required by convention
    public string? MiddleName { get; set; } // Optional by convention

    // Note the following use of constructor binding, which avoids compiled warnings
    // for uninitialized non-nullable properties.
    public Customer(string firstName, string lastName, string? middleName = null)
    {
        FirstName = firstName;
        LastName = lastName;
        MiddleName = middleName;
    }
}

C# 코드로 표현된 null 허용 여부를 EF Core의 모델과 데이터베이스로 전달하고 Fluent API 또는 데이터 주석을 사용하여 동일한 개념을 두 번 표현하지 않도록 하기 때문에 null 허용 참조 형식을 사용하는 것이 좋습니다.

참고 항목

기존 프로젝트에서 null 허용 참조 형식을 사용하도록 설정할 때 주의해야 합니다. 이전에 선택 사항으로 구성되었던 참조 형식 속성은 이제 null 허용으로 명시적으로 주석을 추가하지 않는 한 필요에 따라 구성됩니다. 관계형 데이터베이스 스키마를 관리할 때 마이그레이션이 생성되어 데이터베이스 열의 Null 허용 여부를 변경할 수 있습니다.

null 허용 참조 형식 및 EF Core와 함께 사용하는 방법에 대한 자세한 내용은 이 기능에 대한 전용 설명서 페이지를 참조하세요.

명시적 구성

규칙에 따라 선택 사항인 속성은 다음과 같이 요구되도록 구성할 수 있습니다.

데이터 주석
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [Required]
    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .IsRequired();
}

열 데이터 정렬

데이터 정렬은 텍스트 열에 정의되어 비교 및 정렬 방법을 결정할 수 있습니다. 예를 들어 다음 코드 조각은 대/소문자를 구분하지 않는 SQL Server 열을 구성합니다.

modelBuilder.Entity<Customer>().Property(c => c.Name)
    .UseCollation("SQL_Latin1_General_CP1_CI_AS");

데이터베이스의 모든 열이 특정 데이터 정렬을 사용해야 하는 경우 대신 데이터베이스 수준에서 데이터 정렬을 정의합니다.

데이터 정렬에 대한 EF Core 지원에 대한 일반적인 정보는 데이터 정렬 설명서 페이지에서 찾을 수 있습니다.

열 주석

데이터베이스 열에 설정된 임의의 텍스트 주석을 설정하여 데이터베이스에서 스키마를 문서화할 수 있습니다.

데이터 주석
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [Comment("The URL of the blog")]
    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .HasComment("The URL of the blog");
}

열 순서

기본적으로 마이그레이션을 사용하여 테이블을 만들 때 EF Core는 기본 키 열을 먼저 정렬하고 그 다음에 엔터티 형식과 소유된 형식의 속성을 정렬하고 마지막으로 기본 형식의 속성을 정렬합니다. 그러나 다른 열 순서를 지정할 수 있습니다.

데이터 주석
Fluent API

public class EntityBase
{
    [Column(Order = 0)]
    public int Id { get; set; }
}

public class PersonBase : EntityBase
{
    [Column(Order = 1)]
    public string FirstName { get; set; }

    [Column(Order = 2)]
    public string LastName { get; set; }
}

public class Employee : PersonBase
{
    public string Department { get; set; }
    public decimal AnnualSalary { get; set; }
}

서로 다른 속성의 특성이 동일한 순서 번호를 지정하는 경우 충돌을 해결하는 것을 포함하여 특성으로 지정된 순서를 재정의하는 데 Fluent API를 사용할 수 있습니다.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Employee>(x =>
    {
        x.Property(b => b.Id)
            .HasColumnOrder(0);

        x.Property(b => b.FirstName)
            .HasColumnOrder(1);

        x.Property(b => b.LastName)
            .HasColumnOrder(2);
    });
}

일반적으로 대부분의 데이터베이스는 테이블을 만들 때 열 순서만 지원합니다. 즉 기존 테이블의 열 순서를 변경하는 데 열 순서 특성을 사용할 수 없습니다.

엔터티 속성

포함 및 제외된 속성

열 이름

열 데이터 형식

최대 길이

정밀도 및 규모

Unicode

필수 및 선택 속성

규칙

명시적 구성

열 데이터 정렬

열 주석

열 순서

피드백

추가 리소스