EF Core 11(EF11)의 주요 변경 사항

이 페이지에서는 EF Core 10에서 EF Core 11로 업데이트되는 기존 애플리케이션을 중단시킬 가능성이 있는 API 및 동작 변경 내용을 설명합니다. 이전 버전의 EF Core에서 업데이트하는 경우 과거의 주요 변경 사항을 반드시 검토하십시오.

• EF Core 10의 주요 변경 내용
• EF Core 9의 주요 변경 내용
• EF Core 8 중요한 변경 사항

요약

중간 영향을 주는 변경 내용

Azure Cosmos DB 공급자를 통한 동기화 I/O가 완전히 제거되었습니다.

추적 문제 #37059

기존 동작

Azure Cosmos DB 공급자를 통한 동기 I/O는 EF 9.0(note) 이후 지원되지 않습니다. 특별한 옵트인 구성을 하지 않는 경우 ToList 또는 SaveChanges와 같은 동기화 I/O API를 호출하면 예외가 발생합니다. 옵트인이 구성되었을 때, 동기화 I/O API는 이전과 동일하게 작동하여 공급자가 Azure Cosmos DB SDK에 대해 "sync-over-async" 동기 블로킹을 수행하게 되어 교착 상태 및 기타 성능 문제가 발생할 수 있습니다.

새 동작

EF Core 11.0부터는 동기 I/O API가 호출될 때마다 EF는 항상 예외를 발생시킵니다. 동기화 I/O API를 사용하여 다시 옵트인할 수 있는 방법은 없습니다.

왜

비동기 메서드("sync-over-async")에 대한 동기 차단은 매우 권장되지 않으며 교착 상태 및 기타 성능 문제가 발생할 수 있습니다. Azure Cosmos DB SDK는 비동기 메서드만 지원하기 때문에, EF Cosmos 공급자도 비동기 메서드만 지원합니다.

완화

동기화 I/O API 대신 비동기 I/O API를 사용하도록 코드를 변환합니다. 호출을 SaveChanges()에서 await SaveChangesAsync()로 대체하십시오.

Microsoft. Data.SqlClient가 7.0으로 업데이트되었습니다.

기존 동작

EF Core 10은 Microsoft.Data.SqlClient 6.x를 사용했으며, 이는 핵심 패키지에 Azure/Entra ID 인증 종속성(예: Azure.Core, Azure.Identity, 및 Microsoft.Identity.Client)을 포함했습니다.

새 동작

이제 EF Core 11은 Microsoft.Data.SqlClient 7.0에 의존합니다. 이 버전은 핵심 패키지에서 Azure/Entra ID(이전의 Azure Active Directory) 인증 종속성을 제거합니다. 애플리케이션에서 Entra ID 인증(예: ActiveDirectoryDefault, ActiveDirectoryInteractive, ActiveDirectoryManagedIdentity 또는 ActiveDirectoryServicePrincipal)을 사용하는 경우 이제 Microsoft.Data.SqlClient.Extensions.Azure 패키지를 별도로 설치해야 합니다.

또한 SqlAuthenticationMethod.ActiveDirectoryPassword 사용되지 않는 것으로 표시되었습니다.

자세한 내용은 Microsoft.Data.SqlClient 7.0 릴리스 정보를 참조하세요.

왜

이 변경 내용은 Microsoft. Data.SqlClient 컨테이너화된 배포 및 로컬 개발에 특히 유용한 Azure 인증을 사용하지 않는 애플리케이션에 대한 종속성 블로트를 줄입니다.

완화

애플리케이션이 SQL Server Entra ID 인증을 사용하는 경우 프로젝트의 Microsoft.Data.SqlClient.Extensions.Azure 패키지에 대한 참조를 추가합니다.

<PackageReference Include="Microsoft.Data.SqlClient.Extensions.Azure" Version="7.0.0" />

이 패키지 참조를 추가하는 것 외에는 코드 변경이 필요하지 않습니다. SqlAuthenticationMethod.ActiveDirectoryPassword를 사용하는 경우, ActiveDirectoryDefault 또는 ActiveDirectoryInteractive 같은 최신 인증 방법으로 마이그레이션하십시오.

