Aktualiserad - 27 Okt 2026. Den ursprungliga versionen publicerades i november 2025 | - Korrigerade bundle-optioner och lagt till den nuvarande EF Core | | 9/10 | guidan | МSK3 | Aspire integrering och tydligt markerad EF Core felslutande i slutet för korrigeringar till originalversionen.

Running MigrateAsync() vid startup.?, du ger ditt app-schema, -, ändrar tillstånd och hoppas att inget går fel.., det finns ett bättre sätt.M SK4, EF- migrationspaket låter dig köra migrationer som en kontrollerad CI-steg.

officiella dokument: Migrationer överblick | Att tillämpa migrationer | Bundler

Det sättet jag använder

Denna blogg använder MigrateAsync() i början - tillvägagångssättet Jag ' är på väg att säga åt dig att inte använda

I min Program.cs file Jag har följande:

    using (var scope = app.Services.CreateScope())
    {
        var blogContext = scope.ServiceProvider.GetRequiredService<IMostlylucidDBContext>();
        await blogContext.Database.MigrateAsync();
    }

MigrateAsync() applicerar pågående migrationer och skapar databasen om det behövs. Enkel - men problematiskt

1. Startup beroende - Databasen neråt ? Migrationen misslyckas? Appen kommer att fungera
2. Upphöjda rättigheter - Din app behöver de DDL-licenser som krävs av dess migrationer , möjligen inklusive dropping tabler . Det betyder inte nödvändigtvis SQL Server db_owner roll, men det är fortfarande mer kraft än vanliga sökningar behöver

Varför går jag undan med det? Du kan förmodligen

När Runtime- migrationer är bra

• Lokala dev - Fast iteration beats ceremoni
• Personliga projekt - låg strålning
• Docker-komposera dev miljöer - Möjligheterna vinner
• Prototypering - Programmet förändras konstant ändå

När de inte gör det

• Flera app-instantioner - Start migration couplerar varje kopia till schemadeployment . EF Core | | 9+ | lägger till migrationlocking | МSK3 | men det koordinerar inte gammal applikationskod med ett ändrat schema
• Sensoriska data - PII
• Tillverkning med riktiga användare - Misslyckad migration = avbrott

Den rätta vägen: EF-bundle

Ett EF-bundel är ett utförbart som innehåller dina kompilerade migrationer. Tänk dotnet ef database update packaged as a deployment artifact --self-contained för att inkludera .NET runtime

Varför paket vinner:

• Inget SDK eller EF CLI på målet - En självbyggt paket som innefattar också | . | NET runtime | ; | OS | МSK4 | fortfarande tillämpade native beroende
• Rättvis separerad - En separat utplaceringsidentitet får de nödvändiga schema-förvaltelserna ; runtimeappn bevarar sina normala data-förခွင့်er
• CI-visualitet - Misslyckanden visar sig i pipelinelogs , inte gömd vid appstart
• Deployment-grinden - En icke-zero-bundle utgång stoppar utställningen . Det är inte en garantera för att varje databasförändring rullades tillbaka
• Migrationshistoria - Spurer som migrationer har tillämpats . Custom SQL och frön behöver fortfarande noggranna repetitionsbeteende

Identitetsfrågor: Där din databas supporterar det, managed identity can remove stored passwords . Du behöver fortfarande kopplingsställningar och separata applikationer

Ett exempel på GitHub actions

Stuur in en lokal dotnet-ef verktygsmanifest som är kopplat till den EF-version du använder Microsoft.EntityFrameworkCore.Design i startupprojektet. byggjobbet återställer verktygen och skapar artefakten; den skyddade utpostningensjobbet får produktionsgeheimnM SK2 De här stegen tar hänsyn till att checkout och att den lämpliga | . | NET SDK är redan konfigurerad

# Build job: no production credentials
- name: Restore EF tools
  run: dotnet tool restore

- name: Generate Linux migration bundle
  shell: bash
  run: |
    dotnet restore
    dotnet ef migrations bundle \
      --project Mostlylucid.DbContext \
      --startup-project Mostlylucid \
      --context MostlylucidDbContext \
      --configuration Release \
      --target-runtime linux-x64 \
      --self-contained \
      --output efbundle
  env:
    DOTNET_ENVIRONMENT: Production
    ASPNETCORE_ENVIRONMENT: Production

