⌂ Entity Framework
Fiche 5 sur 8

Les Data Annotations

De petites étiquettes entre crochets pour préciser ce que la table doit contenir.

Après cette fiche, vous saurez :

1Qu'est-ce qu'une annotation ?

Une classe seule ne suffit pas à décrire une table complète. Elle ne dit pas quelle colonne est la clé, ni quelle longueur de texte on accepte, ni si un titre peut exister deux fois.

Pour le préciser, on ajoute des annotations (en anglais Data Annotations, « annotations de données »). Ce sont de petites étiquettes écrites entre crochets, juste au-dessus de ce qu'elles décrivent.

using System.ComponentModel.DataAnnotations;

public class Film
{
    [Key]
    public int IdFilm { get; set; }

    [Required]
    [MaxLength(60)]
    public required string Titre { get; set; }
}

Une annotation ne change pas le fonctionnement du programme : c'est une information que lit Entity Framework au moment de fabriquer la table. Pour utiliser les annotations, il faut la ligne using System.ComponentModel.DataAnnotations; en haut du fichier.

2[Key] : la clé primaire

Une table a besoin d'une clé primaire : une colonne dont la valeur est différente pour chaque ligne, et qui permet de retrouver une ligne précise. [Key] désigne cette colonne.

[Key]
public int IdFilm { get; set; }
CREATE TABLE "Films" (
    "IdFilm" integer GENERATED BY DEFAULT AS IDENTITY,
    ...
    CONSTRAINT "PK_Films" PRIMARY KEY ("IdFilm")
);

Deux choses à remarquer dans le SQL :

Attention

Pourquoi [Key] est-il nécessaire ici ?

Entity Framework devine seul la clé quand la propriété s'appelle Id ou FilmId (le nom de la classe suivi de Id). Or nous écrivons IdFilm, qu'il ne reconnaît pas.

Sans [Key], le programme s'arrête avec le message « The entity type 'Film' requires a primary key to be defined ».

3[Required] : la colonne ne peut pas être vide

[Required] (« obligatoire ») se traduit par NOT NULL en SQL.

[Required]
public required string Titre { get; set; }

Mais attention, il est souvent inutile

On l'a vu à la fiche précédente : le type décide déjà. Un int est toujours NOT NULL, et un string sans ? l'est aussi. Voici la même classe avec et sans [Required] :

public class Personnage
{
    [Key]
    public int IdPerso { get; set; }

    [Required]
    public int PvPerso { get; set; }      // avec [Required]

    public int DefPerso { get; set; }     // sans [Required]
}
CREATE TABLE personnages (
    ...
    "PvPerso" integer NOT NULL,
    "DefPerso" integer NOT NULL,
    ...
);

Les deux colonnes sont identiques. [Required] sur un int ne change rien.

À retenir

[Required] n'a d'effet que sur les types référence comme string, et même là, un string sans ? suffit déjà quand Nullable est activé.

On peut l'écrire quand même, pour que la classe soit claire à relire. Ce n'est pas une faute : c'est simplement redondant.

4[MaxLength] : la longueur du texte

[MaxLength(60)] limite un texte à 60 caractères.

[MaxLength(60)]
public required string Titre { get; set; }
-- avec [MaxLength(60)]
"Titre" character varying(60) NOT NULL

-- sans [MaxLength]
"Titre" text NOT NULL

Sans [MaxLength], le texte peut être aussi long qu'on veut (text). Avec, la colonne devient character varying(60) (on dit aussi varchar(60)), et PostgreSQL refuse un titre plus long.

5[Index] : empêcher les doublons

Un index est comme l'index d'un livre : il aide à retrouver vite une valeur. Avec IsUnique = true, il interdit en plus les doublons : on ne peut pas avoir deux genres « Comédie ».

Contrairement aux autres, cette annotation se place au-dessus de la classe, et il faut en plus la ligne using Microsoft.EntityFrameworkCore;.

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

[Index(nameof(Libelle), IsUnique = true)]
public class Genre
{
    [Key]
    public int IdGenre { get; set; }

