EF Core Kurulumu: Sağlayıcı, Design ve Tools Paketleri

Ön koşullar

Belgelere göre EF Core en güncel .NET SDK'sını ister. Çalışma zamanında ise kullandığınız EF Core sürümünün gerektirdiği .NET sürümü gerekir. Güncel sürüm EF Core 10 için bu, derlemede .NET 10 SDK'sı ve çalışırken .NET 10 çalışma zamanı demektir; EF10 daha eski .NET sürümlerinde ve .NET Framework üzerinde çalışmaz. Sunucunuzda uygulamayı çalıştıracaksanız, oraya da doğru .NET çalışma zamanının kurulu olması gerekir (self-contained yayın yapmıyorsanız).

Windows üzerinde Visual Studio ile geliştirme yapabilirsiniz; belgeler Visual Studio'nun en son sürümünü önerir. Ancak Visual Studio şart değildir: .NET CLI ile Windows, Linux veya macOS üzerinde aynı işleri komut satırından yapabilirsiniz. Bu, uygulamasını Linux bir sunucuda çalıştıran geliştiriciler için önemlidir, çünkü migration üretmek ya da SQL script almak için Visual Studio'ya bağlı kalmazsınız.

1. adım: Veritabanı sağlayıcısını seçin

EF Core, farklı veritabanlarıyla "veritabanı sağlayıcısı" adı verilen ve NuGet paketi olarak dağıtılan eklentiler üzerinden konuşur. Uygulamanız bir veya daha fazla sağlayıcı paketi kurmalıdır. Resmî NuGet paketleri sayfası yaygın sağlayıcıları şöyle listeler:

Belgeler PostgreSQL ve MySQL paketlerini topluluk tarafından geliştirilen, popüler ve yüksek kaliteli açık kaynak sağlayıcılar olarak tanımlar; diğerleri Microsoft tarafından yayımlanır. In-memory sağlayıcı için ise açık bir uyarı vardır: üretim kullanımı için tasarlanmamıştır ve test için bile en iyi çözüm olmayabilir. Testte hangi yolu seçeceğinizi EF Core test yazma yazısı anlatır. Tam sağlayıcı listesi ve SQL Server ile SQLite'a özgü ayrıntılar veritabanı sağlayıcıları yazısında. Hangi veritabanını seçeceğinize karar vermediyseniz MySQL ve PostgreSQL karşılaştırması yardımcı olabilir.

2. adım: Sağlayıcı paketini kurun

Paketleri kurmanın ya da güncellemenin üç yolu vardır: .NET CLI, Visual Studio'nun NuGet paket yöneticisi penceresi ve Visual Studio Package Manager Console. Üçü de aynı sonucu verir, yani projenizin .csproj dosyasına bir PackageReference ekler.

.NET CLI ile

İşletim sisteminin komut satırında, proje klasöründeyken şu komutu çalıştırırsınız. Belirli bir sürüm kurmak için komutun sonuna -v ve sürüm numarasını eklersiniz; belgelerdeki örnek -v 6.0.14 biçimindedir.

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Visual Studio paket yöneticisi penceresi ile

Menüden Project > Manage NuGet Packages yolunu izler, Browse veya güncelleme için Updates sekmesini açar, Microsoft.EntityFrameworkCore.SqlServer paketini seçip onaylarsınız.

Package Manager Console ile

Tools > NuGet Package Manager > Package Manager Console yolundan konsolu açıp aşağıdaki komutu çalıştırırsınız. Güncellemek için Update-Package, belirli bir sürüm için -Version parametresi kullanılır.

Install-Package Microsoft.EntityFrameworkCore.SqlServer

Sağlayıcı paketini kurmak, EF Core'un çekirdek paketlerini de bağımlılık olarak getirir. Resmî sağlayıcılar sayfası, paket kurulduktan sonra sağlayıcıyı DbContext üzerinde, ya OnConfiguring metodunda ya da dependency injection kullanıyorsanız AddDbContext çağrısında yapılandırdığınızı söyler. Belgedeki örnek satır şudur:

