Delen via

Referentie voor Entity Framework Core-hulpprogramma's - .NET Core CLI

  • Artikel

De opdrachtregelinterface (CLI)-tools voor Entity Framework Core voeren ontwerptijdontwikkelingstaken uit. Ze maken bijvoorbeeld migraties, passen migraties toe en genereren code voor een model op basis van een bestaande database. De opdrachten zijn een uitbreiding op de platformoverschrijdende dotnet opdracht, die deel uitmaakt van de .NET Core SDK. Deze hulpprogramma's werken met .NET Core-projecten.

Wanneer u Visual Studio gebruikt, kunt u overwegen de Package Manager Console-hulpprogramma's te gebruiken in plaats van de CLI-hulpprogramma's. Hulpprogramma's van de Package Manager-console automatisch uitvoeren:

  • Werkt met het huidige project dat is geselecteerd in de Package Manager Console zonder dat u handmatig van directory hoeft te wisselen.
  • Hiermee opent u bestanden die zijn gegenereerd door een opdracht nadat de opdracht is voltooid.
  • Biedt tabbladvoltooiing van opdrachten, parameters, projectnamen, contexttypen en migratienamen.

De hulpprogramma's installeren

dotnet ef kan worden geïnstalleerd als een globaal of lokaal hulpprogramma. De meeste ontwikkelaars geven de voorkeur aan het installeren van dotnet ef als een globaal hulpprogramma met behulp van de volgende opdracht:

dotnet tool install --global dotnet-ef

Als u het als een lokaal hulpprogramma wilt gebruiken, herstelt u de afhankelijkheden van een project dat het als hulpprogramma-afhankelijkheid declareert met behulp van een manifestbestand van het hulpprogramma.

Werk het hulpprogramma bij met behulp van de volgende opdracht:

dotnet tool update --global dotnet-ef

Voordat u de hulpprogramma's voor een specifiek project kunt gebruiken, moet u het Microsoft.EntityFrameworkCore.Design pakket eraan toevoegen.

dotnet add package Microsoft.EntityFrameworkCore.Design

Installatie controleren

Voer de volgende opdrachten uit om te controleren of EF Core CLI-hulpprogramma's correct zijn geïnstalleerd:

dotnet ef

De uitvoer van de opdracht identificeert de versie van de hulpprogramma's die worden gebruikt:


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

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

<Usage documentation follows, not shown.>

De hulpprogramma's bijwerken

Gebruik dotnet tool update --global dotnet-ef om de globale hulpprogramma's bij te werken naar de meest recente beschikbare versie. Als u de hulpprogramma's lokaal in uw project hebt geïnstalleerd, gebruikt u dotnet tool update dotnet-ef. Installeer een specifieke versie door --version <VERSION> toe te voegen aan uw opdracht. Zie de sectie Bijwerken van de dotnet-hulpprogrammadocumentatie voor meer informatie.

De hulpprogramma's gebruiken

Voordat u de hulpprogramma's gebruikt, moet u mogelijk een opstartproject maken of de omgeving instellen.

Doelproject en opstartproject

De opdrachten verwijzen naar een project en een opstartproject.

  • Het project wordt ook wel het doelproject genoemd, omdat het is waar de opdrachten bestanden toevoegen of verwijderen. Standaard is het project in de huidige map het doelproject. U kunt een ander project opgeven als doelproject met behulp van de optie --project.

  • Het startupproject is het project dat de tools bouwen en uitvoeren. De hulpprogramma's moeten toepassingscode uitvoeren tijdens het ontwerp om informatie over het project op te halen, zoals de databaseverbindingsreeks en de configuratie van het model. Het project in de huidige map is standaard het opstartproject. U kunt een ander project opgeven als opstartproject met behulp van de optie --startup-project.

Het opstartproject en het doelproject zijn vaak hetzelfde project. Een typisch scenario waarin ze afzonderlijke projecten zijn, is wanneer:

  • De EF Core-context- en entiteitsklassen bevinden zich in een .NET Core-klassebibliotheek.
  • Een .NET Core-console-app of -web-app verwijst naar de klassebibliotheek.

Het is ook mogelijk om migratiecode in een klassebibliotheek te gescheiden van de EF Core-context.

Andere doelplatformen

De CLI-hulpprogramma's werken met .NET Core-projecten en .NET Framework-projecten. Apps met het EF Core-model in een .NET Standard-klassebibliotheek hebben mogelijk geen .NET Core- of .NET Framework-project. Dit geldt bijvoorbeeld voor Xamarin- en Universal Windows Platform-apps. In dergelijke gevallen kunt u een .NET Core-console-app-project maken waarvan het enige doel is om te fungeren als opstartproject voor de hulpprogramma's. Het project kan een dummyproject zonder echte code zijn en is alleen nodig om een doel voor de gereedschappen te bieden.