    [Required]
    [MaxLength(30)]
    public required string Libelle { get; set; }
}
CREATE TABLE "Genres" (
    "IdGenre" integer GENERATED BY DEFAULT AS IDENTITY,
    "Libelle" character varying(30) NOT NULL,
    CONSTRAINT "PK_Genres" PRIMARY KEY ("IdGenre")
);

CREATE UNIQUE INDEX "IX_Genres_Libelle" ON "Genres" ("Libelle");

Le mot nameof(Libelle) veut dire « le nom Libelle ». On l'utilise plutôt que d'écrire "Libelle" entre guillemets, car le compilateur signale une faute de frappe, alors qu'un texte entre guillemets n'est jamais vérifié.

6Le tableau à retenir

AnnotationOùEffet en SQL
[Key]propriétéPRIMARY KEY (+ numérotation automatique pour un int)
[Required]propriétéNOT NULL (souvent déjà vrai grâce au type)
[MaxLength(n)]propriétécharacter varying(n)
[Index(nameof(X), IsUnique = true)]classeCREATE UNIQUE INDEX : pas de doublon

Pour aller plus loin

Trois autres annotations existent. Elles se placent dans System.ComponentModel.DataAnnotations.Schema.

AnnotationEffet
[Table("personnages")]Choisit le nom de la table (au lieu du nom de la classe ou du DbSet).
[Column("atq_ki")]Choisit le nom de la colonne.
[NotMapped]Cette propriété ne devient pas une colonne (par exemple un total calculé).

→Exercices

1Quelle annotation ?Recopier

Associez chaque phrase à l'annotation qui convient : [Key], [Required], [MaxLength(20)], [Index(..., IsUnique = true)].

  1. Le numéro de ticket ne peut pas exister deux fois.
  2. Le numéro de ticket fait 20 caractères au plus.
  3. Chaque ticket a un identifiant unique, numéroté automatiquement.
  4. Le numéro de ticket est obligatoire.

Solution

  1. [Index(nameof(NumTicket), IsUnique = true)], sur la classe.
  2. [MaxLength(20)].
  3. [Key], sur IdTicket.
  4. [Required].
2Lire une classeModifier

Voici une classe, sans le SQL.

[Index(nameof(NomPerso), IsUnique = true)]
public class Personnage
{
    [Key]
    public int IdPerso { get; set; }

    [Required]
    [MaxLength(20)]
    public required string NomPerso { get; set; }

    [Required]
    public int PvPerso { get; set; }

    public string? Description { get; set; }
}
  1. Combien de colonnes aura la table ?
  2. Quelles colonnes sont NOT NULL ?
  3. Quel [Required] est inutile ?
  4. Peut-on avoir deux personnages qui s'appellent « Goku » ?

Solution

  1. 4 : IdPerso, NomPerso, PvPerso, Description.
  2. IdPerso, NomPerso et PvPerso. Seule Description peut rester vide, à cause du ?.
  3. Celui de PvPerso : c'est un int, donc déjà NOT NULL.
  4. Non : l'index unique sur NomPerso refuse le deuxième.
3Annoter la classe SalleCréer

Complétez la classe en ajoutant les annotations qui conviennent :

  • IdSalle est la clé primaire ;
  • deux salles ne peuvent pas avoir le même numéro ;
  • la salle porte un nom d'au plus 30 caractères, obligatoire.
public class Salle
{
    public int IdSalle { get; set; }
    public int NumeroSalle { get; set; }
    public required string Nom { get; set; }
    public int Capacite { get; set; }
}

Solution

[Index(nameof(NumeroSalle), IsUnique = true)]
public class Salle
{
    [Key]
    public int IdSalle { get; set; }

    public int NumeroSalle { get; set; }

    [Required]
    [MaxLength(30)]
    public required string Nom { get; set; }

    public int Capacite { get; set; }
}

N'oubliez pas les deux using en haut du fichier : System.ComponentModel.DataAnnotations et Microsoft.EntityFrameworkCore.

Je sais faire

Une case qui coince ? Relisez la partie concernée avant de passer à la fiche suivante.

← Fiche 4 Fiche 6 : Le DbContext →