Tworzenie i konfigurowanie modelu

Program EF Core używa modelu metadanych do opisania sposobu mapowania typów jednostek aplikacji na bazową bazę danych. Ten model jest tworzony przy użyciu zestawu konwencji — heurystyki, które szukają typowych wzorców. Następnie model można dostosować przy użyciu atrybutów mapowania (nazywanych również adnotacjami danych) i/lub wywołań ModelBuilder metod (nazywanych również płynnym interfejsem API) w systemie OnModelCreating, z których obie zastąpią konfigurację wykonywaną przez konwencje.

Większość konfiguracji można zastosować do modelu przeznaczonego dla dowolnego magazynu danych. Dostawcy mogą również włączyć konfigurację specyficzną dla określonego magazynu danych, a także zignorować konfigurację, która nie jest obsługiwana lub nie dotyczy. Aby uzyskać dokumentację dotyczącą konfiguracji specyficznej dla dostawcy, zobacz sekcję Dostawcy baz danych .

Wskazówka

Przykłady tego artykułu można wyświetlić w witrynie GitHub.

Konfigurowanie modelu przy użyciu płynnego interfejsu API

Możesz zastąpić metodę OnModelCreating w kontekście pochodnym i użyć płynnego interfejsu API do skonfigurowania modelu. Jest to najbardziej zaawansowana metoda konfiguracji i umożliwia określenie konfiguracji bez modyfikowania klas jednostek. Konfiguracja interfejsu API Fluent ma najwyższy priorytet i zastąpi konwencje i adnotacje danych. Konfiguracja jest stosowana w kolejności wywoływania metod i jeśli występują konflikty, najnowsze wywołanie zastąpi wcześniej określoną konfigurację.

using Microsoft.EntityFrameworkCore;

namespace EFModeling.EntityProperties.FluentAPI.Required;

internal class MyContext : DbContext
{
    public DbSet<Blog> Blogs { get; set; }

    #region Required
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Blog>()
            .Property(b => b.Url)
            .IsRequired();
    }
    #endregion
}

public class Blog
{
    public int BlogId { get; set; }
    public string Url { get; set; }
}

Wskazówka

Aby zastosować tę samą konfigurację do wielu obiektów w modelu, zobacz konfigurację zbiorczą.

Konfiguracja grupowania

Aby zmniejszyć rozmiar metody OnModelCreating, całą konfigurację dla typu jednostki można wyodrębnić do oddzielnej klasy implementującej IEntityTypeConfiguration<TEntity>.

public class BlogEntityTypeConfiguration : IEntityTypeConfiguration<Blog>
{
    public void Configure(EntityTypeBuilder<Blog> builder)
    {
        builder
            .Property(b => b.Url)
            .IsRequired();
    }
}

Następnie po prostu wywołaj metodę Configure z klasy OnModelCreating.

new BlogEntityTypeConfiguration().Configure(modelBuilder.Entity<Blog>());

Stosowanie wszystkich konfiguracji w zestawie

Można zastosować całą konfigurację określoną w typach implementujących IEntityTypeConfiguration w określonym zbiorze.

modelBuilder.ApplyConfigurationsFromAssembly(typeof(BlogEntityTypeConfiguration).Assembly);

Uwaga / Notatka

Kolejność stosowania konfiguracji jest niezdefiniowana, dlatego ta metoda powinna być używana tylko wtedy, gdy kolejność nie ma znaczenia.

Używanie EntityTypeConfigurationAttribute w typach jednostek

Zamiast jawnie wywoływać Configure, można umieścić EntityTypeConfigurationAttribute na typie encji, aby EF Core mógł znaleźć i zastosować odpowiednią konfigurację. Przykład:

[EntityTypeConfiguration(typeof(BookConfiguration))]
public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Isbn { get; set; }
}

Ten atrybut oznacza, że program EF Core będzie używać określonej IEntityTypeConfiguration implementacji za każdym razem, gdy Book typ jednostki jest uwzględniony w modelu. Typ jednostki jest uwzględniany w modelu przy użyciu jednego z normalnych mechanizmów. Na przykład przez utworzenie DbSet<TEntity> właściwości dla typu jednostki:

public class BooksContext : DbContext
{
    public DbSet<Book> Books { get; set; }

    //...

Lub rejestrując go w programie OnModelCreating:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Book>();
}

Uwaga / Notatka

EntityTypeConfigurationAttribute typy nie zostaną automatycznie odnalezione w zestawie. Typy jednostek należy dodać do modelu, zanim atrybut zostanie odnaleziony w tym typie jednostki.

Konfigurowanie modelu przy użyciu adnotacji danych