Belangrijk

Xamarin.Android, Xamarin.iOS, Xamarin.Mac zijn nu rechtstreeks geïntegreerd in .NET (te beginnen met .NET 6) als .NET voor Android, .NET voor iOS en .NET voor macOS. Als u vandaag met deze projecttypen bouwt, moeten ze worden bijgewerkt naar .NET SDK-projecten voor continue ondersteuning. Zie voor meer informatie over het upgraden van Xamarin-projecten naar .NET de Upgrade van Xamarin naar .NET & .NET MAUI documentatie.

Waarom is een dummyproject vereist? Zoals eerder vermeld, moeten de hulpprogramma's toepassingscode uitvoeren tijdens het ontwerp. Hiervoor moeten ze de .NET Core-runtime gebruiken. Wanneer het EF Core-model zich in een project bevindt dat gericht is op .NET Core of .NET Framework, lenen de EF Core-hulpprogramma's de runtime van het project. Ze kunnen dat niet doen als het EF Core-model zich in een .NET Standard-klassebibliotheek bevindt. De .NET Standard is geen echte .NET-implementatie; het is een specificatie van een set API's die .NET-implementaties moeten ondersteunen. Daarom is .NET Standard niet voldoende voor de EF Core-hulpprogramma's om toepassingscode uit te voeren. Het dummyproject dat u maakt om te gebruiken als opstartproject biedt een concreet doelplatform waarin de hulpprogramma's de .NET Standard-klassebibliotheek kunnen laden.

ASP.NET Core-omgeving

U kunt de omgeving opgeven voor ASP.NET Core-projecten via de command-line interface. Deze en eventuele aanvullende argumenten worden doorgegeven aan Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Fooi

Het -- token leidt dotnet ef om alles dat volgt als argument te behandelen en deze niet als opties te parseren. Eventuele extra argumenten die niet door dotnet ef worden gebruikt, worden doorgestuurd naar de app.

Algemene opties

Optie Kort Beschrijving
--json JSON-uitvoer weergeven.
--context <DBCONTEXT> -c De DbContext klasse om te gebruiken. Alleen klassenaam of volledig gekwalificeerde naam met naamruimten. Als deze optie wordt weggelaten, vindt EF Core de contextklasse. Als er meerdere contextklassen zijn, is deze optie vereist.
--project <PROJECT> -p Relatief pad naar de projectmap van het doelproject. De standaardwaarde is de huidige map.
--startup-project <PROJECT> -s Relatief pad naar de projectmap van het opstartproject. De standaardwaarde is de huidige map.
--framework <FRAMEWORK> De Target Framework Moniker voor het doelframework. Gebruik deze optie wanneer het projectbestand meerdere doelframeworks opgeeft en u een van deze frameworks wilt selecteren.
--configuration <CONFIGURATION> De buildconfiguratie, bijvoorbeeld: Debug of Release.
--runtime <IDENTIFIER> De id van de doelruntime waarvoor pakketten moeten worden hersteld. Zie de RID-catalogusvoor een lijst met runtime-id's (RID's).
--no-build Bouw het project niet. Bedoeld om te worden gebruikt wanneer de build up-to-date is.
--help -h Help-informatie weergeven.
--verbose -v Toon uitgebreide uitvoer.
--no-color Kleur de uitvoer niet.
--prefix-output Voorzie de uitvoer van een niveau-indicatie.

Eventuele extra argumenten worden doorgegeven aan de toepassing.

dotnet ef database drop

Hiermee verwijdert u de database.

Opties:

Optie Kort Beschrijving
--force -f Bevestig niet.
--dry-run Toon welke database zou worden verwijderd, maar verwijder deze niet.

De algemene opties worden hierboven vermeld.

dotnet ef database update

Hiermee wordt de database bijgewerkt naar de laatste migratie of naar een opgegeven migratie.

Argumenten:

Argument Beschrijving
<MIGRATION> De doelmigratie. Migraties kunnen worden geïdentificeerd op naam of id. Het getal 0 is een speciaal geval, wat betekent dat zich voor de eerste migratie bevindt en dit leidt ertoe dat alle migraties worden teruggedraaid. Als er geen migratie is opgegeven, wordt de opdracht standaard ingesteld op de laatste migratie.

Opties:

Optie Beschrijving
--connection <CONNECTION> De verbindingsreeks voor de database. Standaard ingesteld op de waarde die is opgegeven in AddDbContext of OnConfiguring.

De algemene opties worden hierboven vermeld.

In de volgende voorbeelden wordt de database bijgewerkt naar een opgegeven migratie. De eerste gebruikt de migratienaam en de tweede maakt gebruik van de migratie-id en een opgegeven verbinding:

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

dotnet ef dbcontext info

Haalt informatie op over een DbContext-type.

De algemene opties worden hierboven vermeld.

