Von Entity Framework 6 zu EF Core auf einer bestehenden Datenbank: ein Fallbeispiel

Entity Framework 6 funktioniert weiterhin und erhält Sicherheitskorrekturen, aber keine neuen Funktionen mehr. Alles Neue beim Datenzugriff in .NET entsteht in EF Core. Früher oder später steht dieser Wechsel bei jeder langlebigen .NET-Anwendung an. Die Datenbank bleibt dabei: Sie ist voller Daten, und andere Systeme lesen sie. Die eigentliche Aufgabe lautet also, EF Core mit Tabellen arbeiten zu lassen, die Entity Framework 6 entworfen hat, und nachzuweisen, dass sich die Anwendung danach gleich verhält.

Dieses Fallbeispiel zeigt das an einer kleinen Auftragsverwaltung. Der Code liegt auf GitHub: chudovo/application-modernization, Case 05. Code und Kommentare sind auf Englisch. Es ist der Schritt nach dem Umzug der Anwendung von .NET Framework auf .NET 10.

Auf einen Blick

VorherNachher
BibliothekEntity Framework 6.5EF Core 10
DatenbankSQL Server, von EF6 Code First angelegtdieselbe Datenbank, unverändert
MappingKonventionen und wenige Attributeausgeschrieben, passend zu den vorhandenen Tabellen
Verknüpfte DatenLazy Loading über virtuelle EigenschaftenInclude oder eine Projektion je Abfrage
Eigenes SQLSqlQuery mit SqlParameterSqlQuery mit interpolierter Zeichenkette
Migrationsverlauf__MigrationHistory__EFMigrationsHistory, beginnend mit einer leeren Baseline
Gemeinsame Szenarien bestanden17 von 1717 von 17

Zwei Schritte statt einem

Entity Framework 6 läuft seit Version 6.3 auf modernem .NET. Laufzeit und Datenzugriffsbibliothek müssen also nicht im selben Release wechseln. Die alte Datenschicht in diesem Fallbeispiel ist Entity Framework 6.5 auf .NET 10, unter Linux, gegen einen SQL Server im Container. Wer noch auf .NET Framework ist, zieht zuerst die Laufzeit um und behält EF6. Danach wird EF6 als eigene Änderung mit eigenen Tests ersetzt.

Die bestehende Datenbank

Das Schema im Repository ist nicht von Hand geschrieben. Es ist das Skript, das die Code-First-Migrationen von Entity Framework 6 für das alte Modell erzeugen, und der Build erzeugt es erneut, um Abweichungen zu erkennen. Es zeigt, was EF6 per Konvention entschieden hat:

-- Generated by Entity Framework 6 Code First Migrations for the old model
CREATE TABLE [dbo].[Orders] (
    [Id] [int] NOT NULL IDENTITY,
    [CreatedUtc] [datetime] NOT NULL,
    [Total] [decimal](18, 2) NOT NULL,
    [RowVersion] rowversion NOT NULL,
    [Customer_Id] [int] NOT NULL,
    CONSTRAINT [PK_dbo.Orders] PRIMARY KEY ([Id])
)
CREATE TABLE [dbo].[TagOrders] (
    [Tag_Id] [int] NOT NULL,
    [Order_Id] [int] NOT NULL,
    CONSTRAINT [PK_dbo.TagOrders] PRIMARY KEY ([Tag_Id], [Order_Id])
)
CREATE INDEX [IX_Customer_Id] ON [dbo].[Orders]([Customer_Id])

Drei dieser Entscheidungen werden später wichtig: Die Fremdschlüsselspalte heißt Customer_Id, die Verknüpfungstabelle der n:m-Beziehung heißt TagOrders, und Datumswerte liegen als datetime vor.

Schritt 1: Szenarien, die gegen beide Versionen laufen

Der gesamte Datenzugriff der Anwendung liegt hinter einer Klasse, OrderStore, mit denselben öffentlichen Methoden in beiden Versionen. Dadurch lässt sich eine Quelldatei mit 17 Szenarien gegen die EF6-Datenschicht und gegen die EF-Core-Datenschicht kompilieren. Jeder Test erhält eine frische Datenbank mit dem EF6-Schema und Zeilen, wie die alte Anwendung sie geschrieben hat, auf einem echten SQL Server:

