mchsamples-.net-core/p08_BDD_EntityFramework/ex_042_002_EF_CF_data_annotations

ex_042_002_EF_CF_data_annotations

03/01/2020 ⋅ Marc Chevaldonné

---

Le lien entre une base de données et vos classes à l'aide de Entity Framework Core se fait via une classe dérivant de DbContext. Cette classe doit contenir des DbSet<T>. Chaque DbSet<T> correspond à une table et T correspond à une de vos classes qu'on appelle entité. Le lien entre les tables et les entités est géré plus ou moins automatiquement par le framework.
EF Core permet de lire/écrire les instances d'entité de la base de données ; permet de créer des tables pour les entités via les migrations (pour les bases de données relationnelles) ; les types exposés dans les propriétés d'une entité deviennent automatiquement des entités (mais pas forcément des tables)

Entity Framework Core propose 3 solutions différentes pour relier des entités à des tables de la base de données :

• conventions d'écriture : c'est la solution la plus simple, qui analyse le code de votre classe pour en déduire de quelle manière la relier à la table.
• data annotations : elle se base sur des décorateurs (appelés data annotations) que vous placez autour de vos propriétés pour indiquer de quelle manière les relier aux colonnes de votre table. Les data annotations écrasent les conventions d'écriture.
• Fluent API : directement dans le code de votre DbContext (plus précisément, dans la méthode OnModelCreating), vous précisez comment se fait le mapping entre votre entité et votre table. La Fluent API écrase les conventions d'écriture et les data annotations.

En d'autres termes, si vous n'écrivez rien, EF Core utilise les conventions d'écriture ; si vous n'utilisez que des data annotations, elles sont prioritaires sur les convetions d'écriture ; si vous utilisez la Fluent API, elle est prioritaire sur les deux autres méthodes. Mais on peut faire un mix des différentes méthodes.

Cet exemple montre de quelle manière les data annotations sont utilisées pour transformer une entité en table. Il montre notamment :

• comment choisir le nom de la table
• comment ignorer une propriété de l'entité
• comment le nom et le type d'une colonne de la table peuvent être modifiés
• comment un identifiant unique est choisi et généré.

Cet exemple est répété d'une manière très similaire en utilisant les autres méthodes de mapping entre entité et table :

• ex_042_001_EF_CF_conventions : avec les conventions d'écriture
• ex_042_003_EF_CF_Fluent_API : avec la Fluent API

---

Comment est construit cet exemple ?

• Le projet est de type .NET Core
• Il contient deux classes :
  • Nounours
  • NounoursDBEntities

La classe NounoursDBEntities

• Cette classe dérive de DbContext. Elle contient des DbSet<T> où T est une entité. Elle contient autant de DbSet<T> que de tables.

class NounoursDBEntities : DbContext
{
    public DbSet<Nounours> NounoursSet { get; set; }
}

ici, on indique donc qu'il y aura une table de Nounours.

• EF Core utilisera cette classe pour faire la création de la base de données et de ses tables. Pour cela, elle utilise la chaîne de connexion donnée dans la méthode OnConfiguring.

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseSqlServer(@"Server=(localdb)\mssqllocaldb;Database=ex_042_001_EF_CF_conventions.Nounours.mdf;Trusted_Connection=True;");
}

=> cf ex_041_001_ConnectionStrings pour en savoir plus sur les chaîne de connexion

• Dans cet exemple, la table de Nounours est créée en utilisant les data annotations et les conventions d'écriture de la classe Nounours.

La classe Nounours

• Nounours est une entité, on parle aussi de classe POCO, i.e. Plain Old CLR Object.