dotnet ef dbcontext list

Lijsten met beschikbare DbContext typen.

De algemene opties worden hierboven vermeld.

dotnet ef dbcontext optimize

Genereert een gecompileerde versie van het model dat wordt gebruikt door de DbContext en precompileert queries.

Zie Gecompileerde modellen voor meer informatie.

Opties:

Optie Kort Beschrijving
--output-dir <PATH> -o De map waarin bestanden moeten worden geplaatst. Paden zijn relatief ten opzichte van de projectmap.
--namespace <NAMESPACE> -n De naamruimte die moet worden gebruikt voor alle gegenereerde klassen. Wordt standaard ingesteld op gegenereerd vanuit de hoofdnaamruimte en de uitvoermap plus CompiledModels.
--suffix <SUFFIX> Het achtervoegsel dat moet worden gekoppeld aan de naam van alle gegenereerde bestanden. Bijvoorbeeld .g kan worden gebruikt om aan te geven dat deze bestanden gegenereerde code bevatten
--no-scaffold Genereer geen gecompileerd model. Dit wordt gebruikt wanneer het gecompileerde model al is gegenereerd.
--precompile-queries Genereer vooraf gecompileerde query's. Dit is vereist voor nativeAOT-compilatie als het doelproject query's bevat
--nativeaot Extra code genereren in het gecompileerde model dat is vereist voor nativeAOT-compilatie en vooraf gecompileerde query's

Notitie

NativeAOT-ondersteuning en vooraf gecompileerde query's worden beschouwd als experimenteel in EF 9 en kunnen in de volgende release aanzienlijk veranderen.

De algemene opties worden hierboven vermeld.

In het volgende voorbeeld worden de standaardinstellingen gebruikt en werkt dit als er slechts één DbContext in het project is:

dotnet ef dbcontext optimize

In het volgende voorbeeld wordt het model geoptimaliseerd voor de context met de opgegeven naam en wordt het in een afzonderlijke map en naamruimte geplaatst:

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

dotnet ef dbcontext scaffold

Hiermee genereert u code voor een DbContext en entiteitstypen voor een database. Als u met deze opdracht een entiteitstype wilt genereren, moet de databasetabel een primaire sleutel hebben.

Argumenten:

Discussië Beschrijving
<CONNECTION> De verbindingsreeks voor de database. Voor ASP.NET Core 2.x-projecten kan de waarde naam=<naam van de verbindingsreeks>. In dat geval is de naam afkomstig van de configuratiebronnen die zijn ingesteld voor het project.
<PROVIDER> De te gebruiken provider. Dit is meestal de naam van het NuGet-pakket, bijvoorbeeld: Microsoft.EntityFrameworkCore.SqlServer.

Opties:

Optie Kort Beschrijving
--data-annotations -d Gebruik kenmerken om het model te configureren (indien mogelijk). Als deze optie wordt weggelaten, wordt alleen de fluent-API gebruikt.
--context <NAME> -c De naam van de DbContext-klasse die moet worden gegenereerd.
--context-dir <PATH> De map waarin het DbContext klassebestand moet worden geplaatst. Paden zijn relatief ten opzichte van de projectmap. Naamruimten worden afgeleid van de mapnamen.
--context-namespace <NAMESPACE> De naamruimte die moet worden gebruikt voor de gegenereerde DbContext-klasse. Opmerking: overschrijft --namespace.
--force -f Bestaande bestanden overschrijven.
--output-dir <PATH> -o De map waarin entiteitsklassebestanden worden geplaatst. Paden zijn relatief ten opzichte van de projectmap.
--namespace <NAMESPACE> -n De naamruimte die moet worden gebruikt voor alle gegenereerde klassen. Standaardinstelling is dat het wordt gegenereerd op basis van de hoofdnaamruimte en de uitvoermap.
--schema <SCHEMA_NAME>... De schema's van tabellen en weergaven voor het genereren van entiteitstypen. Als u meerdere schema's wilt opgeven, herhaalt u --schema voor elk schema. Als deze optie wordt weggelaten, worden alle schema's opgenomen. Als deze optie wordt gebruikt, worden alle tabellen en weergaven in het model opgenomen in het model, zelfs als ze niet expliciet zijn opgenomen met behulp van --table.
--table <TABLE_NAME>... -t De tabellen en weergaven waarvoor entiteitstypen moeten worden gegenereerd. Als u meerdere tabellen wilt opgeven, herhaalt u -t of --table voor elke tabel. Tabellen of weergaven in een specifiek schema kunnen worden opgenomen met de indeling schema.table of schema.view. Als deze optie wordt weggelaten, worden alle tabellen en weergaven opgenomen.
--use-database-names Gebruik tabel-, weergave-, volgorde- en kolomnamen precies zoals ze worden weergegeven in de database. Als deze optie wordt weggelaten, worden databasenamen gewijzigd zodat ze beter voldoen aan de C#-naamstijlconventies.
--no-onconfiguring Onderdrukt het genereren van de OnConfiguring methode in de gegenereerde DbContext klasse.
--no-pluralize Gebruik de pluralizer niet.