optionsBuilder.UseSqlServer(
    @"Server=(localdb)\mssqllocaldb;Database=MyDatabase;Trusted_Connection=True;");

UseSqlServer, UseSqlite gibi metotlar sağlayıcı paketinin tanımladığı extension metotlardır. Derleyici bu metodu bulamadığını söylüyorsa belgelerin önerisi iki şeyi kontrol etmektir: sağlayıcı paketinin gerçekten kurulu olması ve dosyada using Microsoft.EntityFrameworkCore; satırının bulunması. Context yapılandırmasının ayrıntıları DbContext yapılandırma yazısında.

3. adım: Çekirdek paketleri doğrudan referans verin

NuGet paketleri sayfası, kurulum için "olağan süreci" şöyle tarif eder: önce sağlayıcıyı seçip paketini kurun; ilişkisel bir veritabanı kullanıyorsanız ek olarak Microsoft.EntityFrameworkCore ve Microsoft.EntityFrameworkCore.Relational paketlerini de doğrudan kurun; son olarak ihtiyaç duyduğunuz araç paketlerini ekleyin. Çekirdek paketler zaten sağlayıcının bağımlılığı olarak gelir, peki neden ayrıca referans verilir?

Belgelerin verdiği iki gerekçe var. Birincisi, doğrudan referans tutarlı sürümler kullanmanızı garanti altına almaya yardım eder. İkincisi, NuGet yeni paket sürümleri yayımlandığında sizi doğrudan referans verdiğiniz paketler için bilgilendirir; dolaylı (transitive) bağımlılıklarda bu bildirimi kaçırabilirsiniz. Sağlayıcılar sayfası buna önemli bir ayrıntı ekler: EF Core'un yeni bir yama sürümü çıktığında bu sürüm çoğu zaman Microsoft.EntityFrameworkCore.Relational paketinde de düzeltmeler içerir. Birçok sağlayıcı EF Core'dan bağımsız yayımlandığı için yeni yamaya bağımlı olacak şekilde güncellenmemiş olabilir. Tüm hata düzeltmelerini aldığınızdan emin olmak için Relational paketinin yama sürümünü uygulamanıza doğrudan bağımlılık olarak eklemeniz önerilir.

4. adım: Araç paketlerini kurun

Migration oluşturmak, uygulamak ya da var olan bir veritabanından model üretmek için EF Core araçlarına ihtiyacınız var. İki araç seti vardır ve ikisi de aynı işlevi sunar:

• .NET CLI araçları: Windows, Linux ve macOS üzerinde çalışır; komutlar dotnet ef ile başlar. SDK tarzı bir proje gerektirir.
• Package Manager Console (PMC) araçları: Windows üzerinde Visual Studio içinde çalışır; komutlar Add-Migration, Update-Database gibi bir fiille başlar. Belgeler Visual Studio kullanıyorsanız daha bütünleşik bir deneyim sundukları için bunları önerir.

.NET CLI araçları

dotnet ef global ya da yerel bir .NET aracı olarak kurulmalıdır. Belgelere göre geliştiricilerin çoğu global kurulumu tercih eder:

dotnet tool install --global dotnet-ef
dotnet tool update --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design

İlk satır aracı kurar, ikinci satır daha sonra güncellemek için kullanılır. Yerel araç olarak kullanmak isterseniz aracı bir tool manifest dosyasında bağımlılık olarak tanımlayan projenin bağımlılıklarını geri yüklersiniz; yerel kurulumda güncelleme komutu dotnet tool update dotnet-ef biçimindedir. Belirli bir araç sürümü için komutun sonuna --version ve sürüm numarası eklenir. Üçüncü satır, araçların projenizde çalışabilmesi için gereken Microsoft.EntityFrameworkCore.Design paketini ekler. Kurulumu doğrulamak için dotnet ef komutunu parametresiz çalıştırabilirsiniz; belgelere göre çıktı kullandığınız araç sürümünü gösterir.

Package Manager Console araçları

