Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Semaine 3

Le lien du Discord est : https://discord.gg/KERTwSz63

Lors de cette séance, vous allez connecter votre backend au frontend fourni et ajouter le jeu : un clicker dont la progression est stockée en BDD. Vous renforcerez aussi le contrôleur User : erreurs normalisées, pseudos uniques, premier administrateur et validation des données.

Résultat attendu

À la fin de la séance, toutes les fonctionnalités du frontend https://csharp.nouvet.fr/front3 doivent fonctionner avec votre backend. Le frontend appelle http://localhost:5000/api et attend exactement les routes, les modèles JSON et les codes d’erreur ci-dessous.

Dans le JSON, les noms des champs commencent par une minuscule. Dans votre code C#, nommez les propriétés en PascalCase (Username, BestScore…) : la sérialisation fait la conversion.

Chaque erreur renvoie le code HTTP indiqué, avec un ErrorResponse dont le champ code contient le code d’erreur indiqué. Par exemple, 404 USER_NOT_FOUND.

Routes User

RouteEntréeComportementRéponse HTTP
GET /api/User/{id}Identifiant dans l’URLRenvoie l’utilisateur correspondant.200 + UserPublic ; 404 USER_NOT_FOUND
POST /api/User/RegisterCorps JSON UserPassCrée un utilisateur avec un mot de passe haché. Il reçoit le rôle Admin si aucun administrateur n’existe en BDD, sinon le rôle User.200 + UserPublic ; 400 USERNAME_EXISTS si le pseudo est déjà pris ; 400 REGISTRATION_FAILED si l’enregistrement échoue
POST /api/User/LoginCorps JSON UserPassVérifie le pseudo et le mot de passe.200 + UserPublic ; 404 USER_NOT_FOUND ; 401 INVALID_PASSWORD
PUT /api/User/{id}Identifiant dans l’URL et corps JSON UserUpdateModifie le pseudo, le rôle et, s’il est fourni, le mot de passe.200 + UserPublic ; 404 USER_NOT_FOUND
DELETE /api/User/{id}Identifiant dans l’URLSupprime l’utilisateur et sa progression.200 + true ; 404 USER_NOT_FOUND
GET /api/User/AllAucuneRenvoie tous les utilisateurs.200 + liste de UserPublic
GET /api/User/AllAdminAucuneRenvoie les utilisateurs dont le rôle est Admin.200 + liste de UserPublic
GET /api/User/Search/{name}Fragment de pseudo dans l’URLRenvoie les utilisateurs dont le Username contient name, en respectant les majuscules et minuscules.200 + liste de UserPublic

Une liste sans résultat est renvoyée sous la forme [].

Routes Game

RouteEntréeComportementRéponse HTTP
GET /api/Game/Progression/{userId}Identifiant de l’utilisateur dans l’URLRenvoie la progression de l’utilisateur.200 + Progression ; 400 NO_PROGRESSION
GET /api/Game/Initialize/{userId}Identifiant de l’utilisateur dans l’URLCrée la progression : count à 0, multiplier à 1, bestScore à 0.200 + Progression ; 400 PROGRESSION_EXISTS ; 400 INITIALIZATION_FAILED si l’enregistrement échoue
GET /api/Game/Click/{userId}Identifiant de l’utilisateur dans l’URLAjoute le gain d’un clic à count (voir Game design).200 + ClickResponse ; 400 NO_PROGRESSION
GET /api/Game/ResetCost/{userId}Identifiant de l’utilisateur dans l’URLRenvoie le coût du prochain reset.200 + ResetCostResponse ; 400 NO_PROGRESSION
POST /api/Game/Reset/{userId}Identifiant de l’utilisateur dans l’URL et corps JSON {}Si count atteint le coût du reset : met à jour bestScore si count est plus élevé, remet count à 0 et augmente multiplier de 1.200 + Progression ; 400 NO_PROGRESSION ; 400 INSUFFICIENT_CLICKS
GET /api/Game/BestScoreAucuneRenvoie la progression qui a le plus grand bestScore.200 + BestScoreResponse ; 404 NO_PROGRESSIONS si aucune progression n’existe

Modèles JSON

Les valeurs indiquent le type attendu. role vaut 0 pour Admin et 1 pour User. Le modèle User (id, username, password, role) reste stocké en BDD et n’est jamais renvoyé.

UserPass :

{
  "username": "string",
  "password": "string"
}

UserPublic :

{
  "id": "integer",
  "username": "string",
  "role": "integer"
}

UserUpdate (password peut être omis ou vide) :

{
  "username": "string",
  "password": "string",
  "role": "integer"
}

Progression :

{
  "id": "integer",
  "userId": "integer",
  "count": "integer",
  "multiplier": "integer",
  "bestScore": "integer"
}

ClickResponse :

{
  "count": "integer",
  "multiplier": "integer"
}

ResetCostResponse :

{
  "cost": "integer"
}

BestScoreResponse :

{
  "userId": "integer",
  "bestScore": "integer"
}

ErrorResponse :