[Fact]
public void New_order_is_stored_with_lines_total_and_tags()
{
    var id = _store.PlaceOrder(new NewOrder(2, Noon,
        [Line("LAMP-07", 3, 39.99m), Line("SHELF-03", 1, 120.00m)], "priority", "export"));

    var order = _store.GetOrder(id);
    Assert.Equal("Atelier Dubois", order.CustomerName);
    Assert.Equal(239.97m, order.Total);
    Assert.Equal(["export", "priority"], order.Tags);

    // The existing tag is reused, the new one is created once.
    Assert.Equal(["export", "priority", "wholesale"], _database.Rows("SELECT Name FROM dbo.Tags ORDER BY Name"));
}

Die Szenarien decken das Lesen vorhandener Aufträge und Kunden ab, neue Aufträge mit Positionen und Tags, die n:m-Beziehung, optimistische Nebenläufigkeit mit Zeilenversion, kaskadierendes Löschen, einen gruppierten Bericht, handgeschriebenes SQL, Paging und einen Import, der ganz oder gar nicht gespeichert wird.

Schritt 2: EF Core mitteilen, was EF6 entschieden hat

Auch EF Core hat Konventionen, nur andere. Alles, was EF6 stillschweigend gewählt hat, muss ausgeschrieben werden, damit das Modell zu den vorhandenen Tabellen passt:

model.Entity<Order>(order =>
{
    order.HasKey(o => o.Id).HasName("PK_dbo.Orders");

    // EF6 mapped DateTime to datetime. EF Core would assume datetime2.
    order.Property(o => o.CreatedUtc).HasColumnType("datetime");

    // The class has no foreign key property. EF6 named the column Customer_Id, EF Core would look for CustomerId.
    order.HasOne(o => o.Customer).WithMany(c => c.Orders)
        .HasForeignKey("Customer_Id").IsRequired()
        .HasConstraintName("FK_dbo.Orders_dbo.Customers_Customer_Id");
    order.HasIndex("Customer_Id").HasDatabaseName("IX_Customer_Id");

    // The join table: EF6 called it TagOrders, EF Core would look for OrderTag with OrdersId and TagsId.
    order.HasMany(o => o.Tags).WithMany(t => t.Orders).UsingEntity<Dictionary<string, object>>(
        "TagOrders",
        right => right.HasOne<Tag>().WithMany().HasForeignKey("Tag_Id"),
        left => left.HasOne<Order>().WithMany().HasForeignKey("Order_Id"),
        join => join.HasKey("Tag_Id", "Order_Id").HasName("PK_dbo.TagOrders"));
});

Um zu sehen, wie viel davon abhängt, wurde jeder Teil aus der fertigen EF-Core-Version entfernt und die Tests liefen erneut:

Aus der EF-Core-Version entferntErgebnis
Das gesamte Mapping von Beziehungen und Tabellen (nur EF-Core-Konventionen)14 von 17 Szenarien schlagen fehl: Invalid column name ‚CustomerId‘, Invalid object name ‚OrderTag‘
Include in der Methode, die einen Auftrag liest6 von 17 Szenarien schlagen mit NullReferenceException fehl
Die Umwandlung der Dezimalwerte1 Szenario schlägt fehl: 19,999 wird als 20,00 statt 19,99 gespeichert
Der Spaltentyp datetimealle 17 Szenarien bestehen, die Schemaprüfungen schlagen fehl
Namen von Schlüsseln, Indizes und Constraintsalle 17 Szenarien bestehen, die Schemaprüfungen schlagen fehl

Lazy Loading gibt es nicht mehr

EF6-Code liest oft eine Entität und hangelt sich zu deren Verwandten. Jeder Schritt ist eine versteckte Abfrage. In EF Core ist die Navigationseigenschaft schlicht null:

// Entity Framework 6: Customer, Lines and Tags load on first access, one query each.
var order = db.Orders.Find(id);
return new OrderDetails { CustomerName = order.Customer.Name, /* ... */ };

