EF Core 10 Yenilikleri ve Kırıcı Değişiklikler: Yükseltme Rehberi

Sürüm durumu ve yükseltme önerileri

Belgelerdeki sürüm tablosu şu anki durumu şöyle gösterir:

EF Core 8 ve 9'un destek bitiş tarihi yakın olduğu için bu sürümlerdeki projelerin EF Core 10'a geçişini planlamak önemlidir. Belgelerin yükseltme önerileri şunlardır: desteklenen sürümler güvenlik ve diğer kritik hatalar için yamalanır, bu yüzden bir sürümün her zaman en son yamasını kullanın; EF Core 10.0 için mevcut en yüksek 10.0.x sürümü. Ana sürüm yükseltmeleri, örneğin 9'dan 10'a geçiş, çoğu zaman kırıcı değişiklik içerir ve kapsamlı test önerilir. Küçük sürüm yükseltmeleri genellikle kırıcı değişiklik içermez, ancak yeni özellikler gerilemelere yol açabileceğinden yine test gerekir. Belgeler ayrıca EF Core sürümlerinin ve desteğinin .NET sürümleriyle hizalandığını belirtir.

Yükseltmeden önce bir test stratejiniz olması bu nedenle kritiktir; EF Core test yazma yazısı bu konuda yardımcı olur. Paketlerin ve araçların sürüm uyumu için EF Core kurulumu yazısına bakın.

Azure SQL ve SQL Server yenilikleri

Vector search

EF 10, Azure SQL Database ve SQL Server 2025'te bulunan vector veri türünü ve VECTOR_DISTANCE() fonksiyonunu tam olarak destekler. Vector türü, anlamsal arama ve RAG gibi yapay zekâ iş yüklerinde benzerlik araması yapılan embedding'leri saklamak için kullanılır. Varlığınıza SqlVector<float> türünde bir özellik eklersiniz ve LINQ sorgularında EF.Functions.VectorDistance ile benzerlik sıralaması yaparsınız:

public class Blog
{
    // ...

    [Column(TypeName = "vector(1536)")]
    public SqlVector<float> Embedding { get; set; }
}

var topSimilarBlogs = context.Blogs
    .OrderBy(b => EF.Functions.VectorDistance("cosine", b.Embedding, sqlVector))
    .Take(3)
    .ToListAsync();

json veri türü varsayılan oluyor

EF 10, yine Azure SQL Database ve SQL Server 2025'te gelen yeni json veri türünü destekler. SQL Server uzun süredir JSON işlevlerine sahipti, ancak veri düz metin kolonlarında saklanıyordu; yeni tür önemli verimlilik iyileştirmeleri ve JSON ile daha güvenli çalışma sağlar. EF'yi UseAzureSql ile veya 170 ya da daha yüksek bir uyumluluk düzeyiyle (SQL Server 2025) yapılandırdıysanız EF primitive koleksiyonlar ve JSON'a eşlenen türler için otomatik olarak bu yeni türü kullanır. Belgelerin örnek çıktısında bir dizi özelliği ve JSON'a eşlenmiş bir complex type için oluşturulan tablo şöyledir:

CREATE TABLE [Blogs] (
    [Id] int NOT NULL IDENTITY,
    [Name] nvarchar(max) NOT NULL,
    [Tags] json NOT NULL,
    [Details] json NOT NULL,
    CONSTRAINT [PK_Blogs] PRIMARY KEY ([Id])
);

Uygulamanız JSON'u zaten nvarchar kolonlarda kullanıyorsa bu kolonlar ilk migration ile otomatik olarak json'a çevrilir. Bu davranıştan çıkmak için kolon türünü elle nvarchar(max) olarak ayarlayabilir veya 170'ten düşük bir uyumluluk düzeyi yapılandırabilirsiniz. Kendi sunucunuzdaki SQL Server için önemli bir ayrıntı: UseSqlServer ile varsayılan uyumluluk düzeyi şu an 150'dir (SQL Server 2019), dolayısıyla json türü kullanılmaz.

Adlandırılmış default constraint'ler

