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

  • Článek

Nástroje rozhraní příkazového řádku (CLI) pro Entity Framework Core provádějí úlohy vývoje v době návrhu. Vytvářejí například 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í sady 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:

  • Funguje s aktuálním projektem vybraným v konzole Správce balíčků, aniž byste museli ručně přepínat adresáře.
  • Po dokončení příkazu otevře soubory vygenerované příkazem.
  • Poskytuje dokončování příkazů, parametrů, názvů projektů, typů kontextu a názvů migrace pomocí tabulátoru.

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 deklarují jako závislost nástrojů 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 nástroje dotnet.

Použití nástrojů

Před použitím nástrojů možná budete muset vytvořit spouštěný 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 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 možnosti můžete zadat jiný projekt jako cílový projekt --project .

  • 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 například databáze připojovací řetězec a konfigurace modelu. Ve výchozím nastavení je projekt v aktuálním adresáři spouštěný projekt. Pomocí této možnosti můžete zadat jiný projekt jako spouštěný projekt --startup-project .

Projekt po spuštění a cílový projekt jsou často stejný projekt. Typický scénář, ve kterém jsou samostatné projekty, jsou v následujících případech:

  • 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 rozhraní .NET Framework. Aplikace, které mají model EF Core v knihovně tříd .NET Standard, nemusí mít projekt .NET Core nebo .NET Framework. To platí například pro Xamarin a Univerzální platforma Windows aplikace. 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 modul runtime půjčí 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 .NET Standard nestačí pro nástroje EF Core ke spuštění kódu aplikace. Fiktivní projekt, který vytvoříte pro použití jako spouštěný projekt, poskytuje konkrétní cílovou platformu, do které mohou nástroje načíst knihovnu tříd .NET Standard.

prostředí ASP.NET Core

Na příkazovém řádku můžete zadat prostředí pro projekty ASP.NET Core. Tyto a všechny další argumenty jsou předány do Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Tip

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

Běžné možnosti

Možnost Krátké Popis
--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 tříd kontextu, je tato možnost povinná.
--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 (RID) najdete v katalogu RID.
--no-build Nevystavujte projekt. Účelem je použít, když je sestavení aktuální.
--help -h Zobrazí informace nápovědy.
--verbose -v Zobrazení podrobného výstupu
--no-color Nevybarvujte výstup.
--prefix-output Výstup předpony s úrovní

Do aplikace se předají všechny další argumenty.

dotnet ef database drop

Odstraní databázi.

Možnosti:

Možnost Krátké Popis
--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

Aktualizace databázi k poslední migraci nebo k zadané migraci.

Argumenty:

Argument Popis
<MIGRATION> Cílová migrace. Migrace můžou být identifikovány podle názvu nebo podle ID. Číslo 0 je zvláštní případ, který znamená , že před první migrací a způsobí vrácení všech migrací zpět. 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 do databáze. Ve výchozím nastavení se nastaví hodnota zadaná v AddDbContext hodnotě nebo OnConfiguring.

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

Následující příklady aktualizují databázi na zadanou migraci. První použije název migrace a druhý použije 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

Seznam dostupných DbContext typů.

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

dotnet ef dbcontext optimize

Vygeneruje zkompilovanou verzi modelu, který DbContextpoužívá .

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

Možnosti:

Možnost Krátké Popis
--output-dir <PATH> -o Adresář, do který se mají umístit soubory. Cesty jsou relativní k adresáři projektu.
--namespace <NAMESPACE> -n Obor názvů, který se má použít pro všechny generované třídy. Výchozí hodnota vygenerovaná 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 pouze 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 Popis
<CONNECTION> Připojovací řetězec do databáze. U ASP.NET projektů Core 2.x může být hodnota name=<název připojovací řetězec>. 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é Popis
--data-annotations -d Pomocí atributů nakonfigurujte model (pokud je to možné). Pokud tuto možnost vynecháte, použije se pouze rozhraní API fluent.
--context <NAME> -c Název třídy, která DbContext se má vygenerovat.
--context-dir <PATH> Adresář, do který chcete umístit DbContext soubor třídy. 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.
--force -f Přepište existující soubory.
--output-dir <PATH> -o Adresář, do který se mají umístit soubory tříd entit. Cesty jsou relativní k adresáři projektu.
--namespace <NAMESPACE> -n Obor názvů, který se má použít pro všechny generované třídy. Ve výchozím nastavení se vygeneruje z kořenového oboru názvů a výstupního adresáře.
--schema <SCHEMA_NAME>... Schémata tabulek a zobrazení pro generování typů entit. Pokud chcete zadat více schémat, opakujte --schema pro každou z nich. Pokud tuto možnost vynecháte, budou zahrnuta všechna schémata. Pokud použijete tuto možnost, budou do modelu zahrnuty všechny tabulky a zobrazení ve schématech, i když nejsou explicitně zahrnuty pomocí parametru --table.
--table <TABLE_NAME>... -t Tabulky a zobrazení pro generování typů entit. Pokud chcete zadat více tabulek, opakujte nebo --table pro každou z nich opakujte-t. Tabulky nebo zobrazení v určitém schématu lze zahrnout pomocí formátu schema.table nebo schema.view. Pokud tuto možnost vynecháte, budou zahrnuty všechny tabulky a zobrazení.
--use-database-names Použijte názvy tabulek, zobrazení, posloupnosti a sloupců přesně tak, jak se zobrazují v databázi. Pokud tuto možnost vynecháte, názvy databází se změní tak, aby lépe odpovídaly konvencím stylu názvů jazyka C#.
--no-onconfiguring Potlačí generování OnConfiguring metody ve vygenerované DbContext třídě.
--no-pluralize Nepoužívejte pluralizátor.

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

Následující příklad vygeneruje všechna schémata a tabulky a umístí 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 ze sady konfigurace 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 aplikace ASP.NET Core ji obvykle konfigurují ve službě 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

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

Možnosti:

Možnost Krátké Popis
--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 Popis
<NAME> Název migrace.

Možnosti:

Možnost Krátké Popis
--output-dir <PATH> -o Adresář slouží k výstupu souborů. Cesty jsou relativní vzhledem 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.

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é Popis
--output <FILE> -o Cesta spustitelného souboru, který chcete vytvořit.
--force -f Přepište 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á seskupit.

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

dotnet ef migrations has-pending-model-changes

Poznámka

Tento příkaz byl přidán v EF Core 8.0.

Zkontroluje, jestli od poslední migrace nedošlo k nějakým změnám modelu.

Možnosti:

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 do databáze. Ve výchozím nastavení se nastaví hodnota zadaná v příkazu AddDbContext nebo OnConfiguring.
--no-connect Nepřipojujte se k databázi.

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

dotnet ef migrations remove

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

Možnosti:

Možnost Krátké Popis
--force -f Vraťte se k 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 v případě, že dojde k chybě při připojování k databázi.

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

dotnet ef migrations script

Generuje skript SQL z migrací.

Argumenty:

Argument Popis
<FROM> Počáteční migrace. Migrace můžou být identifikovány 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. Výchozí hodnota je poslední migrace.

Možnosti:

Možnost Krátké Popis
--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 Negenerujte příkazy transakcí SQL.

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ší prostředky