// EF Core: the same line throws NullReferenceException. The query has to name what it needs.
var order = db.Orders
    .Include(o => o.Customer).Include(o => o.Lines).Include(o => o.Tags)
    .AsSplitQuery().AsNoTracking()
    .SingleOrDefault(o => o.Id == id) ?? throw new NotFoundException("Order " + id);

EF Core hat ein Paket, das Lazy Loading zurückbringt. Wer es nutzt, um sich diese Arbeit zu sparen, behält die versteckten Abfragen, und die sind meist der Grund, warum die Datenschicht langsam ist. Jeden Lesezugriff einmal durchzugehen ist die sinnvollere Investition.

Dezimalwerte werden gerundet, nicht abgeschnitten

Dieser Unterschied erzeugt in keiner Version einen Fehler. Ein Preis mit drei Nachkommastellen in einer Spalte mit zwei: Entity Framework 6 speichert 19,999 als 19,99, EF Core speichert 20,00. Ein Szenario hat das gefunden. Ein Bibliothekswechsel darf Geldbeträge nicht verändern, deshalb behält die neue Version das alte Verhalten ausdrücklich bei:

// 19.999 written to a decimal(18,2) column: EF6 stored 19.99, EF Core stores 20.00.
// Money must not change during a library upgrade, so the old behaviour is kept, in one place.
private static readonly ValueConverter<decimal, decimal> AsEf6Stored =
    new(value => decimal.Round(value, 2, MidpointRounding.ToZero), value => value);

line.Property(l => l.UnitPrice).HasPrecision(18, 2).HasConversion(AsEf6Stored);

Ob das Abschneiden fachlich gewollt ist, ist eine berechtigte Frage. Sie sollte bewusst beantwortet werden und nicht durch ein Paket-Update.

Die Unterschiede, die kein Szenario findet

Die letzten beiden Zeilen der Tabelle oben sind die gefährlichen. Bleibt das Datum beim EF-Core-Standard datetime2 oder gelten die EF-Core-Standardnamen für Schlüssel und Indizes, bestehen alle Szenarien. Die Anwendung funktioniert. Das Problem zeigt sich Wochen später bei der ersten echten Migration: Sie versucht, Spalten zu ändern und Objekte umzubenennen oder zu löschen, die unter diesen Namen nicht existieren.

Deshalb gibt es im Fallbeispiel eine zweite Art von Test. Er liest den Katalog der bestehenden Datenbank, erzeugt dieselbe Beschreibung aus dem EF-Core-Modell und vergleicht beide Zeile für Zeile: jede Spalte mit Typ und Nullbarkeit, jeden Schlüssel, Fremdschlüssel und Index mit seinem Namen.

Migrationen: mit einer leeren Baseline beginnen

Die Tabellen existieren, die erste EF-Core-Migration darf sie also nicht anlegen. Das Werkzeug erzeugt eine Migration voller CREATE-TABLE-Anweisungen, ihr Inhalt wird gelöscht. Beim Anwenden entsteht nur eine Zeile in der neuen Verlaufstabelle. Der daneben erzeugte Modell-Snapshot beschreibt die bestehende Datenbank, und jede spätere Migration ist eine Differenz dazu. Ein Test belegt, dass die Baseline nichts ändert:

[Fact]
public void The_baseline_migration_changes_no_table_and_is_recorded()
{
    var before = Database(line => !IsHistoryTable(line));   // every column, key, foreign key and index, one per line
    using var db = OrderDeskContext.Open(_database.ConnectionString);

    db.Database.Migrate();

    Assert.Equal(before, Database(line => !IsHistoryTable(line)));
    Assert.False(db.Database.HasPendingModelChanges());
}

Die alte Verlaufstabelle von EF6 bleibt bestehen. Sie kostet nichts und dokumentiert, wie das Schema entstanden ist.

Ein Unterschied in die andere Richtung

Ein vorhandener Auftrag wurde um 09:15:00.123 angelegt. Die Suche nach genau diesem Zeitpunkt findet mit EF6 nichts und mit EF Core den Auftrag. EF6 sendet den Wert als datetime2, und SQL Server wandelt den gespeicherten datetime-Wert vor dem Vergleich in 09:15:00.1233333 um. EF Core vergleicht exakt, weil die Spalte als datetime gemappt ist. Der Wechsel behebt also eine Suche, die stillschweigend nie funktioniert hat. Auch das ist eine Verhaltensänderung, deshalb ist sie als je ein Test pro Version festgehalten und nicht versteckt.

