Mapování atributů (neboli datových poznámek) pro relace

Atributy mapování se používají k úpravě nebo přepsání konfigurace zjištěné konvencemi vytváření modelů. Konfigurace prováděná mapováním atributů může být přepsána rozhraním API pro sestavení modelu používaného v OnModelCreating.

Důležité

Tento dokument popisuje pouze atributy mapování v kontextu konfigurace relace. Další použití atributů mapování najdete v příslušných částech širší dokumentace k modelování.

Tip

Níže uvedený kód najdete v MappingAttributes.cs.

Kde získat atributy mapování

Mnoho atributů mapování pochází z oborů názvů System.ComponentModel.DataAnnotations a System.ComponentModel.DataAnnotations.Schema . Atributy v těchto oborech názvů jsou zahrnuty jako součást základní architektury ve všech podporovaných verzích .NET, a proto nevyžadují instalaci žádných dalších balíčků NuGet. Tyto atributy mapování se běžně nazývají "datové poznámky" a používají se různými architekturami, včetně EF Core, EF6, ASP.NET Core MVC atd. Používají se také k ověření.

Použití datových poznámek v mnoha technologiích a pro mapování i ověřování vedlo k rozdílům v sémantice napříč technologiemi. Všechny nové atributy mapování navržené pro EF Core jsou teď specifické pro EF Core, takže jejich sémantika a použití jednoduché a jasné. Tyto atributy jsou obsaženy v balíčku NuGet Microsoft.EntityFrameworkCore.Abstractions . Tento balíček je součástí závislosti při každém použití hlavního balíčku Microsoft.EntityFrameworkCore nebo jednoho z přidružených balíčků zprostředkovatele databáze. Balíček Abstrakce je však jednoduchý balíček, na který lze odkazovat přímo kódem aplikace, aniž by bylo možné načíst všechny EF Core a jeho závislosti.

RequiredAttribute

RequiredAttribute je použita u vlastnosti, která označuje, že vlastnost nemůže být null. V kontextu relací [Required] se obvykle používá u vlastnosti cizího klíče. Tím se cizí klíč nedá použít null, čímž se vztah vyžaduje. Například s následujícími typy se Post.BlogId vlastnost vytvoří bez hodnoty null a relace se vyžaduje.

public class Blog
{
    public string Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }

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

    public Blog Blog { get; init; }
}

Poznámka:

Při použití typů odkazů s možnou BlogId hodnotou null jazyka C# je vlastnost v tomto příkladu již nenulovatelná, což znamená, že [Required] atribut nebude mít žádný vliv.

[Required] umístění na závislé navigaci má stejný účinek. To znamená, že cizí klíč není nullable, a tím se vztah vyžaduje. Příklad:

public class Blog
{
    public string Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }

    public string BlogId { get; set; }

    [Required]
    public Blog Blog { get; init; }
}

Pokud [Required] je nalezena v závislé navigaci a cizí klíč vlastnost je ve stínovém stavu, pak stínová vlastnost je nastavena non-nullable, čímž se relace vyžaduje. Příklad:

public class Blog
{
    public string Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }

    [Required]
    public Blog Blog { get; init; }
}

Poznámka:

Použití [Required] na hlavní navigační straně relace nemá žádný vliv.

ForeignKeyAttribute

ForeignKeyAttribute slouží k propojení vlastnosti cizího klíče s jeho navigacemi. [ForeignKey] lze umístit na vlastnost cizího klíče s názvem závislé navigace. Příklad:

public class Blog
{
    public string Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }

    [ForeignKey(nameof(Blog))]
    public string BlogKey { get; set; }

    public Blog Blog { get; init; }
}

[ForeignKey] Nebo lze umístit do závislé nebo hlavní navigace s názvem vlastnosti, která se má použít jako cizí klíč. Příklad:

public class Blog
{
    public string Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }

    public string BlogKey { get; set; }

    [ForeignKey(nameof(BlogKey))]
    public Blog Blog { get; init; }
}

Když [ForeignKey] se umístí na navigaci a zadaný název neodpovídá žádnému názvu vlastnosti, vytvoří se stínová vlastnost s tímto názvem, která bude fungovat jako cizí klíč. Příklad:

public class Blog
{
    public string Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }

    [ForeignKey("BlogKey")]
    public Blog Blog { get; init; }
}

InversePropertyAttribute

InversePropertyAttribute slouží k propojení navigace s inverzní. Například v následujících typech entit existují dvě relace mezi Blog a Post. Bez jakékoli konfigurace ef konvence nemohou určit, které navigace mezi těmito dvěma typy by se měly spárovat. Přidání [InverseProperty] do jedné z spárovaných navigačních panelů řeší tuto nejednoznačnost a umožňuje EF sestavit model.

public class Blog
{
    public int Id { get; set; }

    [InverseProperty("Blog")]
    public List<Post> Posts { get; } = new();

    public int FeaturedPostId { get; set; }
    public Post FeaturedPost { get; set; }
}

public class Post
{
    public int Id { get; set; }
    public int BlogId { get; set; }

    public Blog Blog { get; init; }
}

Důležité

[InverseProperty] je potřeba pouze v případě, že existuje více než jeden vztah mezi stejnými typy. S jednou relací se obě navigace spárují automaticky.

OdstranitBehaviorAttribute

Ef podle konvence používá ClientSetNull DeleteBehavior volitelné relace a Cascade chování požadovaných relací. To lze změnit umístěním DeleteBehaviorAttribute jedné z navigačních panelů relace. Příklad:

public class Blog
{
    public int Id { get; set; }
    public List<Post> Posts { get; } = new();
}

public class Post
{
    public int Id { get; set; }
    public int BlogId { get; set; }

    [DeleteBehavior(DeleteBehavior.Restrict)]
    public Blog Blog { get; init; }
}

Další informace o kaskádovém chování najdete v tématu Kaskádové odstranění.