EF 10, HasDefaultValueSql ile default constraint'lere veritabanının ürettiği ad yerine sizin verdiğiniz bir ad vermenize, UseNamedDefaultConstraints ile de tüm default constraint'lerin EF tarafından otomatik adlandırılmasına izin verir. Belgeler uyarır: mevcut migration'larınız varsa bir sonraki migration modeldeki tüm default constraint'leri yeniden adlandırır. Değer üretimi için default value ve computed column yazısına bakın.

Azure Cosmos DB yenilikleri

Cosmos DB sağlayıcısında tam metin arama desteği geldi: özellikleri tam metin aramaya açık olarak modelleyebilir ve FullTextContains, FullTextContainsAll, FullTextContainsAny, FullTextScore fonksiyonlarını sorgularda kullanabilirsiniz. Vector benzerlik araması ile tam metin aramayı birleştiren hibrit arama için Rrf (Reciprocal Rank Fusion) fonksiyonu desteklenir. EF 9'da deneysel olan vector benzerlik araması artık deneysel değildir ve model API'leri IsVectorProperty ve IsVectorIndex olarak yeniden adlandırıldı. Model evrimi de kolaylaştı: belgedeki verisi olmayan zorunlu bir özellik için EF artık hata fırlatmak yerine varsayılan değer üretir. Ayrıca sorgu yürütmede yeniden deneme için ExecutionStrategy kullanılıyor; yeniden deneme konusu connection resiliency yazısında.

Complex types: opsiyonel, JSON ve struct

Complex type'lar, varlık türlerinizin içinde yer alan ve kendi kimliği olmayan türleri modellemek için kullanılır. EF 8'den beri tablo bölme (table splitting) ile kapsayıcı tablonun kolonlarına eşlenebiliyorlardı. EF 10 bu desteği üç yönde genişletir. Birincisi opsiyonel complex type'lar: Address? gibi null olabilen bir özellik tanımlayabilirsiniz; belgelere göre opsiyonel complex type'ların şu an en az bir zorunlu özellik içermesi gerekir. İkincisi JSON eşleme: ComplexProperty(c => c.ShippingAddress, c => c.ToJson()) ile her adres tek bir JSON kolonuna eşlenir; tablo bölmeden farklı olarak bu eşleme tür içinde koleksiyonlara izin verir. Üçüncüsü struct desteği: complex type olarak sınıf yerine .NET struct'ları kullanabilirsiniz; ancak struct koleksiyonları henüz desteklenmez.

Belgeler, owned entity türleriyle yapılan JSON ve tablo bölme modellemesinin, owned türlerin arka planda kimliği olan varlık türleri olması nedeniyle birçok soruna yol açtığını anlatır. Örneğin bir müşterinin fatura adresini teslimat adresine eşitlemek owned türlerle hata verir; complex type'lar değer semantiğine sahip olduğu için atama özellikleri kopyalar. Karşılaştırmalar da içeriğe göre yapılır. Bu nedenle belgeler JSON ve tablo bölme için owned türleri kullananlara complex type'lara geçmelerini önerir. Ayrıntılar complex types ve JSON kolon yazısında.

LINQ ve SQL çevirisi

Parametreli koleksiyonlar: birden fazla parametre

ids.Contains(b.Id) gibi parametreli koleksiyon içeren sorgular ilişkisel veritabanlarında bilinen zor bir sorundur. EF 8.0 öncesinde koleksiyon içeriği SQL'e sabit olarak gömülüyordu; bu, her farklı koleksiyon için farklı SQL ve plan önbelleği şişmesi demekti. EF 8 ve 9 koleksiyonu tek bir JSON dizisi parametresi olarak gönderip SQL Server'da OPENJSON ile açtı; SQL sabit kaldı ama sorgu planlayıcısı koleksiyonun eleman sayısını bilemez hale geldi. EF 10'un yeni varsayılanı her değeri ayrı bir skaler parametre olarak göndermektir. Belgelerin örnek çıktısı:

SELECT [b].[Id], [b].[Name]
FROM [Blogs] AS [b]
WHERE [b].[Id] IN (@ids1, @ids2, @ids3)

