EF Core Migrations Pitfall — Resolving Version Mismatch Between Tools and Runtime in Fluent API Projects

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

DevOps

대상자

.NET 개발자, 특히 EF Core Fluent API와 Migrations를 사용하는 중급~고급 개발자

핵심 요약

• EF Core의 Microsoft.EntityFrameworkCore.Design 패키지와 런타임 패키지(예: Microsoft.EntityFrameworkCore.SqlServer)의 버전 불일치는 System.MissingMethodException과 같은 런타임 오류를 유발
• 버전 일치 해결책:

- dotnet add package Microsoft.EntityFrameworkCore.Design --version 10.0.0-preview.4.25258.110로 tooling 패키지 업데이트

- 또는 9.0.5로 런타임 패키지 다운그레이드

• Fluent API 기반 Migrations는 AddMigration, UpdateDatabase, Scaffold-DbContext 작업에 버전 불일치가 직접적으로 영향을 줌

섹션별 세부 요약

1. 문제 발생 배경

• EF Core 10.0.0-preview.4 런타임 패키지 사용 시 Microsoft.EntityFrameworkCore.Design 9.0.5 툴 패키지와의 이진 호환성 문제 발생
• Internal API 변경으로 인한 IProperty IEntityType.FindDiscriminatorProperty() 메서드 누락 오류
• Preview 버전과 Stable 버전 혼합 사용 시 예상치 못한 버그 발생 가능성

2. 해결 옵션

• Option 1: Microsoft.EntityFrameworkCore.Design 패키지를 10.0.0-preview.4.25258.110으로 업데이트
• Option 2: 런타임 패키지를 9.0.5로 다운그레이드 (안정성 확보)
• Fluent API 설정 시 dotnet ef 툴의 버전 확인 필수 (명령어: dotnet ef --version)

3. Fluent API 영향 분석

• builder.Entity(...)와 같은 Fluent API 설정은 버전 불일치 시 .AddMigration(), .UpdateDatabase() 작업에 장애
• 역공학(Reverse Engineering) 작업(Scaffold-DbContext)도 실패
• Job 엔티티의 Ignore(j => j.Resume) 설정 등 구체적인 Fluent API 사용 시 버전 호환성 검증 필수

4. 최선 실천 가이드

• tool/runtime 패키지 버전 일치 (예: SqlServer 10.0.0-preview.4.25258.110)
• Stable + Preview 버전 혼합 금지 (예: 9.0.5와 10.0.0-preview.4 동시 사용)
• Migrations 프로젝트 분리하여 Preview 위험 분리
• 도구 체인 문서화 (팀 업그레이드 및 CI/CD 지원)

결론

• EF Core Migrations 사용 시 Microsoft.EntityFrameworkCore.Design과 런타임 패키지의 버전 일치를 항상 확인해야 한다
• dotnet ef --version 명령어로 툴 버전 검증 후 작업
• Preview 기능 사용 시는 별도의 Migrations 프로젝트를 분리해 안정성 확보
• 버전 불일치로 인한 오류는 .AddMigration() 및 Scaffold-DbContext 작업에 직접적인 영향을 줌