Dela via

Entity Framework Core-verktygsreferens – .NET Core CLI

  • Artikel

CLI-verktygen (command-line interface) för Entity Framework Core utför utvecklingsuppgifter vid designtid. De skapar till exempel migreringar, tillämpar migreringar och genererar kod för en modell baserat på en befintlig databas. Kommandona är ett tillägg till kommandot dotnet, som är del av .NET Core SDK. Dessa verktyg fungerar med .NET Core-projekt.

När du använder Visual Studio bör du överväga att använda Package Manager-konsolverktyg i stället för CLI-verktygen. Package Manager-konsolverktyg automatiskt:

  • Fungerar med det aktuella projektet som valts i Package Manager-konsolen utan att du behöver byta katalog manuellt.
  • Öppnar filer som genereras av ett kommando när kommandot har slutförts.
  • Tillhandahåller tabbordning av kommandon, parametrar, projektnamn, kontexttyper och migreringsnamn.

Installera verktygen

dotnet ef kan installeras som antingen ett globalt eller lokalt verktyg. De flesta utvecklare föredrar att installera dotnet ef som ett globalt verktyg med hjälp av följande kommando:

dotnet tool install --global dotnet-ef

Om du vill använda det som ett lokalt verktyg återställer du beroendena för ett projekt som deklarerar det som ett verktygsberoende med hjälp av en -verktygsmanifestfil.

Uppdatera verktyget med hjälp av följande kommando:

dotnet tool update --global dotnet-ef

Innan du kan använda verktygen i ett visst projekt måste du lägga till Microsoft.EntityFrameworkCore.Design paketet i det.

dotnet add package Microsoft.EntityFrameworkCore.Design

Verifiera installationen

Kör följande kommandon för att kontrollera att EF Core CLI-verktyg är korrekt installerade:

dotnet ef

Utdata från kommandot identifierar versionen av de verktyg som används:


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065

<Usage documentation follows, not shown.>

Uppdatera verktygen

Använd dotnet tool update --global dotnet-ef för att uppdatera de globala verktygen till den senaste tillgängliga versionen. Om du har verktygen installerade lokalt i projektet använder du dotnet tool update dotnet-ef. Installera en specifik version genom att lägga till --version <VERSION> till kommandot. Mer information finns i avsnittet Uppdatera i dotnet-verktygsdokumentationen.

Använda verktygen

Innan du använder verktygen kan du behöva skapa ett startprojekt eller ange miljön.

Målprojekt och startprojekt

Kommandona refererar till ett projekt och ett startprojekt.

  • Det projektet kallas även målprojekt eftersom det är där kommandona lägger till eller tar bort filer. Som standard är projektet i den aktuella katalogen målprojektet. Du kan ange ett annat projekt som målprojekt med hjälp av alternativet --project.

  • Det är -startprojektet som verktygen bygger och kör. Verktygen måste köra programkod vid designtillfället för att få information om projektet, till exempel databasanslutningssträngen och konfigurationen av modellen. Som standard är projektet i den aktuella katalogen startprojektet. Du kan ange ett annat projekt som startprojekt med hjälp av alternativet --startup-project.

Startprojektet och målprojektet är ofta samma projekt. Ett typiskt scenario där de är separata projekt är när:

  • EF Core-kontext- och entitetsklasserna finns i ett .NET Core-klassbibliotek.
  • En .NET Core-konsolapp eller webbapp refererar till klassbiblioteket.

Det är också möjligt att placera migreringskod i ett klassbibliotek separat från EF Core-kontexten.

Andra målramverk

CLI-verktygen fungerar med .NET Core-projekt och .NET Framework-projekt. Appar som har EF Core-modellen i ett .NET Standard-klassbibliotek kanske inte har något .NET Core- eller .NET Framework-projekt. Detta gäller till exempel för Xamarin- och Universal Windows Platform-appar. I sådana fall kan du skapa ett .NET Core-konsolappprojekt vars enda syfte är att fungera som startprojekt för verktygen. Projektet kan vara ett dummyprojekt utan verklig kod – det behövs bara för att ange ett mål för verktygen.

Viktig

