Referenční informace k nástrojům Entity Framework Core – .NET Core CLI

Nástroje rozhraní příkazového řádku (CLI) pro Entity Framework Core provádějí úlohy vývoje v době návrhu. Například vytvářejí migrace, používají migrace a generují kód pro model založený na existující databázi. Příkazy jsou rozšířením příkazu dotnet pro různé platformy, který je součástí sady .NET Core SDK. Tyto nástroje pracují s projekty .NET Core.

Při použití Visual Studio zvažte použití nástrojů konzoly Správce balíčků místo nástrojů rozhraní příkazového řádku. nástroje konzoly Správce balíčků automaticky:

  • Pracuje s aktuálním projektem vybraným v konzole Správce balíčků bez nutnosti ručního přepínání adresářů.
  • Otevře soubory vygenerované příkazem po dokončení příkazu.
  • Poskytuje dokončování příkazů, parametrů, názvů projektů, typů kontextu a názvů migrací.

Instalace nástrojů

dotnet ef lze nainstalovat jako globální nebo místní nástroj. Většina vývojářů preferuje dotnet ef instalaci jako globální nástroj pomocí následujícího příkazu:

dotnet tool install --global dotnet-ef

Pokud ho chcete použít jako místní nástroj, obnovte závislosti projektu, který ho deklaruje jako závislost nástroje pomocí souboru manifestu nástroje.

Aktualizujte nástroj pomocí následujícího příkazu:

dotnet tool update --global dotnet-ef

Než budete moct použít nástroje pro konkrétní projekt, budete do něj muset přidat Microsoft.EntityFrameworkCore.Design balíček.

dotnet add package Microsoft.EntityFrameworkCore.Design

Ověření instalace

Spuštěním následujících příkazů ověřte, že jsou správně nainstalované nástroje rozhraní příkazového řádku EF Core:

dotnet ef

Výstup příkazu identifikuje verzi nástrojů, které se používají:


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

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

<Usage documentation follows, not shown.>

Aktualizace nástrojů

Slouží dotnet tool update --global dotnet-ef k aktualizaci globálních nástrojů na nejnovější dostupnou verzi. Pokud máte nástroje nainstalované místně v projektu, použijte dotnet tool update dotnet-ef. Nainstalujte konkrétní verzi připojením --version <VERSION> k příkazu. Další podrobnosti najdete v části Aktualizace v dokumentaci k nástroji dotnet.

Použití nástrojů

Před použitím nástrojů možná budete muset vytvořit spouštěcí projekt nebo nastavit prostředí.

Cílový projekt a spouštěný projekt

Příkazy odkazují na projekt a spouštěný projekt.

  • Projekt se také označuje jako cílový projekt, protože se jedná o místo, kde příkazy přidávají nebo odebírají soubory. Ve výchozím nastavení je projekt v aktuálním adresáři cílovým projektem. Pomocí této --project možnosti můžete zadat jiný projekt jako cílový projekt.

  • Spouštěcí projekt je projekt, který nástroje sestavují a spouštějí. Nástroje musí v době návrhu spouštět kód aplikace, aby získaly informace o projektu, jako je připojovací řetězec databáze a konfigurace modelu. Ve výchozím nastavení je projekt v aktuálním adresáři spouštěný projekt. Pomocí této --startup-project možnosti můžete zadat jiný projekt jako spouštěný projekt.

Projekt po spuštění a cílový projekt jsou často stejný projekt. Typický scénář, kdy se jedná o samostatné projekty, je následující:

  • Kontext EF Core a třídy entit jsou v knihovně tříd .NET Core.
  • Konzolová aplikace .NET Core nebo webová aplikace odkazuje na knihovnu tříd.

Je také možné vložit kód migrace do knihovny tříd odděleně od kontextu EF Core.

Další cílové architektury

