Sdílet prostřednictvím

Správa migrací

Při změnách modelu se migrace přidají a odeberou jako součást běžného vývoje a soubory migrace se zavádějí do správy zdrojového kódu projektu. Pokud chcete spravovat migrace, musíte nejprve nainstalovat nástroje příkazového řádku EF Core .

Návod

Pokud je DbContext v jiném sestavení než spouštěný projekt, můžete explicitně určit cílové a spouštěné projekty v nástrojích konzoly správce balíčků nebo nástrojů .NET Core CLI.

Přidejte migraci

Po změně modelu můžete přidat migraci pro tuto změnu:

dotnet ef migrations add AddBlogCreatedTimestamp

Název migrace se dá použít jako zpráva potvrzení v systému správy verzí. Například můžete zvolit název jako AddBlogCreatedTimestamp, pokud se jedná o novou vlastnost CreatedTimestamp u vaší entity Blog.

Do vašeho projektu se přidají tři soubory v adresáři Migrations.

  • XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.cs– hlavní soubor migrace. Obsahuje operace potřebné k použití migrace (v Up) a jejich vrácení (v Down).
  • XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.Designer.cs– soubor metadat migrace. Obsahuje informace používané EF.
  • MyContextModelSnapshot.cs- Snímek vašeho aktuálního modelu. Používá se k určení toho, co se změnilo při přidání další migrace.

Časové razítko v názvu souboru pomáhá udržovat je seřazené chronologicky, abyste viděli průběh změn.

Jmenné prostory

Migrační soubory můžete přesunout a změnit jejich obor názvů ručně. Nové migrace jsou vytvořeny jako sourozenci poslední migrace. Případně můžete adresář zadat v době generování následujícím způsobem:

dotnet ef migrations add InitialCreate --output-dir Your/Directory

Poznámka:

Obor názvů můžete také změnit nezávisle na adresáři pomocí --namespace.

Přizpůsobení kódu migrace

I když EF Core obecně vytváří přesné migrace, měli byste vždy zkontrolovat kód a ujistit se, že odpovídá požadované změně; v některých případech je to dokonce nutné.

Přejmenování sloupců

Jedním z příkladů, kdy je nutné přizpůsobit migrace, je přejmenování vlastnosti. Pokud například přejmenujete vlastnost z Name na FullName, EF Core vygeneruje následující migraci:

migrationBuilder.DropColumn(
    name: "Name",
    table: "Customers");

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customers",
    nullable: true);

EF Core obecně nedokáže určit, zda je záměr odstranit sloupec a vytvořit nový (dvě samostatné změny), nebo zda se má sloupec přejmenovat. Pokud se výše uvedená migrace použije as-is, ztratí se všechna jména vašich zákazníků. Pokud chcete přejmenovat sloupec, nahraďte výše vygenerovanou migraci následujícím kódem:

migrationBuilder.RenameColumn(
    name: "Name",
    table: "Customers",
    newName: "FullName");

Návod

Proces konstrukce migrace upozorní, pokud operace může vést ke ztrátě dat (například vyřazení sloupce). Pokud se vám zobrazí toto upozornění, nezapomeňte si projít kód migrace s ohledem na přesnost.

Přidání nezpracovaných SQL

Přejmenování sloupce může být provedeno pomocí vestavěného rozhraní API, ale v mnoha případech to není možné. Můžeme například chtít nahradit existující FirstName a LastName vlastnosti jednou novou vlastností FullName. Migrace generovaná ef Core bude následující:

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customer",
    nullable: true);

Stejně jako předtím by to způsobilo nežádoucí ztrátu dat. Pokud chcete přenést data ze starých sloupců, přeuspořádáme migrace a provedeme nezpracovanou operaci SQL následujícím způsobem:

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customer",
    nullable: true);