De algemene opties worden hierboven vermeld.

In het volgende voorbeeld worden alle schema's en tabellen gestructureerd en worden de nieuwe bestanden in de map Modellen geplaatst.

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

In het volgende voorbeeld worden alleen geselecteerde tabellen geconfigureerd en wordt de context in een afzonderlijke map met een opgegeven naam en naamruimte geplaatst.

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

In het volgende voorbeeld wordt de verbindingsreeks uit de configuratieset van het project gelezen met behulp van het hulpprogramma 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

In het volgende voorbeeld wordt het scaffolding van een OnConfiguring-methode overgeslagen. Dit kan handig zijn als u dbContext buiten de klasse wilt configureren. ASP.NET Core-apps configureren deze bijvoorbeeld meestal in 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

Hiermee wordt een SQL-script gegenereerd vanuit DbContext. Omzeilt alle migraties.

Opties:

Optie Kort Beschrijving
--output <FILE> -o Het bestand waar het resultaat naar moet worden geschreven.

De algemene opties worden hierboven vermeld.

dotnet ef migrations add

Hiermee voegt u een nieuwe migratie toe.

Argumenten:

Discussie Beschrijving
<NAME> De naam van de migratie.

Opties:

Optie Kort Beschrijving
--output-dir <PATH> -o De map die wordt gebruikt om de bestanden uit te voeren. Paden zijn relatief ten opzichte van de doelprojectmap. De standaardwaarde is 'Migraties'.
--namespace <NAMESPACE> -n De naamruimte die moet worden gebruikt voor de gegenereerde klassen. Wordt standaard gegenereerd uit de uitvoermap.

De algemene opties worden hierboven vermeld.

dotnet ef migrations bundle

Hiermee maakt u een uitvoerbaar bestand om de database bij te werken.

Opties:

Optie Kort Beschrijving
--output <FILE> -o Het pad naar het uitvoerbare bestand dat moet worden gemaakt.
--force -f Bestaande bestanden overschrijven.
--self-contained Bundel ook de .NET-runtime zodat deze niet hoeft te worden geïnstalleerd op de computer.
--target-runtime <RUNTIME_IDENTIFIER> -r De doelruntime waarvoor moet worden gebundeld.

De algemene opties worden hierboven vermeld.

dotnet ef migrations has-pending-model-changes

Notitie

Deze opdracht is toegevoegd in EF Core 8.0.

Controleert of er wijzigingen zijn aangebracht in het model sinds de laatste migratie.

Opties:

De algemene opties worden hierboven vermeld.

dotnet ef migrations list

Hier vindt u een lijst met beschikbare migraties.

Opties:

Optie Beschrijving
--connection <CONNECTION> De verbindingsreeks voor de database. Standaard ingesteld op degene die is gespecificeerd in AddDbContext of OnConfiguring.
--no-connect Maak geen verbinding met de database.

De algemene opties worden hierboven vermeld.

dotnet ef migrations remove

Hiermee verwijdert u de laatste migratie, waarbij de codewijzigingen worden teruggezet die zijn uitgevoerd voor de meest recente migratie.

Opties:

Optie Kort Beschrijving
--force -f Herstel de meest recente migratie, waarbij zowel code- als databasewijzigingen worden teruggedraaid die zijn uitgevoerd voor de meest recente migratie. Blijft alleen de codewijzigingen terugdraaien als er een fout optreedt tijdens het maken van verbinding met de database.

De algemene opties worden hierboven vermeld.

dotnet ef migrations script

Hiermee wordt een SQL-script gegenereerd op basis van migraties.

Argumenten:

Argumentatie Beschrijving
<FROM> De start van de migratie. Migraties kunnen worden geïdentificeerd op naam of id. Het getal 0 is een speciaal geval dat betekent vóór de eerste migratie. De standaardwaarde is 0.
<TO> De eindmigratie. Wordt automatisch ingesteld op de laatste migratie.

Opties:

Optie Kort Beschrijving
--output <FILE> -o Het bestand waar het script naar moet worden geschreven.
--idempotent -i Genereer een script dat kan worden gebruikt voor een database tijdens elke migratie.
--no-transactions Genereer geen SQL-transactie-instructies.

De algemene opties worden hierboven vermeld.

In het volgende voorbeeld wordt een script gemaakt voor de InitialCreate-migratie:

dotnet ef migrations script 0 InitialCreate

In het volgende voorbeeld wordt een script gemaakt voor alle migraties na de InitialCreate-migratie.

dotnet ef migrations script 20180904195021_InitialCreate

Aanvullende informatiebronnen