Nástroje rozhraní příkazového řádku pracují s projekty .NET Core a projekty .NET Framework. Aplikace, které mají model EF Core v knihovně tříd .NET Standard, nemusí mít projekt .NET Core nebo .NET Framework. Platí to například pro aplikace Xamarin a Univerzální platforma Windows. V takových případech můžete vytvořit projekt konzolové aplikace .NET Core, jehož jediným účelem je jednat jako spouštěný projekt pro nástroje. Projekt může být fiktivní projekt bez skutečného kódu – stačí zadat cíl pro nástroje.

Proč se vyžaduje fiktivní projekt? Jak už bylo zmíněno dříve, nástroje musí v době návrhu spouštět kód aplikace. K tomu musí použít modul runtime .NET Core. Pokud je model EF Core v projektu, který cílí na .NET Core nebo .NET Framework, nástroje EF Core si půjčí modul runtime z projektu. Nemůžou to udělat, pokud je model EF Core v knihovně tříd .NET Standard. .NET Standard není skutečná implementace .NET; jedná se o specifikaci sady rozhraní API, která musí implementace .NET podporovat. Proto rozhraní .NET Standard nestačí pro nástroje EF Core ke spouštění kódu aplikace. Fiktivní projekt, který vytvoříte pro použití jako spouštěcí projekt, poskytuje konkrétní cílovou platformu, do které mohou nástroje načíst knihovnu tříd .NET Standard.

prostředí ASP.NET Core

Chcete-li zadat prostředí pro ASP.NET Core projekty, nastavte před spuštěním příkazů proměnnou prostředí ASPNETCORE_ENVIRONMENT.

Počínaje ef Core 5.0 je možné do Programu.CreateHostBuilder předat i další argumenty, které umožňují zadat prostředí na příkazovém řádku:

dotnet ef database update -- --environment Production

Tip

Token -- nasměruje dotnet ef na zpracování všeho, co následuje jako argument, a nepokouší se je analyzovat jako možnosti. Všechny další argumenty, které dotnet ef aplikace nepoužívá, se přeposílají do aplikace.

Běžné možnosti

Možnost Krátké Description
--json Zobrazení výstupu JSON
--context <DBCONTEXT> -c Třída DbContext , která se má použít. Pouze název třídy nebo plně kvalifikovaný s obory názvů. Pokud tuto možnost vynecháte, EF Core najde třídu kontextu. Pokud existuje více kontextových tříd, je tato možnost nutná.
--project <PROJECT> -p Relativní cesta ke složce projektu cílového projektu Výchozí hodnota je aktuální složka.
--startup-project <PROJECT> -s Relativní cesta ke složce projektu spouštěného projektu Výchozí hodnota je aktuální složka.
--framework <FRAMEWORK> Moniker cílové architektury pro cílovou architekturu. Použijte, když soubor projektu určuje více cílových architektur a chcete vybrat jednu z nich.
--configuration <CONFIGURATION> Konfigurace sestavení, například: Debug nebo Release.
--runtime <IDENTIFIER> Identifikátor cílového modulu runtime pro obnovení balíčků. Seznam identifikátorů runtime (IDENTIFIKÁTORŮ RID) najdete v katalogu IDENTIFIKÁTORŮ RID.
--no-build Nevystavujte projekt. Účelem je použít, když je sestavení aktuální.
--help -h Zobrazit informace nápovědy
--verbose -v Umožňuje zobrazit podrobný výstup.
--no-color Nevybarvujte výstup.
--prefix-output Výstup předpony s úrovní

Počínaje EF Core 5.0 se do aplikace předávají všechny další argumenty.

dotnet ef database drop

Odstraní databázi.

Možnosti:

Možnost Krátké Description
--force -f Nepotvrzujte.
--dry-run Umožňuje zobrazit, která databáze se zahodí, ale nezahodí ji.

Běžné možnosti jsou uvedené výše.

dotnet ef database update

Aktualizuje databázi na poslední migraci nebo na zadanou migraci.

Argumenty:

Argument Description
<MIGRATION> Cílová migrace. Migrace můžou být identifikovány podle názvu nebo ID. Číslo 0 je zvláštní případ, který znamená před první migrací a způsobí vrácení všech migrací. Pokud není zadána žádná migrace, příkaz se ve výchozím nastavení nastaví na poslední migraci.

Možnosti:

