dotnet ef, EF Core'un tasarım zamanı işlerini komut satırından yapan .NET CLI aracıdır: migration ekler, kaldırır ve listeler, veritabanını belirli bir migration'a günceller, SQL script ve migration bundle üretir, var olan bir veritabanından DbContext ve entity sınıfları üretir (scaffold) ve compiled model oluşturur. Aracı dotnet tool install --global dotnet-ef ile kurar, kullanacağınız projeye Microsoft.EntityFrameworkCore.Design paketini eklersiniz. Visual Studio kullanıyorsanız aynı işlevler Package Manager Console'da Add-Migration, Update-Database gibi komutlarla sunulur.
Bu yazı, Entity Framework Core (EF Core) araçlarının resmî başvuru sayfalarını Türkçe bir başvuru kaynağına dönüştürüyor: kurulum ve doğrulama, hedef proje ile başlangıç projesi farkı, ortak seçenekler, tüm komutlar ve seçenekleri, Package Manager Console karşılıkları, EF Core 10'da çoklu hedefli projeler için gelen değişiklik ve EF Core 11'de geliştirme aşamasında olan yenilikler. Migration'ların günlük kullanımı migration rehberinde, üretime uygulanması production yazısında, scaffolding ise database first yazısında ayrıca anlatılıyor; burada odak komutların kendisi.
İki araç seti: .NET CLI ve Package Manager Console
EF Core araçları iki biçimde gelir ve belgelere göre ikisi de aynı işlevi sunar. .NET CLI araçları platformlar arası dotnet komutunun bir uzantısıdır, Windows, Linux ve macOS üzerinde çalışır ve SDK tarzı bir proje (proje dosyasında Sdk="Microsoft.NET.Sdk" veya benzeri) gerektirir. Package Manager Console (PMC) araçları ise Visual Studio içinde çalışır; .NET Framework ve .NET projeleriyle çalışabilir.
Visual Studio kullanıyorsanız belgeler PMC araçlarını önerir, çünkü PMC araçları otomatik olarak üç kolaylık sağlar: konsolda seçili olan proje ile çalışır ve klasör değiştirmenizi gerektirmez, komut tamamlandığında ürettiği dosyaları açar ve komutlar, parametreler, proje adları, context türleri ve migration adları için sekme ile tamamlama sunar. Visual Studio kullanmıyorsanız, örneğin uygulamanızı bir Linux sunucuda derleyip yayınlıyorsanız, .NET CLI araçları doğru seçimdir.
Kurulum, güncelleme ve doğrulama
dotnet ef global veya yerel araç olarak kurulabilir. Belgelere göre geliştiricilerin çoğu global kurulumu tercih eder. Yerel araç kullanmak için ise aracı bir tool manifest dosyasında araç bağımlılığı olarak tanımlayan projenin bağımlılıklarını geri yüklersiniz; tool manifest'in kendisi .NET araçları belgelerinde anlatılır.
dotnet tool install --global dotnet-ef
dotnet tool update --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet efGlobal kurulumu güncellemek için dotnet tool update --global dotnet-ef, yerel kurulumu güncellemek için dotnet tool update dotnet-ef kullanılır; belirli bir sürüm için komuta --version ve sürüm numarası eklenir. Araçları bir projede kullanmadan önce o projeye Design paketini eklemeniz gerekir. Son satırdaki parametresiz dotnet ef komutu kurulumu doğrular; belgelere göre çıktısı kullanılan araç sürümünü gösterir. Araç sürümünün projedeki EF Core paketlerinin ana sürümüyle eşleşmesi gerektiğini unutmayın; paketlerin ayrıntısı EF Core kurulumu yazısında.
PMC araçları için Install-Package Microsoft.EntityFrameworkCore.Tools ve güncelleme için Update-Package Microsoft.EntityFrameworkCore.Tools çalıştırılır. Doğrulama komutu Get-Help about_EntityFrameworkCore'dur; belgelere göre bu komutun çıktısı araç sürümünü söylemez. Herhangi bir PMC komutunun yardımını görmek için PowerShell'in Get-Help komutunu kullanırsınız.
Hedef proje ve başlangıç projesi
Komutlar iki projeye atıfta bulunur ve bu ayrım, araçlarla ilgili hataların büyük bölümünün kaynağıdır:
- Hedef proje (project): Komutların dosya eklediği veya sildiği projedir. Varsayılan olarak bulunduğunuz klasördeki projedir; başka bir proje için
--projectseçeneği kullanılır. PMC'de varsayılan, konsolda seçili Default project'tir ve-Projectile değiştirilir. - Başlangıç projesi (startup project): Araçların derleyip çalıştırdığı projedir. Araçlar, bağlantı dizesi ve model yapılandırması gibi bilgileri almak için tasarım zamanında uygulama kodunu çalıştırmak zorundadır. Varsayılan olarak bulunduğunuz klasördeki projedir;
--startup-projectile değiştirilir. PMC'de varsayılan, Solution Explorer'daki Startup Project'tir ve-StartupProjectile değiştirilir.
İki proje çoğu zaman aynıdır. Tipik olarak ayrıştıkları senaryo şudur: EF Core context'i ve entity sınıfları bir .NET sınıf kütüphanesindedir ve bu kütüphaneye bir console veya web uygulaması referans verir. Bu durumda migration dosyaları kütüphaneye yazılır ama araçlar yapılandırmayı almak için uygulamayı çalıştırır:
dotnet ef migrations add AddBlogCreatedTimestamp --project src/Blogging.Data --startup-project src/Blogging.AppMigration'ları context'ten de ayrı bir sınıf kütüphanesine koymak mümkündür; bu yerleşim ve oradaki tasarım zamanı factory ihtiyacı design-time DbContext factory yazısında anlatılıyor.
Platforma özgü projeler ve işlemci mimarisi
Araçlar uygulama kodunu bir .NET çalışma zamanı ile çalıştırmak zorunda olduğu için belgeler .NET MAUI, WinUI, Blazor WebAssembly veya Azure Functions gibi platforma özgü bir uygulamanın başlangıç projesi olarak kullanılmamasını söyler. Bunun yerine migration'lar, IDesignTimeDbContextFactory<TContext> içeren sıradan, platformlar arası bir .NET projesine konur ve bu proje hem hedef hem başlangıç projesi olarak kullanılır. Ayrıca araçları çalıştıran işlem hedef ve başlangıç derlemelerini yükleyebilmelidir: örneğin 64 bit bir araç işlemi yalnızca x86 için derlenmiş bir başlangıç derlemesini yükleyemez. Belgeler AnyCPU bir migration projesini tercih etmeyi önerir ve --runtime seçeneğinin yalnızca bir runtime identifier için paket geri yüklemesini kontrol ettiğini, mevcut araç işleminin mimarisini değiştirmediğini vurgular.
Ortam ve uygulamaya argüman iletmek
ASP.NET Core projelerinde ortamı komut satırından belirtebilirsiniz. Bu ve diğer ek argümanlar uygulamaya, yani Program.CreateHostBuilder metoduna iletilir. -- işareti, dotnet ef aracına ondan sonraki her şeyi seçenek olarak ayrıştırmaya çalışmadan argüman olarak görmesini söyler; aracın kullanmadığı tüm ek argümanlar uygulamaya iletilir. PMC'de aynı iş -Args parametresiyle yapılır.
dotnet ef database update -- --environment ProductionUpdate-Database -Args '--environment Production'Ortak seçenekler
Aşağıdaki seçenekler tüm dotnet ef komutlarında kullanılabilir; büyük harfle yazılan kısım, vereceğiniz değerin yer tutucusudur. Bunların dışındaki ek argümanlar uygulamaya iletilir.
| Seçenek | Kısa | Açıklama |
|---|---|---|
| --json | Çıktıyı JSON olarak gösterir. | |
| --context DBCONTEXT | -c | Kullanılacak DbContext sınıfı; yalnızca sınıf adı veya ad alanıyla tam ad. Projede birden fazla context varsa zorunludur. |
| --project PROJECT | -p | Hedef projenin klasörüne göreli yol. Varsayılan geçerli klasördür. |
| --startup-project PROJECT | -s | Başlangıç projesinin klasörüne göreli yol. Varsayılan geçerli klasördür. |
| --framework FRAMEWORK | Proje birden çok hedef framework içeriyorsa kullanılacak olanın Target Framework Moniker değeri. | |
| --configuration CONFIGURATION | Derleme yapılandırması, örneğin Debug veya Release. | |
| --runtime IDENTIFIER | Paket geri yüklemesi yapılacak hedef çalışma zamanının tanımlayıcısı (RID). | |
| --no-build | Projeyi derlemez; derlemenin güncel olduğu durumlar için. | |
| --help | -h | Yardım bilgisini gösterir. |
| --verbose | -v | Ayrıntılı çıktı gösterir. |
| --no-color | Çıktıyı renklendirmez. | |
| --prefix-output | Çıktı satırlarının başına seviye ekler. |
PMC'deki ortak parametreler daha azdır: -Context, -Project, -StartupProject, -Args ve -Verbose. Belgelere göre Context, Project ve StartupProject parametreleri sekme ile tamamlamayı destekler.
EF Core 10: çoklu hedefli projelerde --framework zorunlu
EF Core 10'un orta etkili kırıcı değişikliklerinden biri doğrudan araçlarla ilgilidir. Önceden EF araçları, birden çok framework hedefleyen projelerde hangi framework'ün kullanılacağı belirtilmeden çalışabiliyordu. EF Core 10.0'dan itibaren, proje dosyasında <TargetFramework> yerine <TargetFrameworks> kullanılıyorsa hangi hedefin kullanılacağını --framework ile açıkça belirtmeniz gerekir. Belirtmezseniz belgelere göre "The project targets multiple frameworks. Use the --framework option to specify which target framework to use." hatası fırlatılır.
Belgelerin açıklamasına göre araçlar EF Core 10'da proje bağımlılıkları hakkında daha doğru bilgi almak için ResolvePackageAssets MSBuild görevine dayanmaya başladı ve bu görev birden çok hedef framework içeren projelerde kullanılamıyor. Çözüm, her komutta hedeflerden birini seçmektir. Belgelerdeki örnekler şöyledir:
dotnet ef migrations add MyMigration --framework net9.0
dotnet ef database update --framework net9.0
dotnet ef migrations script --framework net9.0database komutları
dotnet ef database update
Veritabanını son migration'a veya belirtilen bir migration'a günceller. <MIGRATION> argümanı hedef migration'dır ve adla ya da kimlikle (ID) belirtilebilir. 0 özel bir değerdir ve "ilk migration'dan önceki durum" anlamına gelir, yani tüm migration'ları geri alır. Argüman verilmezse son migration hedeflenir. --connection seçeneği, AddDbContext veya OnConfiguring içinde belirtilen bağlantı yerine kullanılacak bağlantı dizesini alır.
dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_stringdotnet ef database drop
Veritabanını siler. --force (-f) onay sormadan siler; --dry-run hangi veritabanının silineceğini gösterir ama silmez. Yanlış ortama bağlı olup olmadığınızdan emin değilseniz önce --dry-run ile kontrol etmek iyi bir alışkanlıktır. PMC karşılığı Drop-Database'dir ve kuru çalıştırma için -WhatIf kullanılır.
dbcontext komutları
- dotnet ef dbcontext info: Bir
DbContexttürü hakkında bilgi verir. - dotnet ef dbcontext list: Kullanılabilir
DbContexttürlerini listeler. Projede birden çok context varsa--contextdeğerini bulmak için kullanışlıdır. - dotnet ef dbcontext script: Migration'ları tamamen atlayarak doğrudan context'ten bir SQL script üretir;
--output(-o) ile dosyaya yazar. - dotnet ef dbcontext scaffold: Bir veritabanı için
DbContextve entity türleri üretir. İki zorunlu argüman alır: bağlantı dizesi ve sağlayıcı (genellikle NuGet paket adı, örneğinMicrosoft.EntityFrameworkCore.SqlServer). Bir tablo için entity türü üretilebilmesi için tablonun birincil anahtarı olmalıdır. Seçenekleri scaffold-dbcontext yazısında ayrıntılı anlatılıyor. - dotnet ef dbcontext optimize: Context'in kullandığı modelin derlenmiş (compiled) bir sürümünü üretir ve sorguları önceden derler.
--output-dir,--namespace,--suffix,--no-scaffold,--precompile-queriesve--nativeaotseçeneklerini alır. Belgeler NativeAOT desteğinin ve önceden derlenmiş sorguların EF 9'da deneysel kabul edildiğini ve bir sonraki sürümde ciddi biçimde değişebileceğini not eder. Compiled model'in ne zaman işe yaradığı DbContext pooling ve compiled query yazısında.
dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContextmigrations komutları
- dotnet ef migrations add <NAME>: Yeni bir migration ekler.
--output-dir(-o) dosyaların yazılacağı klasörü belirler, varsayılanı "Migrations"dır;--namespace(-n) üretilen sınıfların ad alanını belirler. - dotnet ef migrations remove: Son migration'ı kaldırır ve o migration için yapılan kod değişikliklerini geri alır.
--force(-f) son migration'ı hem kodda hem veritabanında geri alır; veritabanına bağlanırken hata olursa yalnızca kod değişikliklerini geri almaya devam eder. - dotnet ef migrations list: Kullanılabilir migration'ları listeler.
--connectionfarklı bir bağlantı dizesi verir;--no-connectveritabanına hiç bağlanmaz. - dotnet ef migrations script [FROM] [TO]: Migration'lardan SQL script üretir.
FROMvarsayılan olarak0,TOson migration'dır.--outputverilmezse script standart çıktıya yazılır.--idempotent(-i) herhangi bir migration'daki veritabanında kullanılabilecek bir script üretir;--no-transactionsSQL transaction ifadelerini üretmez. - dotnet ef migrations bundle: Veritabanını güncelleyen tek dosyalık bir çalıştırılabilir üretir.
--output,--force,--self-contained(.NET çalışma zamanını da pakete katar) ve--target-runtime(-r) seçeneklerini alır. - dotnet ef migrations has-pending-model-changes: Son migration'dan bu yana modelde değişiklik yapılıp yapılmadığını kontrol eder. Belgelere göre bu komut EF Core 8.0'da eklendi. Derleme hattında migration eklemeyi unutan değişiklikleri yakalamak için kullanılabilir; ilgili hata için pending model changes yazısına bakın.
Belgelerdeki script örnekleri, bir migration'ı adıyla ve kimliğiyle hedeflemeyi gösterir. İlk komut boş bir veritabanından InitialCreate'e kadar olan script'i, ikinci komut InitialCreate'ten sonraki tüm migration'ların script'ini üretir:
dotnet ef migrations script 0 InitialCreate
dotnet ef migrations script 20180904195021_InitialCreatePMC karşılıkları
Package Manager Console komutları aynı işlevleri fiil-isim adlarıyla sunar. Seçenek adları da PowerShell üslubuyla yazılır (örneğin --output-dir yerine -OutputDir).
| .NET CLI | Package Manager Console |
|---|---|
| dotnet ef migrations add | Add-Migration |
| dotnet ef migrations remove | Remove-Migration |
| dotnet ef migrations list | Get-Migration |
| dotnet ef migrations script | Script-Migration |
| dotnet ef migrations bundle | Bundle-Migration |
| dotnet ef database update | Update-Database |
| dotnet ef database drop | Drop-Database |
| dotnet ef dbcontext info / list | Get-DbContext |
| dotnet ef dbcontext scaffold | Scaffold-DbContext |
| dotnet ef dbcontext optimize | Optimize-DbContext |
| dotnet ef dbcontext script | Script-DbContext |
Birkaç fark dikkat çekicidir. Script-Migration komutunda -Output verilmezse dosya, belgelere göre uygulamanın çalışma zamanı dosyalarının oluştuğu klasörde üretilmiş bir adla oluşturulur; CLI ise bu durumda script'i standart çıktıya yazar. Bundle-Migration ayrıca -Framework parametresi alır ve varsayılan olarak projedeki ilk hedef framework'ü kullanır. Belgelere göre PMC araçları NativeAOT ve önceden derlenmiş sorgular için gereken kodu üretmeyi şu anda desteklemez; bunun için CLI'daki dbcontext optimize seçenekleri gerekir.
Update-Database 0
Update-Database InitialCreate
Script-Migration 0 InitialCreateMSBuild görevleri ve tasarım zamanı servisleri
Komut satırı araçlarının dışında, EF 9 ile gelen Microsoft.EntityFrameworkCore.Tasks paketi compiled model ve önceden derlenmiş sorguları derleme veya yayın sırasında otomatik üretebilir. Belgeler bunun ağırlıklı olarak NativeAOT yayını için tasarlandığını ve hem NativeAOT desteğinin hem de MSBuild entegrasyonunun deneysel olduğunu, henüz üretim kullanımına uygun olmadığını söyler. Proje <PublishAot>true</PublishAot> içeriyorsa görev varsayılan olarak yayın sırasında çalışır; aksi hâlde EFScaffoldModelStage ve EFPrecompileQueriesStage gibi MSBuild özellikleriyle kontrol edilir. EFOptimizeContext özelliği belgelere göre yalnızca EF Core 9 ve 10'da vardır ve EF Core 11'de kaldırılmıştır.
Araçların kullandığı bazı servisler yalnızca tasarım zamanında kullanılır ve uygulamayla birlikte yayına gitmemeleri için çalışma zamanı servislerinden ayrı yönetilir. Örneğin migration dosyalarını üreten servisi değiştirmek isterseniz başlangıç projenize bir IDesignTimeServices uygulaması eklersiniz. Bu ileri konu design-time DbContext factory yazısında kısaca ele alınıyor.
EF Core 11'de geliştirme aşamasındaki araç yenilikleri
EF Core 11 geliştirme aşamasındadır ve aşağıdaki özellikler belgelerde "EF Core 11'de eklendi" olarak işaretlenmiştir. EF Core 10 kullanan bir projede bu seçenekler yoktur; EF11 yayımlandığında son hâllerini sürüm notlarından kontrol edin.
- Yapılandırma dosyası:
dotnet ef, geçerli klasörden yukarı doğru arayarak bulduğu ilk.config/dotnet-ef.jsondosyasındanproject,startupProject,framework,contextgibi varsayılan seçenek değerlerini okuyabilecek. Komut satırında açıkça verilen seçenekler her zaman dosyadaki değerlerden önceliklidir. - Tek adımda oluştur ve uygula:
database updatekomutuna--addseçeneği geliyor; yeni bir migration'ı oluşturup Roslyn ile çalışma zamanında derleyerek tek adımda uygular. Migration dosyaları yine diske kaydedilir. - Bağlantısız kaldırma:
migrations removekomutu--connectionve--offlineseçeneklerini,database dropise--connectionseçeneğini alacak.--offlineile--forcebirlikte kullanılamaz, çünkü--forcemigration'ın uygulanıp uygulanmadığını kontrol etmek için veritabanına bağlanmayı gerektirir. - Joker context:
migrations list,migrations script,database updatevedatabase dropkomutlarında--context "*"ile projedeki tüm context'ler hedeflenebilecek. - PMC'de -NoBuild:
Add-MigrationveUpdate-Databasederleme adımını atlayan-NoBuildparametresini alacak. - Çıktı ayrımı: Araç tüm log ve durum mesajlarını standart hataya yazacak, standart çıktıyı yalnızca komutun beklenen çıktısına (örneğin
migrations scriptiçin yalnızca SQL) ayıracak.
Sık yapılan hatalar
- Komutu yanlış klasörde çalıştırmak: Varsayılan hedef ve başlangıç projesi bulunduğunuz klasördeki projedir. Proje başka yerdeyse
--projectve--startup-projectverin. - Birden çok context varken --context vermemek: Belgelere göre bu durumda seçenek zorunludur; adları
dotnet ef dbcontext listile görebilirsiniz. - Design paketi olmadan çalıştırmak: Araçları bir projede kullanmadan önce Design paketini eklemelisiniz.
- Platforma özgü projeyi başlangıç projesi yapmak: MAUI, WinUI, Blazor WebAssembly veya Azure Functions projeleri yerine ayrı, platformlar arası bir migration projesi kullanın.
- Çoklu hedefli projede framework belirtmemek: EF Core 10 ile
--frameworkzorunlu hâle geldi. - database update ile geri gitmeyi hafife almak: Daha eski bir migration adı vermek, aradaki tüm migration'ların
Downişlemlerini çalıştırır. - --no-build ile eski derlemeyi kullanmak: Bu seçenek yalnızca derleme güncelse kullanılmalıdır; aksi hâlde araç eski kodla çalışır.
Sık Sorulan Sorular
dotnet ef mi, Package Manager Console mu kullanmalıyım?
İkisi aynı işlevi sunar. Visual Studio'da çalışıyorsanız belgeler daha bütünleşik bir deneyim sunduğu için PMC araçlarını önerir. Komut satırında, Linux veya macOS üzerinde ya da bir derleme hattında çalışıyorsanız dotnet ef doğru seçimdir.
Araçlar neden uygulamamı çalıştırıyor?
Çünkü bağlantı dizesi ve model yapılandırması gibi bilgileri ancak context'i oluşturarak alabilirler. Başlangıç projesi derlenir ve context oluşturulur; bunun hangi yollarla yapıldığı design-time DbContext factory yazısında anlatılıyor.
Global mi yerel mi kurmalıyım?
Belgelere göre geliştiricilerin çoğu global kurulumu tercih eder. Yerel kurulumda araç, projenin tool manifest dosyasında bir bağımlılık olarak tanımlanır ve o projenin araç bağımlılıkları geri yüklenerek kullanılır; güncelleme komutu da --global olmadan yazılır. Hangisini seçerseniz seçin, araç sürümünü projedeki EF Core paketlerinin ana sürümüyle aynı tutun.
migrations script ile dbcontext script farkı nedir?
migrations script, migration'lardan, yani şemanın adım adım geçmişinden script üretir ve var olan bir veritabanını güncellemek için kullanılır. dbcontext script ise belgelere göre migration'ları tamamen atlayarak doğrudan modelden script üretir.
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 · EF Core migration rehberi · Design-time DbContext factory · EF Core kurulumu