낮은 영향을 주는 변경 내용

이제 마이그레이션을 찾을 수 없는 경우 EF Core가 기본적으로 예외를 발생시킵니다.

추적 문제 #35218

기존 동작

이전에는 어셈블리에서 마이그레이션이 없는 데이터베이스를 호출하거나 Migrate 호출 MigrateAsync 할 때 EF Core는 정보 메시지를 기록하고 변경 내용을 적용하지 않고 반환했습니다.

새 동작

EF Core 11.0부터 EF Core는 어셈블리에서 마이그레이션을 찾을 수 없는 경우 기본적으로 예외를 throw합니다. 이는 PendingModelChangesWarning 동작과 일치합니다.

왜

호출 Migrate() 또는 MigrateAsync() 마이그레이션이 없는 경우 일반적으로 잘못된 구성을 나타냅니다. 데이터베이스를 자동으로 계속 진행하여 잘못된 상태로 두는 대신, 이제 EF Core는 개발자에게 이 문제를 즉시 알릴 수 있습니다.

완화

의도적으로 Migrate()을(를) 마이그레이션 없이 호출하는 경우(예: 다른 방법으로 데이터베이스 스키마를 관리하기 때문에), 경고를 구성하거나 예외를 억제하고, 호출을 Migrate() 제거합니다.

options.ConfigureWarnings(w => w.Ignore(RelationalEventId.MigrationsNotFound))

또는 이벤트를 던지기 대신 기록하려면 다음을 수행합니다.

options.ConfigureWarnings(w => w.Log(RelationalEventId.MigrationsNotFound))

EFOptimizeContext MSBuild 속성이 제거되었습니다.

추적 문제 #35079

기존 동작

이전에는 EFOptimizeContext MSBuild 속성을 true으로 설정하여 빌드 또는 게시 중에 컴파일된 모델 및 미리 컴파일된 쿼리 코드 생성을 활성화할 수 있었습니다.

<EFOptimizeContext Condition="'$(Configuration)'=='Release'">true</EFOptimizeContext>

새 동작

EF Core 11.0 EFOptimizeContext 부터 MSBuild 속성이 제거되었습니다. 이제 코드 생성은 EFScaffoldModelStage 및 EFPrecompileQueriesStage 속성을 통해서만 제어됩니다. PublishAOT이(가) true으로 설정되면, 추가적인 속성 없이 게시 시 코드 생성이 자동으로 활성화됩니다.

왜

EFScaffoldModelStage 및 EFPrecompileQueriesStage 속성은 코드 생성이 발생하는 시기를 세밀하게 제어할 수 있습니다. EFOptimizeContext 는 중복된 활성화 게이트였습니다.

완화

EFOptimizeContext의 사용을 EFScaffoldModelStage 속성 및 EFPrecompileQueriesStage 속성으로 대체합니다. 코드 생성의 단계 제어를 위해 publish 또는 build로 설정할 수 있습니다.

<EFScaffoldModelStage>publish</EFScaffoldModelStage>
<EFPrecompileQueriesStage>publish</EFPrecompileQueriesStage>

다른 값(예: none)은 해당 생성을 사용하지 않도록 설정합니다.

PublishAOT를 true로 설정하면, 코드 생성은 게시할 때 자동으로 활성화되어 추가 구성이 필요하지 않습니다.

EF 도구 패키지는 더 이상 Microsoft.EntityFrameworkCore.Design 참조하지 않습니다.

추적 문제 #37739

기존 동작

이전에는 Microsoft.EntityFrameworkCore.Tools 및 Microsoft.EntityFrameworkCore.Tasks NuGet 패키지에 Microsoft.EntityFrameworkCore.Design 종속성이 있었습니다.

새 동작

EF Core 11.0부터 Microsoft.EntityFrameworkCore.Tools 및 Microsoft.EntityFrameworkCore.Tasks NuGet 패키지는 더 이상 Microsoft.EntityFrameworkCore.Design 종속성이 없습니다.

왜