Was geprüft ist und was nicht

PrüfungErgebnis
17 Szenarien gegen Entity Framework 6, SQL Server 202217 / 17
17 Szenarien gegen EF Core 10, SQL Server 202217 / 17
EF-Core-Modell entspricht dem bestehenden Schema, einschließlich der Namenidentisch
Baseline-Migration ändert keine Tabelle, vorhandene Daten danach lesbarbesteht
Eingechecktes Schemaskript entspricht dem, was EF6 erzeugtidentisch
  • Die Performance wurde nicht gemessen. Die Zahl der Datenbankzugriffe ändert sich, die Wirkung auf eine echte Last wurde nicht verglichen.
  • Alt und Neu liefen nicht nebeneinander. Bei einem Rollout schreiben oft beide Versionen eine Zeit lang in dieselbe Datenbank. Das Schema bleibt unberührt, es sollte also funktionieren, aber kein Test führt beide gleichzeitig aus.
  • Nur SQL Server, nur Code First. Kein EDMX-Modell, kein Mapping auf gespeicherte Prozeduren, keine Table-per-Type-Vererbung, keine Geodatentypen. Jedes davon ist ein eigenes Thema.
  • Die API bleibt synchron, in beiden Versionen, wie im Original.

In der Testumgebung ging eine Sache schief: Der Connection-String-Builder des neuen SQL-Clients schreibt die Option als Trust Server Certificate, mit Leerzeichen, und der alte Client lehnt das mit Keyword not supported ab. Lesen beide Versionen während eines Rollouts dieselbe Konfiguration, sollte die Schreibweise ohne Leerzeichen verwendet werden.

Selbst ausführen

Benötigt werden das .NET 10 SDK und Docker für den SQL Server. Die Tests legen ihre Datenbanken selbst an und löschen sie wieder:

docker run -d -e ACCEPT_EULA=Y -e MSSQL_SA_PASSWORD=Local_dev_only_1 -p 14330:1433 mcr.microsoft.com/mssql/server:2022-latest
dotnet test before/tests/OrderDesk.Scenarios
dotnet test after/tests/OrderDesk.Scenarios

Wann dieser Weg passt

Die Datenzugriffsbibliothek unter einer laufenden Anwendung auszutauschen ist eine abgegrenzte Änderung: keine neuen Funktionen, kein neues Schema und eine klare Definition von fertig. Sie passt, sobald die Anwendung auf modernem .NET läuft und das Team nutzen möchte, was EF Core bietet, von besserem SQL bis zu kompilierten Modellen und Massenaktualisierungen. Ist die Datenbank selbst das Problem, ist das ein anderes Projekt. Wie die Teile eines solchen Vorhabens zusammenpassen, behandeln der Leitfaden zur Strategie für die Anwendungsmodernisierung und die Leitlinien zur Modernisierung von Datenbanken.

Wenn Sie für eine solche Migration ein Team suchen, finden Sie hier unseren Vergleich der Top-Unternehmen für .NET-Modernisierung.

Eugene begann seine Karriere bei Chudovo im Jahr 2015. Der Experte ist für Beratungsleistungen verantwortlich, die unter anderem eine enge Kommunikation mit den Kunden, die Analyse ihrer Bedürfnisse, die Entwicklung maßgeschneiderter Softwarestrategien usw. umfassen. Während seiner Tätigkeit bei Chudovo nahm ein IT-Berater an über 17 Projekten teil, die ein breites Spektrum an Kundendienstleistungen abdeckten und Kundenprobleme aus geschäftlicher Sicht lösten. Dank Eugenes Beteiligung konnten die Kunden eine effiziente Strategie für das Geschäftswachstum sowie eine langfristige Technologie-Roadmap entwickeln. Eugene nimmt in der Rolle des IT-Beraters aktiv an Softwareentwicklungsprojekten teil und erstellt Vorschläge für die Kunden.