Možnost Popis
--connection <CONNECTION> Připojovací řetězec k databázi. Výchozí hodnota je nastavená na hodnotu zadanou v AddDbContext nebo OnConfiguring. Přidáno v EF Core 5.0.

Běžné možnosti jsou uvedené výše.

Následující příklady aktualizují databázi na zadanou migraci. První používá název migrace a druhý používá ID migrace a zadané připojení:

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

dotnet ef dbcontext info

Získá informace o DbContext typu.

Běžné možnosti jsou uvedené výše.

dotnet ef dbcontext list

Seznamy dostupných DbContext typů.

Běžné možnosti jsou uvedené výše.

dotnet ef dbcontext optimize

Vygeneruje zkompilovanou verzi modelu, kterou DbContextpoužívá . Přidáno v EF Core 6.

Další informace najdete v tématu Kompilované modely .

Možnosti:

Možnost Krátké Description
--output-dir <PATH> -o Adresář pro vložení souborů. Cesty jsou relativní k adresáři projektu.
--namespace <NAMESPACE> -n Obor názvů, který se má použít pro všechny vygenerované třídy. Ve výchozím nastavení se vygeneruje z kořenového oboru názvů a výstupního adresáře plus CompiledModels.

Běžné možnosti jsou uvedené výše.

Následující příklad používá výchozí nastavení a funguje, pokud je v projektu jenom jeden DbContext :

dotnet ef dbcontext optimize

Následující příklad optimalizuje model pro kontext se zadaným názvem a umístí ho do samostatné složky a oboru názvů:

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

dotnet ef dbcontext scaffold

Generuje kód pro DbContext typy entit a pro databázi. Aby tento příkaz mohl vygenerovat typ entity, musí mít tabulka databáze primární klíč.

Argumenty:

Argument Description
<CONNECTION> Připojovací řetězec k databázi. U projektů ASP.NET Core 2.x může být hodnota name=<název připojovacího řetězce>. V takovém případě název pochází ze zdrojů konfigurace, které jsou nastavené pro projekt.
<PROVIDER> Poskytovatel, který se má použít. Obvykle se jedná o název balíčku NuGet, například: Microsoft.EntityFrameworkCore.SqlServer.

Možnosti:

Možnost Krátké Description
--data-annotations -d Pomocí atributů nakonfigurujte model (pokud je to možné). Pokud tuto možnost vynecháte, použije se pouze fluentské rozhraní API.
--context <NAME> -c Název třídy, která DbContext se má vygenerovat.
--context-dir <PATH> Adresář pro umístění DbContext souboru třídy do. Cesty jsou relativní k adresáři projektu. Obory názvů jsou odvozeny z názvů složek.
--context-namespace <NAMESPACE> Obor názvů, který se má použít pro vygenerovanou DbContext třídu. Poznámka: přepsání --namespace. Přidáno v EF Core 5.0.
--force -f Přepište existující soubory.
--output-dir <PATH> -o Adresář pro umístění souborů třídy entity. Cesty jsou relativní k adresáři projektu.
--namespace <NAMESPACE> -n Obor názvů, který se má použít pro všechny vygenerované třídy. Ve výchozím nastavení se vygeneruje z kořenového oboru názvů a výstupního adresáře. Přidáno v EF Core 5.0.
--schema <SCHEMA_NAME>... Schémata tabulek pro generování typů entit. Pokud chcete zadat více schémat, opakujte --schema pro každou z nich. Pokud je tato možnost vynechána, zahrnou se všechna schémata.
--table <TABLE_NAME>... -t Tabulky pro generování typů entit. Pokud chcete zadat více tabulek, opakujte nebo --table pro každou z nich opakujte-t. Pokud je tato možnost vynechána, budou zahrnuty všechny tabulky.
--use-database-names Názvy tabulek a sloupců používejte přesně tak, jak se zobrazují v databázi. Pokud tuto možnost vynecháte, názvy databází se změní tak, aby přesněji odpovídaly konvencím stylu názvů jazyka C#.
--no-onconfiguring Potlačí generování OnConfiguring metody ve vygenerované DbContext třídě. Přidáno v EF Core 5.0.
--no-pluralize Nepoužívejte pluralizátor. Přidáno v EF Core 5.0