Microsoft.EntityFrameworkCore.Design 코드에 대한 하드 종속성이 없었으며, 이 종속성으로 인해 이전 프레임워크를 대상으로 하는 프로젝트에서 최신 Microsoft.EntityFrameworkCore.Tools 사용할 때 문제가 발생했습니다.

완화

프로젝트가 도구 패키지를 통해 전이적으로 Microsoft.EntityFrameworkCore.Design를 가져오는 경우, 프로젝트에 직접 참조를 추가하세요.

<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="11.0.0" PrivateAssets="all" />

SqlVector 속성은 기본적으로 더 이상 로드되지 않습니다.

추적 문제 #37279

기존 동작

이전에는 SqlVector<T> 속성을 가진 엔터티를 쿼리할 때, EF Core가 SELECT 문에 벡터 열을 포함하고 반환된 엔터티의 속성을 채웠습니다.

새 동작

EF Core 11.0부터는 엔터티를 구체화할 때, SqlVector<T> 속성이 더 이상 SELECT 문에 포함되지 않습니다. 반환된 엔터티의 속성은 null 상태입니다.

벡터 속성은 VectorDistance()VectorSearch() 절을 포함한 WHEREORDER BY 절에서 여전히 사용할 수 있지만, 엔터티 프로젝션에는 포함되지 않습니다.

왜

벡터 열은 수백 또는 수천 개의 부동 소수점 값을 포함하는 매우 클 수 있습니다. 대부분의 경우 벡터는 데이터베이스에 기록된 다음 다시 읽을 필요 없이 검색에 사용됩니다. 기본적으로 제외하면 SELECT 불필요한 데이터 전송이 방지됩니다.

완화

벡터 값을 다시 읽어야 하는 경우 명시적 프로젝션을 사용합니다.

var embeddings = await context.Blogs
    .Select(b => new { b.Id, b.Embedding })
    .ToListAsync();

Cosmos: 비어 있는 소유 컬렉션은 이제 null 대신 빈 컬렉션을 반환합니다.

추적 문제 #36577

기존 동작

이전에 소유된 컬렉션에 항목이 없는 경우 Azure Cosmos DB 공급자를 통해 엔터티를 쿼리하면, 구체화된 엔터티에서 컬렉션 속성이 null로 나타났습니다.

새 동작

EF Core 11.0부터 Azure Cosmos DB 공급자는 빈 소유 컬렉션을 올바르게 초기화하고 null 대신 빈 컬렉션을 반환합니다.

왜

비어 있는 소유 컬렉션을 null로 구체화했던 이전 동작은 버그였습니다.

완화

코드에서 소유된 컬렉션 속성을 null 명시적으로 검사하여 컬렉션이 비어 있음을 감지하는 경우 이제 컬렉션이 항상 초기화되므로 해당 검사를 간단히 제거할 수 있습니다.

// Before
if (entity.OwnedCollection is null or { Count: 0 })
{
    // treated as empty
}

// After
if (entity.OwnedCollection is { Count: 0 })
{
    // treated as empty
}

Microsoft.Data.Sqlite 호환성을 깨뜨리는 변경 사항

요약

중간 영향을 주는 변경 내용

암호화 사용 SQLite 패키지가 제거되었습니다.

추적 문제 #5108

기존 동작

이전에는 NuGet 패키지에서 SQLitePCLRaw.bundle_e_sqlcipher 암호화 사용 SQLite 빌드를 비용 없이 제공했습니다.

새 동작

SQLitePCLRaw 3.0(는 Microsoft.Data.Sqlite 11.0에서 사용됨)부터 SQLitePCLRaw.bundle_e_sqlcipher 패키지가 지원 종료되어 NuGet에서 제거되었습니다. 비용 없는 암호화 사용 SQLite 빌드는 더 이상 배포되지 않습니다.

왜

이전의 무비용 SQLitePCLRaw.bundle_e_sqlcipher 패키지는 거의 유지 관리되지 않았으며, 이는 보안 취약성이 패치되지 않을 수 있는 암호화 소프트웨어에 대한 중요한 관심사입니다. SQLitePCLRaw 유지 관리는 지속적인 보안 업데이트를 제공하는 전문적으로 유지 관리되는 유료 대안을 위해 버전 3.0에서 이러한 빌드를 제거했습니다.