PMC araçları için Visual Studio içinden Microsoft.EntityFrameworkCore.Tools paketini kurarsınız; güncellemek için aynı paket adıyla Update-Package çalıştırılır. Kurulumu doğrulamak için belgeler Get-Help about_EntityFrameworkCore komutunu önerir; bu komutun çıktısı araçların hangi sürüm olduğunu söylemez, yalnızca kurulu olduklarını gösterir.

Install-Package Microsoft.EntityFrameworkCore.Tools
Update-Package Microsoft.EntityFrameworkCore.Tools
Get-Help about_EntityFrameworkCore

Bu iki araç setinin komutlarını, ortak seçeneklerini ve birbirine karşılıklarını dotnet ef komutları yazısında tablo hâlinde bulabilirsiniz.

Design paketi neden yayına gitmez?

NuGet paketleri sayfasındaki bir ipucu, birçok geliştiricinin kafasını karıştıran bir davranışı açıklar: Microsoft.EntityFrameworkCore.Design paketi varsayılan olarak uygulamanızla birlikte dağıtılmayacak şekilde kurulur. Bu paket bir "DevelopmentDependency" paketidir; yani bağımlılığı diğer projelere aktarılmaz ve varsayılan olarak içindeki türlere kodunuzdan referans veremezsiniz. Tasarım zamanı servisleri ayrıca yönetilir ki uygulamanızla birlikte yayına gitmesin.

Çoğu proje için bu tam istenen davranıştır: Design paketi yalnızca araçların ihtiyaç duyduğu bir paket olarak kalır. Ancak tasarım zamanı servislerini özelleştirmek gibi bir sebeple bu paketteki türlere erişmeniz gerekiyorsa, .csproj dosyasındaki PackageReference öğesinin meta verisini değiştirmeniz gerekir. Belgelerdeki örnek, IncludeAssets satırının kaldırılmasını (örnekte yorum satırına alınmasını) gösterir:

<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
  <PrivateAssets>all</PrivateAssets>
  <!-- Remove IncludeAssets to allow compiling against the assembly -->
  <!--<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>-->
</PackageReference>

Örnekteki 9.0.0 sürüm numarası belgeden aynen alınmıştır; kendi projenizde diğer EF Core paketlerinizle aynı sürümü yazmalısınız. Design paketi Microsoft.EntityFrameworkCore.Tools üzerinden dolaylı olarak geliyorsa, belgelere göre pakete açık bir PackageReference ekleyip meta verisini bu şekilde değiştirmeniz gerekir. Tasarım zamanı servislerinin listesi ve kullanımı design-time DbContext factory yazısında kısaca ele alınıyor.

İsteğe bağlı paketler

Temel kurulum için sağlayıcı ve araç paketleri yeterlidir. Belirli özellikler ise ek paketler gerektirir. NuGet paketleri sayfası yaygın eklenti paketlerini şöyle sıralar:

Proxies paketi, UseLazyLoadingProxies gibi metotları sağlar; tembel yüklemenin artıları ve riskleri lazy loading yazısında. Microsoft.EntityFrameworkCore.Tasks paketi EF 9 ile gelen MSBuild entegrasyonunu sağlar ve compiled model ile önceden derlenmiş sorguları derleme veya yayın sırasında üretir; belgeler bu entegrasyonun ve NativeAOT desteğinin deneysel olduğunu, henüz üretim kullanımına uygun olmadığını açıkça belirtir. Bu paketin, üretilen dosyalarla derlenmesi gereken her projeye ayrı ayrı eklenmesi gerekir, çünkü varsayılan olarak bağımlılığı aktarılmaz.