Farklı eleman sayıları yine farklı SQL üreteceği için EF parametre listesini doldurur (padding): belgelere göre listede 8 değer varsa 10 parametreli SQL üretilir ve son iki parametre sekizinci değerle aynı değeri taşır, böylece sonuç değişmez. Bu seçimin her sorgu için doğru olmayabileceğini belgeler de kabul eder. Bu yüzden çeviri modu genel düzeyde UseParameterizedCollectionMode(ParameterTranslationMode.Constant) gibi bir çağrıyla, sorgu düzeyinde ise EF.Constant, EF.Parameter ve EF.MultipleParameters ile seçilebilir:

LeftJoin ve RightJoin

.NET 10, LINQ'e birinci sınıf LeftJoin metodunu ekler ve EF Core bunu tanır. Önceden LEFT JOIN için SelectMany, GroupJoin ve DefaultIfEmpty'yi belirli bir düzende birleştirmek gerekiyordu. EF 10 benzer RightJoin operatörünü de destekler ve onu RIGHT JOIN'e çevirir. C# sorgu söz dizimi henüz bu şekilde left/right join ifade etmeyi desteklemiyor. Kullanım örnekleri join, GroupBy ve LeftJoin yazısında.

Split query sıralaması daha tutarlı

Split query'ler ilişkili veriyi ayrı SQL sorgularıyla yüklediği için tutarlılık sorunları doğabilir. EF 10 öncesinde OrderBy ve Take içeren bir split query'de ikinci sorgunun içindeki alt sorgu sıralamada anahtar kolonunu atlıyordu; bu da yanlış veri döndürülmesine yol açabiliyordu. EF 10 sıralamanın sorgular arasında tutarlı olmasını sağlar. Ayrıntılar split query yazısında.

Diğer çeviri iyileştirmeleri

• DateOnly.ToDateTime() ve DateOnly.DayNumber çevirileri; SQL Server ve SQLite için DayNumber çıkarma desteği.
• SQL Server'da çoğu durumda COALESCE yerine ISNULL çevirisi.
• SQLite'ta decimal ile MAX, MIN ve ORDER BY desteği.
• Çeşitli senaryolarda DefaultIfEmpty çevirisi düzeltmeleri.
• SQL parametre adlarının sadeleşmesi, örneğin @__city_0 yerine @city.

ExecuteUpdateAsync yenilikleri

İki önemli değişiklik var. İlki JSON kolonları: EF 10, complex type olarak eşlenmiş JSON kolonlarına ve içlerindeki özelliklere ExecuteUpdateAsync içinde başvurmanıza izin verir. Bu destek owned entity olarak eşlenen türlerde çalışmaz. İkincisi, kolon atayıcıları artık ifade ağacı değil normal bir lambda olarak alınır. Önceden bazı atamaları koşula bağlamak için ifade ağacını elle kurmak gerekiyordu; şimdi şöyle yazabilirsiniz:

await context.Blogs.ExecuteUpdateAsync(s =>
{
    s.SetProperty(b => b.Views, 8);
    if (nameChanged)
    {
        s.SetProperty(b => b.Name, "foo");
    }
});

Bu değişiklik aynı zamanda kırıcı değişiklikler listesinde yer alır: atayıcı argümanını dinamik olarak ifade ağacıyla kuran mevcut kod artık derlenmez ve yukarıdaki çok daha basit biçime dönüştürülmelidir. Toplu güncelleme ayrıntıları için ExecuteUpdate ve ExecuteDelete yazısına bakın.

Adlandırılmış query filter'lar

Global query filter'lar soft delete ve çok kiracılı yapı gibi desenleri uzun süredir kolaylaştırıyordu, ancak varlık türü başına tek filtre desteklendiği için birden fazla filtreyi yönetmek ve yalnızca birini kapatmak zordu. EF 10 filtrelere ad vermenizi ve sorguda yalnızca belirli filtreleri devre dışı bırakmanızı sağlar:

modelBuilder.Entity<Blog>()
    .HasQueryFilter("SoftDeletionFilter", b => !b.IsDeleted)
    .HasQueryFilter("TenantFilter", b => b.TenantId == tenantId);

var allBlogs = await context.Blogs.IgnoreQueryFilters(["SoftDeletionFilter"]).ToListAsync();

Filtrelerin tamamı ve soft delete deseni global query filter ve soft delete yazısında anlatılıyor.

Güvenlikle ilgili iyileştirmeler