완화

SQLite 암호화가 필요한 경우 다음과 같은 옵션이 있습니다.

• SQLite 암호화 확장(SEE): SQLite 팀의 공식 암호화 구현입니다. 유료 라이선스가 필요합니다. 자세한 내용은 https://sqlite.org/com/see.html를 참조하세요. NuGet 패키지는 SourceGear의 SQLite 빌드 서비스를 통해 사용할 수 있습니다.
• SQLCipher: Zetetic에서 지원되는 빌드를 구입하거나 오픈 소스 코드 빌드합니다.
• SQLite3 여러 암호: NuGet 패키지는 SQLite3MultipleCiphers-NuGet에서 사용할 수 있습니다.
  • 새 데이터베이스를 암호화하거나 SQLCipher로 암호화된 기존 데이터베이스를 여는 경우 URI 매개 변수(예: Data Source=file:example.db?cipher=sqlcipher&legacy=4;Password=<password>)를 사용하여 연결 문자열 암호화 체계를 구성해야 합니다. 자세한 내용은 SQLCipher로 암호화된 기존 데이터베이스를 여는 방법을 참조하세요.

자세한 내용은 SQLitePCLRaw 및 SQLitePCLRaw3.0 릴리스 정보에서 사용할 SQLite 암호화 옵션을 참조하세요.

일부 SQLitePCLRaw 번들 패키지가 제거되었습니다.

추적 문제 #5108

기존 동작

SQLitePCLRaw.bundle_sqlite3이전에는 , SQLitePCLRaw.bundle_winsqlite3, SQLitePCLRaw.bundle_green및 SQLitePCLRaw.bundle_e_sqlite3mc 패키지가 해당 SQLite 공급자를 사용하여 SQLitePCLRaw를 구성하는 편리한 방법을 제공했습니다.

새 동작

SQLitePCLRaw 3.0부터 (Microsoft.Data.Sqlite 11.0 사용), 이러한 번들 패키지가 제거되었습니다. 애플리케이션이 이러한 번들 중 하나에 의존하는 경우 이제 해당 공급자 패키지를 참조하고 명시적으로 초기화해야 합니다.

왜

이러한 각 번들 패키지에는 한 줄의 구성 코드만 포함되었으며 불필요한 패키징 오버헤드가 추가되었습니다. 해당 공급자 패키지는 계속 지원됩니다.

완화

제거된 번들 패키지를 해당 공급자 패키지로 바꾸고 명시적 초기화 코드를 추가합니다.

bundle_sqlite3 또는 bundle_winsqlite3을 사용하는 경우, 패키지 참조를 바꾸십시오:

<!-- Old -->
<PackageReference Include="SQLitePCLRaw.bundle_sqlite3" Version="2.x.x" />
<!-- or -->
<PackageReference Include="SQLitePCLRaw.bundle_winsqlite3" Version="2.x.x" />

<!-- New -->
<PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="3.x.x" />
<!-- or -->
<PackageReference Include="SQLitePCLRaw.provider.winsqlite3" Version="3.x.x" />

그런 다음, SQLite를 사용하기 전에 명시적 초기화를 추가합니다.

// For sqlite3
static void Init()
{
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
}

// For winsqlite3
static void Init()
{
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_winsqlite3());
}

을(를) 사용하는 경우, 권장되는 마이그레이션 경로는 로 전환하는 것입니다. 또는 SQLitePCLRaw.config.e_sqlite3와 별도의 네이티브 라이브러리 패키지인 SourceGear.sqlite3를 함께 사용하여 SQLite 버전을 독립적으로 업데이트할 수 있습니다.

<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="3.x.x" />

iOS만 대상으로 하고 시스템 SQLite 라이브러리를 계속 사용하려는 경우 공급자를 직접 참조합니다.

<PackageReference Include="SQLitePCLRaw.core" Version="3.x.x" />
<PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="3.x.x" />

그리고 명시적으로 초기화합니다.

static void Init()
{
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
}