Xamarin.Android, Xamarin.iOS, Xamarin.Mac är nu direkt integrerade i .NET (från och med .NET 6) som .NET för Android, .NET för iOS och .NET för macOS. Om du skapar med dessa projekttyper i dag bör de uppgraderas till .NET SDK-liknande projekt för fortsatt support. Mer information om hur du uppgraderar Xamarin-projekt till .NET finns i dokumentationen Upgrade from Xamarin to .NET & .NET MAUI.

Varför krävs ett dummyprojekt? Som tidigare nämnts måste verktygen köra programkod vid designtillfället. För att göra det måste de använda .NET Core-runtime. När EF Core-modellen finns i ett projekt som riktar sig till .NET Core, eller .NET Framework, använder EF Core-verktygen körningen från projektet. Det kan de inte göra om EF Core-modellen finns i ett klassbibliotek för .NET Standard. .NET Standard är inte en faktisk .NET-implementering. det är en specifikation av en uppsättning API:er som .NET-implementeringar måste stödja. Därför räcker det inte med .NET Standard för att EF Core-verktygen ska kunna köra programkod. Det dummy-projekt som du skapar för att använda som startprojekt ger en konkret målplattform där verktygen kan läsa in klassbiblioteket för .NET Standard.

ASP.NET Core-miljö

Du kan ange miljön för ASP.NET Core-projekt på kommandoraden. Detta och eventuella ytterligare argument skickas till Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Tips

Det ---token dirigerar dotnet ef att behandla allt som följer som ett argument och inte försöka parsa dem som alternativ. Eventuella extra argument som inte används av dotnet ef vidarebefordras till appen.

Vanliga alternativ

Alternativ Kort Beskrivning
--json Visa JSON-utdata.
--context <DBCONTEXT> -c Den DbContext klass som ska användas. Endast klassnamn eller fullständigt kvalificerat med namnområden. Om det här alternativet utelämnas hittar EF Core kontextklassen. Om det finns flera kontextklasser krävs det här alternativet.
--project <PROJECT> -p Relativ sökväg till projektmappen för målprojektet. Standardvärdet är den aktuella mappen.
--startup-project <PROJECT> -s Relativ sökväg till projektmappen för startprojektet. Standardvärdet är den aktuella mappen.
--framework <FRAMEWORK> Target Framework Moniker för målramverket. Använd när projektfilen anger flera målramverk och du vill välja ett av dem.
--configuration <CONFIGURATION> Byggkonfigurationen, till exempel: Debug eller Release.
--runtime <IDENTIFIER> Identifieraren för målkörningsmiljön som paketen ska återställas för. En lista över Runtime Identifiers (RID) finns i RID-katalogen.
--no-build Skapa inte projektet. Avsedd att användas när versionen är up-to-date.
--help -h Visa hjälpinformation.
--verbose -v Visa utförliga utdata.
--no-color Färglägga inte utdata.
--prefix-output Prefixa utdata med nivå.

Eventuella ytterligare argument skickas till programmet.

dotnet ef database drop

Tar bort databasen.

Alternativ:

Alternativ Kort Beskrivning
--force -f Bekräfta inte.
--dry-run Visa vilken databas som skulle tas bort, men släpp den inte.

De vanliga alternativen visas ovan.

dotnet ef database update

Uppdaterar databasen till den senaste migreringen eller till en angiven migrering.

Argument:

Argument Beskrivning
<MIGRATION> Målmigreringen. Migreringar kan identifieras med namn eller ID. Talet 0 är ett specialfall som betyder före den första migreringen och orsakar att alla migreringar återställs. Om ingen migrering har angetts är kommandot standard för den senaste migreringen.

Alternativ:

Alternativ Beskrivning
--connection <CONNECTION> Anslutningssträngen till databasen. Standardvärdet är det som specificeras i AddDbContext eller OnConfiguring.

De vanliga alternativen visas ovan.

I följande exempel uppdateras databasen till en angiven migrering. Den första använder migreringsnamnet och det andra använder migrerings-ID:t och en angiven anslutning:

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string

dotnet ef dbcontext info

Hämtar information om en DbContext typ.

De vanliga alternativen visas ovan.