EF, çalıştırılan SQL'i loglarken parametre değerlerini varsayılan olarak loglamaz, çünkü bunlar hassas veya kişisel veri içerebilir. Ancak EF bazı durumlarda, örneğin EF.Constant kullanıldığında, parametreleri SQL'e gömer ve önceki sürümlerde bu gömülü değerler loglara düşüyordu. EF 10 bu değerleri varsayılan olarak soru işaretiyle (?) maskeler; veritabanına giden SQL değişmez, yalnızca logdaki metin maskelenir. Tam loglama EnableSensitiveDataLogging ile yeniden açılabilir; bu ayarın yalnızca geliştirmede kullanılması gerektiği SQL loglama yazısında anlatılıyor.

İkinci iyileştirme SQL injection ile ilgilidir. FromSql bir FormattableString alır ve araya giren değerleri otomatik olarak ayrı SQL parametreleri olarak gönderir. FromSqlRaw ise SQL parçalarını birleştirmek için tasarlanmıştır ve tüm parçaların güvenilir olmasını kullanıcıya bırakır. EF 10 ile gelen bir analyzer, ham SQL metodu çağrısının içinde string birleştirme yapıldığında uyarı verir. Birleştirilen değer güvenilirse veya doğru şekilde temizlendiyse uyarı bastırılabilir. Ayrıntılar FromSql ve ham SQL yazısında.

Diğer iyileştirmeler

• SQLite'ta AUTOINCREMENT artık kapatılabilir ve value converter'lı özelliklerde de desteklenir.
• EF 9'da yapılan, tüm migration'ları tek transaction'a alma değişikliği çeşitli migration senaryolarında sorun çıkardığı için geri alındı. Migration'ları uygulama yolları için migration production rehberi yazısına bakın.
• SQL Server scaffolding, Azure Data Explorer ile uyumlu hale getirildi.
• Lazy loading performansı için AsyncLocal kullanımında değişiklikler yapıldı.

EF Core 10 kırıcı değişiklikleri

Belgeler EF Core 9'dan 10'a yükseltirken uygulamaları bozabilecek değişiklikleri etkilerine göre sıralar. Daha eski bir sürümden geliyorsanız EF 9 ve EF 8 kırıcı değişikliklerini de gözden geçirmeniz gerekir; örneğin EF 9'un bekleyen model değişikliklerinde hata fırlatması pending model changes hatası yazısında anlatılıyor.

Çoklu hedefli projelerde --framework zorunlu

Tek orta etkili değişiklik budur. Proje dosyanızda TargetFramework yerine birden fazla değer içeren TargetFrameworks kullanıyorsanız, EF Core 10 ile EF araçlarını çalıştırırken hangi framework'ün kullanılacağını --framework seçeneğiyle açıkça belirtmeniz gerekir. Aksi halde belgelerde gösterildiği şekilde "The project targets multiple frameworks. Use the --framework option to specify which target framework to use." hatası alırsınız. Nedeni, araçların artık proje bağımlılıkları hakkında daha doğru bilgi almak için çoklu hedefte kullanılamayan bir MSBuild görevine dayanmasıdır:

dotnet ef migrations add MyMigration --framework net9.0
dotnet ef database update --framework net9.0
dotnet ef migrations script --framework net9.0

Belgelerdeki örnek net9.0 değerini kullanır; siz projenizin hedeflediği framework'lerden birini yazarsınız. Araçların genel kullanımı için dotnet ef komutları yazısına bakın.

Bağlantı ve SqlClient ile ilgili değişiklikler

Microsoft.Data.SqlClient 6.1.6, Microsoft Entra ID kimlik doğrulaması için gereken Microsoft.Identity.Client.Broker paketine bağımlılık ekler ve bu, SQL Server sağlayıcısını kullanan uygulamanın yayımlanmış boyutunu ciddi şekilde artırabilir. Entra ID kullanmıyorsanız belgeler projenizde açıkça Microsoft.Data.SqlClient 7.1.x'e başvurmanızı önerir; 7.0'dan itibaren SqlClient çekirdek paketinde Azure/Entra ID bağımlılıkları bulunmaz.