- uses: actions/upload-artifact@v4
  with:
    name: ef-migrations
    path: efbundle

# Deployment job: after downloading the same tested artifact
- uses: actions/download-artifact@v4
  with:
    name: ef-migrations

- name: Apply migrations
  shell: bash
  run: |
    chmod +x ./efbundle
    ./efbundle --connection "$MIGRATION_CONNECTION_STRING" --no-color --prefix-output
  env:
    DOTNET_ENVIRONMENT: Production
    ASPNETCORE_ENVIRONMENT: Production
    MIGRATION_CONNECTION_STRING: ${{ secrets.PROD_SQL_CONNECTIONSTRING }}

Använd din faktiska kontext namn. Att explicitt välja Produktion (Produktion) är också bra för att undvika att oavsiktligt ladda utvecklingskonfigurationen . Att skapa Design

Förstärk samma artefakt genom testning, inscenering och produktion. Använd en skyddad GitHub-miljö och serialisera utpostningar till samma databasM SK2 Om kreationen läser inställningarna i config files , skicka de nödvändiga ickesalade plierna med paketet också användnings- och konfigurationsguidansen.

Lokala Bundler

Ingen CI? Vill testa innan du trycker på strömmen ? Att bygga paket lokalt

Använd fall: Test före CI, DBA handoff ( själv -contained exeM SK3 ingen SDK behövs --verbose.

Att skapa ett paket

# Once per repository: create a tool manifest if you do not already have one
dotnet new tool-manifest
# Example version: choose the supported patch matching your EF packages
dotnet tool install dotnet-ef --version 10.0.12
# In CI or after cloning
dotnet tool restore

# Basic bundle
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle

# Self-contained (includes runtime for the selected OS/architecture)
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle \
    --self-contained

# Cross-platform (e.g., build on Windows, deploy to Linux)
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle \
    --target-runtime linux-x64

Att köra din paket

Folgende använder en Unix skala. på Windows, som bygger med --output efbundle.exe och springa .\efbundle.exe i PowerShell.

# Using the connection configured by your DbContext
./efbundle

# Override with a specific connection string
./efbundle --connection "$MIGRATION_CONNECTION_STRING"

# Or use an environment variable matching the key your context reads
export ConnectionStrings__DefaultConnection="$MIGRATION_CONNECTION_STRING"
./efbundle

För det sista exemplet i PowerShell:

$env:ConnectionStrings__DefaultConnection = $env:MIGRATION_CONNECTION_STRING
.\efbundle.exe

användbara Bundle-optioner

Det finns två olika gränssnitt: dotnet ef migrations bundle byggar den utförbara; ./efbundle springer it. Deras val är inte utwechselbaraM SK1

Instrumenten har också en gemensam --runtime option. Använd paketet --target-runtime att göra deploymentmålet explicitt

./efbundle --help
./efbundle --version

# Apply pending migrations, with deployment-friendly logs
./efbundle --verbose --no-color --prefix-output

# Target is positional: this is NOT --target-migration
./efbundle 20231115_AddUserTable

# Revert everything: destructive, only for a disposable test database
./efbundle 0

Det utförbara stöder --connection, --verbose/-v, --no-color, --prefix-output, hjälp och version EF-bundle-commandokälla visar den faktiska tolkaren.

Det finns ingen Bundle Dry Run

./efbundle --dry-run gör inte existerar . Inte heller --verbose omvandla utführungen till en preview. Generera SQL utan att tillämpa det:

dotnet ef migrations script PreviousMigration AddNewFeature \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output migrations.sql

Använda 0 som det första argumentet för en ny databas.

För att se projektets migrationer och de som väntar på konfigurerad databasen

dotnet ef migrations list \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid

Lägg till: --no-connect att lista upp montagen's migrationer utan att kontakta databasen

Lokala tester av arbetsflödet

# 1. Create and inspect the migration
dotnet ef migrations add AddNewFeature \
    --project Mostlylucid.DbContext --startup-project Mostlylucid

# 2. Generate reviewable SQL for the expected starting point
dotnet ef migrations script PreviousMigration AddNewFeature \
    --project Mostlylucid.DbContext --startup-project Mostlylucid \
    --output migrations.sql

# 3. Build the bundle for this test host
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext --startup-project Mostlylucid \
    --output efbundle --force

# 4. Apply to a disposable database or restored test copy
./efbundle --connection "$TEST_MIGRATION_CONNECTION_STRING" --verbose

# 5. Run again to verify migration history/retry behaviour
./efbundle --connection "$TEST_MIGRATION_CONNECTION_STRING"

Testa både en ny databas och en uppgradering från en repräsenterande existerande databas

Om den senaste migrationen behöver göras om och bara tillämpats lokalt, så måste den först uppdateras lokala databas till PreviousMigration. Sedan använda dotnet ef migrations remove med samma projekt

Att bygga prestationer

Bundle generation kan vara långsamt, speciellt för självständiga mål

• Generera manuell när man testar lokalt
• Att bygga release bundle i CI och köra migrationskontroller på PR
• Cache med alla relevanta inmatningar: migrationer , modellM SK2 konfigurationen/ fabrikskodMSC4 beroenden och mål RID

Om du verkligen vill ha automatiserad generation

<Target Name="BuildMigrationBundle">
  <Exec Command="dotnet ef migrations bundle --output $(OutputPath)efbundle.exe --force" />
</Target>

Sedan: dotnet build -t:BuildMigrationBundle

Hybrid-metoden

Den bästa av båda världarna : bekvämlighet lokalt, säkerhet i produktionen

if (builder.Environment.IsDevelopment())
{
    using var scope = app.Services.CreateScope();
    var context = scope.ServiceProvider.GetRequiredService<IMostlylucidDBContext>();
    await context.Database.MigrateAsync();
}
// Production: CI pipeline runs the bundle

Alternativer till paket

SQL- skript

Generera enkel SQL istället för en lösbar

# All migrations
dotnet ef migrations script --output migrations.sql

# Idempotent: checks migration history, when supported by the provider
dotnet ef migrations script --idempotent --output migrations.sql

# Range of migrations
dotnet ef migrations script FromMigration ToMigration --output migrations.sql

Pros: Full visibility, vilken SQL-client som helst kan köra den , version control friendly

Cons: Din löpare måste hantera misslyckanden korrekt, och ett intervallskrypt antar den förväntade migrationn som börjar. Genererade skript uppdaterar EF- migrationshistorien också ; --idempotent lägger till villkorliga kontroller istället för att uppfinna historiaspårning. SQLite supporterar inte idempotent migration skript.

Se officiella dokument i SQL- skript.

SQL Skripte i CI

För SQL Server, gör att SQL-errorerna misslyckas i pipelinen

sqlcmd -S "$DB_SERVER" -d "$DB_NAME" -b -i migrations.sql

För PostgreSQL, gör samma sak eksplicitt

psql --host="$DB_HOST" --username="$DB_USER" --dbname="$DB_NAME" \
    --set=ON_ERROR_STOP=1 --file=migrations.sql

Släpp ut credentialer genom runnern' den stödda säkra mekanismen . Det här är alternativ för den som skapade SQL, inte två kommandor att köra mot samma databas sqlcmd och handling av fel i psql. Kan du inte blindt lägga till en annan transaktions-wrapper : genererade skript kan redan hantera transaktioner , och vissa operationer kan inte fungera inuti en

DACPAC (Sål SQL-Servern)

DACPACs är stat-baserad inte migration-baserad. Du definierar det önskade schemat , och SqlPackage skiljer det mot den måldatabasen

SqlPackage.exe /Action:Publish /SourceFile:MyDatabase.dacpac /TargetConnectionString:"..."

Pros: Schema som kod

Cons: Bara SQL Server, schema på två ställen | ( | EF-modeller |+ | SQL-projekt ♫ ), | diff-enginer gör tvivelfulla val ♫

Se SqlPackage dokument.

Vergleichstabellen

Tips

Designerdatet fick dig

Migrationer fungerar lokalt men inte i CI? Sprawa att du lovar alla tre genererade bitar

• 20231115_AddUserTable.cs - Migrationskod
• 20231115_AddUserTable.Designer.cs - Metadata och målmodellen för den migrationen
• BlogDbContextModelSnapshot.cs - Den nuvarande modellbildern som används för att bilda nästa migration

Missande designer-metadata kan hindra EF från att upptäcka migrationen; en sakna eller föråldrade bildbild orsakar felaktiga framtida diffs att hantera migrationer.

Don' inte blanda skapandestrategier EnsureCreated() förbipassar migrationer och deras historia. MigrateAsync() och förväntar sig att EF ska anamma resultatet av schemat Instruktioner för att skapa en EF-databas.

Flera Dbkontexter

dotnet ef migrations bundle --context BlogDbContext --output blog-migrations.exe
dotnet ef migrations bundle --context IdentityDbContext --output identity-migrations.exe

Koppelns sträng prioritet

Paketet's --connection överrider kopplingen som konfigurerats för kontexten din application's konfigurationskedjor. Med den standardmäßiga ASP-variablen, ., NET Core builder och , överrider JSON-variabilierna, men kundentillhandahållare eller en designfabrik kan ändra det.

ConnectionStrings__DefaultConnection fungerar bara om din kontext faktiskt läser ConnectionStrings:DefaultConnection; AdminSite__ConnectionString som användes av fabriken härunder läser en annan ny nyckel. miljövariabler är konfigurationsinputar , inte en särskild bundle koppling M SK2 string lookup . se konfiguratorer och ordning.

IDesignTimeDbContextFactory

EF-verktyg behöver göra din DbContext instanserad IDesignTimeDbContextFactory<T>:

public class AdminDbContextFactory : IDesignTimeDbContextFactory<AdminDbContext>
{
    public AdminDbContext CreateDbContext(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", optional: true)
            .AddUserSecrets<AdminDbContextFactory>(optional: true)
            .AddEnvironmentVariables()
            .Build();

        var connectionString = config["AdminSite:ConnectionString"]
            ?? throw new InvalidOperationException("Missing connection string");

        var optionsBuilder = new DbContextOptionsBuilder<AdminDbContext>();
        optionsBuilder.UseSqlServer(connectionString, sql => sql.CommandTimeout(120));

        return new AdminDbContext(optionsBuilder.Options);
    }
}

Använd när: Db Kontext i ett separat projekt , komplext uppstartning , eller styrd kreation av kontext för verktygsverktyg M SK3 EF använder en upptäckt fabrik istället för en normal uppstarting Mska4 baserad kreation M Ska5 inbegripande i en bundle Mske6 Håll tillhandahållarenMska7 modellen i harmlighet med appet Mka8 Den här minimala fabriken laddar medvetet bara bas JSON, Mska9 optionella användar hemligheter och miljövariabler, m.in. Mska10 lägger till miljöer, M Ska11, specifika plikter specifikt om det behövs, ,, och håller produktionshemligheterna utanför artefakten, . Miljövariablerna är de sista här, så att CI kan överrida lokala hemligheter,Mska14

Vad har förändrats kring migrationer?

Kernrådet överlever nyare EF-ut releases : bygga ett repeterabelt artefakt och ge schemaimplementering sin egen identitet. Men flera detaljer har förbättrats sedan den ursprungliga artikeln

EF Core 9+: Locking , Tester på frön och modeller

EF Core 9 introducerade migrationlocking för att skydda samtida migrationimplementeringar . Det löser en viktig gammal ras ; det gör inte en förstörande schemaförändring kompatibel med krav som fortfarande körs på gammal kod Migrationslockning för EF Core 9.

EF Core 9 börjar också avfärda migration-applikationer när modellen inte har några ändringar från ögonblicksbilderna.

dotnet ef migrations has-pending-model-changes \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid

Det kontrollerar modell mot ett ögonblicksbild, inte huruvida produktionen har tillämpat varje migration . Det är inte driftdetektorn i scheman HasData värden som DateTime.Now eller Guid.NewGuid() kan skapa upprepade modellförändringar; fixa dem istället för att trycka ned kontrollen. EF Core 9 brytande förändringar.

UseSeeding och UseAsyncSeeding, introducerades i EF Core 9, körs under migrationslockning. verktygen och paketet använder den synkroniska hakenM SK3 så att implementera bara den asyncka är inte tillräckligtMSC4 Skörning kan utföras även när det inte finns några upphängande migrationerMska5 ett andra paket körs inte nödvändigtvis är något som inte gör det Mska6 op, Mska7 kolla för existerande data och göra operationen upprepabarMske8 Genererade SQL- skript kör inte dessa C-delegerade Sädebeteende.

EF Core 10: Observerns standardbegränsande namn

EF Core 10 är den nuvarande stabila LTS-utsläppen och kräver | . | NET | МSK2 | En migration |- | specifik tillsats för SQL Server är explicitt standard |

modelBuilder.Entity<Blog>()
    .Property(b => b.Rating)
    .HasDefaultValue(3, "DF_Blog_Rating");

Det finns också modelBuilder.UseNamedDefaultConstraints(). Om man gör det på ett redan model får nästa migration att omnämna varje standardbegränsning i det modellen . En liten Konfigurationsförändring kan därför leda till en stor migration Namerade standardbegränsningar; EF Core 10 release details.

Aspire kan äga orkestret

Aspire har nu en första migrationsresurs i klass - Aspire.Hosting.EntityFrameworkCore. I en AppHost , kan lokal utveckling uttrycka beroendet direkt

var migrations = api.AddEFMigrations("api-migrations")
    .RunDatabaseUpdateOnStart();

api.WaitForCompletion(migrations);

RunDatabaseUpdateOnStart() är lokalt-run-beteende PublishAsMigrationBundle() och PublishAsMigrationScript() producera utpostningsartefakter; paketet kan också publiceras som en behållare . Använd ett ett- -ett slag jobb istället för att permanent återstarta tjänsterna . Det här är orkestrering kring samma utpostningseparation Attspire migreringsintegration.

EF Core 11 Föreställelse : Säg dessa separata

Från och med denna redigering, EF Core 11 är fortfarande under utveckling. Den nuvarande dokumentationen innehåller egenskaper som är inte EF Core 10 alternativ:

• .config/dotnet-ef.json förser upprepade CLI-standarder som projekt, startprojekt och -kontext
• dotnet ef migrations remove --offline tar bort den senaste migrationn utan databaseuppkoppling. Du måste veta att den inte har tillämpats --force.
• migrations remove --connection väljer databaseuppkoppling explicit.
• dotnet ef database update AddFeature --add scaffolds, sammanfattar och applicerar en migration tillsammans . Praktisk utvecklings convenience

Se den version-märkt CLI referens och skapa- och- tillämpa dokumentation. Pinna dina verktyg istället för att anta att varje alternativ på den senaste docks-sidan finns i din installerade release

Vad sägs om?

vanliga frågor och bakslag I' har fått

" Varför inte bara springa dotnet ef database update i CI?"

Omfattade ovanför, men den korta versionen : paket är bärbara artefakter. ditt utplaceringsteg behöver inteMSC3 EF CLIM SK4 källkodMska5 eller designM Ska6 tidupplösningMske7 Samma paket körs i testerMssa8 stagingMsa9 och prod MSA10 samma kompilerade migrationerMsaka11 Anslutningskonfiguration och faktisk datadrift behöver fortfarande kontrollerasMSa12

" Är det? '? Är det här överkill för en liten app?

Kanske . Om du ' är ensam | , | är data offentliga ♫ , | och chockradien är låg ♫ MigrateAsync() är bra. Men så fort du lägger till en andra utvecklare , känsliga data M SK2 eller flera miljöer , byter betalar sig själva

"Vad sägs om rollbacks?

En misslyckad migration gynnar vanligtvis av EF/tillhandahållare-transaktionshantering, men vissa operationer kör utanför transaktioner . Det skiljer sig från att medvetet nedgradera en lyckad Veröffentlichung

• Runna paketet med en tidigare migration som dess positionella mål Down() metoder; det genererar inte en ny "Down migrationM SK2
• Återställ en provad backup när data behöver återställas
• Att skriva och implementera en ny korrigerande migration

Att återställa en rad som föll inte återställer dess innehåll. Försök och kolla Down() lika noggrant som Up().

För kritiska system: testa migrationer mot en databas klon först.

"Kan jag köra migrationer i en Kubernetes init-container

En init-container kan köra en bundle, men den kör bara en gång per kupol, inte en gång per utplacering . För replikerade produktionslaster , föredrar en dedikerad migration

initContainers:
  - name: migrate
    image: myapp:latest
    command: ["./efbundle"]
    env:
      - name: ConnectionStrings__Default
        valueFrom:
          secretKeyRef:
            name: db-secrets
            key: connection-string

App-containern väntar på att init-init är färdigt.. Bilden måste innehålla linuxpaketet och dess konfiguration.

" Vad sägs om FluentMigrator / DbUp | / | andra verktyg

De fungerar jättebra. Fluent-igrator och DbUp har sina fans. nyckelskillnader : de är migrationer- specifika verktygM SK3 medan EF-bundler kommer från din nuvarande EF-modell

"Mijn DBA vill övervaka all SQL innan den körs

Använda --idempotent skript:

dotnet ef migrations script --idempotent --output migrations.sql

DBA överprüfer och bekräftar. Om godkännandet är för den exakta SQLn som överprüft skriften och arkivera den med Veröffentlichungen. En paket genererar SQL vid uitvoeringstid och kan också köra konfigurerad frökod

" Hur hanterar jag migrationer med noll avbrott

Att "'" är en fråga om utpostningsstrategier, ",", inte om migrationer.

1. Expandera schemat med förändringar som den gamla appen kan tolerera, som en ny nullbel kolumn
2. Deploy koden som hanterar övergången, ,, inklusive dubbelskrivande när det behövs
3. fylla i existerande data och verifiera den
4. Switch läser och begränsar när både koden och data är redo
5. Kontrakt senare, att ta bort gamla kolumner först efter att gamla instanser har dränkts

Bundler löser inte detta. De ger ett kontrollerat sätt att leverera schemastepparna. . Locktid. , Tabellen omskrivs och bakuppfyllningar behöver fortfarande mätas.

Errata

Den ursprungliga versionen innehöll flera felaktiga kommandor och vissa påståenden som var för breda.

• No bundle dry run. efbundle --dry-run är inte supporterad. Generera ett SQL- skrypt för att bedöma --verbose fortfarande utför migrationer.
• Migrationen är positionell Använda efbundle PreviousMigration, inte --target-migration. mål 0 återvänder alla migrationer genom att utföra deras Down() metoder.
• Själva "-", omfattat av opt , "-, in, .," Ett standardpaket behöver fortfarande en kompatible .NET runtime. --self-contained inkluderar den för ett mål RID
• Schema tillstånd är inte synonymer med db_owner. Ge utställningsidentiteten de rättigheter som dess migrationer kräver, istället för att anamma en särskild SQL Server roll
• Ett utplaceringsportaal är inte automatiskt återställande. En misslyckad paket hindrar användningen, men transaktioner, -, försämrade operationer och dataförluster behöver sin egen återhämtningsplan. ., Att ta bort en migration från källan är inte en rollback på produktionen.
• Designern är inte bilden. Bedriv migrationen .Designer.cs metadata och det separata kontextmodellet
• Skripter följer migrationer. Genererade SQL-uppdateringar migrationshistoria. --idempotent lägger till kontroller på redan implementerade migrationer
• Anslutningskonfiguration är application-defined. Omgivningsvariabler påverkar kopplingen bara om kontexten
• Migrationslockning ändrar samspelningsrådet. EF Core 9+ skyddar migrationsöverdrag med en låsning . Den koordinerar inte live-insökningar eller gör brytande schemaförändringar säkra för gamla versioner
• En init behållare är per kapsyl. Det är inte en engångsprocess.
• En paket löser inte din överprüfda SQL-Datei. Där godkännande tässt innefattar SQL, implementera att artifacten. Bundler kan också köra konfigurerade frön , inklusive när inga migrationer finns kvar

De nya EF Core-elementen 11 är separat bemärkta för att se dem.