Les Data Annotations
De petites étiquettes entre crochets pour préciser ce que la table doit contenir.
Après cette fiche, vous saurez :
- expliquer ce qu'est une annotation
- utiliser [Key], [Required], [MaxLength] et [Index]
- prévoir le SQL produit par chaque annotation
- savoir quand une annotation est inutile
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 :
PRIMARY KEY: la clé primaire.GENERATED BY DEFAULT AS IDENTITY: PostgreSQL numérote tout seul (1, 2, 3...). Vous n'aurez jamais à choisir un identifiant.
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
| Annotation | Où | 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)] | classe | CREATE UNIQUE INDEX : pas de doublon |
Pour aller plus loin
Trois autres annotations existent. Elles se placent dans
System.ComponentModel.DataAnnotations.Schema.
| Annotation | Effet |
|---|---|
[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
Associez chaque phrase à l'annotation qui convient : [Key],
[Required], [MaxLength(20)], [Index(..., IsUnique = true)].
- Le numéro de ticket ne peut pas exister deux fois.
- Le numéro de ticket fait 20 caractères au plus.
- Chaque ticket a un identifiant unique, numéroté automatiquement.
- Le numéro de ticket est obligatoire.
Solution
[Index(nameof(NumTicket), IsUnique = true)], sur la classe.[MaxLength(20)].[Key], surIdTicket.[Required].
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; } }
- Combien de colonnes aura la table ?
- Quelles colonnes sont NOT NULL ?
- Quel
[Required]est inutile ? - Peut-on avoir deux personnages qui s'appellent « Goku » ?
Solution
- 4 :
IdPerso,NomPerso,PvPerso,Description. IdPerso,NomPersoetPvPerso. SeuleDescriptionpeut rester vide, à cause du?.- Celui de
PvPerso: c'est unint, donc déjà NOT NULL. - Non : l'index unique sur
NomPersorefuse le deuxième.
Complétez la classe en ajoutant les annotations qui conviennent :
IdSalleest 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
- Je sais écrire une annotation entre crochets au-dessus d'une propriété ou d'une classe.
- Je sais à quoi servent [Key], [Required], [MaxLength] et [Index].
- Je sais pourquoi une clé comme IdFilm a besoin de [Key].
- Je sais qu'un [Required] sur un int ne change rien.
Une case qui coince ? Relisez la partie concernée avant de passer à la fiche suivante.