Bağlantı dizesinde Application Name yoksa EF artık EF ve SqlClient sürümleri hakkında anonim bilgi içeren bir değer ekler. Çoğu durumda bunun bir etkisi olmaz; ancak aynı veritabanına hem EF hem de Dapper veya ADO.NET ile bağlanıyorsanız iki farklı bağlantı dizesi oluşur, SqlClient farklı iç bağlantı havuzları kullanır ve bu erişim bir TransactionScope içindeyse dağıtık transaction'a yükselme yaşanabilir. Çözüm, bağlantı dizenizde kendi Application Name değerinizi tanımlamaktır; tanımlıysa EF değiştirmez. Konunun transaction tarafı transaction yönetimi yazısında.

Sorgu ve model değişiklikleri

Parametreli koleksiyonların yeni çevirisi çoğu durumda davranış veya performans değişikliğine yol açmaz; ancak belgelere göre EF 8 veya 9 ile geliştirilip JSON dizisi parametresinin performans özelliklerine dayanan uygulamalar, özellikle büyük koleksiyonlarda, farklılık görebilir. Gerileme görürseniz yukarıdaki modlarla eski davranışa genel olarak veya sorgu bazında dönebilirsiniz.

Complex type tarafında iki değişiklik var. Farklı complex type'lardaki aynı adlı özellikler önceden sessizce aynı kolonu paylaşıyordu; EF 10 artık aynı adda kolon varsa sonuna sayı ekleyerek kolon adlarını benzersizleştirir. Bu, istenmeden aynı kolona eşlenen özelliklerin yol açtığı veri bozulmasını önler. İç içe complex type özellikleri ise artık kolon adında tam yolu kullanır: Complex.NestedComplex.Property önceden NestedComplex_Property kolonuna eşlenirken şimdi Complex_NestedComplex_Property kolonuna eşlenir. Belgelerin önerdiği çözüm, eski kolon adlarını korumak istiyorsanız ilgili özellikleri Property ve HasColumnName ile açıkça yapılandırmaktır; aynı kolonu bilerek paylaştırmak istediğiniz durumlar için de aynı yol geçerlidir.

SQL parametre adlarının sadeleşmesi çoğu uygulama için şeffaftır, çünkü çalışan sorgular işlevsel olarak aynıdır. Ancak üretilen SQL metnini karşılaştıran anlık görüntü (snapshot) testleri veya DbCommand.CommandText'i ayrıştıran interceptor ve logger'lar güncellenmelidir. Belgeler önemli bir operasyonel notu da ekler: parametre adları SQL metninin parçası olduğundan yükseltme, veritabanı sunucusundaki önbelleğe alınmış sorgu planlarının neredeyse tamamının yeniden derlenmesine yol açabilir; büyük sistemler dağıtımdan hemen sonra geçici bir derleme yükü artışını hesaba katmalıdır.

Kendi konvansiyon veya logger uygulamanızı yazdıysanız iki imza değişikliğine bakın: IDiscriminatorPropertySetConvention.ProcessDiscriminatorPropertySet artık IConventionEntityTypeBuilder yerine IConventionTypeBaseBuilder alır ve IRelationalCommandDiagnosticsLogger metotlarına loglanacak, maskelenmiş olabilecek SQL'i taşıyan logCommandText parametresi eklendi.

Microsoft.Data.Sqlite kırıcı değişiklikleri

Microsoft.Data.Sqlite kullanıyorsanız ayrı bir bölümde listelenen üç yüksek etkili değişiklik var ve üçü de tarih/saat ile UTC davranışıyla ilgili:

• Ofset içermeyen metin bir zaman damgasında GetDateTimeOffset kullanmak artık değeri yerel saat dilimi yerine UTC kabul eder; bu, SQLite'ın ofsetsiz zaman damgalarını UTC sayma davranışıyla uyum içindir.
• REAL kolona DateTimeOffset yazmak artık değeri yazmadan önce UTC'ye çevirir; önceki davranış ofseti hesaba katmadığı için yanlış değer yazıyordu.
• Ofset içeren metin bir zaman damgasında GetDateTime kullanmak artık değeri UTC'ye çevirip DateTimeKind.Utc ile döndürür; önceden makinenin yerel saat dilimine bağlı olarak DateTimeKind.Local dönüyordu.