Bunların dışında NuGet sayfası, normalde sağlayıcının bağımlılığı olarak gelen ama isterseniz doğrudan referans verebileceğiniz paketleri de listeler: Microsoft.EntityFrameworkCore.Abstractions (EF Core attribute'ları gibi hafif öğeler), Microsoft.EntityFrameworkCore.Analyzers (EF Core kullanımına yönelik Roslyn kod analizcileri) ve yerel SQLite bağımlılığı olmadan gelen Microsoft.EntityFrameworkCore.Sqlite.Core. Sağlayıcı geliştiricilerin test için kullandığı Specification.Tests paketlerini ise uygulamalara kurmamanız gerekir.

Sürüm uyumu: en sık yapılan hata

Kurulumda en çok sorun çıkaran konu sürüm karışıklığıdır. Belgelerin kuralı açıktır: Microsoft tarafından yayımlanan tüm EF Core paketlerinin aynı sürümünü kurun. Örneğin Microsoft.EntityFrameworkCore.SqlServer paketinin 5.0.3 sürümü kuruluysa, diğer bütün Microsoft.EntityFrameworkCore.* paketleri de 5.0.3 olmalıdır. Belgeler ayrıca NuGet'in tutarlı sürümleri zorlamadığı konusunda uyarır; bu yüzden .csproj dosyanızda hangi sürümlere referans verdiğinizi dikkatle kontrol etmeniz gerekir.

Aşağıdaki parça, ilişkisel bir sağlayıcı kullanan bir projede paket listesinin nasıl görünmesi gerektiğini gösterir. Sürüm alanını, belgelerdeki ayrı migration projesi örneğinde olduğu gibi "..." olarak bıraktık; buraya tüm satırlarda aynı EF Core sürümünü yazmanız gerekir.

<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore" Version="..." />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="..." />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="..." />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="...">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>
</ItemGroup>

Dış paketler için de benzer bir kontrol gerekir. Özellikle üçüncü taraf bir veritabanı sağlayıcısının kullandığınız EF Core sürümünü desteklediğinden emin olmalısınız. Belgelere göre EF Core'un yeni ana sürümleri genellikle güncellenmiş bir sağlayıcı ister ve sağlayıcılar tipik olarak ana sürümler arasında çalışmaz: EF Core 8 için yayımlanmış bir sağlayıcı EF Core 9 ile çalışmaz. Belgelerin alındığı andaki sağlayıcı tablosunda örneğin Npgsql ve Pomelo sağlayıcıları için "8, 9" yazıyordu; EF Core 10'a geçmeden önce kullandığınız sağlayıcının kendi belgelerinden EF10 uyumlu bir sürüm yayımlanıp yayımlanmadığını kontrol edin.

EF Core'u güncellerken

• Microsoft sağlayıcıları: EF Core'un her yeni sürümüyle birlikte EF Core projesinin parçası olan sağlayıcıların (SqlServer, Sqlite, Cosmos, InMemory) yeni sürümü de yayımlanır. Bu sağlayıcıyı güncellemeniz, tüm iyileştirmeleri almanız için yeterlidir.
• Üçüncü taraf sağlayıcılar: Güncellemeden önce hedeflediğiniz EF Core sürümüyle uyumlu bir sağlayıcı sürümü olup olmadığına bakın. Bu sağlayıcılar genellikle EF Core'un yama sürümleriyle eş zamanlı yama yayımlamaz; EF Core'un bir yama sürümüne geçmek için Microsoft.EntityFrameworkCore ve Microsoft.EntityFrameworkCore.Relational paketlerine doğrudan referans eklemeniz gerekebilir.
• Araçlar: dotnet-ef aracını ve Design ile Tools paketlerini çalışma zamanı paketleriyle aynı ana sürüme getirin.
• Ana sürüm geçişleri: EF Core 9'dan 10'a gibi geçişler kırıcı değişiklik içerebilir; geçişten önce EF Core 10 breaking changes listesini okuyun.

EF10'un kırıcı değişiklikler listesinde paket kurulumuyla doğrudan ilgili bir madde de var: SQL Server sağlayıcısının kullandığı Microsoft.Data.SqlClient 6.1.6, Microsoft Entra ID kimlik doğrulaması için gereken Microsoft.Identity.Client.Broker bağımlılığını getirir ve yayımlanan uygulamanın boyutunu ciddi biçimde artırabilir. Belgelere göre Entra ID kimlik doğrulaması kullanmıyorsanız projenize Microsoft.Data.SqlClient 7.1.x sürümüne açık bir referans ekleyerek EF Core'un kullandığı sürümü geçersiz kılabilirsiniz; 7.0 sürümünden itibaren bu kütüphanenin çekirdek paketi Azure ve Entra ID bağımlılıklarını içermez.

Kaldırmanız gereken eski paketler

Eski projelerden kalan bazı paketler artık kullanılmaz. Belgeler şu paketleri kurmamanızı ve kuruluysa kaldırmanızı söyler: Microsoft.EntityFrameworkCore.Relational.Design, Microsoft.EntityFrameworkCore.Tools.DotNet, Microsoft.EntityFrameworkCore.SqlServer.Design, Microsoft.EntityFrameworkCore.Sqlite.Design ve Microsoft.EntityFrameworkCore.Relational.Design.Specification.Tests. Özellikle eski bir projeyi yeni EF Core sürümüne taşırken .csproj dosyasında bu adlardan birini görürseniz silin.

Kurulumda sık karşılaşılan sorunlar

• "dotnet ef" komutu bulunamıyor: dotnet-ef global veya yerel araç olarak kurulmamıştır. Kurulum komutunu çalıştırın; yerel araç kullanıyorsanız tool manifest dosyasının bulunduğu klasörde araçları geri yükleyin.
• Araç çalışıyor ama proje üzerinde hata veriyor: Projeye Microsoft.EntityFrameworkCore.Design paketi eklenmemiş olabilir. Belgeler, araçları bir projede kullanmadan önce bu paketi eklemeniz gerektiğini söyler.
• UseSqlServer ya da UseSqlite bulunamıyor: Sağlayıcı paketi eksiktir veya using Microsoft.EntityFrameworkCore; satırı yoktur.
• Karışık sürümler: Bir paket 10.x, diğeri 9.x ise derleme geçse bile çalışma zamanında beklenmedik hatalar görebilirsiniz. Tüm EF Core paketlerini aynı sürüme çekin.
• .NET sürümü uyumsuzluğu: EF Core 10 paketleri .NET 10 hedeflemeyen bir projede kullanılamaz; ya projeyi .NET 10'a taşıyın ya da projenizin .NET sürümünün desteklediği bir EF Core sürümünde kalın.

Sık Sorulan Sorular

Microsoft.EntityFrameworkCore paketini ayrıca kurmam şart mı?

Şart değil, çünkü sağlayıcı paketi onu bağımlılık olarak getirir. Ancak belgeler, sürümleri tutarlı tutmak ve yeni sürümlerden haberdar olmak için bu paketi (ve ilişkisel bir veritabanı kullanıyorsanız Relational paketini) doğrudan kurmayı önerir.

Hem dotnet-ef hem Tools paketini kurmalı mıyım?

Gerekmez. İkisi aynı işlevi sunar; komut satırında çalışıyorsanız dotnet-ef ve Design paketi, Visual Studio Package Manager Console kullanıyorsanız Tools paketi yeterlidir. Ekipte iki yöntemi de kullanan geliştiriciler varsa ikisini birlikte kurmanızda sakınca yoktur.

Design paketi sunucuya yüklenen uygulamaya dahil olur mu?

Varsayılan kurulumda olmaz. Paket, uygulamayla dağıtılmayacak şekilde kurulur ve bağımlılığı diğer projelere aktarılmaz. Bu davranışı yalnızca paketin türlerine kodunuzdan erişmeniz gerekiyorsa, PackageReference meta verisini değiştirerek bilinçli olarak değiştirirsiniz.

PostgreSQL veya MySQL için hangi paketi kullanmalıyım?

NuGet paketleri sayfası PostgreSQL için Npgsql.EntityFrameworkCore.PostgreSQL, MySQL için Pomelo.EntityFrameworkCore.MySql paketini yaygın sağlayıcılar olarak listeler; sağlayıcılar tablosunda MySQL için Oracle'ın MySql.EntityFrameworkCore paketi de yer alır. Bu paketlerin hangi EF Core sürümünü desteklediğini ve kendine özgü yapılandırmasını sağlayıcının kendi belgelerinden kontrol edin.

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 · İlk EF Core uygulaması · dotnet ef komutları · Veritabanı sağlayıcıları