[Table("TableNounours")]
public class Nounours
{
    [Key]
    [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public Guid UniqueId
    {
        get; set;
    }

    [Required]
    [MaxLength(256)]
    //[Column("name", Order=0, TypeName ="varchar(200)")]
    public string Nom
    {
        get;
        set;
    }

    [Column("Naissance", TypeName = "date")]
    public DateTime DateDeNaissance
    {
        get;
        set;
    }

    [NotMapped]
    public int NbPoils
    {
        get;
        set;
    }

    public override string ToString()
    {
        return $"{UniqueId}: {Nom} ({DateDeNaissance:dd/MM/yyyy}, {NbPoils} poils)";
    }
}

• Elle contient 3 propriétés en lecture/écriture : Nom, DateDeNaissance et NbPoils. Nous parlerons de la 4ème (UniqueId) dans un moment.
• Entity Framework Core va utiliser la classe POCO Nounours pour créer une table dans la base de données, lorsque le DbSet va être créé.
• S'il y a des data annotations, elles sont prioritaires sur l'utilisation des conventions d'écriture d'Entity Framework.

Un petit tour des annotations utilisées dans l'exemple et quelques indications sur celles manquantes :

• la classe Nounours est précédée de l'annotation [Table("TableNounours")] : la table créée n'aura donc pas le nom de la classe (comme le permettent les conventions d'écriture), mais le nom indiqué dans l'annotation :

[Table("TableNounours")]
public class Nounours
{
    //...
}

• on peut changer le nom, le type ou l'ordre d'une colonne en précédant une propriété de l'annotation [Column(...)]. Dans l'exemple ci-dessous, la colonne ne s'appellera pas "DateDeNaissance" (comme le permettraient les conventions d'écriture), mais "Naissance" grâce à l'annotation.

[Column("Naissance")]
public DateTime DateDeNaissance
{
    get;
    set;
}

• On pourrait aller plus loin en indiquant l'ordre et le changement de type, par exemple :

[Column("name", Order=0, TypeName=varchar(200))]
public string Nom
{
    get; 
    set;
}

• Dans la classe Nounours, la propriété DateDeNaissance est annotée de façon à modifier le type par défaut de mapping (la partie time sera évincée) et le nom de colonne sera modifé en "Naissance".

[Column("Naissance", TypeName = "date")]
public DateTime DateDeNaissance
{
    get;
    set;
}

• L'annotation [Required] permet de rendre obligatoire une propriété. Une propriété peut être optionnelle seulement si elle peut avoir la valeur null. Dans l'exemple ci-dessous, le nom est obligatoire.

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

• L'annotation [MaxLength(256)] permet d'imposer une taille max à une chaîne de caractères. Dans l'exemple ci-dessous, le nom ne doit pas avoir plus de 256 caractères.

[MaxLength(256)]
public string Nom
{
    get;
    set;
}

• L'annotation [NotMapped] permet d'indiquer qu'une propriété ne doit pas être mappée en colonne de table. Par exemple, ici, le nombre de poils ne sera pas mappé en colonne.

[NotMapped]
public int NbPoils
{
    get;
    set;
}

• L'annotation [Key] transforme n'importe quelle propriété en clé primaire.
  Si on ajoute l'annotation [DatabaseGenerated(DatabaseGeneratedOption.Identity)], on précise par exemple que la clé primaire sera générée par la base, lors de l'insertation dans la table.
  Notez que la clé n'est donc, contrairement aux conventions d'écriture, pas nécessairement un int. Elle peut-être un Guid, un string, etc. Son nom peut-être autre chose que "ID".
  Note : on peut aussi faire des clés composées, comme je le montrerai dans un autre exemple.
  Dans l'exemple ci-dessous, un Nounourspossédera une clé unique de type Guid générée par la base et placée dans la colonne "UniqueId".

[Key]
[DatabaseGenerated(DatabaseGeneratedOption.Identity)]
public Guid UniqueId
{
    get; set;
}

En résumé, avec les data annotations :

• on peut changer le nom de la table
• on peut changer le nom, le type et l'ordre d'une colonne
• on peut rendre une propriété obligatoire ou optionnelle
• on peut empêcher le mapping d'une propriété
• on peut imposer une taille max pour les chaînes de caractères
• on peut transformer une propriété en clé primaire et demander à la base de la générée lors de l'insertion.

La classe Program

Cette classe est le point d'entrée du programme :

• Elle crée des instances de Nounours

Nounours chewie = new Nounours { Nom = "Chewbacca", DateDeNaissance = new DateTime(1977, 5, 27), NbPoils = 1234567 };
Nounours yoda = new Nounours { Nom = "Yoda", DateDeNaissance = new DateTime(1980, 5, 21), NbPoils = 3 };
Nounours ewok = new Nounours { Nom = "Ewok", DateDeNaissance = new DateTime(1983, 5, 25), NbPoils = 3456789 };

• Elle démarre une connexion à la base de données

using (NounoursDBEntities db = new NounoursDBEntities())
{
//...
}

• Elle vérifie si la table est vide, et si ce n'est pas le cas, elle la vide.
  Notez l'accès à la table de Nounours via db.NounoursSet.
  Notez également que tant que SaveChanges n'est pas appelée, les suppressions ne sont pas effectives dans la base, seulement en local dans le programme.
  Cette partie de l'exemple ne s'exécutera que si la base existe déjà, par exemple lors d'une deuxième exécution.

if (db.NounoursSet.Count() > 0)
{
    WriteLine("La base n'est pas vide !");
    foreach (var n in db.NounoursSet)
    {
        WriteLine($"\t{n}");
    }
    WriteLine("début du nettoyage...");

    foreach (var n in db.NounoursSet.ToArray())
    {
        WriteLine($"Suppression de {n}");
        db.NounoursSet.Remove(n);
    }

    WriteLine("Base avant sauvegarde des changements :");
    foreach (var n in db.NounoursSet)
    {
        WriteLine($"\t{n}");
    }
    db.SaveChanges();
    WriteLine("Base après sauvegarde des changements :");
    foreach (var n in db.NounoursSet)
    {
        WriteLine($"\t{n}");
    }
}

• Elle ajoute ensuite les Nounourset sauvegarde les changements pour que ceux-ci soit effectivement ajoutés à la base.

db.NounoursSet.AddRange(new Nounours[] { chewie, yoda, ewok });

db.SaveChanges();
WriteLine("Base après ajout des 3 nounours et sauvegarde des changements :");
foreach (var n in db.NounoursSet)
{
    WriteLine($"\t{n}");
}

Comment exécuter cet exemple ?

Pour tester cette application, n'oubliez pas les commandes comme présentées dans l'exemple ex_041_001 : pour générer l'exemple, il vous faut d'abord préparer les migrations et les tables.

• Ouvrez la Console du Gestionnaire de package, pour cela, dirigez-vous dans le menu Outils, puis Gestionnaire de package NuGet, puis Console du Gestionnaire de package.
• Dans la console que vous venez d'ouvrir, déplacez-vous dans le dossier du projet .NET Core, ici :

cd .\p08_BDD_EntityFramework\ex_042_002_EF_CF_data_annotations

Note: si vous n'avez pas installé correctement EntityFrameworkCore, il vous faudra peut-être utiliser également :

• dotnet tool install --global dotnet-ef si vous utilisez la dernière version de .NET Core (3.1 aujourd'hui),

• dotnet tool install --global dotnet-ef --version 3.0.0 si vous vous utiliser spécifiquement .NET Core 3.0.

  • Migration :

dotnet ef migrations add migration_ex_042_002

• Création de la table :

dotnet ef database update

• Génération et exécution Vous pouvez maintenant générer et exécuter l'exemple ex_042_002_EF_CF_data_annotations.

• Le résultat de l'exécution peut ressembler à :

Base après ajout des 3 nounours et sauvegarde des changements :
      fbc3f7c5-a333-4d07-f7f2-08d7907e5437: Chewbacca (27/05/1977, 1234567 poils)
      63b18e10-a683-4144-f7f3-08d7907e5437: Yoda (21/05/1980, 3 poils)
      c4eab29b-315b-416e-f7f4-08d7907e5437: Ewok (25/05/1983, 3456789 poils)

Note : les identifiants seront bien sûr différents

• Comment vérifier le contenu des bases de données SQL Server ? Vous pouvez vérifier le contenu de votre base en utilisant l'Explorateur d'objets SQL Server.

• Pour cela, allez dans le menu Affichage puis Explorateur d'objets SQL Server.
  

• Déployez dans l'Explorateur d'objets SQL Server :

  • SQL Server,

  • puis (localdb)\MSSQLLocalDB ...,

  • puis Bases de données

  • puis celle portant le nom de votre migration, dans mon cas : ex_042_002_EF_CF_data_annotations.Nounours.mdf

  • puis Tables

  • Faites un clic droit sur la table dbo.Nounours puis choisissez Afficher les données
    

  • Vous devriez maintenant pouvoir voir les données suivantes dans le tableau :

  UniqueId	Nom	Naissance
  fbc3f7c5-a333-4d07-f7f2-08d7907e5437	Chewbacca	27/05/1977
  63b18e10-a683-4144-f7f3-08d7907e5437	Yoda	21/05/1980
  c4eab29b-315b-416e-f7f4-08d7907e5437	Ewok	25/05/1983

Notes: les identifiants seront bien sûr différents.
Notez l'absence de la colonne "NbPoils"
Notez le nom de la colonne "Naissance" et le formatage de la date