Belgelerin önerisi kodu buna göre ayarlamaktır. Son ve geçici bir çare olarak eski davranışa şu AppContext anahtarıyla dönebilirsiniz:

AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", isEnabled: true);

Sunucunuzun saat dilimi ayarı geliştirme makinenizden farklıysa bu değişiklikler davranışı ortama bağlı olmaktan çıkardığı için uzun vadede faydalıdır; ama yükseltme sırasında SQLite'tan okunan tarihleri mutlaka test edin.

Yükseltme kontrol listesi

• Projenin .NET 10 SDK ve çalışma zamanını hedeflediğinden emin olun; EF 10 daha eski .NET sürümlerinde çalışmaz.
• Tüm EF Core paketlerini ve dotnet-ef aracını aynı 10.0.x yamasına getirin.
• Çoklu hedefli projelerde EF araç komutlarınıza ve betiklerinize --framework ekleyin.
• Azure SQL veya uyumluluk düzeyi 170 kullanıyorsanız ilk migration'daki nvarchar kolonlarından json'a geçişi gözden geçirin.
• Complex type kullanıyorsanız yeni migration'da kolon adı değişikliği olup olmadığını kontrol edin.
• SQL metnine bağlı testleri, interceptor'ları ve log ayrıştırıcıları yeni parametre adlarına göre güncelleyin.
• Bağlantı dizesine Application Name ekleyip eklemeyeceğinize karar verin.
• SQLite kullanıyorsanız tarih/saat okuma ve yazma kodunu test edin.
• Büyük koleksiyonlu Contains sorgularında performansı ölçün.

EF Core 11: geliştirme aşamasında

Belgelere göre EF Core 11.0 (EF11), EF Core 10.0'dan sonraki sürümdür ve şu anda geliştirme aşamasındadır; sürüm planlama sayfası onu Kasım 2026 için planlanan bir sonraki kararlı sürüm olarak gösterir. EF11 .NET 11 SDK ve çalışma zamanı gerektirecek. Geliştirme notlarında öne çıkanlar arasında .NET 11'in FullJoin operatörünün FULL JOIN'e çevrilmesi, migration oluşturup uygulamayı tek adımda yapan dotnet ef database update --add seçeneği ve TPT/TPC kalıtımlı varlıklarda complex type ve JSON kolonları desteği var. Kırıcı değişiklik taslağında ise migration bulunamadığında varsayılan olarak hata fırlatılması ve Microsoft.Data.SqlClient'ın 7.0'a güncellenmesi gibi maddeler yer alıyor. Bunlar yayımlanmamış bir sürümün notlarıdır ve değişebilir; üretim projelerinde EF Core 10 LTS'yi temel alın.

Sık Sorulan Sorular

EF Core 10 hangi .NET sürümünde çalışır?

Yalnızca .NET 10'da. Belgelere göre derlemek için .NET 10 SDK'sı, çalıştırmak için .NET 10 çalışma zamanı gerekir; önceki .NET sürümlerinde ve .NET Framework'te çalışmaz.

EF Core 9'dan 10'a geçmek zor mu?

Kırıcı değişikliklerin yalnızca biri orta etkili (çoklu hedefli projelerde --framework gereksinimi), geri kalanı düşük etkili olarak sınıflandırılır. Yine de ana sürüm geçişi olduğu için belgeler kapsamlı test önerir; özellikle JSON kolonları, complex type kolon adları ve SQLite tarih davranışına bakın.

Yükselttikten sonra Contains sorguları yavaşladı, ne yapmalıyım?

EF 10 parametreli koleksiyonları varsayılan olarak çoklu parametreyle çevirir. Gerileme görürseniz UseParameterizedCollectionMode ile genel olarak veya EF.Parameter/EF.Constant ile sorgu bazında başka bir moda geçebilirsiniz.

EF Core 11 çıktı mı?

Bu yazının kaynağı olan belgelerde EF Core 11 geliştirme aşamasında olarak işaretli. Yayımlandığında sürüm notlarını ve kırıcı değişiklikleri ayrıca incelemeniz gerekir.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: EF Core öğrenme rehberi · Complex types ve JSON · Named query filter · ExecuteUpdate · LeftJoin ve RightJoin · EF Core kurulumu