EF Core 8 - sentinel values

Wstęp

Co to są sentinel values w EF Core 8 i jak z nich korzystać 😊

Przykład na początek

Mamy tabelę Customers, która wygląda tak:

CREATE TABLE [dbo].[Customers](
	[Id] [int] IDENTITY(1,1) NOT NULL,
	[Name] [nvarchar](max) NOT NULL,
	[Status] [int] NOT NULL,
	[Points] [int] NOT NULL,
	[Created] [datetime2](7) NOT NULL,

-- [... other, not relevant SQL code ...]

ALTER TABLE [dbo].[Customers] ADD  DEFAULT ((1)) FOR [Status]
ALTER TABLE [dbo].[Customers] ADD  DEFAULT ((10)) FOR [Points]
ALTER TABLE [dbo].[Customers] ADD  DEFAULT (getdate()) FOR [Created]
ALTER TABLE [dbo].[Customers] ADD  DEFAULT (N'') FOR [Name]

Bardzo prosta tabela, zaznaczę tylko że Status to jest enum w kodzie.
Tabela zawiera informacje o klientach, każdy klient posiada:

• nazwę,
• status (new, verified, deactivated), domyślna wartość to: New oraz
• liczbę punktów, domyślna wartość to 10.

W kodzie konfiguracja pola Points wygląda tak:

modelBuilder.Entity<Customer>()
	.Property(x => x.Points)
	.IsRequired()
	.HasDefaultValue(10);

Przyda Nam się to w dalszej części wpisu. Konfiguracja innych pól Nas nie interesuje.

Dodawanie klientów

Dodajemy dwóch klientów:

• dla pierwszego używamy domyślnych wartości kolumn,
• dla drugiego chcemy z góry ustalić że będzie miał ZERO punktów.

AddCustomer(new Customer {Name = "Default values, points: 10"});
AddCustomer(new Customer {Name = "Zero points", Points = 0 });

Co otrzymujemy w wyniku takiego kodu:

Każdy klient ma 10 punktów. Przecież jasno wskazaliśmy, że ma być 0.

Co się stało? 🤔

Wartości domyślne w konfiguracji EF Core

Wartość domyślna (CLR default) dla default(int) to jest właśnie 0.
EF Core działa tak, że musi wiedzieć kiedy do bazy wstawić tą naszą wartość domyślną. Czyli 10 w przypadku punktów. Porównuje właśnie wstawianą wartość do domyślnej wartości tego typu w .NET.

W naszym przypadku chcieliśmy wpisać klientowi 0 punktów, czyli default(int), więc została wstawiona nasza wartość domyślna czyli 10.

Sentinel values

I tutaj wchodzą do gry sentinel values czyli po polsku wartości wartownicze 😊

Żeby móc wstawić klientowi 0 punktów trzeba skonfigurować pole w następujący sposób:

modelBuilder.Entity<Customer>()
	.Property(x => x.Points)
	.IsRequired()
	.HasDefaultValue(10)
	.HasSentinel(-1);

To oznacza że jak będzie 0 to wstaw 0, jak będzie -1 to wstaw wartość domyślną, czyli w tym przypadku 10.

Przy takiej konfiguracji do bazy zostaną zapisane takie dane:

Każdy klient ma 0 punktów. Co tym razem się stało? 🤔

Wartości domyślne w modelu

Stało się to, że pierwszy klient nie ma ustawionych punktów, czyli default(int) = 0, a 0 można już wstawić do tabeli i to się właśnie stało 😊

// TUTAJ JEST POINTS == 0
AddCustomer(new Customer {Name = "Default values, points: 10"});
AddCustomer(new Customer {Name = "Zero points", Points = 0 });

Żeby wszystko działało tak jak chcemy, to trzeba w modelu zrobić wartość domyślną dla punktów:

public sealed class Customer
{
    [...other code...]

    public int Points { get; init; } = 10; // << Domyślne 10 punktów
    
    [...other code...]
}

Dopiero wtedy wszystko będzie w bazie się zapisywało tak jak chcemy.

W tym momencie wartość domyślna 10 jest w dwóch miejscach: w modelu oraz konfiguracji EF Core. Żeby nie duplikować danych można od razu w modelu dać -1, tą wartość ustawioną jako wartownik (metoda HasSentinel) i wtedy wszystko będzie działać jak tego oczekujemy.

// sentinel value configure in OnModelCreating
public int Points { get; init; } = -1;

Drugi sposób

Inny sposobem na poradzenie sobie z tym jest zrobienie pola nullowalnego dla naszej właściwości i tam ogarnięcie tej wartości domyślnej.

private readonly int? _points;

public int Points
{
    get => _points ?? 10;
    init => _points = value;
}

W konfiguracji już nie trzeba robić .HasSentinel(-1).

Podsumowanie

Jak widać na powyższym przykładzie trzeba uważać z wartościami domyślnymi dla kolumn. Może to trochę popsuć nasze dane. Po pewnym czasie może się okazać, że na produkcji klient ma za dużo punktów lub za mało niż na prawdę powinien mieć 😊.

Kod którego użyłem we wpisie znajduje się na moin GitHubie: https://github.com/tomaszprasolek/EfCore8_SentinelValues

Linki

• What’s New in EF Core 8