dotnet ef dbcontext list

Visar tillgängliga typer av DbContext.

De vanliga alternativen visas ovan.

dotnet ef dbcontext optimize

Genererar en kompilerad version av modellen som används av DbContext och förkompilerar frågorna.

För mer information, se kompilerade modeller.

Alternativ:

Alternativ Kort Beskrivning
--output-dir <PATH> -o Katalogen att lägga filer i. Sökvägarna är relativa till projektkatalogen.
--namespace <NAMESPACE> -n Namnområdet som ska användas för alla genererade klasser. Som standard genereras från rotnamnområdet och utdatakatalogen plus CompiledModels.
--suffix <SUFFIX> Suffixet som ska kopplas till namnet på alla genererade filer. T.ex. .g kan användas för att indikera att dessa filer innehåller genererad kod
--no-scaffold Generera inte en kompilerad modell. Detta används när den kompilerade modellen redan har genererats.
--precompile-queries Generera förkompilerade frågor. Detta krävs för NativeAOT-kompilering om målprojektet innehåller frågor
--nativeaot Generera ytterligare kod i den kompilerade modellen som krävs för NativeAOT-kompilering och förkompilerade frågor

Observera

NativeAOT-stöd och förkompilerade frågor anses vara experimentella i EF 9 och kan ändras dramatiskt i nästa version.

De vanliga alternativen visas ovan.

I följande exempel används standardinställningarna och fungerar om det bara finns en DbContext i projektet:

dotnet ef dbcontext optimize

I följande exempel optimeras modellen för kontexten med det angivna namnet och placerar den i en separat mapp och ett namnområde:

dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext

dotnet ef dbcontext scaffold

Genererar kod för en DbContext och entitetstyper för en databas. För att det här kommandot ska generera en entitetstyp måste databastabellen ha en primärnyckel.

Argument:

Argument Beskrivning
<CONNECTION> Anslutningssträngen till databasen. För ASP.NET Core 2.x-projekt kan värdet vara name=<namnet på anslutningssträngen>. I så fall kommer namnet från de konfigurationskällor som har konfigurerats för projektet.
<PROVIDER> Providern som ska användas. Det här är vanligtvis namnet på NuGet-paketet, till exempel: Microsoft.EntityFrameworkCore.SqlServer.

Alternativ:

Alternativ Kort Beskrivning
--data-annotations -d Använd attribut för att konfigurera modellen (där det är möjligt). Om det här alternativet utelämnas används endast api:et fluent.
--context <NAME> -c Namnet på den DbContext klass som ska genereras.
--context-dir <PATH> Katalogen som DbContext-klassfilen ska placeras i. Sökvägarna är relativa till projektkatalogen. Namnrymder härleds från mappnamnen.
--context-namespace <NAMESPACE> Namnområdet som ska användas för den genererade DbContext-klassen. Notera: åsidosätter --namespace.
--force -f Skriv över befintliga filer.
--output-dir <PATH> -o Katalogen som entitetsklassfiler ska placeras i. Sökvägarna är relativa till projektkatalogen.
--namespace <NAMESPACE> -n Namnområdet som ska användas för alla genererade klasser. Som standard genereras från rotnamnområdet och utdatakatalogen.
--schema <SCHEMA_NAME>... Scheman för tabeller och vyer som ska generera entitetstyper för. Om du vill ange flera scheman upprepar du --schema för var och en. Om det här alternativet utelämnas inkluderas alla scheman. Om det här alternativet används inkluderas alla tabeller och vyer i schemana i modellen, även om de inte uttryckligen ingår med hjälp av --table.
--table <TABLE_NAME>... -t Tabeller och vyer som ska generera entitetstyper för. Om du vill ange flera tabeller upprepar du -t eller --table för var och en. Tabeller eller vyer i ett visst schema kan inkluderas med formatet "schema.table" eller "schema.view". Om det här alternativet utelämnas inkluderas alla tabeller och vyer.
--use-database-names Använd tabell-, vy-, sekvens- och kolumnnamn exakt som de visas i databasen. Om det här alternativet utelämnas ändras databasnamnen så att de bättre överensstämmer med C#-namnformatkonventionerna.
--no-onconfiguring Undertrycker generering av metoden OnConfiguring i den genererade DbContext-klassen.
--no-pluralize Använd inte pluraliseraren.