migrationBuilder.Sql(
@"
    UPDATE Customer
    SET FullName = FirstName + ' ' + LastName;
");

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

Libovolné změny prostřednictvím nezpracovaného SQL

Nezpracovaný SQL lze také použít ke správě databázových objektů, o které EF Core neví. Chcete-li to provést, přidejte migraci bez provedení jakékoli změny modelu; Vygeneruje se prázdná migrace, kterou pak můžete naplnit nezpracovanými operacemi SQL.

Například následující migrace vytvoří uloženou proceduru SQL Serveru:

migrationBuilder.Sql(
@"
    EXEC ('CREATE PROCEDURE getFullName
        @LastName nvarchar(50),
        @FirstName nvarchar(50)
    AS
        RETURN @LastName + @FirstName;')");

Návod

EXEC se používá, když příkaz musí být první nebo pouze jeden v dávce SQL. Dá se také použít k řešení chyb analyzátoru ve skriptech idempotentní migrace, ke kterým může dojít, když odkazované sloupce v tabulce aktuálně neexistují.

Můžete ho použít ke správě libovolného aspektu databáze, včetně těchto:

  • Uložené procedury
  • Hledání v plném textu
  • Funkce
  • Spouštěče
  • Pohledy

Ve většině případů EF Core při použití migrací automaticky uzavře každou migraci do vlastní transakce. Některé operace migrace bohužel nelze provést v rámci transakce v některých databázích; v těchto případech se můžete odhlásit z transakce předáním suppressTransaction: truemigrationBuilder.Sql.

Odstraňte migraci

Někdy přidáte migraci a zjistíte, že před použitím je potřeba provést další změny modelu EF Core. Pokud chcete poslední migraci odebrat, použijte tento příkaz.

dotnet ef migrations remove

Po odebrání migrace můžete provést další změny modelu a znovu ho přidat.

Varování

Vyhněte se odebrání migrací, které už byly použity pro produkční databáze. To znamená, že nebudete moct tyto migrace z databází vrátit a můžete narušit předpoklady provedené následnými migracemi.

Výpis migrací

Všechny existující migrace můžete zobrazit následujícím způsobem:

dotnet ef migrations list

Kontrola čekajících změn modelu

Poznámka:

Tato funkce byla přidána v EF Core 8.0.

Někdy můžete chtít zkontrolovat, jestli nedošlo k nějakým změnám modelu od poslední migrace. To vám může pomoct zjistit, kdy jste vy nebo člen týmu zapomněli přidat migraci. Jedním ze způsobů, jak to udělat, je použít tento příkaz.

dotnet ef migrations has-pending-model-changes

Tuto kontrolu můžete provést také programově pomocí context.Database.HasPendingModelChanges(). To lze použít k vytvoření jednotkového testu, který selže, pokud zapomenete přidat migraci.

Resetování všech migrací

V některých extrémních případech může být nutné odebrat všechny migrace a začít znovu. Můžete to snadno provést odstraněním složky Migrations a vyřazením databáze; v tomto okamžiku můžete vytvořit novou počáteční migraci, která bude obsahovat celé vaše aktuální schéma.

Je také možné resetovat všechny migrace a vytvořit jednu migraci bez ztráty dat. To se někdy nazývá "squashing" a zahrnuje ruční práci.

  1. Zálohujte databázi, pokud se něco pokazí.
  2. V databázi odstraňte všechny řádky z tabulky historie migrací (např. DELETE FROM [__EFMigrationsHistory] na SQL Serveru).
  3. Odstraňte složku Migrations.
  4. Vytvořte novou migraci a vygenerujte pro ni skript SQL (dotnet ef migrations script).
  5. Vložte do historie migrací jeden řádek a poznamenejte si, že se už použila první migrace, protože vaše tabulky už existují. Insert SQL je poslední operace ve skriptu SQL vygenerovaném výše a podobá se následující (nezapomeňte aktualizovat hodnoty):
INSERT INTO [__EFMigrationsHistory] ([MIGRATIONID], [PRODUCTVERSION])
VALUES (N'<full_migration_timestamp_and_name>', N'<EF_version>');

Varování

Při odstranění složky migrace dojde ke ztrátě jakéhokoli vlastního kódu migrace. Všechna vlastní nastavení je třeba ručně aplikovat na novou úvodní migraci, aby se zachovala.

Další zdroje informací