Běžné možnosti jsou uvedené výše.

Následující příklad vygeneruje všechna schémata a tabulky a vloží nové soubory do složky Models .

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

Následující příklad vygeneruje pouze vybrané tabulky a vytvoří kontext v samostatné složce se zadaným názvem a oborem názvů:

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

Následující příklad načte připojovací řetězec z konfigurační sady projektu pomocí nástroje 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

Následující příklad přeskočí generování OnConfiguring metody. To může být užitečné, když chcete nakonfigurovat DbContext mimo třídu. Například ASP.NET Core aplikace ji obvykle konfigurují ve službě Startup.ConfigureServices. Přidáno v EF Core 5.0.

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

dotnet ef dbcontext script

Vygeneruje SQL skript z DbContext. Obchází všechny migrace.

Možnosti:

Možnost Krátké Description
--output <FILE> -o Soubor pro zápis výsledku.

Běžné možnosti jsou uvedené výše.

dotnet ef migrations add

Přidá novou migraci.

Argumenty:

Argument Description
<NAME> Název migrace.

Možnosti:

Možnost Krátké Description
--output-dir <PATH> -o Adresář slouží k výstupu souborů. Cesty jsou relativní k cílovému adresáři projektu. Výchozí hodnota je migrace.
--namespace <NAMESPACE> -n Obor názvů, který se má použít pro vygenerované třídy. Ve výchozím nastavení se vygeneruje z výstupního adresáře. Přidáno v EF Core 5.0.

Běžné možnosti jsou uvedené výše.

dotnet ef migrations bundle

Vytvoří spustitelný soubor pro aktualizaci databáze.

Možnosti:

Možnost Krátké Description
--output <FILE> -o Cesta spustitelného souboru, který chcete vytvořit.
--force -f Přepsat existující soubory.
--self-contained Sbalte také modul runtime .NET, aby se na počítači nemusel instalovat.
--target-runtime <RUNTIME_IDENTIFIER> -r Cílový modul runtime, pro který se má sbalit.

Běžné možnosti jsou uvedené výše.

dotnet ef migrations list

Zobrazí seznam dostupných migrací.

Možnosti:

Možnost Popis
--connection <CONNECTION> Připojovací řetězec k databázi. Ve výchozím nastavení se nastaví hodnota zadaná v addDbContext nebo OnConfiguring. Přidáno v EF Core 5.0.
--no-connect Nepřipojujte se k databázi. Přidáno v EF Core 5.0.

Běžné možnosti jsou uvedené výše.

dotnet ef migrations remove

Odebere poslední migraci a vrátí změny kódu, které byly provedeny pro nejnovější migraci.

Možnosti:

Možnost Krátké Description
--force -f Vraťte nejnovější migraci a vraťte zpět změny kódu i databáze, které byly provedeny pro nejnovější migraci. Pokračuje v vrácení zpět pouze změny kódu, pokud dojde k chybě při připojování k databázi.

Běžné možnosti jsou uvedené výše.

dotnet ef migrations script

Vygeneruje SQL skript z migrací.

Argumenty:

Argument Description
<FROM> Počáteční migrace. Migrace se můžou identifikovat podle názvu nebo podle ID. Číslo 0 je zvláštní případ, který znamená před první migrací. Výchozí hodnota je 0.
<TO> Koncová migrace. Ve výchozím nastavení se nastaví poslední migrace.

Možnosti:

Možnost Krátké Description
--output <FILE> -o Soubor pro zápis skriptu.
--idempotent -i Vygenerujte skript, který lze použít v databázi při jakékoli migraci.
--no-transactions Nevygenerujte SQL výpisy transakcí. Přidáno v EF Core 5.0.

Běžné možnosti jsou uvedené výše.

Následující příklad vytvoří skript pro migraci InitialCreate:

dotnet ef migrations script 0 InitialCreate

Následující příklad vytvoří skript pro všechny migrace po migraci InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Další materiály