{
  "message": "string",
  "code": "string"
}

Les noms ClickResponse, ResetCostResponse et BestScoreResponse sont libres : seuls les champs du JSON comptent.

Changements à apporter au code de la semaine 2

Conservez la BDD, le hachage des mots de passe et les huit routes de UserController. Cette semaine :

  • les DTO deviennent des records ;
  • chaque erreur renvoie un ErrorResponse ;
  • POST /api/User/Register vérifie l’unicité du pseudo et désigne le premier administrateur ;
  • DELETE /api/User/{id} supprime aussi la progression de l’utilisateur ;
  • UserPass et UserUpdate valident leurs données ;
  • un nouveau contrôleur GameController et une nouvelle table Progressions gèrent le jeu.

Ordre de travail

Le frontend a besoin de l’inscription et de la connexion avant tout le reste. Implémentez et testez les routes dans cet ordre :

  1. POST /api/User/Register
  2. POST /api/User/Login
  3. GET /api/Game/Progression/{userId}
  4. GET /api/Game/Initialize/{userId}
  5. GET /api/Game/Click/{userId}
  6. GET /api/Game/ResetCost/{userId}
  7. POST /api/Game/Reset/{userId}
  8. GET /api/User/{id}
  9. GET /api/Game/BestScore
  10. GET /api/User/All
  11. DELETE /api/User/{id}
  12. PUT /api/User/{id}
  13. GET /api/User/AllAdmin
  14. GET /api/User/Search/{name}

Connecter le frontend

Pour que le frontend puisse appeler votre API, deux conditions doivent être réunies :

  • le backend tourne sur le port 5000 : voir Fixer le port de l’application ;
  • l’API autorise les requêtes CORS venant de https://csharp.nouvet.fr : voir CORS. Appelez app.UseCors(...) avant app.MapControllers().

Une erreur CORS n’apparaît pas dans le terminal de l’API : ouvrez la console du navigateur (F12) sur la page du frontend pour la lire.

Gitignore

Depuis le dossier de la solution, générez un fichier .gitignore adapté à .NET :

dotnet new gitignore

Il évite de commiter les dossiers bin/ et obj/, les fichiers propres à votre IDE, les journaux, etc. Vous pouvez aussi partir du fichier https://github.com/microsoft/dotnet/blob/main/.gitignore.

Records pour les DTO

Un DTO (Data Transfer Object) est un objet échangé entre le frontend et le backend. Utilisez des records pour tous vos DTO : UserPass, UserPublic, UserUpdate, ErrorResponse, ClickResponse, ResetCostResponse et BestScoreResponse. Les modèles stockés en BDD, User et Progression, restent des classes.

UserPass et UserUpdate portent des annotations de validation : déclarez-les en record nominal, avec les propriétés dans le corps, comme dans le chapitre Validation des données. Les autres DTO peuvent être des records positionnels.

Retour d’erreur

Créez le record ErrorResponse dans le dossier Models :

public record ErrorResponse(string Message, string Code);

Les tableaux du Résultat attendu donnent, pour chaque erreur, le code HTTP et le code d’erreur. Par exemple, 404 USER_NOT_FOUND s’écrit :

return NotFound(new ErrorResponse("User not found", "USER_NOT_FOUND"));

Pour un 400, utilisez BadRequest(...) ; pour un 401, Unauthorized(...) : voir Codes de retour d’un contrôleur. Le frontend s’appuie sur le champ code : respectez-le exactement.

Utilisateurs

Pseudo unique

Dans l’action de POST /api/User/Register, cherchez d’abord un utilisateur portant le même pseudo : s’il existe, renvoyez 400 USERNAME_EXISTS sans rien enregistrer. Voir Rechercher des données.

Premier administrateur

Un nouvel utilisateur reçoit le rôle User, sauf si aucun utilisateur Admin n’existe en BDD : il devient alors Admin. Le premier inscrit sur une base vide est donc administrateur.

Si l’enregistrement échoue, c’est-à-dire si SaveChangesAsync lève une exception, renvoyez 400 REGISTRATION_FAILED : voir Les exceptions.

Supprimer la progression avec l’utilisateur

Dans l’action de DELETE /api/User/{id}, supprimez aussi la progression de l’utilisateur, si elle existe, avant d’appeler SaveChangesAsync. Sinon, la table Progressions garde une ligne orpheline. Voir Supprimer des données.

Validation des données

Ajoutez des annotations de validation à UserPass et UserUpdate : voir Validation des données.

Règles à implémenter :

  • Le pseudo contient de 3 à 20 lettres ou chiffres.
  • Le mot de passe contient de 4 à 20 caractères : uniquement des lettres, des chiffres et les caractères spéciaux &^!@#.
  • Dans UserPass, les deux champs sont obligatoires.
  • Dans UserUpdate, le pseudo est obligatoire. Le mot de passe peut être omis ou vide pour conserver l’ancien ; s’il est fourni, les mêmes règles s’appliquent.

