엔터티 속성

아티클
01/15/2025

모델의 각 엔터티 형식에는 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인 소수로 설정합니다.

데이터 주석
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을 구성하면 SQL Server에서 nvarchar(500) 형식의 열이 만들어집니다.

데이터 주석
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);
}

정밀도 및 배율

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

메모

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

다음 예제에서 Score 속성을 정밀도 14 및 소수점 이하 자리수 2로 구성하면 SQL 서버에 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)입니다.

유니코드

일부 관계형 데이터베이스에서는 유니코드 및 비유니코드 텍스트 데이터를 나타내는 다양한 형식이 존재합니다. 예를 들어 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등)이 있는 모든 속성은 필요에 따라 구성되며 nullable .NET 값 형식(int?, decimal?, bool?등)이 있는 모든 속성은 선택 사항으로 구성됩니다.

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

nullable 참조 형식을 사용하지 않도록 설정하면 .NET 참조 형식이 있는 모든 속성이 규칙에 따라 선택적으로 구성됩니다(예: string).
nullable 참조 형식이 활성화된 경우, 속성은 .NET 형식의 C# null 허용성에 따라 구성됩니다: string?는 선택 사항으로, string은 필수로 구성됩니다.

nullable 참조 기능이 꺼져 있거나 켜져 있을 때의 필수 및 선택 속성을 가진 엔터티 유형을 다음 예제에서 보여줍니다.

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;
    }
}

nullable 참조 형식을 사용하는 것이 좋습니다. 이는 C# 코드에서 표현한 null 허용 여부를 EF Core의 모델과 데이터베이스에 반영하며, Fluent API나 데이터 주석으로 동일한 개념을 중복해서 표현할 필요를 없애주기 때문입니다.

메모

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

nullable 참조 형식 및 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는 기본적으로 기본 키 열을 먼저 정렬한 다음 엔터티 형식과 소유된 형식의 속성을 정렬하며, 마지막으로 기본 형식의 속성을 정렬합니다. 그러나 다른 열 순서를 지정할 수 있습니다.

데이터 주석
유창한 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);
    });
}

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

다음을 통해 공유