Entity Framework Core – Fluent API Mapper
Kiedy potrzebujemy użyć jakiegoś ORM’a (Object – Relational Mapping) w naszym projekcie, z reguły pierwsza myśl jaka przychodzi nam do głowy to Entity Framework. Dzięki temu narzędziu w bardzo prosty i szybki sposób jesteśmy w stanie skonfigurować połączenie z naszą bazą danych i odwzorować nasze tabele w projekcie. W najnowszej wersji dla .NET Core’a otrzymaliśmy również wsparcie dla innych baz. Poza Microsoft SQL Server połączymy się również z SQLite, PostgreSQL, czy MySQL. W najczęściej stosowanym podejściu do odwzorowania naszej bazy w projekcie, którym jest Code First (i na tę chwilę jedynym dostępnym dla Entity Framework Core), pojawia się problem odpowiedniej konfiguracji encji. Musimy zdefiniować odpowiednie klucze, relacje i właściwości kolumn. Możemy do tego wykorzystać odpowiednie atrybuty (Data Annotations) lub nadpisać metodę OnModelCreating na naszym kontekście i użyć Fluent API. Poniżej przedstawię Wam jak w schludny sposób definiować encje w Entity Framework Core.
Atrybyty, czy Fluent API?
To, którego podejścia użyjemy w projekcie zależy tylko i wyłącznie od zespołu, jego pomysłów i potrzeb projektu. Osobiście jestem zwolennikiem używania Fluent API, natomiast zdecydowanie nie jestem zwolennikiem stosowania obu podejść. Załóżmy, że mamy taką encję:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
public class SomeEntity { [Key] public int Id { get; set; } public byte[] RowVersion { get; set; } public DateTime CreationUtcDate { get; set; } public DateTime ModificationUtcDate { get; set; } [MaxLength(100)] public string SomeText { get; set; } public int SomeNumber { get; set; } } |
Teraz spójrzmy na przykładową metodę OnModelCreating w naszym kontekście:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder.Entity<SomeEntity>() .Property(p => p.SomeNumber) .IsRequired(); modelBuilder.Entity<SomeEntity>() .Property(p => p.SomeText) .IsRequired(); base.OnModelCreating(modelBuilder); } |
W tym momencie mamy konfigurację w dwóch różnych miejscach. Przy jednej encji jest to widoczne, ale co w momencie, gdy mamy ich na przykład dwieście? Nasza metoda przybiera rozmiary na setki linijek kodu. Przyjdzie moment w którym musimy określić jakąś relację między encjami i nie wiemy gdzie wprowadzić zmiany. Niejedna osoba wejdzie do pliku encji, zauważy brak relacji i doda odpowiednie atrybuty. Niestety nie zauważy, że w metodzie OnModelCreating w linii 1236 taka relacja już jest – mamy konflikt. Skoro nie lubię atrybutów, to jak w takim razie uniknąć rozrastającego się kontekstu Entity Framework’a przez kolejne odwołania do Fluent API? Skoro ma być schludnie, to spróbujmy to poukładać.
Interfejsy dla encji
Na początku wyciągam część wspólną każdej encji, czyli klucz główny. Zacznijmy od zdefiniowania takiego generycznego interfejsu:
|
1 2 3 4 5 |
public interface IIdentifiableEntity<TKey> { TKey Id { get; set; } bool IsNew(); } |
Klucz główny może przyjmować różne typy: long, int, lub Guid. Warto więc już na początku zadbać o to, aby można było go swobodnie wybrać w zależności od potrzeby. Dodałem tutaj również przydatną deklarację metody IsNew. Następnie interesuje mnie historyczność encji, czyli daty utworzenia i ostatniej modyfikacji. Oddzieliłem je ponieważ zdarzają się tabele, które nie potrzebują takich informacji. Dodatkowo zadbamy też o konkurencję na poziomie encji. Stwórzmy więc kolejny interfejs:
|
1 2 3 4 5 6 |
public interface IAuditableEntity { byte[] RowVersion { get; set; } DateTime CreationUtcDate { get; set; } DateTime ModificationUtcDate { get; set; } } |
Teraz zdefiniujmy naszą encję i zaimplementujmy nasze interfejsy:
|
1 2 3 4 5 6 7 8 9 10 |
public class SomeEntity : IAuditableEntity, IIdentifiableEntity<int> { public int Id { get; set; } public byte[] RowVersion { get; set; } public DateTime CreationUtcDate { get; set; } public DateTime ModificationUtcDate { get; set; } public string SomeText { get; set; } public int SomeNumber { get; set; } public bool IsNew() => Id == 0; } |
Mapper – implementacja
Za konfigurację encji odpowiada typ EntityTypeBuilder dostępny razem z Entity Framework’iem. Mając tę wiedzę możemy utworzyć klasę abstrakcyjną z mapowaniem klucza głównego:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
public abstract class IdentifiableEntityMapper<TEntity, TKey> where TEntity : class, IIdentifiableEntity<TKey> { protected readonly string _schemaName; protected IdentifiableEntityMapper(string schemaName) { _schemaName = schemaName; } public virtual void Map(EntityTypeBuilder<TEntity> entity) { entity .ToTable(typeof(TEntity).Name, _schemaName) .HasKey(e => e.Id); } } |
EntityTypeBuilder musi wiedzieć, że nasz generyczny typ to typ referencyjny, potrzebujemy też informacji o kluczu głównym. Jako parametr konstruktora przyjmujemy nazwę schematu dla naszej tabeli. Metoda Map odpowiada tutaj za ustawienie klucza głównego, nazwy tabeli i schematu. Rozwińmy to o kolejny mapper:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
public abstract class AuditableEntityMapper<TEntity, TKey> : IdentifiableEntityMapper<TEntity, TKey> where TEntity : class, IAuditableEntity, IIdentifiableEntity<TKey> { protected AuditableEntityMapper(string schemaName) : base(schemaName) { } public override void Map(EntityTypeBuilder<TEntity> entity) { base.Map(entity); entity.Property(p => p.RowVersion) .IsConcurrencyToken() .IsRowVersion(); entity.Property(p => p.CreationUtcDate) .HasColumnType("datetime2"); entity.Property(p => p.ModificationUtcDate) .HasColumnType("datetime2"); } } |
Celowo dziedziczę po klasie IdentifiableEntityMapper. Zabieg ten ma mi ułatwić dodawanie odpowiednich konfiguracji w kontekście Entity Framework’a. Oczywiście możemy zmienić sposób implementacji według naszych potrzeb (np. dla klucza kompozytowego można dodać kolejny mapperm czy usunąć dziedziczenie i zaimplementować dodawanie mapperów na różne sposoby). W metodzie Map ustawiliśmy, że pole RowVersion odpowiada za wersję i konkurencję. Pola dla daty utworzenia i modyfikacji rekordu są domyślnie ustawione jako wymagane (nie są typu nullable), dlatego ustawiamy tylko typ ich pola jako datetime2.
Model Builder Extension Methods
W starszej wersji Entity Framework’a mieliśmy gotowe metody umożliwiające dodanie odpowiedniej konfiguracji. W wersji dla .NET Core’a nie jest to już takie proste, dlatego musimy napisać do tego własny mechanizm. Jeśli przyjrzymy się metodzie Entity w klasie ModelBuilder zauważymy, że jako parametr przyjmuje ona obiekt typu Action<EntityTypeBuilder<TEntity>>. Możemy więc napisać taką klasę:
|
1 2 3 4 5 6 7 8 |
public static class ModelBuilderExtensions { public static ModelBuilder AddMapper<TEntity, TKey>(this ModelBuilder modelBuilder, IdentifiableEntityMapper<TEntity, TKey> entityConfiguration) where TEntity : class, IIdentifiableEntity<TKey> { return modelBuilder.Entity<TEntity>(entityConfiguration.Map); } } |
Entity mapper
W tym momencie możemy już zaimplementować mapper dla naszej encji, a następnie wywołać metodę AddConfiguration w naszym kontekście w metodzie OnModelCreating:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
public sealed class SomeEntityMapper : AuditableEntityMapper<SomeEntity, int> { public SomeEntityMapper() : base(schemaName: "Sample") { } public override void Map(EntityTypeBuilder<SomeEntity> entity) { entity.Property(p => p.SomeText) .IsRequired() .HasMaxLength(200); entity.Property(p => p.SomeNumber) .IsRequired(); base.Map(entity); } } |
|
1 2 3 4 5 6 7 |
protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder .AddMapper(new SomeEntityMapper()); base.OnModelCreating(modelBuilder); } |
Dla zachowania porządku zalecam dodawanie kolejnych mapperów w porządku alfabetycznym.
Podsumowanie
W każdym projekcie z Entity Framework’iem musimy w jakiś sposób definiować nasze encje. Na pewno warto zastanowić się jak chcemy to robić, ponieważ bez odpowiedniego porządku łatwo o błędy. Powyższe rozwiązania pozwala nam trzymać konfiguracje encji w jednym miejscu, a dzięki Fluent API nie musimy się martwić o atrybuty. Unikamy w ten sposób rozrastającej się metody OnModelCreating, a w razie potrzeby edytowania któregoś mappera wiemy gdzie należy wprowadzić odpowiednie zmiany. To tylko jeden z wielu sposobów na implementację takiego mechanizmu. Zamiast interfejsów można tworzyć klasy abstrakcyjne, można też implementować dodatkowe metody rozszerzające dla klasy Model Builder – wszystko zależy od naszych potrzeb. Jeśli macie jakieś równie ciekawe pomysły na trzymanie porządku w swoich projektach z Entity Framework’iem, zapraszam do dyskusji 🙂
Istnieje również możliwość wygenerowania kodu z istniejącej bazy. Prawdopodobnie nie ma jeszcze designera ale jest ‘Scaffold-DbContext’
https://docs.microsoft.com/en-us/ef/core/get-started/aspnetcore/existing-db
Atrybuty mają jeszcze jedną ważną zaletę – informacje o modelu trzymane są w jednym miejscu i w przypadku dużych struktur, pisanych przez obce osoby łatwiej jest zobaczyć zależności, typy, ograniczenia. We fluent api powstanie dużo kodu, który po osiągnięciu dużych rozmiarów może być trudny w utrzymywaniu.
Ja też się zastanawiam co lepsze. Przy małym kodzie kwestia wyboru ale jak pisze więcej to czasem zastanawiam się nad wyższością FluentAPI bo w modelu widzę od razu [xxxx] nad polem a we fluent hmm