Do klas i właściwości można również zastosować pewne atrybuty (znane jako adnotacje danych). Adnotacje danych zastąpią konwencje, ale zostaną zastąpione przez konfigurację interfejsu API Fluent.

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;

namespace EFModeling.EntityProperties.DataAnnotations.Annotations;

internal class MyContext : DbContext
{
    public DbSet<Blog> Blogs { get; set; }
}

[Table("Blogs")]
public class Blog
{
    public int BlogId { get; set; }

    [Required]
    public string Url { get; set; }
}

Konwencje wbudowane

Program EF Core zawiera wiele konwencji tworzenia modeli, które są domyślnie włączone. Wszystkie z nich można znaleźć na liście klas, które implementują IConvention interfejs. Jednak ta lista nie zawiera konwencji wprowadzonych przez dostawców i wtyczek baz danych innych firm.

Aplikacje mogą usuwać lub zastępować dowolną z tych konwencji, a także dodawać nowe konwencje niestandardowe które stosują konfigurację dla wzorców, które nie są rozpoznawane przez EF w podstawowej konfiguracji.

Wskazówka

Poniższy kod pochodzi z ModelBuildingConventionsSample.cs.

Usuwanie istniejącej konwencji

Czasami jedna z wbudowanych konwencji może nie być odpowiednia dla aplikacji, w tym przypadku można ją usunąć.

Wskazówka

Jeśli model nie używa atrybutów mapowania, czyli adnotacji danych, do konfiguracji, można bezpiecznie usunąć wszystkie konwencje o nazwie kończącej się na AttributeConvention, aby przyspieszyć tworzenie modelu.

Przykład: nie twórz indeksów dla kolumn kluczy obcych

Zwykle warto utworzyć indeksy dla kolumn klucza obcego (FK), dlatego istnieje wbudowana konwencja dla tego: ForeignKeyIndexConvention. Patrząc na widok debugowania modelu dla Post typu jednostki z relacjami z Blog i Author, możemy zobaczyć, że dwa indeksy są tworzone — jeden dla BlogId klucza FK, a drugi dla AuthorId klucza FK.

  EntityType: Post
    Properties:
      Id (int) Required PK AfterSave:Throw ValueGenerated.OnAdd
      AuthorId (no field, int?) Shadow FK Index
      BlogId (no field, int) Shadow Required FK Index
    Navigations:
      Author (Author) ToPrincipal Author Inverse: Posts
      Blog (Blog) ToPrincipal Blog Inverse: Posts
    Keys:
      Id PK
    Foreign keys:
      Post {'AuthorId'} -> Author {'Id'} ToDependent: Posts ToPrincipal: Author ClientSetNull
      Post {'BlogId'} -> Blog {'Id'} ToDependent: Posts ToPrincipal: Blog Cascade
    Indexes:
      AuthorId
      BlogId

Jednak indeksy mają obciążenie i może nie zawsze być odpowiednie do utworzenia ich dla wszystkich kolumn FK. Aby to osiągnąć, ForeignKeyIndexConvention można go usunąć podczas kompilowania modelu:

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Conventions.Remove(typeof(ForeignKeyIndexConvention));
}

Patrząc na widok debugowania modelu na Post razie, widzimy, że indeksy na zestawach FKs nie zostały utworzone:

  EntityType: Post
    Properties:
      Id (int) Required PK AfterSave:Throw ValueGenerated.OnAdd
      AuthorId (no field, int?) Shadow FK
      BlogId (no field, int) Shadow Required FK
    Navigations:
      Author (Author) ToPrincipal Author Inverse: Posts
      Blog (Blog) ToPrincipal Blog Inverse: Posts
    Keys:
      Id PK
    Foreign keys:
      Post {'AuthorId'} -> Author {'Id'} ToDependent: Posts ToPrincipal: Author ClientSetNull
      Post {'BlogId'} -> Blog {'Id'} ToDependent: Posts ToPrincipal: Blog Cascade

W razie potrzeby można jawnie tworzyć indeksy dla kolumn z kluczem obcym, używając IndexAttribute lub konfiguracji w OnModelCreating.

Widok debugowania

Dostęp do widoku debugowania konstruktora modelu można uzyskać w debugerze środowiska IDE. Na przykład w programie Visual Studio:

Dostęp do niego można również uzyskać bezpośrednio z kodu, na przykład w celu wysłania widoku debugowania do konsoli:

Console.WriteLine(context.Model.ToDebugString());

Widok debugowania ma krótką formę i długą formę. Długi formularz zawiera również wszystkie adnotacje, które mogą być przydatne, jeśli musisz wyświetlić metadane relacyjne lub specyficzne dla dostawcy. Dostęp do długiego widoku można uzyskać również z poziomu kodu:

Console.WriteLine(context.Model.ToDebugString(MetadataDebugStringOptions.LongDefault));