Pour le mot de passe de UserUpdate, n’utilisez ni [Required] ni [MinLength] : une chaîne vide serait rejetée. [RegularExpression] laisse passer une valeur absente ou vide et n’applique son motif qu’aux autres valeurs : imposez donc la longueur dans le motif, avec {4,20}.

Grâce à l’attribut [ApiController], une donnée invalide est rejetée avec un 400 avant même d’entrer dans l’action. Le corps de cette réponse est généré par ASP.NET : ce n’est pas un ErrorResponse.

Le jeu

Game design

Le jeu est un clicker :

  • chaque clic ajoute multiplier points à count, soit 1 point par clic au départ ;
  • quand count atteint le coût du reset, le joueur peut faire un reset : count repasse à 0 et multiplier augmente de 1 ;
  • bestScore conserve le plus grand count atteint au moment d’un reset.

Le coût du reset dépend du multiplicateur. Ajoutez cette méthode à votre GameController :

private int CalculateResetCost(int multiplier)
{
    // Coût exponentiel : 100 * 1.5^(multiplier - 1)
    double baseCost = 100.0;
    double growthFactor = 1.5;
    double cost = baseCost * Math.Pow(growthFactor, multiplier - 1);
    return (int)Math.Floor(cost);
}

Le premier reset coûte 100, le deuxième 150, le troisième 225.

Table Progressions

Créez une classe Progression dans le dossier Models :

PropriétéTypeValeur à l’initialisation
IdintAttribuée par la BDD
UserIdintIdentifiant de l’utilisateur
Countint0
Multiplierint1
BestScoreint0

Ajoutez une propriété DbSet<Progression> Progressions à BDDContext, puis créez et appliquez une nouvelle migration : voir Faire évoluer le modèle.

Chaque utilisateur a au plus une progression : retrouvez-la avec son UserId, et non avec son Id.

GameController

Depuis le dossier du projet GameServerApi, créez le contrôleur :

dotnet new apicontroller -n GameController -p:n GameServerApi.Controllers -o Controllers

Injectez BDDContext dans son constructeur, comme pour UserController, puis implémentez les six routes du tableau Routes Game.

Le frontend envoie un corps {} à POST /api/Game/Reset/{userId} : l’action n’a pas besoin de le lire.

Vérification finale et livrables

Pour repartir d’une base vide, supprimez BDD.db, puis recréez-la avec dotnet ef database update. Relancez l’API, ouvrez Scalar et vérifiez que les quatorze routes apparaissent. Réalisez ensuite le scénario suivant :

  1. Appelez GET /api/Game/BestScore : vous devez recevoir 404 NO_PROGRESSIONS.
  2. Inscrivez Alice puis Bob avec POST /api/User/Register : Alice reçoit le rôle 0 (Admin), Bob le rôle 1. Réinscrivez Alice : 400 USERNAME_EXISTS.
  3. Tentez une inscription avec le pseudo ab, puis avec le mot de passe abc : 400 dans les deux cas, sans utilisateur créé.
  4. Connectez Alice avec POST /api/User/Login et un mauvais mot de passe : 401, avec un corps JSON contenant "code": "INVALID_PASSWORD".
  5. Appelez GET /api/Game/Progression/{userId} avec l’identifiant de Bob : 400 NO_PROGRESSION. Appelez GET /api/Game/Initialize/{userId} : 200, avec count à 0 et multiplier à 1. Rappelez GET /api/Game/Initialize/{userId} : 400 PROGRESSION_EXISTS.
  6. Appelez GET /api/Game/Click/{userId} pour Bob : count passe à 1. GET /api/Game/ResetCost/{userId} renvoie un cost de 100 et POST /api/Game/Reset/{userId} renvoie 400 INSUFFICIENT_CLICKS.
  7. Ouvrez le frontend et connectez-vous avec Bob. Cliquez jusqu’à atteindre 100 points, puis faites un reset : count repasse à 0, multiplier vaut 2 et GET /api/Game/ResetCost/{userId} renvoie un cost de 150. Un clic rapporte désormais 2 points.
  8. GET /api/Game/BestScore renvoie l’identifiant de Bob et un bestScore d’au moins 100.
  9. Supprimez Bob avec DELETE /api/User/{id} (200 et true), puis appelez GET /api/Game/Progression/{userId} avec son identifiant : 400 NO_PROGRESSION.
  10. Parcourez toutes les fonctionnalités du frontend avec Alice : aucune erreur CORS ni code d’erreur inattendu ne doit apparaître dans la console du navigateur.

À la fin de la séance, vous devez avoir :

  • Les DTO UserPass, UserPublic, UserUpdate, ErrorResponse et les réponses du jeu déclarés en records ; User et Progression restent des classes.
  • Une migration ajoutant la table Progressions, appliquée à BDD.db.
  • Les huit routes de UserController et les six routes de GameController conformes aux tableaux du Résultat attendu, avec les codes d’erreur exacts.
  • Des pseudos uniques, un premier inscrit administrateur et des données validées.
  • CORS configuré et un fichier .gitignore à la racine de la solution.
  • Le frontend front3 utilisable de bout en bout.