De vanliga alternativen visas ovan.

I det följande exemplet uppbyggs alla scheman och tabeller, och de nya filerna placeras i mappen Models.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models

I exemplet nedan struktureras endast utvalda tabeller och kontexten genereras i en separat mapp med ett angivet namn och namnområde.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models -t Blog -t Post --context-dir Context -c BlogContext --context-namespace New.Namespace

I följande exempel läss anslutningssträngen från projektets konfigurationsuppsättning med hjälp av verktyget Secret Manager.

dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer

I följande exempel hoppar du över en OnConfiguring metod. Detta kan vara användbart när du vill konfigurera DbContext utanför klassen. Till exempel konfigurerar ASP.NET Core-appar vanligtvis den i Startup.ConfigureServices.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

Genererar ett SQL-skript från DbContext. Kringgår alla migreringar.

Alternativ:

Alternativ Kort Beskrivning
--output <FILE> -o Filen som resultatet ska skrivas till.

De vanliga alternativen visas ovan.

dotnet ef migrations add

Lägger till en ny migrering.

Argumenten

Argument Beskrivning
<NAME> Namnet på migreringen.

Alternativ:

Alternativ Kort Beskrivning
--output-dir <PATH> -o Katalogen som används för att mata ut filerna. Sökvägarna är relativa till målprojektkatalogen. Standardinställningen är "Migreringar".
--namespace <NAMESPACE> -n Namnområdet som ska användas för de genererade klasserna. Är som standard genererat från utdatakatalogen.

De vanliga alternativen visas ovan.

dotnet ef migrations bundle

Skapar en körbar fil för att uppdatera databasen.

Alternativ:

Alternativ Kort Beskrivning
--output <FILE> -o Sökvägen till den körbara fil som ska skapas.
--force -f Skriv över befintliga filer.
--self-contained Paketera .NET-körmiljön så att den inte behöver installeras på datorn.
--target-runtime <RUNTIME_IDENTIFIER> -r Den målmiljö som ska paketeras för.

De vanliga alternativen visas ovan.

dotnet ef migrations has-pending-model-changes

Not

Det här kommandot lades till i EF Core 8.0.

Kontrollerar om några ändringar har gjorts i modellen sedan den senaste migreringen.

Alternativ:

De vanliga alternativen visas ovan.

dotnet ef migrations list

Visar tillgängliga migreringar.

Alternativ:

Alternativ Beskrivning
--connection <CONNECTION> Anslutningssträngen till databasen. Standardvärdet är det som anges i AddDbContext eller OnConfiguring.
--no-connect Anslut inte till databasen.

De vanliga alternativen visas ovan.

dotnet ef migrations remove

Tar bort den senaste migreringen och återställer de kodändringar som gjordes för den senaste migreringen.

Alternativ:

Alternativ Kort Beskrivning
--force -f Återställ den senaste migreringen och återställ både kod- och databasändringar som gjordes för den senaste migreringen. Fortsätter att återställa endast kodändringarna om ett fel inträffar när du ansluter till databasen.

De vanliga alternativen visas ovan.

dotnet ef migrations script

Genererar ett SQL-skript från migreringar.

Argument:

Argument Beskrivning
<FROM> Påbörjandet av migreringen. Migreringar kan identifieras med namn eller ID. Talet 0 är ett specialfall som betyder att kommer före den första migreringen. Standardvärdet är 0.
<TO> Den avslutande migreringen. Standardinställningen är den senaste migreringen.

Alternativ:

Alternativ Kort Beskrivning
--output <FILE> -o Filen som skriptet ska skrivas till.
--idempotent -i Generera ett skript som kan användas i en databas vid valfri migrering.
--no-transactions Generera inte SQL-transaktionsinstruktioner.

De vanliga alternativen visas ovan.

I följande exempel skapas ett skript för migreringen InitialCreate:

dotnet ef migrations script 0 InitialCreate

I följande exempel skapas ett skript för alla migreringar efter migreringen InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Ytterligare resurser