Skip to content

11. Fallstudie: Die Anwendung RdvMedecins

11.1. Die Aufgabenstellung

Die Anwendung RdvMedecins verwaltet die Termine einer Arztpraxis. Jeder Arzt hat Zeitfenster (zum Beispiel von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten); ein Termin besteht aus einem Tag, einem Zeitfenster und einem Klienten (einem Patienten). Dies ist die exakte Umsetzung der [NestJS]-Anwendung aus der vorherigen Lektion in [ASP.NET Core MVC]: gleiche Datenbank, gleiche Geschäftsregeln, gleiche Seiten, gleiche Übersetzungswörterbücher. Die HTML-Seiten werden vom Server mithilfe von [Razor]-Views erzeugt.

Drei Benutzerrollen teilen sich die Anwendung:

Rolle
Wer
Was sie tun kann
ADMIN
Der Administrator ([admin])
Terminkalender einsehen, Termine für beliebige Patienten vereinbaren und absagen; Ärzte und Klienten verwalten (auflisten, hinzufügen, bearbeiten, löschen)
DOCTOR
Ärzte
Terminkalender einsehen, Termine vereinbaren und Termine beliebiger Patienten absagen
USER
Klienten (Patienten)
Terminkalender einsehen, ohne die Namen anderer Patienten zu sehen; für sich selbst einen Termin buchen; den eigenen Termin absagen; das eigene Konto verwalten; ein Konto erstellen

Wichtige Verwaltungsregeln:

  • keine Termine in der Vergangenheit;
  • ein Zeitfenster kann pro Tag nur einmal gebucht werden;
  • ein Patient darf zu einem Zeitpunkt nur einen bevorstehenden Termin haben;
  • zwei Ärzte (oder zwei Klienten) dürfen nicht denselben Vor- und Nachnamen haben, und ein Login gehört zu nur einem Konto;
  • ein Arzt mit Terminen kann nicht gelöscht werden; ein Klient wird zusammen mit seinen Terminen gelöscht;
  • die Anmeldeseite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und das Erstellen eines Klientenkontos setzt voraus, dass zuvor auf dieser Seite das CAPTCHA gelöst wurde.

11.2. Verwendung der Anwendung

11.2.1. Die Anmeldeseite

Image

Die Seite enthält zwei Schaltflächen: Anmelden und Patientenkonto erstellen. Bei beiden müssen Sie die im Bild gezeigten Zeichen eingeben. Die Schaltflächen FR / EN wechseln die Sprache:

Image

Ein Fehler (hier ein falsch eingegebenes CAPTCHA) wird am Seitenende auf hellrosa Hintergrund angezeigt:

Image

11.2.2. Der Terminkalender aus Sicht des Administrators und der Ärzte

Nach der Anmeldung gelangt der Administrator auf die Kalenderseite. Er wählt einen Arzt und einen Tag aus:

Image

Image

Jedes Zeitfenster ist entweder frei (Schaltfläche Buchen) oder belegt (Name des Patienten, Schaltfläche Absagen). Ein Klick auf Buchen öffnet ein Fenster, das nach den Daten des Patienten fragt:

Image

Ein Klick auf „Absagen“ löst eine Bestätigungsabfrage aus (hier bei Dr. Pélissier, dessen Navigationsleiste die Verwaltungsmenüs nicht enthält):

Image

11.2.3. Der Patientenbereich

Ein Patient (Rolle USER) gelangt in Mein Bereich: sein bevorstehender Termin, den er absagen kann, sowie Links zur Kontoverwaltung und zum Kalender:

Image

Im Kalender sieht er seinen eigenen Termin, aber nicht die Namen anderer Patienten. Da er bereits einen bevorstehenden Termin hat, kann er keinen weiteren vereinbaren:

Image

Ein Patient ohne Termin kann ein freies Zeitfenster für sich selbst buchen:

Image

Kontoverwaltung: persönliche Daten ändern, das Passwort ändern oder das Konto (und seine Termine) löschen. Für jede Änderung ist das aktuelle Passwort erforderlich:

Image

Ein Patient, der versucht, eine dem Administrator vorbehaltene Seite zu öffnen, erhält eine Fehlerseite:

Image

11.2.4. Verwaltung von Ärzten und Klienten

Der Administrator hat zwei zusätzliche Menüs, „Ärzte“ und „Patienten“:

Image

Image

Das Formular zum Hinzufügen eines Arztes, mit Fehlern übermittelt:

Image

Ein Name, der mit dem eines vorhandenen Arztes übereinstimmt, wird abgelehnt:

Image

Das Löschen eines Klienten erfordert eine Bestätigung:

Image

11.2.5. Erstellen eines Klientenkontos

Auf der Anmeldeseite öffnet die Schaltfläche „Patientenkonto erstellen“ das Formular nur, wenn das CAPTCHA korrekt eingegeben wurde:

Image

Image

11.3. Installation und Ausführung

Die Installationsschritte wurden am Anfang dieses Dokuments beschrieben (im Abschnitt „Ausführen der Fallstudie“ der Einführung): die Datenbank mit dem SQL-Skript erstellen, die Verbindungszeichenfolge in [appsettings.json] überprüfen und dann [dotnet run] im Anwendungsordner ausführen. Der Anwendungsordner:

rdvmedecins2-aspnetcore-mvc/
├── Auth/
│   ├── AttemptLimiterService.cs
│   ├── AuthService.cs
│   ├── CaptchaService.cs
│   ├── ConnectedUser.cs
│   ├── InvalidSessionException.cs
│   ├── JwtAuthentication.cs
│   ├── README.md
│   └── RegistrationPassService.cs
├── Business/
│   ├── BusinessException.cs
│   ├── BusinessService.cs
│   ├── Dates.cs
│   ├── IBusiness.cs
│   └── README.md
├── Config/
│   ├── AuthOptions.cs
│   ├── ProtectionOptions.cs
│   └── README.md
├── Controllers/
│   ├── AuthController.cs
│   ├── ClientsController.cs
│   ├── DoctorsController.cs
│   ├── ErrorController.cs
│   ├── LanguageController.cs
│   ├── PatientAreaController.cs
│   ├── PersonsControllerBase.cs
│   ├── README.md
│   ├── RegistrationController.cs
│   └── ScheduleController.cs
├── Data/
│   ├── RdvMedecinsDbContext.cs
│   └── README.md
├── database/
│   ├── dbrdvmedecins2.sql
│   └── README.md
├── Domain/
│   ├── DoctorDaySchedule.cs
│   ├── DoctorDaySlot.cs
│   └── README.md
├── Entities/
│   ├── AbstractEntity.cs
│   ├── Appointment.cs
│   ├── Client.cs
│   ├── Doctor.cs
│   ├── Person.cs
│   ├── README.md
│   ├── Role.cs
│   ├── Slot.cs
│   └── User.cs
├── i18n/
│   ├── en.json
│   └── fr.json
├── Models/
│   ├── Forms.cs
│   ├── README.md
│   └── ViewModels.cs
├── Properties/
│   └── launchSettings.json
├── Repositories/
│   ├── AppointmentRepository.cs
│   ├── PersonRepository.cs
│   ├── README.md
│   ├── SlotRepository.cs
│   └── UserRepository.cs
├── Views/
│   ├── Auth/
│   │   ├── _Captcha.cshtml
│   │   └── Login.cshtml
│   ├── PatientArea/
│   │   ├── Account.cshtml
│   │   └── Area.cshtml
│   ├── Persons/
│   │   ├── Form.cshtml
│   │   └── List.cshtml
│   ├── Registration/
│   │   └── Registration.cshtml
│   ├── Schedule/
│   │   ├── _Booking.cshtml
│   │   └── Schedule.cshtml
│   ├── Shared/
│   │   ├── _Confirmation.cshtml
│   │   ├── _Errors.cshtml
│   │   ├── _Flash.cshtml
│   │   ├── _Layout.cshtml
│   │   ├── _Navbar.cshtml
│   │   ├── _PersonFields.cshtml
│   │   └── Error.cshtml
│   ├── _ViewImports.cshtml
│   ├── _ViewStart.cshtml
│   └── README.md
├── Web/
│   ├── ApplicationModel.cs
│   ├── Flash.cs
│   ├── HtmlExceptionFilter.cs
│   ├── README.md
│   ├── Translator.cs
│   ├── Utils.cs
│   ├── Validation.cs
│   └── ViewPage.cs
├── wwwroot/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
│           ├── css/
│           │   └── bootstrap.min.css
│           └── LICENSE
├── .gitignore
├── appsettings.Development.json
├── appsettings.json
├── Program.cs
├── RdvMedecins.csproj
└── README.md

Jeder Ordner enthält eine Datei namens [README.md] , die seine Dateien auflistet. Die Konsole beim Start:

dotnet run
Using launch settings from Properties/launchSettings.json...
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:8081
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\course\rdvmedecins2-aspnetcore-mvc

Im Entwicklungsmodus (siehe [Properties/launchSettings.json]) zeigt die Konsole außerdem jeden von EF Core an die Datenbank gesendeten SQL-Befehl an. Sie können auch:

  • die Anwendung mit [dotnet watch] starten: Sie wird bei jeder Änderung einer Datei neu kompiliert und neu gestartet;
  • sie in [Visual Studio Code] schrittweise durchlaufen: Mit der Erweiterung [C# Dev Kit] startet die Taste F5 die Anwendung unter der Kontrolle des Debuggers; einen Haltepunkt setzen Sie mit einem einzigen Klick in den Rand neben einer Codezeile.

11.4. Die Architektur der Anwendung

Image

  • [Program.cs] konfiguriert die Anwendung: Services (Dependency Injection), Middleware (statische Dateien, Fehlerseiten, Sprache, Authentifizierung), Controller;
  • [Auth]: Anmeldung, JWT-Token, Rollen, CAPTCHA und Begrenzung der Versuche;
  • [Controllers]: die Controller der Web-Schicht. Sie laufen alle über einen einzigen Service, [ApplicationModel] (Ordner [Web]), der die Listen der Ärzte und Klienten im Speicher hält und andere Anfragen an die Geschäftsschicht weiterleitet;
  • [Web]: gemeinsame Elemente der Web-Schicht: Übersetzung, Flash-Meldungen, Validierung, View-Basisklasse, Exception-Filter; [Models]: Formular- und View-Modelle;
  • [Business]: Geschäftsregeln;
  • [Repositories]: die DAO-Schicht, eine Klasse pro Tabelle; [Data]: die [DbContext]-Schicht von EF Core;
  • [Entities]: die EF-Core-Entitäten; [Domain]: die Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
  • [Views]: die [Razor]-Views; [i18n]: Wörterbücher; [wwwroot]: das Stylesheet, das Seitenskript und [Bootstrap].

Die folgenden Abschnitte kommentieren alle Dateien, von den unteren Schichten (Datenbank) bis zu den oberen Schichten (Views).

11.5. Die Datenbank

Die Datenbank [dbrdvmedecins2] wird durch das Skript [database/dbrdvmedecins2.sql] erstellt, das auf dieselbe Weise ausgeführt wird wie in Beispiel 28 (das Tool [HeidiSQL] von [Laragon] oder der Befehl [mysql -u root < database/dbrdvmedecins2.sql]). Es ist wortgleich das Skript der [NestJS]-Anwendung: Beide Anwendungen können mit derselben Datenbank arbeiten, und die eine kann die andere ersetzen, ohne dass Änderungen nötig sind.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Datenbank [dbrdvmedecins2] - MySQL 8
--
-- Weiterentwicklung von [dbrdvmedecins]:
--   1. die Tabellen [doctors] und [clients] erhalten eine Spalte [user],
--      Fremdschlüssel auf users(id): jeder Arzt und jeder Client ist
--      nun auch ein Benutzer, der sich anmelden kann;
--   2. eine dritte Rolle erscheint: DOCTOR (zusätzlich zu ADMIN und USER);
--   3. das Skript erstellt für jeden Arzt (Rolle DOCTOR)
--      und für jeden Client (Rolle USER) eine Zeile in [users]:
--        - login        = Nachname in Kleinbuchstaben
--        - password     = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
--        - display name = Vorname + Nachname
--
--   4. Eindeutigkeitsbedingungen, alle BENANNT (die Anwendung erkennt
--      den Namen der verletzten Bedingung in der MySQL-Fehlermeldung):
--        - unq_users_login                   : ein Login gehört nur zu einem Konto;
--        - unq_doctors_first_name_last_name  : zwei Ärzte dürfen nicht denselben
--                                              Vor- und Nachnamen haben;
--        - unq_clients_first_name_last_name  : dasselbe für die Clients.
--      Achtung: die Collation utf8mb4_unicode_ci vergleicht ohne Rücksicht auf
--      Groß-/Kleinschreibung und Akzente - "Hélène DUPONT" und "helene dupont"
--      gelten daher als identisch.
--
-- Die Tabelle [users] muss nun VOR [doctors] und [clients] erstellt werden
-- (diese verweisen auf sie) und NACH ihnen gelöscht werden.
-- =========================================================================

-- bei jeder Ausführung des Skripts beginnen wir wieder mit einer leeren Datenbank (praktisch in der Entwicklung)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- Reihenfolge des Löschens: von den "Kind"-Tabellen zu den "Eltern"-Tabellen
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- Tabelle [users]: die Benutzer, die sich bei der Anwendung anmelden dürfen
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- ein Login darf nur zu einem Konto gehören
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- Tabelle [doctors]: die Ärzte der Praxis
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- ein Konto pro Arzt und ein Arzt pro Konto
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [clients]: die Patienten der Ärzte
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- ein Konto pro Client und ein Client pro Konto
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- zwei Clients dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [slots]: die Zeitfenster jedes Arztes
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- Tabelle [appointments]: die von den Clients gebuchten Termine
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- dasselbe Zeitfenster darf am selben Tag nur einmal gebucht werden
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Demodaten
-- =========================================================================

-- die Benutzer: Passwörter mit bcrypt gehasht (10 Salt-Runden)
--   admin/admin (ADMIN)
--   ein DOCTOR-Konto pro Arzt, ein USER-Konto pro Client
--   (das Demokonto user/user gibt es nicht mehr: ein USER-Konto ist
--   nun IMMER das Konto eines Clients, der buchen und das Konto verwalten kann)
--   (Login = Passwort = Nachname in Kleinbuchstaben)
INSERT INTO users (login, password, name, role) VALUES
  ('admin',     '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator',    'ADMIN'),
  -- doctors
  ('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER',  'DOCTOR'),
  ('tatou',     '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU',       'DOCTOR'),
  ('dupont',    '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT',    'DOCTOR'),
  -- clients
  ('martin',    '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN',      'USER'),
  ('durand',    '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND',     'USER'),
  ('bistrou',   '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
  ('german',    '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN',       'USER');

-- die Ärzte: die Spalte [user] wird anhand des Logins nachgeschlagen,
-- statt die Werte der Primärschlüssel von [users] vorauszusetzen
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
  ('Mme',  'PELISSIER', 'Marie',  (SELECT id FROM users WHERE login = 'pelissier')),
  ('Mr',   'TATOU',     'Paul',   (SELECT id FROM users WHERE login = 'tatou')),
  ('Melle','DUPONT',    'Sophie', (SELECT id FROM users WHERE login = 'dupont'));

INSERT INTO clients (title, last_name, first_name, `user`) VALUES
  ('Mr',   'MARTIN',  'Jean',     (SELECT id FROM users WHERE login = 'martin')),
  ('Mme',  'DURAND',  'Alice',    (SELECT id FROM users WHERE login = 'durand')),
  ('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
  ('Mr',   'GERMAN',  'Luc',      (SELECT id FROM users WHERE login = 'german'));

-- Zeitfenster von Arzt PELISSIER (doctor_id = 1): von 8:00 bis 12:00 in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- Zeitfenster von Arzt TATOU (doctor_id = 2): von 14:00 bis 18:00 in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- ein bereits gebuchter Termin, um im Terminkalender sofort ein belegtes Zeitfenster zu sehen
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);

Gehen wir dieses Skript durch:

  • Zeile 30: Die Datenbank wird erstellt, falls sie noch nicht existiert, mit dem Zeichensatz [utf8mb4] und der Kollation [utf8mb4_unicode_ci] wie in Beispiel 28: Zeichenkettenvergleiche unterscheiden nicht zwischen Groß- und Kleinschreibung und ignorieren Akzente. Dies gilt auch für Eindeutigkeitsbedingungen: [Hélène DUPONT] und [helene dupont] sind für [MySQL] zwei Ausprägungen derselben Person;
  • Zeilen 34–38: Das Skript beginnt bei jeder Ausführung mit einer leeren Datenbank. Die Tabellen werden von den „untergeordneten“ zu den „übergeordneten“ Tabellen gelöscht: Eine Tabelle, auf die ein Fremdschlüssel verweist ([users] zum Beispiel, auf die [doctors] und [clients] verweisen), kann nicht gelöscht werden, solange noch eine andere Tabelle auf sie verweist. Die Tabellen werden in umgekehrter Reihenfolge erstellt;
  • Zeilen 43–52: die Benutzerkonten. Jede Tabelle beginnt mit einem Primärschlüssel [id], der von der Datenbank vergeben wird ([AUTO_INCREMENT]), und einer Spalte [version], die beim Erstellen der Zeile auf 0 gesetzt wird;
  • Zeilen 46–49: der Login, das Passwort, der nach der Anmeldung angezeigte Name und die Rolle ([ADMIN], [DOCTOR], oder [USER]). Die Spalte [password] enthält nie das Passwort selbst, sondern dessen Hash, [bcrypt] (siehe Beispiel 25): 60 Zeichen, daher die Spaltenbreite;
  • Zeile 51: Ein Login gehört zu nur einem Konto. Wie in Beispiel 28 ist die Bedingung benannt: Wenn [MySQL] einen Schreibvorgang ablehnt, nennt die Fehlermeldung den Namen der verletzten Bedingung, und die Geschäftsschicht wählt daran die anzuzeigende Meldung aus (siehe [Business/BusinessService.cs]);
  • Zeilen 57–69: die Ärzte: Anrede, Nachname, Vorname;
  • Zeile 59: Die Spalte [version] dient dem optimistischen Sperren (siehe Beispiel 28): Sie wird bei jeder Änderung der Zeile erhöht, wodurch sich erkennen lässt, ob ein anderer Benutzer die Zeile zwischen dem Lesen und dem Schreiben geändert hat. Wie in Beispiel 28 erhöht die Anwendung diesen Wert selbst (siehe [DbContext], weiter unten);
  • Zeilen 63–64: Jeder Arzt hat ein Konto: Die Spalte [user] ist ein Fremdschlüssel , der auf [users(id)] verweist. Die Datenbank lehnt einen Wert ab, der auf kein Konto verweist, und weigert sich, ein Konto zu löschen, auf das noch ein Arzt verweist. Da [user] in [MySQL] ein reserviertes Wort ist, steht der Spaltenname in Backticks;
  • Zeile 66: Ein Konto gehört zu nur einem Arzt: Die Beziehung zwischen [doctors] und [users] ist eine „Eins-zu-eins“-Beziehung;
  • Zeile 68: Zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben. Die Bedingung gilt für das Spaltenpaar: Zwei Ärzte können denselben Nachnamen haben, wenn sie nicht denselben Vornamen haben;
  • Zeilen 74–86: die Klienten (Patienten) nach demselben Muster: ein Konto pro Klient (Fremdschlüssel [fk_clients_user], Eindeutigkeitsbedingung [unq_clients_user]); keine zwei Klienten dürfen denselben Vor- und Nachnamen haben;
  • Zeilen 91–100: die Zeitfenster jedes Arztes (Fremdschlüssel [doctor_id]): Start- und Endstunde sowie Start- und Endminute. Ein Zeitfenster hat kein Datum; es wiederholt sich jeden Tag;
  • Zeilen 105–115: die Termine: ein Datum (Typ [DATE], ohne Uhrzeit), ein Zeitfenster und ein Klient, identifiziert durch zwei Fremdschlüssel;
  • Zeile 114: Dasselbe Zeitfenster kann pro Tag nur einmal gebucht werden. Die Datenbank selbst erzwingt diese Regel: Buchen zwei Benutzer gleichzeitig dasselbe Zeitfenster, wird das zweite [INSERT] abgelehnt, unabhängig davon, was die Anwendung kurz zuvor geprüft hat;
  • Zeilen 127–137: Demokonten: der Administrator, drei Ärzte (Rolle [DOCTOR]) und vier Klienten (Rolle [USER]). Das Passwort jedes Benutzers entspricht seinem Login ([admin] / [admin], [pelissier] / [pelissier] …). Die Hashes beginnen mit [$2b$10$]: dem Algorithmus [bcrypt] mit dem Kostenfaktor 10 (siehe Beispiel 25); die Bibliothek [BCrypt.Net-Next] der Anwendung kann sie verifizieren;
  • Zeilen 141–144: Die Spalte [user] jedes Arztes wird über eine Unterabfrage auf den Login ermittelt, statt die von der Datenbank vergebenen Kennungen der Konten vorauszusetzen;
  • Zeilen 146–150: Die Klienten werden auf dieselbe Weise behandelt;
  • Zeilen 153–157: zwölf 20-Minuten-Zeitfenster von 8:00 bis 12:00 Uhr für Dr. PELISSIER. Hier ist die Kennung des Arztes (1) fest im Code verankert: Die Tabelle [doctors] wurde gerade erst erstellt, ihre Kennungen beginnen also bei 1;
  • Zeilen 160–164: zwölf Zeitfenster von 14:00 bis 18:00 Uhr für Dr. TATOU. Dr. DUPONT hat keine Zeitfenster: Sein Terminkalender ist leer;
  • Zeilen 167–168: Für Brigitte BISTROU (Klientin Nr. 3) wurde bereits ein Termin im zweiten Zeitfenster von Dr. PELISSIER (8:20 Uhr) vereinbart. [CURDATE()] ist das Datum der Skriptausführung: Bei der ersten Anmeldung zeigt der heutige Kalender daher ein bereits gebuchtes Zeitfenster.

11.6. Projektkonfiguration

11.6.1. RdvMedecins.csproj

<!--
  =========================================================================
  RdvMedecins.csproj - die Projektdatei (das Äquivalent von package.json).

  Microsoft.NET.Sdk.Web: das SDK der ASP.NET-Core-Anwendungen. Für sich allein
  bringt es das gesamte Web-Framework mit (MVC, Razor-Views, Authentifizierung,
  Lokalisierung, statische Dateien...): nur die Bibliotheken, die
  AUSSERHALB des Frameworks liegen, sind unten aufgeführt (PackageReference) und
  werden von nuget.org durch [dotnet restore] / [dotnet build] heruntergeladen.
  =========================================================================
-->
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <!-- .NET 10, LTS-Version (Long-Term Support) -->
    <TargetFramework>net10.0</TargetFramework>
    <!-- "nullable" Referenztypen: der Compiler meldet die Risiken einer
         NullReferenceException (das Äquivalent von strictNullChecks in TypeScript) -->
    <Nullable>enable</Nullable>
    <!-- implizite Usings: System, System.Linq, System.Threading.Tasks... -->
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>RdvMedecins</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <!-- Entity Framework Core + sein MySQL- / MariaDB-Provider.
         Pomelo selbst zieht Microsoft.EntityFrameworkCore (und MySqlConnector,
         den ADO.NET-Treiber) in der dazu passenden Version nach. -->
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- Authentifizierung per JWT-Token (Lesen und Überprüfen des Tokens) -->
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
    <!-- Passwort-Hashing (bcrypt), kompatibel mit den
         $2b$-Hashes des SQL-Skripts -->
    <PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
  </ItemGroup>

  <ItemGroup>
    <!-- die Übersetzungswörterbücher werden beim Start gelesen. Das Web-SDK
         nimmt bereits alle .json-Dateien unter die zu veröffentlichenden Dateien auf (Content):
         wir legen lediglich fest, dass sie immer kopiert werden (dotnet publish) -->
    <Content Update="i18n\*.json" CopyToPublishDirectory="PreserveNewest" />
    <!-- das SQL-Skript muss nicht veröffentlicht werden -->
    <Content Remove="database\**" />
    <None Include="database\**" />
  </ItemGroup>

</Project>

Gehen wir diese Datei durch:

  • Zeile 12: das SDK für Webanwendungen, wie in allen Beispielen (siehe Einführung);
  • Zeilen 14–23: die Einstellungen, die die Beispiele in der gemeinsamen Datei [examples/Directory.Build.props] fanden: [.NET] 10, „Nullable“-Referenztypen, implizite [using]-Anweisungen. Die Fallstudie ist ein eigenständiges Projekt: Sie schreibt diese Einstellungen selbst. [RootNamespace] ist der Stammnamespace des Projekts, den [Visual Studio Code] für eine neue Datei vorschlägt;
  • Zeile 29: der [MySQL]-Provider für EF Core, der EF Core und den Treiber [MySqlConnector] einbindet (siehe Beispiel 28);
  • Zeilen 31–34: die beiden Authentifizierungspakete, die bereits in Kapitel 8 verwendet wurden: Überprüfung von JWT-Token und Passwort-Hashing;
  • Zeile 41: Die Übersetzungswörterbücher [i18n/*.json] werden beim Start von der Festplatte gelesen. Wenn die Anwendung für einen Produktionsserver vorbereitet wird (Befehl [dotnet publish]), müssen sie mitkopiert werden: Genau das bewirkt [CopyToPublishDirectory];
  • Zeilen 43–44: Das SQL-Skript ist keine Anwendungsdatei; es wird von den veröffentlichten Dateien ausgeschlossen, wie in Beispiel 28 gezeigt.

11.6.2. appsettings.json

Die Datei [appsettings.json] erfüllt denselben Zweck wie die Datei [.env] in der [NestJS]-Anwendung. Ein wichtiger Unterschied: Die Datei [.env] wurde nie weitergegeben, und eine Datei namens [.env.example] diente als ihre Vorlage. Hier ist [appsettings.json] Teil des Projekts; rechnerspezifische Werte (etwa ein Passwort) können auf andere Weise bereitgestellt werden, ohne die Datei zu ändern (siehe unten).

// =========================================================================
// appsettings.json - die Konfiguration der Anwendung (das Äquivalent
// der Datei .env des NestJS-Projekts). ASP.NET Core akzeptiert Kommentare
// in dieser JSON-Datei.
//
// Die sensiblen Werte (MySQL-Passwort, JWT-Secret) können ersetzt
// werden, ohne diese Datei anzufassen: Umgebungsvariablen oder
// "User Secrets" (siehe README.md, Abschnitt Configuration).
// =========================================================================
{
  // Listening-Port. Der JSON-Server lauscht bereits auf 8080: wir wählen einen anderen
  // Port, um beide gleichzeitig ausführen zu können.
  "Urls": "http://localhost:8081",

  // Verbindung zur MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql)
  "ConnectionStrings": {
    "RdvMedecins": "Server=localhost;Port=3306;Database=dbrdvmedecins2;User=root;Password=;"
  },
  "MySql": {
    // Serverversion, damit EF Core den richtigen SQL-Dialekt erzeugt:
    // "8.0.0-mysql" für MySQL 8, "10.11.0-mariadb" für MariaDB 10.11...
    "ServerVersion": "8.0.0-mysql"
  },

  // Authentifizierung (siehe Auth/)
  "Auth": {
    // geheimer Schlüssel der JWT-Tokens: mindestens 32 Zeichen (HMAC-SHA256).
    // Muss in der Produktion unbedingt geändert werden (lange Zufallszeichenfolge).
    "JwtSecret": "change-me-to-a-long-random-string",
    // Gültigkeitsdauer eines Tokens in Sekunden (7200 s = 2 h); das Cookie,
    // das das Token trägt, hat dieselbe Lebensdauer
    "JwtExpiresInSeconds": 7200,
    // true in der Produktion (Website über HTTPS ausgeliefert): das Authentifizierungs-Cookie
    // wird dann nie über eine unverschlüsselte Verbindung gesendet
    "CookieSecure": false
  },

  // Schutz vor Robotern (siehe Auth/AttemptLimiterService.cs)
  "Protection": {
    // Login: erlaubte Fehlversuche für denselben Login von derselben IP-Adresse...
    "LoginMaxFailures": 5,
    // ... vor einer Sperre dieser Dauer (die gesamte IP-Adresse wird ebenfalls
    // gesperrt, wenn sie 5-mal so viele Fehlversuche ansammelt, alle Logins zusammen)
    "LoginBlockMinutes": 15,
    // Anlegen von Client-Konten: höchstens so viele Konten pro Stunde und pro
    // IP-Adresse. In einem Kursraum gehen oft alle Rechner über dieselbe
    // Adresse ins Netz: bei Bedarf erhöhen.
    "RegistrationMaxPerHour": 10
  },

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Gehen wir diese Datei durch:

  • Zeilen 1–9: Anders als Standard-JSON erlaubt [ASP.NET Core] Kommentare in seinen Konfigurationsdateien;
  • Zeile 13: die Adresse und der Listening-Port. Die Beispiele lauschten auf Port 5000, dem Standardport; die Anwendung lauscht auf Port 8081, wie die [NestJS]-Version;
  • Zeilen 16–18: die Verbindungszeichenfolge zur Datenbank [dbrdvmedecins2] mit den Standardwerten von [Laragon] (Benutzername [root], kein Passwort); siehe Beispiel 28;
  • Zeilen 19–23: die Serverversion, die dem Provider [Pomelo] mitteilt, welchen SQL-Dialekt er erzeugen soll (siehe Beispiel 28);
  • Zeilen 26–36: der Authentifizierungsabschnitt: der geheime Schlüssel, der die Token signiert (mindestens 32 Zeichen; in der Produktion zu ersetzen), die Lebensdauer des Tokens (zwei Stunden) und die Option [Secure] im Cookie, das es trägt. In der Produktion wird die Website über HTTPS ausgeliefert, und das Cookie darf niemals über eine unverschlüsselte Verbindung übertragen werden: Die Option ist auf [true] gesetzt;
  • Zeilen 39–49: die Schwellenwerte des Bot-Schutzes (siehe Beispiel 27): Anzahl der erlaubten fehlgeschlagenen Anmeldeversuche und Dauer der daraus folgenden Sperre; Anzahl der Klientenkonten, die pro Stunde von derselben IP-Adresse erstellt werden dürfen;
  • Zeilen 51–57: die Protokollierungsebenen (siehe Einführung). Meldungen von EF Core werden erst ab der Ebene [Warning] angezeigt: SQL-Befehle, die auf der Ebene [Information] liegen, erscheinen nicht (siehe Beispiel 28);
  • Zeile 58: Alle Domainnamen werden akzeptiert.

Die Abschnitte [Auth] und [Protection] werden als typisierte Klassen interpretiert (siehe [Config/AuthOptions.cs], weiter unten). Jeder Wert wird durch seinen Pfad bezeichnet, wobei die Ebenen durch [:] getrennt sind: [Auth:JwtSecret], [ConnectionStrings:RdvMedecins], [MySql:ServerVersion]. [ASP.NET Core] liest die Konfiguration aus mehreren aufeinanderfolgenden Quellen, von denen jede die Werte der vorherigen überschreiben kann: [appsettings.json], dann [appsettings.{environment}.json] (siehe die nächste Datei), dann in der Entwicklung „User Secrets“ (Werte, die außerhalb des Projekts im Profil des Benutzers gespeichert sind), dann Umgebungsvariablen und schließlich Befehlszeilenargumente. Ein Passwort kann so über eine Umgebungsvariable bereitgestellt werden, wobei [:] als [__] geschrieben wird:

export ConnectionStrings__RdvMedecins="Server=localhost;Port=3306;Database=dbrdvmedecins2;User=root;Password=myPassword;"

Die Datei [README.md] der Anwendung beschreibt diese Optionen ausführlich.

11.6.3. appsettings.Development.json

// Überschreibung von appsettings.json in der Entwicklung (ASPNETCORE_ENVIRONMENT=
// Development, siehe Properties/launchSettings.json): wir zeigen in der
// Konsole die von EF Core erzeugten SQL-Abfragen an - wie es die
// Option logging: true von TypeORM tat.
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
    }
  }
}
  • Zeile 10: [ASP.NET Core] kennt die Umgebung , in der die Anwendung läuft: [Development], [Production] … Es liest sie aus der Umgebungsvariablen [ASPNETCORE_ENVIRONMENT] (siehe die folgende Datei); andernfalls verwendet es [Production]. Nach [appsettings.json] liest es, sofern vorhanden, die Datei [appsettings.{environment}.json] und führt beide zusammen: Die in der zweiten Datei vorhandenen Schlüssel ersetzen die der ersten, die übrigen bleiben erhalten. In der Entwicklung fügen wir daher die Ebene [Information] für die Kategorie [Microsoft.EntityFrameworkCore.Database.Command] hinzu: Die spezifischere Regel hat Vorrang vor der allgemeineren aus [appsettings.json] ([Warning] für alle [Microsoft.EntityFrameworkCore]), und jeder an die Datenbank gesendete SQL-Befehl wird in der Konsole angezeigt. Das entspricht der Option [logging] von [TypeORM], die die [NestJS]-Version außerhalb der Produktion aktivierte. Alle übrigen Werte (Verbindung, Authentifizierung usw.) bleiben dieselben wie in [appsettings.json].

11.6.4. Properties/launchSettings.json

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:8081",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Diese Datei wird nur während der Entwicklung von [dotnet run], [dotnet watch] und [Visual Studio Code] verwendet; sie wird nicht veröffentlicht. Kommentieren wir sie:

  • Zeilen 3–4: Ein Startprofil beschreibt eine Möglichkeit, die Anwendung zu starten. Hier gibt es nur eines; [dotnet run] verwendet das erste;
  • Zeile 5: Die Anwendung wird direkt mit ihrem eigenen Webserver gestartet;
  • Zeilen 6–7: [dotnet run] zeigt seine Kompilierungsmeldungen an, und der Browser öffnet die Anwendung, sobald sie bereit ist;
  • Zeile 8: die Listening-Adresse, identisch mit dem Schlüssel [Urls] aus [appsettings.json]. Beim Start über dieses Profil verwendet die Anwendung diese Adresse; beim Start außerhalb des Profils (zum Beispiel nach der Veröffentlichung) verwendet sie die Adresse aus [appsettings.json];
  • Zeilen 9–10: die an die Anwendung übergebenen Umgebungsvariablen. [ASPNETCORE_ENVIRONMENT=Development] legt die Umgebung fest: [appsettings.Development.json] wird gelesen, und die SQL-Befehle werden angezeigt. Auf einem Produktionsserver ist die Umgebung ohne diese Datei oder diese Variable [Production].

11.6.5. Config/AuthOptions.cs

// =========================================================================
// Config/AuthOptions.cs
// -------------------------------------------------------------------------
// Der Abschnitt "Auth" von appsettings.json als typisierte Klasse.
//
// Es ist das "Options Pattern" von ASP.NET Core: in
// Program.cs bindet builder.Services.Configure<AuthOptions>(...) den Abschnitt
// an die Klasse; eine Klasse, die ihn braucht, erhält dann IOptions<AuthOptions>
// per Dependency Injection. So vermeiden wir es, Zeichenketten
// überall zu lesen, wie es process.env.JWT_SECRET tat.
// =========================================================================

namespace RdvMedecins.Config;

public class AuthOptions
{
    public const string Section = "Auth";

    // geheimer Schlüssel zum Signieren / Überprüfen der JWT-Tokens. Der Algorithmus HMAC-SHA256
    // verlangt einen Schlüssel von mindestens 256 Bit, also 32 Byte.
    public string JwtSecret { get; set; } = "";

    // Gültigkeitsdauer eines Tokens in Sekunden; das Cookie, das es trägt,
    // hat dieselbe Lebensdauer
    public int JwtExpiresInSeconds { get; set; } = 7200;

    // true in der Produktion (HTTPS): das Authentifizierungs-Cookie wird nie
    // über eine unverschlüsselte Verbindung gesendet
    public bool CookieSecure { get; set; }
}

Kommentieren wir diesen Code:

  • Zeile 15: der Abschnitt [Auth] aus [appsettings.json] in Form einer gewöhnlichen Klasse: eine Eigenschaft pro Schlüssel, mit demselben Namen. Dies ist das Options-Muster ([options pattern]) von [ASP.NET Core]. In [Program.cs] verknüpft [Configure<AuthOptions>(...)] den Abschnitt mit der Klasse: Das Framework erzeugt ein [AuthOptions]-Objekt und füllt seine Eigenschaften mit den Werten des Abschnitts, wobei es sie in den richtigen Typ umwandelt (["7200"] wird zur Ganzzahl 7200, [false] wird zum booleschen Wert [false]). Eine Klasse, die ihn benötigt, erhält ihn per Dependency Injection in Form eines ***[IOptions<AuthOptions>], dessen Eigenschaft ***[Value] das gefüllte Objekt ist: So macht es [Auth/AuthService.cs] mit seinem Parameter [IOptions<AuthOptions> options] und seinem Feld [auth = options.Value]. So muss man nicht überall Zeichenketten lesen, wie es [process.env.JWT_SECRET] in der Version [NestJS] tat: Die Schlüsselnamen werden vom Compiler überprüft, und die Werte sind bereits umgewandelt;
  • Zeile 17: der Abschnittsname, der nur einmal geschrieben wird;
  • Zeilen 21–29: die drei Werte dieses Abschnitts. Die Standardwerte ([7200], [false] für einen booleschen Wert) werden verwendet, wenn der Schlüssel in der Konfiguration fehlt.

11.6.6. Config/ProtectionOptions.cs

// =========================================================================
// Config/ProtectionOptions.cs
// -------------------------------------------------------------------------
// Der Abschnitt "Protection" von appsettings.json: die Schwellenwerte des Schutzes
// vor Robotern (siehe Auth/AttemptLimiterService.cs).
// =========================================================================

namespace RdvMedecins.Config;

public class ProtectionOptions
{
    public const string Section = "Protection";

    // Login: Anzahl erlaubter Fehlversuche (falsches CAPTCHA oder Passwort)
    // für denselben Login von derselben IP-Adresse, bevor dieses Paar gesperrt wird...
    public int LoginMaxFailures { get; set; } = 5;

    // ... für diese Dauer (eine IP-Adresse wird ebenfalls gesperrt, wenn sie
    // 5-mal so viele Fehlversuche ansammelt, alle Logins zusammen)
    public int LoginBlockMinutes { get; set; } = 15;

    // Anlegen von Client-Konten: maximale Anzahl pro Stunde angelegter Konten
    // von derselben IP-Adresse. In einem Kursraum gehen oft alle Rechner
    // über dieselbe Adresse ins Netz: bei Bedarf erhöhen.
    public int RegistrationMaxPerHour { get; set; } = 10;
}
  • Zeilen 10–25: der Abschnitt [Protection] aus [appsettings.json] nach demselben Muster. Er wird in Form eines [IOptions<ProtectionOptions>] in [Auth/AttemptLimiterService.cs] injiziert, der daraus seine Schwellenwerte liest.

11.7. Start der Anwendung

11.7.1. Program.cs

Die Datei [Program.cs] übernimmt zugleich die Rolle von [main.ts] (Start, Middleware) und von [app.module.ts] (welcher Service was bereitstellt) aus der Version [NestJS]. Sie folgt dem Aufbau aller Beispiele: zuerst die Services registrieren, dann die Middleware-Pipeline aufbauen. Wir zerlegen sie in Abschnitte.

11.7.1.1. Die Konfiguration

// =========================================================================
// Program.cs
// -------------------------------------------------------------------------
// Der Einstiegspunkt der Anwendung: das Äquivalent von main.ts
// (Start, Middlewares) und app.module.ts (wer was bereitstellt) zusammen.
//
// Zwei Phasen, immer in dieser Reihenfolge:
//
//   1. builder.Services... : wir REGISTRIEREN die Services im Container für Dependency
//      Injection (das Äquivalent der "Provider" der NestJS-
//      Module). Jeder Service hat eine LEBENSDAUER:
//        - Singleton : eine einzige Instanz für die gesamte Anwendung;
//        - Scoped    : eine Instanz pro HTTP-Anfrage (der DbContext und alles,
//                      was ihn verwendet);
//        - Transient : bei jeder Anforderung eine neue Instanz.
//
//   2. app.Use... : wir bauen die Middleware-PIPELINE, die jede Anfrage
//      in der Reihenfolge durchläuft, in der sie deklariert sind.
// =========================================================================

using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Microsoft.AspNetCore.Localization;
using Microsoft.EntityFrameworkCore;
using RdvMedecins.Auth;
using RdvMedecins.Config;
using RdvMedecins.Data;
using RdvMedecins.Business;
using RdvMedecins.Repositories;
using RdvMedecins.Web;

var builder = WebApplication.CreateBuilder(args);

// =========================================================================
// 1. die Services
// =========================================================================

// ──── die typisierte Konfiguration (Abschnitte von appsettings.json, siehe Config/)
builder.Services.Configure<AuthOptions>(builder.Configuration.GetSection(AuthOptions.Section));
builder.Services.Configure<ProtectionOptions>(builder.Configuration.GetSection(ProtectionOptions.Section));
var authOptions = builder.Configuration.GetSection(AuthOptions.Section).Get<AuthOptions>() ?? new AuthOptions();
  • Zeilen 21–31: die verwendeten Namespaces, zusätzlich zu den impliziten [using]-Anweisungen: die des Frameworks (Lokalisierung, EF Core, HTML-Codierung) und die der Anwendung, einer pro Ordner;
  • Zeile 33: der Anwendungs-Builder, wie in allen Beispielen. Er hat die Konfiguration bereits gelesen ([appsettings.json], [appsettings.Development.json], Umgebungsvariablen …), die über [builder.Configuration] zugänglich ist;
  • Zeilen 40–41: das Options-Muster (siehe [Config/AuthOptions.cs]): Jeder Abschnitt wird mit seiner Klasse verknüpft. [GetSection("Auth")] bezeichnet den Abschnitt; [Configure<T>] registriert den entsprechenden Service [IOptions<T>], den die Authentifizierungsservices per Injektion erhalten;
  • Zeile 42: derselbe Abschnitt, diesmal direkt als Objekt gelesen ([Get<AuthOptions>()]), oder als Objekt mit Standardwerten, falls der Abschnitt fehlt. Die Konfiguration von [JwtBearer] (weiter unten) benötigt den geheimen Schlüssel sofort, bei der Registrierung der Services: Zu diesem Zeitpunkt ist der Dependency-Injection-Container noch nicht gebaut, und es kann kein [IOptions<AuthOptions>] injiziert werden.

11.7.1.2. Die Datenbank sowie die DAO- und die Geschäftsschicht

// ──── Entity Framework Core: der DbContext, einer pro Anfrage (Scoped).
// UseMySql: der Pomelo-Provider für MySQL / MariaDB. Die Serverversion
// sagt ihm, welchen SQL-Dialekt er erzeugen soll.
var connectionString = builder.Configuration.GetConnectionString("RdvMedecins")
    ?? throw new InvalidOperationException("ConnectionStrings:RdvMedecins missing from appsettings.json");
var serverVersion = ServerVersion.Parse(builder.Configuration["MySql:ServerVersion"] ?? "8.0.0-mysql");
builder.Services.AddDbContext<RdvMedecinsDbContext>(options => options.UseMySql(connectionString, serverVersion));

// ──── DAO-Schicht und Geschäftsschicht: Scoped, wie der DbContext, von dem sie
// abhängen (ein Service darf nie LÄNGER leben als seine Abhängigkeiten)
builder.Services.AddScoped<DoctorRepository>();
builder.Services.AddScoped<ClientRepository>();
builder.Services.AddScoped<SlotRepository>();
builder.Services.AddScoped<AppointmentRepository>();
builder.Services.AddScoped<UserRepository>();
// "wenn ein IBusiness angefordert wird, einen BusinessService liefern" (NestJS:
// { provide: BUSINESS_TOKEN, useClass: BusinessService }). In C# dient die Schnittstelle
// selbst als Injection-Token.
builder.Services.AddScoped<IBusiness, BusinessService>();

// ──── der Cache (Singleton) und seine Fassade (Scoped), siehe Web/ApplicationModel.cs
builder.Services.AddSingleton<ListCache>();
builder.Services.AddScoped<ApplicationModel>();
  • Zeilen 4–5: die Verbindungszeichenfolge, wie in Beispiel 28. Der Operator [??] liefert den Wert links, wenn er nicht [null] ist; andernfalls liefert er den Wert rechts: Fehlt der Schlüssel, bricht die Anwendung sofort ab und zeigt eine Meldung an, die angibt, was fehlt, statt bei der ersten Anfrage einen kryptischen Fehler zu liefern;
  • Zeile 6: die [MySQL]-Serverversion, mit einem Standardwert, falls der Schlüssel fehlt;
  • Zeile 7: der [DbContext] der Anwendung (siehe [Data/RdvMedecinsDbContext.cs]), einer pro Anfrage ([Scoped]), mit dem Provider [MySQL] (siehe Beispiel 28);
  • Zeilen 11–15: die DAO-Schicht: eine Klasse pro Tabelle (außer [users], deren Repository für die Authentifizierung verwendet wird). Sie ist [Scoped], genau wie der [DbContext] , den sie verwendet. Ein Service darf seine Abhängigkeiten nie überleben: Ein [Singleton]-DAO würde den [DbContext] der ersten Anfrage dauerhaft festhalten, obwohl er am Ende dieser Anfrage zerstört wird (siehe Kapitel 6);
  • Zeile 19: die Geschäftsschicht. [AddScoped<IBusiness, BusinessService>()] lautet gelesen: „Wenn ein Service ein [IBusiness] anfordert, liefere ihm einen [BusinessService].“ Wer die Geschäftsschicht nutzt, hängt von der Schnittstelle ab, nicht von der Klasse: Wir könnten die Implementierung (zum Beispiel durch eine Testversion) ersetzen, indem wir nur diese Zeile ändern. Die [NestJS]-Version benötigte dafür ein Token ([BUSINESS_TOKEN]), da die [TypeScript]-Schnittstellen zur Kompilierzeit verschwinden; in [C#] dient die Schnittstelle selbst als Token;
  • Zeilen 22–23: Der Cache der Web-Schicht (die Listen der Ärzte und Klienten) hat Anwendungsgültigkeit: [Singleton], eine einzige Instanz, die von allen Anfragen gemeinsam genutzt wird (siehe Beispiel 23). Seine Fassade, [ApplicationModel], über die alle Controller laufen, verwendet die Geschäftsschicht: Sie ist daher [Scoped]. Der Cache selbst, der von nichts anderem abhängt, kann die Fassade überdauern.

11.7.1.3. Authentifizierung, Übersetzung und HTML-Codierung

// ──── Authentifizierung
builder.Services.AddScoped<AuthService>();
builder.Services.AddSingleton<CaptchaService>(); // ausstehende CAPTCHAs: im Speicher
builder.Services.AddSingleton<AttemptLimiterService>(); // Zähler: im Speicher
builder.Services.AddSingleton<RegistrationPassService>(); // Pässe: im Speicher
builder.Services.AddJwtAuthentication(authOptions); // siehe Auth/JwtAuthentication.cs
builder.Services.AddAuthorization();

// ──── Übersetzung
builder.Services.AddSingleton<Translator>();

// ──── der Razor-HTML-Encoder. Standardmäßig ersetzt er jedes Nicht-ASCII-Zeichen
// durch eine Entität ("é" -> "&#xE9;"): die Seite wird korrekt angezeigt,
// aber ihr Quelltext wird unlesbar. Wir erlauben ihm, die Zeichen aller Sprachen
// unverändert zu schreiben; < > & " ' werden dagegen immer maskiert.
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
  • Zeile 2: der Anmeldeservice (Überprüfung von Benutzername und Passwort, Erzeugung des Tokens; siehe Beispiel 25). Er verwendet das Konto-Repository: Er ist [Scoped];
  • Zeilen 3–5: ausstehende CAPTCHAs, Fehlerzähler und Zugangscodes für die Kontoerstellung (siehe Beispiel 27). Diese Daten werden im Speicher gehalten und müssen für alle Anfragen dieselben sein: Alle drei Services sind [Singleton]. Der Nachteil: Sie gehen bei jedem Neustart des Servers verloren;
  • Zeile 6: die Konfiguration von [JwtBearer] (Token wird aus dem Cookie gelesen, Umleitung auf die Anmeldeseite …), wie in Beispiel 25. Sie ist in einer Erweiterungsmethode von [IServiceCollection] untergebracht (siehe [Auth/JwtAuthentication.cs]), die wie eine Framework-Methode aufgerufen wird und dadurch [Program.cs] entlastet;
  • Zeile 7: die Autorisierungsservices, die von [[Authorize]] und von der Middleware [UseAuthorization] verwendet werden;
  • Zeile 10: der Übersetzungsservice, der die Wörterbücher ein für alle Mal liest (siehe Beispiel 22);
  • Zeile 16: Der HTML-Encoder von [Razor] lässt Zeichen aller Sprachen unverändert durch, wie in Beispiel 15.

11.7.1.4. MVC und seine Optionen

// ──── MVC: Controller + Razor-Views
builder.Services.AddControllersWithViews(options =>
{
    // InvalidSessionException -> zurück zur Login-Seite
    options.Filters.Add<HtmlExceptionFilter>();

    // bei aktivierten "Nullable"-Typen behandelt MVC eine (nicht nullable)
    // String-Eigenschaft automatisch als erforderlich. Wir sagen es lieber selbst,
    // ausdrücklich, mit [Required] (siehe Models/Forms.cs).
    options.SuppressImplicitRequiredAttributeForNonNullableReferenceTypes = true;

    // die Meldungen der BINDING-Fehler (ein Text, wo eine Zahl
    // erwartet wird: version="abc"...) sind ebenfalls Übersetzungsschlüssel
    var messages = options.ModelBindingMessageProvider;
    messages.SetValueMustNotBeNullAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetAttemptedValueIsInvalidAccessor((_, _) => "ERRORS.INVALID_FORM");
    messages.SetValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetValueMustBeANumberAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetUnknownValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyAttemptedValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyUnknownValueIsInvalidAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyValueMustBeANumberAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetMissingBindRequiredValueAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetMissingKeyOrValueAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetMissingRequestBodyRequiredValueAccessor(() => "ERRORS.INVALID_FORM");
});
  • Zeile 2: die [Razor]-Controller und -Views. Die als Parameter übergebene Funktion legt die Optionen von MVC fest;
  • Zeile 5: ein globaler Exception-Filter (siehe Beispiel 24), der für alle Aktionen gilt. Er behandelt nur einen Fall: Eine [InvalidSessionException] (das Token ist gültig, aber das Konto, auf das es verweist, wurde inzwischen gelöscht) führt zur Anmeldeseite. Die übrigen Ausnahmen setzen ihren Weg zur Middleware [UseExceptionHandler] fort (weiter unten);
  • Zeile 10: eine Falle der „Nullable“-Typen. Wenn sie aktiviert sind, behandelt MVC eine (nicht nullable) Eigenschaft [string] eines Modells als erforderlich, genau so, als hätte sie das Attribut [[Required]], mit einer englischen Fehlermeldung, die wir nicht verstehen. Diese Option entfernt dieses Standardverhalten: Ein Feld ist nur dann erforderlich, wenn es ausdrücklich das Attribut [[Required]] hat, mit unserer eigenen Meldung (siehe [Models/Forms.cs]);
  • Zeilen 14–25: die Fehlermeldungen des Bindings (siehe Beispiel 19): Text, wo eine Zahl erwartet wird ([version=abc]), ein fehlender Wert … Beispiel 19 hat nur zwei davon neu definiert, auf Englisch; die Fallstudie definiert sie alle neu, und jede liefert denselben Übersetzungsschlüssel, [ERRORS.INVALID_FORM], statt eines Textes: Die Meldung wird erst bei der Anzeige in der Sprache des Benutzers übersetzt. Das Zeichen [_] steht für einen nicht verwendeten Parameter (den Feldnamen, den eingegebenen Wert): Die Meldung ist unabhängig vom Feld dieselbe. Diese Fehler sollten bei den Formularen der Anwendung nie auftreten: Sie weisen auf eine manuell erstellte Anfrage hin.

11.7.1.5. Laden des Caches

var app = builder.Build();

// =========================================================================
// Laden des Caches (Listen der Ärzte und Clients). Scoped-Services
// existieren nur innerhalb eines "Scopes" (normalerweise: einer Anfrage): wir erstellen
// einen für die Dauer dieses Ladens. Datenbank nicht erreichbar -> die Anwendung
// stoppt hier, mit der EF-Core-Ausnahme in der Konsole.
// =========================================================================
using (var scope = app.Services.CreateScope())
{
    await scope.ServiceProvider.GetRequiredService<ApplicationModel>().LoadAsync();
}
  • Zeile 1: Aufbau der Anwendung. Der Dependency-Injection-Container ist nun erstellt: Es können keine Services mehr registriert, aber abgerufen werden;
  • Zeilen 9–12: Die Listen der Ärzte und Klienten werden in den Cache geladen, bevor der Server zu lauschen beginnt. [ApplicationModel] ist ein [Scoped]-Service: Er kann nur innerhalb eines Scopes erstellt werden, und außerhalb einer Anfrage gibt es keinen Scope. [CreateScope()] erstellt einen; [GetRequiredService<ApplicationModel>()] liefert daraus den Service (samt der Geschäftsschicht, den Repositories und dem [DbContext] , von denen er abhängt), und [LoadAsync()] füllt den Cache, der ein [Singleton] ist und daher den Scope überlebt. Die [using]-Anweisung zerstört den Scope – und mit ihm den [DbContext] –, wenn der Block endet. Ist die Datenbank nicht erreichbar, wird die Ausnahme von EF Core nicht abgefangen: Die Anwendung wird mit einer Fehlermeldung in der Konsole beendet. Das ist das erste Anzeichen für eine falsche Verbindungszeichenfolge oder einen angehaltenen [MySQL]-Server.

11.7.1.6. Die Middleware-Pipeline

// =========================================================================
// 2. die Middleware-Pipeline - die REIHENFOLGE ist wichtig
// =========================================================================

// ──── Fehler werden zu HTML-Seiten (siehe Web/HtmlExceptionFilter.cs):
// unbehandelte Ausnahme -> 500-Seite (die Ausnahme wird ins Log geschrieben);
// 400- / 403- / 404-Antwort ohne Inhalt -> entsprechende Fehlerseite
app.UseExceptionHandler("/error/500");
app.UseStatusCodePagesWithReExecute("/error/{0}");

// ──── statische Dateien des Ordners wwwroot/: /css/..., /js/..., /lib/bootstrap/...
app.UseStaticFiles();

// ──── die Sprache jeder Anfrage: aus einem Cookie gelesen (siehe LanguageController),
// standardmäßig Englisch. Sie setzt CultureInfo.CurrentCulture (Datumsformate)
// und CultureInfo.CurrentUICulture (Sprache der Texte, siehe Web/Translator.cs).
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
    SupportedCultures = cultures,
    SupportedUICultures = cultures,
};
// nur das Cookie entscheidet (weder die Browsersprache noch ein URL-Parameter)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);

// ──── Routing, dann Authentifizierung (wer ist es? -> HttpContext.User, aus
// dem Token), dann Autorisierung (ist es erlaubt? -> [Authorize])
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

// ──── die Controller, mit ihren per Attribut deklarierten Routen ([HttpGet("...")])
app.MapControllers();

app.Run();

Jede Anfrage durchläuft die Middleware-Komponenten in der Reihenfolge, in der sie deklariert sind (siehe Kapitel 7): Diese Reihenfolge ist daher wichtig.

  • Zeile 8: Die erste Middleware umschließt alle anderen. Wurde eine Ausnahme von niemandem behandelt (ein Programmierfehler, eine unerreichbar gewordene Datenbank usw.), protokolliert sie die Ausnahme und führt die Anfrage mit der Adresse [/error/500] erneut aus: Der Benutzer sieht eine Fehlerseite der Anwendung und keine technische Meldung (siehe Kapitel 7);
  • Zeile 9: Eine leere Fehlerantwort (400, 403, 404) wird auf dieselbe Weise in eine Seite umgewandelt, über die Aktion [/error/{code}] des Controllers [ErrorController] (siehe Beispiele 24 und 26). Die erneut ausgeführte Anfrage durchläuft die folgenden Middleware-Komponenten noch einmal: Die Fehlerseite wird daher dargestellt und erkennt den angemeldeten Benutzer;
  • Zeile 12: die statischen Dateien im Ordner [wwwroot] (siehe Beispiel 15): das Stylesheet, das Seitenskript und [Bootstrap], hier abgelegt in [wwwroot/lib/bootstrap]. Weit vorn in der Pipeline platziert, beantwortet diese Middleware Dateianfragen, ohne sie durch Lokalisierung oder Authentifizierung zu leiten;
  • Zeilen 17–23: die Lokalisierungskonfiguration, wie in Beispiel 22. Die unterstützten Sprachen und die Standardsprache stammen vom Übersetzungsservice ([Translator.Languages], [Translator.DefaultLanguage]): Sie sind nur an einer Stelle definiert;
  • Zeile 25: Nur das von [LanguageController] gesetzte Cookie bestimmt die Sprache (siehe Beispiel 22). Die Syntax [[...]] ist ein Collection Expression: hier eine Liste mit nur einem Element;
  • Zeile 26: die Lokalisierungs-Middleware, die für jede Anfrage die Sprache festlegt;
  • Zeilen 30–32: Routing, danach Authentifizierung, danach Autorisierung. Das Routing wählt anhand der per Attribut deklarierten Routen die Aktion aus, die die Anfrage bearbeitet. Die Beispiele riefen es nicht auf: [WebApplication] fügt es daher automatisch am Anfang der Pipeline hinzu. Der ausdrückliche Aufruf macht die Reihenfolge sichtbar: Die Autorisierung muss nach dem Routing kommen, denn es ist die ausgewählte Aktion, die das zu prüfende Attribut [[Authorize]] trägt; und nach der Authentifizierung, die anhand des Tokens bestimmt, wer der Benutzer ist (siehe Beispiel 25);
  • Zeile 35: die Controller und ihre per Attribut deklarierten Routen ([[Route("schedule")]] …);
  • Zeile 37: Der Server startet und wartet auf Anfragen an Port 8081.

11.8. Die Entitäten

Die EF-Core-Entitäten entsprechen den Datenbanktabellen und den [C#]-Klassen (siehe Beispiel 28). Sie bilden die [TypeORM]-Entitäten der Version [NestJS] eins zu eins nach: Die Attribute [[Table]], [[Column]], [[Key]], [[ForeignKey]] übernehmen die Rolle der Dekoratoren [@Entity], [@Column], [@PrimaryGeneratedColumn] und [@JoinColumn]. Die Datenbank wird nicht von EF Core erstellt, sondern durch das SQL-Skript [database/dbrdvmedecins2.sql]: Die Entitäten müssen lediglich die bereits vorhandenen Tabellen genau beschreiben.

11.8.1. Entities/AbstractEntity.cs

// =========================================================================
// Entities/AbstractEntity.cs
// -------------------------------------------------------------------------
// Die beiden Felder, die allen Entitäten gemeinsam sind: die Kennung [id] und die
// Versionsnummer [version] (optimistisches Sperren).
//
// Wie bei TypeORM (und @MappedSuperclass in JPA) genügt es, dass eine
// ABSTRAKTE Klasse die Elternklasse der Entitätsklassen ist: EF Core legt dafür keine Tabelle
// an, fügt aber ihre Eigenschaften zu den Tabellen der Kindklassen hinzu.
//
// Die Attribute [Key], [Column]... stammen aus dem Standard-Namespace
// System.ComponentModel.DataAnnotations: EF Core liest sie, um sein
// "Modell" aufzubauen (welche Klasse in welche Tabelle, welche Eigenschaft in
// welche Spalte kommt). Sie spielen die Rolle der Dekoratoren @PrimaryGeneratedColumn
// und @Column von TypeORM.
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

public abstract class AbstractEntity
{
    // [Key]: der Primärschlüssel. Ein Integer-Schlüssel wird konventionsgemäß
    // von der Datenbank erzeugt (Spalte AUTO_INCREMENT): EF Core liest seinen Wert nach
    // jedem INSERT zurück.
    [Key]
    [Column("id")]
    public int Id { get; set; }

    // [ConcurrencyCheck]: das optimistische Sperren. Jedes von EF
    // Core erzeugte UPDATE trägt die Bedingung "WHERE id = ... AND version = <gelesener Wert>".
    // Hat jemand die Zeile in der Zwischenzeit geändert, wird keine Zeile
    // aktualisiert und EF Core löst eine DbUpdateConcurrencyException aus.
    //
    // Unterschied zu @VersionColumn von TypeORM: EF Core INKREMENTIERT eine
    // ganzzahlige Versionsnummer NICHT von selbst. Das übernimmt unser DbContext,
    // unmittelbar vor jedem Speichern (siehe Data/RdvMedecinsDbContext.cs).
    [Column("version")]
    [ConcurrencyCheck]
    public int Version { get; set; }
}
  • Zeile 23: eine abstrakte Klasse ohne das Attribut [[Table]]: Sie entspricht keiner Tabelle, aber ihre Eigenschaften werden zu denen der Tabellen ihrer abgeleiteten Klassen hinzugefügt. Alle Entitäten der Anwendung erben von ihr und haben daher eine Kennung und eine Version;
  • Zeilen 28–30: der Primärschlüssel ([[Key]]), Spalte [id]. Per Konvention wird in EF Core ein ganzzahliger Schlüssel von der Datenbank erzeugt ([AUTO_INCREMENT]): EF Core liest seinen Wert nach jedem [INSERT] erneut ein;
  • Zeilen 40–42: die Zeilenversion für das optimistische Sperren (siehe Beispiel 28). [[ConcurrencyCheck]] fügt bei jedem [AND version = <value read>] die Bedingung [UPDATE] hinzu. Anders als [@VersionColumn] von [TypeORM] erhöht EF Core die Version nicht selbst: [DbContext] übernimmt das (siehe unten).

11.8.2. Entities/Person.cs

// =========================================================================
// Entities/Person.cs
// -------------------------------------------------------------------------
// Elternklasse (ohne Tabelle) der Entitäten [Doctor] und [Client]: eine Anrede, ein
// Nachname, ein Vorname - und das zugehörige Benutzerkonto (Spalte [user]).
//
// Eine in einer abstrakten Klasse deklarierte Beziehung wird von den
// Kindklassen genau wie die Spalten geerbt: EF Core fügt die
// Beziehung [User] daher zur Tabelle [doctors] UND zur Tabelle [clients] hinzu.
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

public abstract class Person : AbstractEntity
{
    [Column("title")]
    [MaxLength(5)]
    public string Title { get; set; } = ""; // Melle, Mme, Mr

    [Column("last_name")]
    [MaxLength(20)]
    public string LastName { get; set; } = "";

    [Column("first_name")]
    [MaxLength(20)]
    public string FirstName { get; set; } = "";

    // -----------------------------------------------------------------------
    // Die Beziehung zum Benutzerkonto in ZWEI Eigenschaften - das ist die
    // bei EF Core übliche Vorgehensweise:
    //   - UserId : der Fremdschlüssel selbst (Spalte [user]). Er kann gelesen
    //     werden, ohne den vollständigen User zu laden (TypeORM: @RelationId);
    //   - User   : die "Navigationseigenschaft", das User-Objekt selbst. Sie
    //     wird nur gefüllt, wenn sie in der Abfrage angefordert wird (.Include(...),
    //     siehe Repositories/), sonst ist sie null.
    // [ForeignKey] verknüpft die beiden. Die "Eins-zu-eins"-Natur der Beziehung
    // (Spalte [user] UNIQUE) wird in RdvMedecinsDbContext festgelegt.
    // -----------------------------------------------------------------------
    [Column("user")]
    public int UserId { get; set; }

    // "= null!": wir versprechen dem Compiler, diese Eigenschaft nur zu lesen,
    // wenn sie geladen (Include) oder zugewiesen wurde
    [ForeignKey(nameof(UserId))]
    public User User { get; set; } = null!;
}
  • Zeile 17: die Elternklasse – die ebenfalls abstrakt ist – von [Doctor] und [Client], selbst abgeleitet von [AbstractEntity]. Ärzte und Klienten haben dieselben Spalten: Sie werden nur einmal definiert;
  • Zeilen 19–29: die Anrede (Mme, Mr, Melle), der Nachname und der Vorname. [[MaxLength]] gibt die Spaltenbreite an. Diese Eigenschaften haben den Typ [string] (nicht [string?]): Sie dürfen nie auf [null] gesetzt werden, und der Compiler verlangt daher einen Anfangswert, hier die leere Zeichenkette [""];
  • Zeilen 42–43: der Fremdschlüssel zum Benutzerkonto, Spalte [user]. Die Kennung des Kontos kann gelesen werden, ohne das Konto selbst zu laden: Das tat [@RelationId] in der Version [NestJS];
  • Zeilen 47–48: die Navigationseigenschaft: das [User]-Objekt selbst. [[ForeignKey(nameof(UserId))]] gibt an, welche Eigenschaft den Fremdschlüssel enthält ([nameof(UserId)] ist gleich der Zeichenkette ["UserId"], aber der Compiler prüft, dass die Eigenschaft existiert). Eine Navigationseigenschaft wird nur gefüllt, wenn die Abfrage es verlangt ([Include]; siehe die DAO-Schicht); andernfalls ist sie [null]. Die Schreibweise [= null!] unterdrückt die Compilerwarnung: Sie garantiert, dass die Eigenschaft erst gelesen wird, nachdem sie geladen wurde. Die „Eins-zu-eins“-Natur der Beziehung wird in [DbContext] festgelegt. Eine in einer Elternklasse deklarierte Beziehung wird wie die Spalten vererbt: Die Tabellen [doctors] und [clients] haben jeweils ihre eigene Beziehung zu [users].

11.8.3. Entities/Doctor.cs

// =========================================================================
// Entities/Doctor.cs
// -------------------------------------------------------------------------
// Ein Arzt der Praxis (Tabelle [doctors]).
//
// SQL-Eindeutigkeitsbedingung: unq_doctors_first_name_last_name (zwei Ärzte
// dürfen nicht denselben Vor- und Nachnamen haben) - vom SQL-Skript angelegt,
// in der Geschäftsschicht an ihrem Namen erkannt.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("doctors")]
public class Doctor : Person
{
    // inverse (optionale) Beziehung: die Zeitfenster dieses Arztes.
    // Sie zeigt die Beziehung "1 Arzt -> mehrere Zeitfenster" in beiden
    // Richtungen; wie jede Navigation wird sie nur bei Bedarf gefüllt.
    public List<Slot> Slots { get; set; } = [];
}
  • Zeile 15: Die Klasse [Doctor] entspricht der Tabelle [doctors]. Sie erbt alle ihre Eigenschaften von [Person]. Die im Kommentar erwähnte Eindeutigkeitsbedingung [unq_doctors_first_name_last_name] wird vom SQL-Skript erstellt; die Geschäftsschicht erkennt sie an ihrem Namen (siehe Beispiel 28);
  • Zeile 21: die inverse Beziehung zu der von [Slot] zu seinem Arzt: die Zeitfenster dieses Arztes. EF Core ordnet die beiden Navigationen automatisch einander zu ([Doctor.Slots] und [Slot.Doctor]), die dieselbe Beziehung „ein Arzt, mehrere Zeitfenster“ aus jeweils einer Sicht beschreiben. Wie jede Navigation wird sie nur auf Anforderung gefüllt; die Anwendung verwendet sie tatsächlich nicht : Sie liest die Zeitfenster über die DAO-Schicht. [[]] ist ein Collection Expression: hier eine leere Liste.

11.8.4. Entities/Client.cs

// =========================================================================
// Entities/Client.cs
// -------------------------------------------------------------------------
// Achtung: [Client] bezeichnet hier einen PATIENTEN der Arztpraxis, keinen
// HTTP-Client! Es ist das Vokabular der ursprünglichen Fachdomäne, unverändert
// übernommen (Tabelle [clients]).
//
// SQL-Eindeutigkeitsbedingung: unq_clients_first_name_last_name (siehe Doctor.cs).
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("clients")]
public class Client : Person
{
}

Ein Klient, also ein Patient der Praxis (kein HTTP-Client): eine [Person] aus der Tabelle [clients] (Zeile 15), ohne zusätzliche Eigenschaften.

11.8.5. Entities/Slot.cs

// =========================================================================
// Entities/Slot.cs
// -------------------------------------------------------------------------
// Ein Zeitfenster eines Arztes (Tabelle [slots]): 8:00 - 8:20 usw.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("slots")]
public class Slot : AbstractEntity
{
    [Column("start_hour")] public int StartHour { get; set; } // Startstunde des Zeitfensters
    [Column("start_minute")] public int StartMinute { get; set; } // Startminute des Zeitfensters
    [Column("end_hour")] public int EndHour { get; set; } // Endstunde des Zeitfensters
    [Column("end_minute")] public int EndMinute { get; set; } // Endminute des Zeitfensters

    // mehrere Zeitfenster für denselben Arzt: Fremdschlüssel [doctor_id]
    // + Navigation [Doctor] (gleiche Technik wie Person.UserId / User)
    [Column("doctor_id")]
    public int DoctorId { get; set; }

    [ForeignKey(nameof(DoctorId))]
    public Doctor Doctor { get; set; } = null!;
}
  • Zeilen 14–17: die Stunde und die Minute des Beginns und des Endes des Zeitfensters. Attribut und Eigenschaft stehen in derselben Zeile: Das ist erlaubt und für diese vier ähnlichen Spalten kompakter;
  • Zeilen 21–25: die „Viele-zu-eins“-Beziehung zum Arzt: mehrere Zeitfenster für einen Arzt. Dieselbe Technik wie in [Person]: der Fremdschlüssel [DoctorId] (Spalte [doctor_id]) und der Navigationsschlüssel [Doctor], verknüpft durch [[ForeignKey]]. EF Core benötigt keine weiteren Angaben: eine Referenz auf der einen Seite, eine Liste auf der anderen – das ist eine „Eins-zu-viele“-Beziehung.

11.8.6. Entities/Appointment.cs

// =========================================================================
// Entities/Appointment.cs
// -------------------------------------------------------------------------
// Ein Termin (Tabelle [appointments]): ein Client, in einem Zeitfenster, an einem bestimmten Tag.
//
// SQL-Eindeutigkeitsbedingung: unq1_appointments (day, slot_id) - ein Zeitfenster wird pro Tag
// nur einmal gebucht. Vom SQL-Skript angelegt, in der Geschäftsschicht
// an ihrem Namen erkannt.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("appointments")]
public class Appointment : AbstractEntity
{
    // DateOnly: ein Datum OHNE Uhrzeit, das genau dem SQL-Typ
    // DATE der Spalte [day] entspricht. (Das NestJS-Projekt verwendete einen String
    // "yyyy-MM-dd": JavaScript kennt keinen Typ "Datum ohne Uhrzeit".)
    // Zwei DateOnly-Werte werden direkt verglichen: day < today...
    [Column("day")]
    public DateOnly Day { get; set; }

    [Column("client_id")]
    public int ClientId { get; set; }

    [ForeignKey(nameof(ClientId))]
    public Client Client { get; set; } = null!;

    [Column("slot_id")]
    public int SlotId { get; set; }

    [ForeignKey(nameof(SlotId))]
    public Slot Slot { get; set; } = null!;
}
  • Zeile 15: die Termintabelle. Ihre Eindeutigkeitsbedingung [unq1_appointments (day, slot_id)] stellt sicher, dass ein Zeitfenster pro Tag nur einmal reserviert wird;
  • Zeilen 22–23: der Tag des Termins. Der Typ [DateOnly] (ein Datum ohne Uhrzeit) entspricht genau dem SQL-Typ [DATE]: keine Uhrzeit, also auch keine Zeitzonenprobleme. Die [NestJS]-Version verarbeitete eine Zeichenkette vom Typ [yyyy-mm-dd], da es in [JavaScript] keinen solchen Typ gab. Zwei [DateOnly] -Werte lassen sich direkt mit [<], [>=] … vergleichen, in [C#] wie in den [LINQ]-Abfragen;
  • Zeilen 25–35: der Klient und das Zeitfenster des Termins: zwei „Viele-zu-eins“-Beziehungen, die jeweils mit einem Fremdschlüssel und einer Navigation definiert sind. Um einen Termin zu erstellen, genügt es, die Fremdschlüssel [ClientId] und [SlotId] zu füllen: Das tut die Geschäftsschicht.

11.8.7. Entities/Role.cs

// =========================================================================
// Entities/Role.cs
// -------------------------------------------------------------------------
// Die drei Rollen eines Benutzers (Spalte users.role):
//   - ADMIN  : der Administrator - Termine + Verwaltung von Ärzten und Clients;
//   - DOCTOR : ein Arzt - bucht und storniert Termine;
//   - USER   : ein Client (Patient) - bucht für sich selbst, verwaltet sein Konto.
//
// In C# eine Enumeration (enum) statt eines Union-Typs aus Strings
// ('ADMIN' | 'DOCTOR' | 'USER'): der Compiler weist jeden anderen Wert zurück.
// EF Core speichert sie in der Datenbank als TEXT ('ADMIN'...), wie es das
// SQL-Skript tut (siehe HasConversion<string>() in RdvMedecinsDbContext).
// =========================================================================

namespace RdvMedecins.Entities;

public enum Role
{
    ADMIN,
    DOCTOR,
    USER,
}
  • Zeilen 17–21: die drei Rollen in Form einer Aufzählung ([enum]): Eine Variable vom Typ [Role] kann nur die Werte [Role.ADMIN], [Role.DOCTOR] oder [Role.USER] annehmen, und der Compiler lehnt jeden anderen Wert ab. Das entspricht dem Zeichenketten-Union-Typ ['ADMIN' | 'DOCTOR' | 'USER'] der Version [NestJS]. Standardmäßig würde EF Core eine einfache Aufzählung als Zahl (0, 1, 2) speichern; die Spalte [role] enthält jedoch Text: Die Umwandlung wird in [DbContext] angefordert.

11.8.8. Entities/User.cs

// =========================================================================
// Entities/User.cs
// -------------------------------------------------------------------------
// Ein Benutzer, der sich an der Anwendung anmelden darf (Tabelle [users]).
// Jeder Arzt und jeder Client hat SEIN eigenes Benutzerkonto (Spalte [user]
// der Tabellen [doctors] und [clients], siehe Person.cs).
//
// SQL-Eindeutigkeitsbedingung: unq_users_login (ein Login gehört nur zu einem
// Konto). Sie wird vom Skript database/dbrdvmedecins2.sql angelegt;
// die Geschäftsschicht erkennt sie an ihrem NAMEN (siehe Business/BusinessService.cs).
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("users")]
public class User : AbstractEntity
{
    [Column("login")]
    [MaxLength(30)]
    public string Login { get; set; } = "";

    // das GEHASHTE Passwort (bcrypt) - nie im Klartext
    [Column("password")]
    [MaxLength(100)]
    public string Password { get; set; } = "";

    // der nach der Anmeldung angezeigte Name - bei einem Arzt oder einem Client:
    // "firstName LASTNAME" (z. B. "Marie PELISSIER")
    [Column("name")]
    [MaxLength(40)]
    public string Name { get; set; } = "";

    // ADMIN, DOCTOR oder USER, in der Datenbank als Text gespeichert
    [Column("role")]
    public Role Role { get; set; }
}
  • Zeile 18: die Konten der zur Anmeldung berechtigten Benutzer: der Administrator, jeder Arzt und jeder Klient. Die Bedingung [unq_users_login] verbietet zwei Konten mit demselben Login;
  • Zeilen 21–23: der Login;
  • Zeilen 26–28: der [bcrypt]-Hash des Passworts, nie das Passwort selbst (siehe Beispiel 25);
  • Zeilen 32–34: der nach der Anmeldung in der Navigationsleiste angezeigte Name („Marie PELISSIER“);
  • Zeilen 37–38: die Rolle vom Typ [Role]. Da die Klasse [User] keine Navigation zu dem Arzt oder Klienten deklariert, dem sie gehört, ist die Beziehung nur auf der Seite von [Person] bekannt.

11.9. Der DbContext

Der [DbContext] der Anwendung basiert auf dem aus Beispiel 28, mit fünf statt einer Tabelle und einigen Präzisierungen zum Modell, die sich mit Attributen nicht ausdrücken lassen.

11.9.1. Data/RdvMedecinsDbContext.cs

// =========================================================================
// Data/RdvMedecinsDbContext.cs
// -------------------------------------------------------------------------
// Der DbContext ist das zentrale Stück von Entity Framework Core. Er spielt
// gleichzeitig die Rolle:
//   - der DataSource von TypeORM: die Verbindung zur Datenbank;
//   - des Repository<T> von TypeORM: ein DbSet<T> pro Tabelle, das
//     mit LINQ abgefragt wird (db.Doctors.Where(...)...);
//   - einer "Unit of Work": er VERFOLGT die Entitäten, die er
//     geladen hat (Change Tracking). Wird eine Eigenschaft geändert, geht nichts
//     an die Datenbank; erst SaveChangesAsync() sendet in einem Rutsch die
//     nötigen INSERT / UPDATE / DELETE.
//
// Lebensdauer: ein DbContext pro HTTP-Anfrage (Registrierung "Scoped",
// siehe Program.cs). Alle Repositories derselben Anfrage teilen sich daher
// DENSELBEN DbContext - und folglich dieselbe Verbindung und dieselbe
// Transaktion, wenn die Geschäftsschicht eine öffnet.
//
// Das Mapping Klasse <-> Tabelle wird größtenteils durch die Attribute
// der Entitäten beschrieben ([Table], [Column], [ForeignKey]...); OnModelCreating ergänzt,
// was die Attribute nicht ausdrücken können.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Entities;

namespace RdvMedecins.Data;

public class RdvMedecinsDbContext(DbContextOptions<RdvMedecinsDbContext> options) : DbContext(options)
{
    // eine "Tabelle" pro Entität. Set<T>() gibt das DbSet zurück, das EF Core
    // für den Typ T angelegt hat.
    public DbSet<Doctor> Doctors => Set<Doctor>();
    public DbSet<Client> Clients => Set<Client>();
    public DbSet<Slot> Slots => Set<Slot>();
    public DbSet<Appointment> Appointments => Set<Appointment>();
    public DbSet<User> Users => Set<User>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // ein Arzt (ein Client) hat EIN Konto, und ein Konto gehört höchstens
        // EINER Person (Spalte [user] UNIQUE im SQL-Skript): Beziehung "Eins zu eins",
        // deren Fremdschlüssel von doctors.user
        // (clients.user) getragen wird. Ohne diese Präzisierung würde EF Core "mehrere
        // Ärzte für dasselbe Konto" annehmen - was auch funktionieren würde, aber
        // das Modell schlecht beschriebe.
        modelBuilder.Entity<Doctor>().HasOne(d => d.User).WithOne().HasForeignKey<Doctor>(d => d.UserId);
        modelBuilder.Entity<Client>().HasOne(c => c.User).WithOne().HasForeignKey<Client>(c => c.UserId);

        // die Rolle ist eine C#-Enumeration, in der Datenbank als Text gespeichert
        // ('ADMIN', 'DOCTOR', 'USER') und nicht als Zahl (0, 1, 2)
        modelBuilder.Entity<User>().Property(u => u.Role).HasConversion<string>();
    }

    // -----------------------------------------------------------------------
    // Das optimistische Sperren (siehe AbstractEntity.Version): unmittelbar vor jedem
    // Speichern inkrementieren wir die Version jeder GEÄNDERTEN Entität.
    // EF Core vergleicht den ALTEN Wert (den aus der Datenbank gelesenen) in der
    // WHERE-Klausel des UPDATE und schreibt den neuen:
    //     UPDATE doctors SET last_name = ..., version = 4 WHERE id = 1 AND version = 3
    //
    // ChangeTracker: das "Change Tracking" des DbContext. Er weiß für
    // jede geladene Entität, ob sie hinzugefügt (Added), geändert
    // (Modified), gelöscht (Deleted) oder unverändert (Unchanged) ist.
    //
    // Alle Varianten von SaveChanges(Async) münden in dieser Methode.
    // -----------------------------------------------------------------------
    public override Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess, CancellationToken cancellationToken = default)
    {
        foreach (var entry in ChangeTracker.Entries<AbstractEntity>())
        {
            if (entry.State == EntityState.Modified)
            {
                entry.Entity.Version++;
            }
        }
        return base.SaveChangesAsync(acceptAllChangesOnSuccess, cancellationToken);
    }
}

Kommentieren wir diesen Code:

  • Zeile 29: Wie in Beispiel 28 erhält der [DbContext] seine Optionen ([MySQL]-Provider, Verbindungszeichenfolge) von [AddDbContext] in [Program.cs]. Er wird mit der Lebensdauer [Scoped] registriert: ein [DbContext] pro Anfrage, den alle Repositories dieser Anfrage gemeinsam nutzen, also eine einzige Verbindung und gegebenenfalls eine einzige Transaktion. Er übernimmt damit die Rollen sowohl der [DataSource] als auch der [Repository<T>] von [TypeORM];
  • Zeilen 33–37: ein [DbSet] pro Tabelle. Für [AbstractEntity] und [Person] gibt es keines: Diese abstrakten Klassen haben keine Tabellen. EF Core nimmt sie nicht als Entitäten in das Modell auf; es fügt lediglich ihre Eigenschaften zu denen der abgeleiteten Klassen hinzu;
  • Zeile 39: [OnModelCreating] wird einmal aufgerufen, wenn EF Core sein Modell (die Beschreibung der Tabellen und Beziehungen) erstellt. Die Methode ergänzt die Entitätsattribute um eine Fluent API: eine Kette von Methodenaufrufen;
  • Zeilen 47–48: Die Beziehung zwischen einem Arzt (einem Kunden) und seinem Konto ist „eins-zu-eins“: [HasOne(d => d.User)] (ein Arzt hat ein Konto), [WithOne()] (ein Konto gehört höchstens einem Arzt; die leeren Klammern zeigen an, dass [User] keine Rückwärtsnavigation hat), [HasForeignKey<Doctor>(d => d.UserId)] (der Fremdschlüssel liegt in der Tabelle [doctors]). Ohne diese Zeilen würde EF Core eine „viele-zu-eins“-Beziehung annehmen (mehrere Ärzte für ein einziges Konto), was ebenfalls funktionieren, das Modell aber ungenau beschreiben würde: In der Datenbank ist die Spalte [user] eindeutig;
  • Zeile 52: [HasConversion<string>()] speichert die Rolle in der Datenbank als Text (['ADMIN'] ...) und wandelt sie beim Lesen wieder in [Role] um;
  • Zeilen 68–77: Die Versionsnummer jeder geänderten Entität wird unmittelbar vor dem Speichern erhöht, wie in Beispiel 28. [ChangeTracker.Entries<AbstractEntity>()] durchläuft alle verfolgten Entitäten, deren Klasse von [AbstractEntity] abgeleitet ist: Dank der gemeinsamen Elternklasse gilt diese eine Schleife für alle fünf Tabellen. Die Variante von [SaveChangesAsync] wird mit zwei Parametern neu definiert, denn diese Variante ruft letztlich [SaveChangesAsync()] ohne Parameter auf. EF Core vergleicht die alte Version in der [WHERE]-Klausel von [UPDATE] und schreibt die neue: Hat sich die Zeile in der Zwischenzeit geändert, wird keine Zeile modifiziert, und EF Core löst eine [DbUpdateConcurrencyException] aus.

11.10. Die Domäne: der Terminkalender

Der Ordner [Domain] enthält zwei Klassen, die keiner Tabelle entsprechen: Sie beschreiben den Terminkalender eines Arztes für einen einzelnen Tag, der von der Geschäftsschicht berechnet ([BusinessService.GetDoctorDayScheduleAsync]) und vom Terminkalender-Controller angezeigt wird.

11.10.1. Domain/DoctorDaySlot.cs

// =========================================================================
// Domain/DoctorDaySlot.cs
// -------------------------------------------------------------------------
// Ein "fachliches" Objekt (ohne Tabelle), das ein Zeitfenster mit dem an diesem Tag
// möglicherweise gebuchten Termin verknüpft.
//
// Ein C#-"Record" ist eine Klasse, deren Eigenschaften einmalig
// vom Konstruktor gesetzt werden (unveränderliches Objekt): genau das Richtige
// für ein berechnetes Objekt, das danach niemand ändert.
// =========================================================================

using RdvMedecins.Entities;

namespace RdvMedecins.Domain;

// Appointment? : null, wenn das Zeitfenster an diesem Tag frei ist
public record DoctorDaySlot(Slot Slot, Appointment? Appointment);
  • Zeile 17: ein Zeitfenster und der für dieses Zeitfenster an diesem Tag vereinbarte Termin, [null] wenn das Zeitfenster frei ist (daher der Typ [Appointment?]). Ein [record] , der auf diese Weise mit seinen Parametern in Klammern geschrieben wird (Positional Record), deklariert in einer einzigen Zeile eine Klasse, ihren Konstruktor und ihre Eigenschaften [Slot] und [Appointment], die nach der Konstruktion nicht mehr geändert werden können: Dies entspricht der Syntax [constructor(public slot: Slot, ...)] in der [NestJS]-Version. Records für Daten, die an die Geschäftsschicht übergeben werden, sind uns bereits begegnet (siehe Beispiel 28).

11.10.2. Domain/DoctorDaySchedule.cs

// =========================================================================
// Domain/DoctorDaySchedule.cs
// -------------------------------------------------------------------------
// Der vollständige Terminkalender eines Arztes für einen bestimmten Tag: die Liste seiner
// Zeitfenster, jeweils frei oder durch einen Termin belegt. Berechnet von
// BusinessService.GetDoctorDayScheduleAsync, von
// ScheduleController in eine HTML-Tabelle umgewandelt.
// =========================================================================

using RdvMedecins.Entities;

namespace RdvMedecins.Domain;

public record DoctorDaySchedule(Doctor Doctor, DateOnly Day, List<DoctorDaySlot> DoctorDaySlots);

Der Terminkalender (Zeile 14): ein Arzt, ein Tag und die Liste seiner freien oder gebuchten Zeitfenster in chronologischer Reihenfolge.

11.11. Die DAO-Schicht

Eine Klasse pro Tabelle, wie in Beispiel 28: kurze Methoden ohne Geschäftslogik, die die Datenbank lediglich abfragen oder ändern. Hier heißen sie „Repositories“, wie in der Version [NestJS]. Zwei Unterschiede zu dieser Version:

  • Abfragen werden in [LINQ] geschrieben, das EF Core in SQL übersetzt: Sie navigieren über Navigationseigenschaften von einer Entität zur nächsten, und EF Core schreibt die Joins selbst;
  • Die Methoden haben keinen Parameter [manager] für Transaktionen: Alle Repositories einer Anfrage nutzen denselben [DbContext], und eine Transaktion, die die Geschäftsschicht auf diesem [DbContext] öffnet, umfasst automatisch alle ihre Abfragen.

Alle Methoden sind asynchron und geben einen [Task] zurück: Der Aufrufer wartet darauf mit [await]. Viele sind in der Form [=> expression] geschrieben: Sie geben direkt den [Task] der Abfrage zurück, ohne [async] oder [await], da sie danach nichts weiter zu tun haben.

11.11.1. Repositories/PersonRepository.cs

In der Version [NestJS] waren die Repositories für Ärzte und Kunden bis auf eine einzige Zeile identisch. In [C#] schreibt eine generische Klasse sie nur einmal.

// =========================================================================
// Repositories/PersonRepository.cs
// -------------------------------------------------------------------------
// Die DAO-Schicht, die Ärzten und Clients gemeinsam ist.
//
// Die beiden DAOs des NestJS-Projekts (DoctorRepository, ClientRepository)
// waren bis auf eine Zeile identisch. In C# schreibt eine GENERISCHE Klasse sie
// nur einmal: PersonRepository<T>, wobei T Doctor oder Client ist.
// "where T : Person" garantiert, dass T LastName, FirstName, User... hat.
//
// Transaktionen: die Methoden brauchen den optionalen Parameter EntityManager
// von TypeORM nicht mehr. Alle Repositories einer Anfrage teilen sich DENSELBEN
// DbContext (siehe Data/RdvMedecinsDbContext.cs): öffnet die Geschäftsschicht
// eine Transaktion auf diesem DbContext, sind alle ihre Abfragen
// automatisch Teil davon.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public abstract class PersonRepository<T>(RdvMedecinsDbContext db) where T : Person
{
    protected readonly RdvMedecinsDbContext db = db;

    // die "Tabelle" der Personen vom Typ T (db.Doctors oder db.Clients)
    protected DbSet<T> Table => db.Set<T>();

    // nach Nachname, dann Vorname sortierte Liste, Benutzerkonto eingeschlossen.
    // Include(p => p.User): liefert ZUSÄTZLICH das Konto über einen Join
    // (SELECT ... FROM doctors INNER JOIN users ...). Ohne es wäre p.User
    // null.
    // AsNoTracking(): diese Listen werden vom Cache (Web/ApplicationModel.cs)
    // weit über die HTTP-Anfrage hinaus im Speicher gehalten: es ist unnötig
    // (und teuer), dass der DbContext sie verfolgt.
    public Task<List<T>> FindAllAsync() =>
        Table.AsNoTracking().Include(p => p.User).OrderBy(p => p.LastName).ThenBy(p => p.FirstName).ToListAsync();

    public Task<T?> FindByIdAsync(int id) =>
        Table.Include(p => p.User).FirstOrDefaultAsync(p => p.Id == id);

    // die Person, deren Benutzerkonto [userId] ist, oder null
    public Task<T?> FindByUserIdAsync(int userId) =>
        Table.Include(p => p.User).FirstOrDefaultAsync(p => p.UserId == userId);

    // die Person mit diesem Vor- und Nachnamen, falls es eine gibt. Der Vergleich
    // erfolgt durch MySQL, also mit der Kollation der Datenbank
    // (utf8mb4_unicode_ci: ohne Beachtung von Groß-/Kleinschreibung und Akzenten) -
    // genau dieselbe Regel wie bei der SQL-Eindeutigkeitsbedingung.
    public Task<T?> FindByFirstNameLastNameAsync(string firstName, string lastName) =>
        Table.FirstOrDefaultAsync(p => p.FirstName == firstName && p.LastName == lastName);

    // Anlegen (Id = 0: noch nicht in der Datenbank) oder Aktualisieren (Entität
    // bereits vom DbContext verfolgt: SaveChanges erkennt selbst, was sich geändert hat)
    public async Task<T> SaveAsync(T person)
    {
        if (person.Id == 0)
        {
            Table.Add(person);
        }
        await db.SaveChangesAsync();
        return person;
    }

    // ExecuteDeleteAsync (EF Core 7+): ein direkt an die Datenbank gesendetes DELETE,
    // ohne die Entitäten vorher zu laden:  DELETE FROM doctors WHERE id = ?
    public Task DeleteByIdAsync(int id) => Table.Where(p => p.Id == id).ExecuteDeleteAsync();
}

// die beiden konkreten DAOs: alles wird geerbt
public class DoctorRepository(RdvMedecinsDbContext db) : PersonRepository<Doctor>(db);

public class ClientRepository(RdvMedecinsDbContext db) : PersonRepository<Client>(db)
{
    // -----------------------------------------------------------------------
    // liest einen Client und setzt dabei eine SPERRE auf seine Zeile bis zum Ende der
    // aktuellen Transaktion (SELECT ... FOR UPDATE). Eine zweite Transaktion,
    // die dieselbe Sperre anfordert, WARTET, bis die erste fertig ist.
    // Verwendet beim Buchen von Terminen (siehe BusinessService.AddAppointmentAsync):
    // zwei gleichzeitige Buchungen für denselben Patienten werden so
    // eine NACH der anderen verarbeitet, und die zweite sieht den von der ersten angelegten Termin.
    //
    // LINQ kann "FOR UPDATE" nicht ausdrücken: wir schreiben die SQL-Abfrage
    // selbst. FromSqlInterpolated wandelt {id} in einen SQL-PARAMETER um (keine
    // String-Verkettung, also keine SQL-Injection möglich).
    // -----------------------------------------------------------------------
    public async Task<Client?> LockAsync(int id)
    {
        var clients = await Table.FromSqlInterpolated($"SELECT * FROM clients WHERE id = {id} FOR UPDATE").ToListAsync();
        return clients.FirstOrDefault();
    }
}

Kommentieren wir diesen Code:

  • Zeile 24: [PersonRepository<T>] ist eine generische Klasse; [T] ist ein Typparameter, der bei der Verwendung der Klasse durch einen konkreten Typ ersetzt wird ([Doctor] oder [Client]), wie [T] in [List<T>]. Die Einschränkung [where T : Person] akzeptiert für [T] nur [Person] oder ihre abgeleiteten Klassen : Der Compiler weiß dann, dass ein [T] die Eigenschaften [Id], [LastName], [FirstName], [UserId], [User] ... enthält und akzeptiert [p.LastName] in Abfragen. Die Klasse ist abstrakt: Nur ihre beiden unten aufgeführten abgeleiteten Klassen werden verwendet;
  • Zeile 26: Der Parameter [db] des primären Konstruktors ist nur innerhalb dieser Klasse sichtbar. Er wird in ein [protected]-Feld kopiert , damit die abgeleiteten Klassen ([ClientRepository]) darauf zugreifen können;
  • Zeile 29: die Tabelle der Personen des Typs [T]. [db.Set<T>()] ordnet [DbSet] diesem Typ zu: [db.Doctors] für [T = Doctor], [db.Clients] für [T = Client];
  • Zeilen 38–39: alle Personen, sortiert nach Nachname und dann nach Vorname ([OrderBy], dann [ThenBy] , um bei gleichen Nachnamen die Reihenfolge zu bestimmen). [Include(p => p.User)] lädt über einen Join auch das Konto jeder Person ([INNER JOIN users]): Ohne dies wäre [p.User] gleich [null]. Das Konto wird verwendet, um den Login in den Listen anzuzeigen. [AsNoTracking()] (siehe Beispiel 28): Diese Listen werden von [ApplicationModel] noch lange nach dem Ende der Abfrage im Speicher gehalten; der [DbContext] muss sie nicht verfolgen. Ausdrücke wie [p => p.LastName] werden nicht in [C#] ausgeführt: EF Core analysiert sie, um sie in SQL zu übersetzen ([ORDER BY last_name, first_name]);
  • Zeilen 41–42: eine Person und ihr Konto oder [null]. Hier gibt es kein [AsNoTracking()]: Die Geschäftsschicht ändert die abgerufene Person (und ihr Konto) und ruft dann [SaveAsync] auf; der [DbContext], der beide Objekte verfolgt, weiß, was sich geändert hat;
  • Zeilen 45–46: die Person, deren Konto [userId] ist. So findet ein angemeldeter Patient, dessen Token die Konto-ID enthält, seinen Kundendatensatz. Der Filter bezieht sich auf den Fremdschlüssel selbst ([WHERE clients.user = ...]); der Join mit [users] dient nur dazu, das Konto zu laden ([Include]);
  • Zeilen 52–53: ein möglicher Namensvetter. Der Operator [==] wird in den SQL-Operator [=] umgewandelt: Der Vergleich wird von [MySQL] gemäß der Kollation der Datenbank durchgeführt, ohne Beachtung von Groß- und Kleinschreibung oder Akzenten, genau wie bei der Eindeutigkeitsbedingung (siehe Beispiel 28). Ein Vergleich in [C#] würde die Großschreibung berücksichtigen;
  • Zeilen 57–64: Erstellen oder Ändern, wie in Beispiel 28: Eine neue Person ([Id] gleich 0) wird dem [DbSet] hinzugefügt; eine bereits vorhandene Person erfordert keine Aktion. Achtung: [SaveChangesAsync] schreibt alle ausstehenden Änderungen des [DbContext], nicht nur die von [person]: Das gleichzeitig geänderte Konto wird im selben Aufruf mitgespeichert;
  • Zeile 69: Löschen über [ExecuteDeleteAsync] (siehe Beispiel 28): ein [DELETE] , das direkt und ohne vorheriges Lesen an die Datenbank gesendet wird. Es durchläuft weder die Änderungsverfolgung noch folglich die optimistische Sperre;
  • Zeile 73: das Repository der Ärzte: [PersonRepository<Doctor>], sonst nichts. Es reicht den erhaltenen [DbContext] an den Konstruktor seiner Elternklasse weiter; das abschließende Semikolon ersetzt einen leeren Klassenrumpf;
  • Zeile 75: das Repository der Kunden, mit einer zusätzlichen Methode;
  • Zeilen 89–92: Lesen eines Kunden mit einer Sperre: [SELECT ... FOR UPDATE] setzt eine Sperre auf die Zeile bis zum Ende der aktuellen Transaktion; eine andere Transaktion, die dieselbe Sperre anfordert, wartet, bis die erste abgeschlossen ist. Die Methode zur Terminvereinbarung ([BusinessService.AddAppointmentAsync]) nutzt dies, um zwei gleichzeitige Reservierungen für denselben Patienten nacheinander abzuarbeiten: Die zweite Reservierung sieht den von der ersten angelegten Termin und hält damit die Regel „nur ein bevorstehender Termin“ ein. [LINQ] kann [FOR UPDATE] nicht ausdrücken: Sie müssen die SQL-Abfrage mit [FromSqlInterpolated] selbst schreiben. Die Zeichenfolge [$"..."] ist eine interpolierte Zeichenfolge; [FromSqlInterpolated] übernimmt sie nicht unverändert: Jeder in geschweifte Klammern eingeschlossene Wert ([{id}]) wird zu einem SQL-Parameter. Daher gibt es keine Zeichenfolgenverkettung, und eine SQL-Injection ist nicht möglich. Die Abfrage wird unverändert ausgeführt ([ToListAsync]), und der erste Kunde der resultierenden Liste wird ermittelt ([FirstOrDefault], im Speicher): Ein nach [LINQ] [FromSqlInterpolated] angehängter Operator würde EF Core dazu veranlassen, unser SQL in eine Unterabfrage zu verpacken.

11.11.2. Repositories/SlotRepository.cs

// =========================================================================
// Repositories/SlotRepository.cs
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Slot].
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class SlotRepository(RdvMedecinsDbContext db)
{
    public Task<Slot?> FindByIdAsync(int id) =>
        db.Slots.Include(s => s.Doctor).FirstOrDefaultAsync(s => s.Id == id);

    // die Zeitfenster eines Arztes in chronologischer Reihenfolge
    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) =>
        db.Slots
            .Where(s => s.DoctorId == doctorId)
            .OrderBy(s => s.StartHour)
            .ThenBy(s => s.StartMinute)
            .ToListAsync();

    // löscht alle Zeitfenster eines Arztes (Löschen eines Arztes):
    //   DELETE FROM slots WHERE doctor_id = ?
    public Task DeleteByDoctorAsync(int doctorId) =>
        db.Slots.Where(s => s.DoctorId == doctorId).ExecuteDeleteAsync();
}
  • Zeilen 15–16: ein Zeitfenster für Termine, mit seinem Arzt ([Include]);
  • Zeilen 19–24: die Zeitfenster eines Arztes in chronologischer Reihenfolge: [Where] filtert, [OrderBy] und [ThenBy] sortieren (nach Stunde, dann nach Startminute). Die Abfrage wird Methode für Methode aufgebaut, wie mit dem QueryBuilder von [TypeORM], und erst ausgeführt, wenn [ToListAsync] aufgerufen wird: [SELECT ... FROM slots WHERE doctor_id = @p ORDER BY start_hour, start_minute]. Der Wert [doctorId] wird ebenfalls als SQL-Parameter übergeben;
  • Zeilen 28–29: Löschen der Zeitfenster eines Arztes mit einem einzigen [DELETE]. Die Geschäftsschicht ruft es auf, bevor sie den Arzt löscht; andernfalls würde der Fremdschlüssel [slots.doctor_id] das Löschen verhindern.

11.11.3. Repositories/AppointmentRepository.cs

// =========================================================================
// Repositories/AppointmentRepository.cs
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Appointment].
//
// Die Abfragen sind in LINQ geschrieben: EF Core übersetzt sie in SQL. Wir navigieren
// über die Navigationseigenschaften von einer Entität zur anderen (a.Slot.DoctorId),
// und EF Core schreibt die nötigen Joins selbst.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class AppointmentRepository(RdvMedecinsDbContext db)
{
    public Task<Appointment?> FindByIdAsync(int id) =>
        db.Appointments.Include(a => a.Client).Include(a => a.Slot).FirstOrDefaultAsync(a => a.Id == id);

    public async Task<Appointment> SaveAsync(Appointment appointment)
    {
        if (appointment.Id == 0)
        {
            db.Appointments.Add(appointment);
        }
        await db.SaveChangesAsync();
        return appointment;
    }

    public Task DeleteByIdAsync(int id) => db.Appointments.Where(a => a.Id == id).ExecuteDeleteAsync();

    // die Termine eines Arztes an einem bestimmten Tag, Client und Zeitfenster eingeschlossen.
    // a.Slot.DoctorId: die Tabelle [appointments] verweist nicht direkt auf den
    // Arzt; EF Core geht über den Join mit [slots].
    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) =>
        db.Appointments
            .Include(a => a.Client)
            .Include(a => a.Slot)
            .Where(a => a.Slot.DoctorId == doctorId && a.Day == day)
            .ToListAsync();

    // die Termine eines Clients ab dem Tag [fromDay] (eingeschlossen), in
    // chronologischer Reihenfolge, mit dem Zeitfenster UND dem Arzt dieses Zeitfensters
    // (Include, dann ThenInclude: Termin -> Zeitfenster -> Arzt)
    public Task<List<Appointment>> FindUpcomingByClientAsync(int clientId, DateOnly fromDay) =>
        db.Appointments
            .Include(a => a.Slot).ThenInclude(s => s.Doctor)
            .Where(a => a.ClientId == clientId && a.Day >= fromDay)
            .OrderBy(a => a.Day)
            .ThenBy(a => a.Slot.StartHour)
            .ThenBy(a => a.Slot.StartMinute)
            .ToListAsync();

    // Anzahl der Termine eines Clients ab dem Tag [fromDay] (eingeschlossen)
    public Task<int> CountUpcomingByClientAsync(int clientId, DateOnly fromDay) =>
        db.Appointments.CountAsync(a => a.ClientId == clientId && a.Day >= fromDay);

    // löscht ALLE Termine (vergangene und künftige) eines Clients:
    //   DELETE FROM appointments WHERE client_id = ?
    public Task DeleteByClientAsync(int clientId) =>
        db.Appointments.Where(a => a.ClientId == clientId).ExecuteDeleteAsync();

    // Anzahl der Termine (vergangene oder künftige) eines Arztes:
    //   SELECT COUNT(*) FROM appointments INNER JOIN slots s ON ... WHERE s.doctor_id = ?
    public Task<int> CountByDoctorAsync(int doctorId) =>
        db.Appointments.CountAsync(a => a.Slot.DoctorId == doctorId);
}

Kommentieren wir diesen Code:

  • Zeilen 19–20: ein Termin mit seinem Kunden und seinem Zeitfenster: zwei [Include]-Aufrufe, also zwei Joins;
  • Zeilen 22–29: dasselbe Muster wie bei den Personen. In der Praxis wird es nur für das Erstellen verwendet: Die Geschäftsschicht erzeugt einen [Appointment], in dem nur die Fremdschlüssel gesetzt sind; nach [SaveChangesAsync] enthält [appointment.Id] den von der Datenbank vergebenen Bezeichner;
  • Zeile 32: Stornieren eines Termins;
  • Zeilen 37–42: die Termine eines Arztes an einem bestimmten Tag, jeweils mit ihrem Patienten und ihrem Zeitfenster (das Äquivalent zu [leftJoinAndSelect] in der [NestJS]-Version). Die Tabelle [appointments] verweist nicht direkt auf Ärzte: Der Filter [a.Slot.DoctorId == doctorId] läuft über die Navigation [Slot], und EF Core fügt den Join mit [slots] hinzu. Es ist wichtig, die beiden Verwendungen einer Navigation zu unterscheiden: In [Where] dient sie zum Filtern; nur [Include] lädt das Objekt in das Ergebnis;
  • Zeilen 47–54: die Termine eines Kunden ab dem Tag [fromDay], zusammen mit ihrem Zeitfenster und dem Arzt dieses Zeitfensters: [Include(a => a.Slot)] lädt das Zeitfenster, dann [ThenInclude(s => s.Doctor)] den Arzt dieses Zeitfensters (zwei verkettete Joins). Sortiert wird zuerst nach dem Tag, dann nach der Uhrzeit des Zeitfensters. Dies wird unter „Mein Bereich“ angezeigt;
  • Zeilen 57–58: die Anzahl dieser Termine ([SELECT COUNT(*)]) für die Regel „nur ein bevorstehender Termin“. [CountAsync] erfüllt die Bedingung direkt, ebenso wie [FirstOrDefaultAsync];
  • Zeilen 62–63: das Löschen aller Termine eines Kunden, vergangene wie künftige: Die Geschäftsschicht ruft dies vor dem Löschen des Kunden auf, was der Fremdschlüssel [appointments.client_id] andernfalls verhindern würde;
  • Zeilen 67–68: die Anzahl der Termine eines Arztes, um das Löschen eines Arztes zu verhindern, der welche hat. Auch hier erzeugt die Navigation [a.Slot] einen Join ([INNER JOIN slots]), ohne etwas zu laden: Das ist der [innerJoin] aus der [NestJS]-Version.

11.11.4. Repositories/UserRepository.cs

// =========================================================================
// Repositories/UserRepository.cs
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [User]. Das Anlegen (oder Löschen) eines Arztes oder
// Clients legt auch sein Konto an (oder löscht es) - siehe Business/BusinessService.cs.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class UserRepository(RdvMedecinsDbContext db)
{
    // null, wenn kein Benutzer diesen Login hat
    public Task<User?> FindByLoginAsync(string login) => db.Users.FirstOrDefaultAsync(u => u.Login == login);

    public async Task<User> SaveAsync(User user)
    {
        if (user.Id == 0)
        {
            db.Users.Add(user);
        }
        await db.SaveChangesAsync();
        return user;
    }

    public Task DeleteByIdAsync(int id) => db.Users.Where(u => u.Id == id).ExecuteDeleteAsync();
}
  • Zeile 17: das mit diesem Login verknüpfte Konto oder [null]. Es wird für die Anmeldung ([AuthService]) verwendet und um zu prüfen, ob ein Login verfügbar ist, bevor er vergeben wird;
  • Zeilen 19–26: Erstellen oder Ändern eines Kontos. Um einen Arzt oder einen Kunden anzulegen, müssen Sie zuerst sein Konto erstellen: Die Person benötigt die Konto-ID für ihren Fremdschlüssel;
  • Zeile 29: Löschen eines Kontos. Die Reihenfolge ist die Umkehrung des Erstellens: Die Geschäftsschicht löscht zuerst die Person, die auf das Konto verweist, und dann das Konto.

11.12. Die Geschäftsschicht

Die Geschäftsschicht enthält die Geschäftsregeln der Anwendung: keine Termine in der Vergangenheit, nur ein bevorstehender Termin pro Patient, eindeutige Logins und Personen sowie das Löschen eines Arztes oder eines Kunden. Zum Lesen und Schreiben stützt sie sich auf die DAO-Schicht (Ordner [Repositories]) und weiß nichts von HTML oder der Sprache der Oberfläche. Genauer gesagt handelt es sich um die Schicht [PersonsBusiness] aus Beispiel 28.

11.12.1. Business/Dates.cs

// =========================================================================
// Business/Dates.cs
// -------------------------------------------------------------------------
// Das heutige Datum. Es wird von GESCHÄFTSREGELN verwendet (keine Buchung
// in der Vergangenheit, nur ein KÜNFTIGER Termin pro Patient): es gehört daher
// in die Geschäftsschicht. Die Web-Schicht verwendet es wieder.
// =========================================================================

namespace RdvMedecins.Business;

public static class Dates
{
    // das heutige Datum in der Zeitzone des Servers
    public static DateOnly Today() => DateOnly.FromDateTime(DateTime.Now);
}
  • Zeile 11: Eine [static]-Klasse wird nicht instanziiert; sie fasst lediglich Methoden zusammen, die über den Klassennamen aufgerufen werden ([Dates.Today()]);
  • Zeile 14: das heutige Datum in der Zeitzone des Servers. [DateTime.Now] liefert Datum und Uhrzeit; [DateOnly.FromDateTime] liefert nur das Datum (der Typ [DateOnly] wurde in Beispiel 12 behandelt; dies ist das Format der Spalte [appointments.day]). Zwei [DateOnly]-Werte lassen sich direkt mit [<] oder [>=] vergleichen; die [NestJS]-Version, die [yyyy-mm-dd]-Zeichenfolgen verarbeitete, musste dieses Format selbst erzeugen. Das aktuelle Datum wird für Geschäftsregeln benötigt und liegt daher in der Geschäftsschicht; die Web-Schicht verwendet es wieder (zum Beispiel in [ScheduleController], um zu bestimmen, ob ein Tag noch buchbar ist).

11.12.2. Business/BusinessException.cs

// =========================================================================
// Business/BusinessException.cs
// -------------------------------------------------------------------------
// Die Ausnahme, die die Geschäftsschicht auslöst, wenn eine GESCHÄFTSREGEL
// verletzt wird (Login bereits vergeben, Arzt mit noch bestehenden Terminen, Zeitfenster
// bereits gebucht...). Sie trägt keinen Text, sondern einen
// Übersetzungsschlüssel (z. B. "ERRORS.LOGIN_TAKEN"): die Web-Schicht übersetzt
// ihn bei der Anzeige der Seite ins Französische oder Englische
// (siehe i18n/fr.json, i18n/en.json).
//
// Eine BusinessException ist keine Anomalie: sie ist eine normale Antwort
// ("dieser Login ist bereits vergeben"), die dem Benutzer angezeigt wird. Jede andere
// Ausnahme ist eine echte Anomalie, die auf der 500-Fehlerseite landet.
// =========================================================================

namespace RdvMedecins.Business;

public class BusinessException(string key, IReadOnlyDictionary<string, string>? messageParams = null) : Exception(key)
{
    // Übersetzungsschlüssel der Meldung
    public string Key { get; } = key;

    // mögliche Parameter der Meldung ({minutes}...)
    public IReadOnlyDictionary<string, string> Params { get; } = messageParams ?? new Dictionary<string, string>();
}
  • Zeile 18: Die Ausnahme, die ausgelöst wird, wenn eine Geschäftsregel eine Transaktion ablehnt (siehe Beispiel 28). Die Klasse verwendet einen primären Konstruktor (die Parameter [key] und [messageParams] werden nach dem Klassennamen aufgeführt); [: Exception(key)] übergibt den Schlüssel an den Konstruktor der Elternklasse [Exception], die ihn als Eigenschaft [Message] setzt (nützlich in Fehlerprotokollen). Unterschied zu Beispiel 28: Die Ausnahme trägt keinen englischen Text, sondern einen Übersetzungsschlüssel ([ERRORS.LOGIN_TAKEN]). Die Geschäftsschicht kennt die Sprache der Oberfläche also nicht: Die Web-Schicht übersetzt den Schlüssel mithilfe der Wörterbücher [i18n/fr.json] und [i18n/en.json] (siehe Kapitel 5);
  • Zeile 21: der Übersetzungsschlüssel, schreibgeschützt ([get] ohne [set]);
  • Zeile 24: etwaige Meldungsparameter, die Platzhalter wie [{minutes}] im übersetzten Text ersetzen. [IReadOnlyDictionary] ist ein schreibgeschütztes Wörterbuch. Der Operator [??] liefert ein leeres Wörterbuch, wenn keine Parameter angegeben sind: Die Web-Schicht muss nie auf [null] prüfen. Die von [BusinessService] ausgelösten Ausnahmen verwenden tatsächlich nur Schlüssel ohne Parameter.

Eine [BusinessException] ist kein Fehler: Sie ist eine normale Antwort („dieser Login ist bereits vergeben“), die die Controller abfangen, um sie dem Benutzer anzuzeigen, entweder auf der Seite oder in einer Popup-Meldung. Jede andere Ausnahme ist ein echter Fehler, der zu einer 500-Fehlerseite führt.

11.12.3. Business/IBusiness.cs

// =========================================================================
// Business/IBusiness.cs
// -------------------------------------------------------------------------
// Der Vertrag der Geschäftsschicht: Lesezugriffe, Terminkalender, Termine, Verwaltung
// der Ärzte und der Clients.
//
// .NET-Konvention: eine asynchrone Methode gibt einen Task<T> zurück (das Äquivalent
// eines Promise<T>) und ihr Name endet auf "Async".
// =========================================================================

using RdvMedecins.Domain;
using RdvMedecins.Entities;

namespace RdvMedecins.Business;

// die im Formular "Arzt" oder "Client" eingegebenen Daten
public record PersonData
{
    public required string Title { get; init; } // Mr, Mme, Melle
    public required string LastName { get; init; }
    public required string FirstName { get; init; }

    // Anlegen: optional, standardmäßig der Nachname in Kleinbuchstaben
    // Aktualisieren: optional, der Login bleibt unverändert, wenn er fehlt
    public string? Login { get; init; }

    // Anlegen: optional, standardmäßig der Login
    // Aktualisieren: optional, das Passwort bleibt unverändert, wenn es fehlt
    public string? Password { get; init; }

    // Aktualisieren: die Version des Datensatzes zum Zeitpunkt der Anzeige des
    // Formulars (optimistisches Sperren, siehe AbstractEntity.Version)
    public int? Version { get; init; }
}

public interface IBusiness
{
    // ──────────────────────────────────────────────── Lesezugriffe
    Task<List<Client>> GetAllClientsAsync();
    Task<List<Doctor>> GetAllDoctorsAsync();
    Task<List<Slot>> GetAllSlotsAsync(int doctorId);
    Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day);
    Task<Client?> GetClientByIdAsync(int id);
    Task<Doctor?> GetDoctorByIdAsync(int id);
    Task<Appointment?> GetAppointmentByIdAsync(int id);
    Task<Slot?> GetSlotByIdAsync(int id);
    Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day);

    /// <summary>der Client (Patient), dessen Benutzerkonto [userId] ist, oder null</summary>
    Task<Client?> GetClientByUserIdAsync(int userId);

    /// <summary>die Termine eines Clients, von heute oder in der Zukunft, mit Zeitfenster und Arzt</summary>
    Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId);

    // ──────────────────────────────────────────────── Termine (ADMIN, DOCTOR, USER)
    /// <summary>
    /// löst eine BusinessException aus, wenn:
    ///  - der Tag in der Vergangenheit liegt ("ERRORS.PAST_DATE");
    ///  - der Patient bereits einen künftigen Termin hat ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    ///  - das Zeitfenster an diesem Tag bereits gebucht ist ("ERRORS.SLOT_ALREADY_BOOKED").
    /// </summary>
    Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client);

    Task DeleteAppointmentAsync(Appointment appointment);

    // ──────────────────────────────────────────────── Ärzte (ADMIN)
    /// <summary>legt den Arzt UND sein Benutzerkonto an (Rolle DOCTOR)</summary>
    Task<Doctor> AddDoctorAsync(PersonData data);

    /// <summary>aktualisiert den Arzt UND sein Benutzerkonto</summary>
    Task<Doctor> EditDoctorAsync(int id, PersonData data);

    /// <summary>löscht den Arzt, seine Zeitfenster UND sein Konto - abgelehnt, wenn er Termine hat</summary>
    Task DeleteDoctorAsync(int id);

    // ──────────────────────────────────────────────── Clients
    // (der ADMIN; AddClientAsync wird auch für die Registrierung eines Patienten verwendet,
    // EditClientAsync und DeleteClientAsync vom Patienten für sein eigenes Konto)
    /// <summary>legt den Client UND sein Benutzerkonto an (Rolle USER)</summary>
    Task<Client> AddClientAsync(PersonData data);

    Task<Client> EditClientAsync(int id, PersonData data);

    /// <summary>
    /// löscht den Client, sein Konto UND alle seine Termine (vergangene und künftige).
    /// Verwendet vom ADMIN (Seite "Patients") und vom Patienten selbst ("Manage my account").
    /// </summary>
    Task DeleteClientAsync(int id);
}
  • Zeilen 17–33: Daten eines anzulegenden oder zu ändernden Arztes oder Kunden, wie sie von der Web-Schicht übermittelt werden (siehe Beispiel 28). [required] verlangt Anrede, Nachnamen und Vornamen; [init] verhindert, dass diese später geändert werden (siehe Beispiel 18). Login und Passwort sind optional ([string?]): Beim Erstellen entsprechen sie standardmäßig dem Namen in Kleinbuchstaben; beim Ändern werden sie nur geändert, wenn sie eingegeben wurden. [Version] ist die Version des Datensatzes, die beim Anzeigen des Bearbeitungsformulars gelesen wurde: Sie dient dem optimistischen Sperren (siehe unten);
  • Zeile 36: der Vertrag der Geschäftsschicht: was andere Schichten von ihr anfordern können, ohne festzulegen, wie es umgesetzt wird (Schnittstellen wurden in Beispiel 06 behandelt). Per Konvention gibt in [.NET] eine asynchrone Methode einen [Task<T>] zurück (das Äquivalent zu einem [Promise<T>] in [JavaScript]), und ihr Name endet auf [Async];
  • Zeilen 39–53: die Lesezugriffe. Ein Typ, gefolgt von [?] ([Task<Client?>]), zeigt an, dass die Methode [null] zurückgeben kann: Niemand hat diesen Bezeichner. Die Kommentare [/// <summary>] sind Dokumentationskommentare: [Visual Studio Code] zeigt sie an, wenn Sie mit der Maus über die Methode fahren;
  • Zeilen 57–64: Termine. Der Kommentar zu [AddAppointmentAsync] listet die möglichen Fehlercodes auf: Das gehört zum Vertrag, den Tester kennen müssen;
  • Zeilen 68–74: Verwaltung der Ärzte (ADMIN vorbehalten). Jeder Arzt wird zusammen mit seinem Benutzerkonto erstellt, geändert und gelöscht;
  • Zeilen 80–88: Verwaltung der Kunden, nach derselben Logik. [AddClientAsync] dient auch zur Registrierung eines Patienten, während [EditClientAsync] und [DeleteClientAsync] für Patienten gedacht sind, die ihr eigenes Konto verwalten.

Die Implementierung wird in [Program.cs] über die Zeile [builder.Services.AddScoped<IBusiness, BusinessService>()] registriert: „Wenn ein Konstruktor ein [IBusiness] anfordert, stelle ihm einen [BusinessService] bereit“, und zwar einen pro Anfrage ([Scoped]), ebenso wie den [DbContext] und die DAO-Klassen, die er verwendet (siehe Beispiel 28 und Kapitel 6). Mit [NestJS] verschwand eine [TypeScript]-Schnittstelle zur Kompilierzeit: Ein Token ([BUSINESS_TOKEN]) und [@Inject(BUSINESS_TOKEN)] waren erforderlich. In [C#] existieren die Schnittstellen zur Laufzeit: Die Schnittstelle selbst dient als Token. Der einzige Service, der ein [IBusiness] erhält, ist [ApplicationModel] (Ordner [Web]), der ebenfalls [IBusiness] implementiert: Die Controller sehen daher denselben Vertrag, angereichert um einen Cache für die Listen der Ärzte und Kunden.

11.12.4. Business/BusinessService.cs

Dies ist die umfangreichste Datei der Anwendung. Wir zeigen sie in fünf aufeinanderfolgenden Auszügen.

11.12.4.1. Die Deskriptoren

// =========================================================================
// Business/BusinessService.cs
// -------------------------------------------------------------------------
// Implementierung der Geschäftsschicht.
//
// Die Verwaltung der Ärzte und Clients folgt drei Geschäftsregeln:
//
//   1. eine Person (Arzt oder Client) und ihr Benutzerkonto gehören
//      IMMER zusammen: sie werden zusammen angelegt, aktualisiert und gelöscht, in
//      derselben TRANSAKTION - entweder gelingt alles, oder nichts wird geschrieben;
//   2. der Login ist in der gesamten Anwendung eindeutig, und zwei Ärzte (oder
//      zwei Clients) dürfen nicht denselben Vor- und Nachnamen haben;
//   3. Löschen:
//      - ein ARZT mit Terminen kann nicht gelöscht werden (seine
//        Patienten würden ihren Termin verlieren, ohne gewarnt zu werden): sie müssen
//        zuerst storniert werden. Seine Zeitfenster verschwinden mit ihm;
//      - ein CLIENT dagegen verschwindet mit ALLEN seinen Terminen (vergangenen und
//        künftigen) - ob das Löschen vom ADMIN oder vom Patienten
//        selbst kommt.
//
// Und zwei Regeln für das Buchen von Terminen, unabhängig von der Rolle
// dessen, der bucht (ADMIN, DOCTOR oder der Patient selbst):
//   4. kein Termin in der Vergangenheit;
//   5. ein Patient hat immer nur EINEN künftigen Termin.
//
// Ärzte und Clients folgen genau denselben Regeln: der gemeinsame Code
// wird EINMAL geschrieben (generische private Methoden XxxPersonAsync<T>) und
// durch einen kleinen "Deskriptor" parametrisiert, der angibt, mit welchem
// Personentyp wir es zu tun haben.
// =========================================================================

using System.Text.RegularExpressions;
using Microsoft.EntityFrameworkCore;
using MySqlConnector;
using RdvMedecins.Data;
using RdvMedecins.Domain;
using RdvMedecins.Entities;
using RdvMedecins.Repositories;

namespace RdvMedecins.Business;

public class BusinessService : IBusiness
{
    // Anzahl der bcrypt-Salting-Runden - dieselbe wie im SQL-Skript ($2b$10$...)
    private const int BcryptRounds = 10;

    // alles, was einen Arzt für die Geschäftsregeln von einem Client unterscheidet.
    // "where T : Person, new()": T ist eine Person, und wir können new T() schreiben.
    private record PersonDescriptor<T>(
        PersonRepository<T> Dao,
        Role Role, // DOCTOR oder USER
        string NotFoundKey, // Meldung, wenn die Person nicht existiert
        string AlreadyExistsKey, // Meldung, wenn derselbe Vor- und Nachname bereits existiert
        // optional: falls vorhanden, wird das Löschen ABGELEHNT, solange die
        // Person Termine hat (CountAppointments > 0), mit der Meldung HasAppointmentsKey
        Func<int, Task<int>>? CountAppointments = null,
        string? HasAppointmentsKey = null,
        // optional: was VOR der Person gelöscht werden muss (die Zeilen, die
        // sie über einen Fremdschlüssel referenzieren)
        Func<int, Task>? BeforeDelete = null) where T : Person, new();

    private readonly RdvMedecinsDbContext db;
    private readonly DoctorRepository doctorRepository;
    private readonly ClientRepository clientRepository;
    private readonly SlotRepository slotRepository;
    private readonly AppointmentRepository appointmentRepository;
    private readonly UserRepository userRepository;
    private readonly PersonDescriptor<Doctor> doctorDescriptor;
    private readonly PersonDescriptor<Client> clientDescriptor;

    // alle Abhängigkeiten werden von der Dependency Injection
    // von ASP.NET Core bereitgestellt (siehe Program.cs). Der DbContext wird hier NUR zum Öffnen
    // von Transaktionen verwendet - die Abfragen selbst bleiben in der DAO-Schicht.
    public BusinessService(
        RdvMedecinsDbContext db,
        DoctorRepository doctorRepository,
        ClientRepository clientRepository,
        SlotRepository slotRepository,
        AppointmentRepository appointmentRepository,
        UserRepository userRepository)
    {
        this.db = db;
        this.doctorRepository = doctorRepository;
        this.clientRepository = clientRepository;
        this.slotRepository = slotRepository;
        this.appointmentRepository = appointmentRepository;
        this.userRepository = userRepository;

        doctorDescriptor = new PersonDescriptor<Doctor>(
            doctorRepository,
            Role.DOCTOR,
            "ERRORS.DOCTOR_NOT_FOUND",
            "ERRORS.DOCTOR_ALREADY_EXISTS",
            CountAppointments: appointmentRepository.CountByDoctorAsync,
            HasAppointmentsKey: "ERRORS.DOCTOR_HAS_APPOINTMENTS",
            // ein Arzt ohne Termine kann noch Zeitfenster haben:
            // ohne ihn ergeben sie keinen Sinn mehr, wir löschen sie mit dem Arzt (sonst
            // würde der Fremdschlüssel slots.doctor_id das Löschen verbieten)
            BeforeDelete: slotRepository.DeleteByDoctorAsync);

        clientDescriptor = new PersonDescriptor<Client>(
            clientRepository,
            Role.USER,
            "ERRORS.PATIENT_NOT_FOUND",
            "ERRORS.PATIENT_ALREADY_EXISTS",
            // kein CountAppointments: das Löschen eines Clients wird nie abgelehnt;
            // seine Termine (vergangene und künftige) werden mit ihm gelöscht (sonst
            // würde der Fremdschlüssel appointments.client_id das Löschen verbieten)
            BeforeDelete: appointmentRepository.DeleteByClientAsync);
    }
  • Zeilen 6–29: Der Kopfkommentar fasst die fünf Geschäftsregeln zusammen, die die Klasse anwendet;
  • Zeile 34: der [MySQL]-Treiber (siehe Kapitel 9): Die Klasse verwendet seine Ausnahme [MySqlException], um Verletzungen von Eindeutigkeitsbedingungen zu erkennen;
  • Zeile 42: Die Klasse implementiert die Schnittstelle; sie muss alle ihre Methoden bereitstellen;
  • Zeile 45: der Aufwand von [bcrypt] (siehe Beispiel 25), der derselbe ist wie bei den Passwörtern im SQL-Skript (Präfix [$2b$10$]);
  • Zeilen 49–60: alles, was einen Arzt hinsichtlich der Geschäftsregeln von einem Kunden unterscheidet: ihre DAO-Klasse, die Rolle ihres Kontos ([DOCTOR] oder [USER]), ihre Fehlermeldungen und was beim Löschen geschieht. Da Ärzte und Kunden denselben Regeln folgen, wird der Code für diese Regeln nur einmal geschrieben, in generischen Methoden (parametrisiert durch einen Typ [T]), die einen Deskriptor akzeptieren. Die Einschränkung [where T : Person, new()] verlangt, dass [T] von [Person] erbt (wir könnten [LastName], [FirstName], [User] ... lesen) und einen parameterlosen Konstruktor hat (wir könnten [new T()] schreiben). [Func<int, Task<int>>] ist der Typ einer Funktion, die einen [int] entgegennimmt und einen [Task<int>] zurückgibt; [Func<int, Task>] ist der Typ einer asynchronen Funktion, die nichts zurückgibt. Diese Parameter haben einen Standardwert ([= null]): Sie sind optional;
  • Zeilen 62–69: die Felder der Klasse: der [DbContext], die fünf DAO-Klassen und die beiden Deskriptoren. [readonly] verhindert, dass sie nach dem Konstruktor geändert werden;
  • Zeilen 74–87: Alle Abhängigkeiten werden per Dependency Injection bereitgestellt. Der [DbContext] dient hier nur zum Öffnen von Transaktionen: Die Abfragen verbleiben in der DAO-Schicht. Wie in Beispiel 28 erhalten die DAO-Klassen und die Geschäftsschicht während einer Anfrage den selben [DbContext] und somit dieselbe Verbindung und dieselbe Transaktion;
  • Zeilen 89–99: der Deskriptor der Ärzte. Die benannten Argumente ([CountAppointments:], [HasAppointmentsKey:] ...) bezeichnen einen Parameter über seinen Namen, wodurch optionale Parameter übersprungen werden können (der weiter unten stehende Deskriptor der Kunden lässt so [CountAppointments] und [HasAppointmentsKey] weg). [appointmentRepository.CountByDoctorAsync] wird hier nicht aufgerufen: Die Methode selbst wird übergeben und erst später aufgerufen (eine Methode kann somit als Wert vom Typ [Func] dienen). Das Löschen eines Arztes wird abgelehnt, solange er Termine hat; seine Zeitfenster werden dagegen vor dem Löschen des Arztes gelöscht;
  • Zeilen 101–109: der Deskriptor der Kunden. Kein [CountAppointments]: Das Löschen eines Kunden wird nie abgelehnt, und seine Termine (vergangene und künftige) werden vor dem Kunden selbst gelöscht; andernfalls würde der Fremdschlüssel [appointments.client_id] das Löschen verhindern.

11.12.4.2. Lesezugriffe und Terminkalender

    // =======================================================================
    // Lesezugriffe
    // =======================================================================

    public Task<List<Client>> GetAllClientsAsync() => clientRepository.FindAllAsync();

    public Task<List<Doctor>> GetAllDoctorsAsync() => doctorRepository.FindAllAsync();

    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) => slotRepository.GetAllSlotsAsync(doctorId);

    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) =>
        appointmentRepository.GetDoctorDayAppointmentsAsync(doctorId, day);

    public Task<Client?> GetClientByIdAsync(int id) => clientRepository.FindByIdAsync(id);

    public Task<Doctor?> GetDoctorByIdAsync(int id) => doctorRepository.FindByIdAsync(id);

    public Task<Appointment?> GetAppointmentByIdAsync(int id) => appointmentRepository.FindByIdAsync(id);

    public Task<Slot?> GetSlotByIdAsync(int id) => slotRepository.FindByIdAsync(id);

    public Task<Client?> GetClientByUserIdAsync(int userId) => clientRepository.FindByUserIdAsync(userId);

    public Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId) =>
        appointmentRepository.FindUpcomingByClientAsync(clientId, Dates.Today());

    // derselbe Algorithmus wie beim JSON-Server (und beim ursprünglichen Spring-Projekt)
    public async Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day)
    {
        var doctor = await GetDoctorByIdAsync(doctorId);
        if (doctor is null)
        {
            return null;
        }
        var timeSlots = await GetAllSlotsAsync(doctorId);
        var bookings = await GetDoctorDayAppointmentsAsync(doctorId, day);
        // Nr. des Zeitfensters -> in diesem Zeitfenster gebuchter Termin
        var bookingsBySlot = bookings.ToDictionary(booking => booking.SlotId);
        var doctorDaySlots = timeSlots
            .Select(slot => new DoctorDaySlot(slot, bookingsBySlot.GetValueOrDefault(slot.Id)))
            .ToList();
        return new DoctorDaySchedule(doctor, day, doctorDaySlots);
    }
  • Zeilen 5–22: Die Lesezugriffe delegieren einfach an die DAO-Schicht. Die Syntax [=> expression] (ein Ausdruckskörper) ersetzt einen [{ return expression; }]-Block. Diese Methoden sind nicht [async]: Sie geben direkt den [Task] der DAO-Schicht zurück, ohne darauf zu warten;
  • Zeilen 24–25: die bevorstehenden Termine eines Patienten: Die Geschäftsschicht übergibt der DAO-Schicht das aktuelle Datum;
  • Zeilen 28–42: Berechnung des Terminkalenders eines Arztes für einen bestimmten Tag, nach demselben Algorithmus wie in der [NestJS]-Version. Ein unbekannter Arzt ergibt [null]; andernfalls werden die Zeitfenster und die Termine des Arztes für den Tag gelesen;
  • Zeile 38: [ToDictionary] speichert die Termine in einem Wörterbuch, dessen Schlüssel die Slot-ID ist (entspricht [Map] in der [NestJS]-Version). Das Wörterbuch erspart es, für jedes Zeitfenster die Terminliste zu durchsuchen;
  • Zeilen 39–41: Jedes Zeitfenster wird mit seinem Termin verknüpft oder mit [null] ([GetValueOrDefault] liefert den Standardwert [null], wenn der Schlüssel fehlt). [Select] transformiert jedes Element einer Liste (siehe [LINQ], Kapitel 9). Das Ergebnis ist ein [DoctorDaySchedule]-Objekt im Ordner [Domain], das die Kalenderansicht anzeigen wird.

11.12.4.3. Einen Termin vereinbaren

    // =======================================================================
    // Termine
    // =======================================================================

    // -----------------------------------------------------------------------
    // Buchung eines Termins in einer Transaktion:
    //   1. kein Termin in der Vergangenheit;
    //   2. wir SPERREN die Zeile des Patienten (SELECT ... FOR UPDATE): bucht
    //      derselbe Patient im selben Augenblick zwei Zeitfenster (zwei Tabs,
    //      Doppelklick...), wartet die zweite Transaktion auf das Ende der
    //      ersten - und sieht dann den Termin, den diese gerade angelegt hat;
    //   3. nur ein künftiger Termin pro Patient;
    //   4. schließlich das Einfügen. Wurde das Zeitfenster gerade von einem ANDEREN
    //      Patienten belegt, so ist es die SQL-Bedingung unq1_appointments (day, slot_id), die
    //      das Einfügen abweist - von TransactionAsync in eine BusinessException übersetzt.
    // -----------------------------------------------------------------------
    public Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client) =>
        TransactionAsync(async () =>
        {
            var today = Dates.Today();
            if (day < today)
            {
                throw new BusinessException("ERRORS.PAST_DATE");
            }
            if (await clientRepository.LockAsync(client.Id) is null)
            {
                throw new BusinessException("ERRORS.PATIENT_NOT_FOUND");
            }
            if (await appointmentRepository.CountUpcomingByClientAsync(client.Id, today) > 0)
            {
                throw new BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
            }
            // wir füllen die Fremdschlüssel: die Objekte Slot und Client selbst müssen nicht
            // angehängt werden, um die Zeile [appointments] zu schreiben
            var appointment = new Appointment { Day = day, SlotId = slot.Id, ClientId = client.Id };
            return await appointmentRepository.SaveAsync(appointment);
        });

    public Task DeleteAppointmentAsync(Appointment appointment) => appointmentRepository.DeleteByIdAsync(appointment.Id);
  • Zeilen 17–18: Die gesamte Buchung findet innerhalb einer einzigen Transaktion statt: Die Methode übergibt eine asynchrone anonyme Funktion, [async () => { ... }], an [TransactionAsync] (siehe unten), die die Aufgabe ausführt;
  • Zeilen 20–23: keine Termine in der Vergangenheit. Die Regel wird hier unabhängig von der Rolle der buchenden Person (ADMIN, DOCTOR oder Patient) geprüft, auch wenn die Web-Schicht die Schaltflächen „Buchen“ für vergangene Daten bereits ausgeblendet hat: Eine Anfrage kann manuell erstellt werden;
  • Zeilen 25–27: Der Datensatz des Patienten wird gesperrt: [LockAsync] führt [SELECT * FROM clients WHERE id = ... FOR UPDATE] aus (siehe [Repositories/PersonRepository.cs]). Dies ist eine pessimistische Sperre: Sie wird erworben, bevor die Verarbeitung beginnt, in der Annahme eines möglichen Konflikts, und bleibt bis zum Ende der Transaktion bestehen. Ohne sie könnten zwei zeitgleich gesendete Reservierungen für denselben Patienten (zwei Tabs, ein Doppelklick) beide den folgenden Test bestehen, bevor eine von ihnen ihren Termin in die Datenbank geschrieben hat. Mit dieser Sperre wartet die zweite Transaktion, bis die erste fertig ist, und sieht dann den von ihr angelegten Termin. Ein nicht auffindbarer Patient (in der Zwischenzeit gelöscht) wird abgelehnt;
  • Zeilen 29–31: nur ein bevorstehender Termin pro Patient;
  • Zeilen 35–36: das Einfügen. Nur die Fremdschlüssel [SlotId] und [ClientId] werden angegeben: Die Objekte [Slot] und [Client] müssen nicht verknüpft werden, um die Zeile [appointments] zu schreiben. Wenn ein anderer Patient soeben dasselbe Zeitfenster gebucht hat, hat die Sperre dies nicht verhindert (die Sperre gilt für die Zeile des Patienten): Es ist die Eindeutigkeitsbedingung [unq1_appointments (day, slot_id)] der Datenbank, die das Einfügen ablehnt, und [TransactionAsync] übersetzt den Fehler in eine [BusinessException] mit dem Schlüssel [ERRORS.SLOT_ALREADY_BOOKED];
  • Zeile 39: Stornierung eines Termins: ein einfaches [DELETE] ohne besondere Regeln.

11.12.4.4. Ärzte und Kunden verwalten

    // =======================================================================
    // Ärzte und Clients - die öffentlichen Methoden delegieren an die gemeinsamen
    // privaten Methoden, mit dem passenden Deskriptor
    // =======================================================================

    public Task<Doctor> AddDoctorAsync(PersonData data) => AddPersonAsync(doctorDescriptor, data);

    public Task<Doctor> EditDoctorAsync(int id, PersonData data) =>
        EditPersonAsync(doctorDescriptor, id, data);

    public Task DeleteDoctorAsync(int id) => DeletePersonAsync(doctorDescriptor, id);

    public Task<Client> AddClientAsync(PersonData data) => AddPersonAsync(clientDescriptor, data);

    public Task<Client> EditClientAsync(int id, PersonData data) =>
        EditPersonAsync(clientDescriptor, id, data);

    // der Client, sein Konto UND alle seine Termine (ADMIN oder der Patient
    // selbst über "Manage my account": gleiche Methode, gleiche Regel)
    public Task DeleteClientAsync(int id) => DeletePersonAsync(clientDescriptor, id);

    // -----------------------------------------------------------------------
    // Anlegen: zuerst das Benutzerkonto (die Person referenziert es),
    // dann die Person - alles in EINER Transaktion.
    // -----------------------------------------------------------------------
    private Task<T> AddPersonAsync<T>(PersonDescriptor<T> d, PersonData data) where T : Person, new()
    {
        var lastName = data.LastName.Trim().ToUpperInvariant();
        var firstName = data.FirstName.Trim();
        // die Regeln der Datenbank dbrdvmedecins2: Login = Nachname in Kleinbuchstaben,
        // Passwort = Login - es sei denn, der ADMIN hat andere eingegeben
        var login = (string.IsNullOrEmpty(data.Login) ? lastName : data.Login).ToLowerInvariant();
        var password = string.IsNullOrEmpty(data.Password) ? login : data.Password;

        return TransactionAsync(async () =>
        {
            await CheckPersonUniqueAsync(d, firstName, lastName, null);
            await CheckLoginFreeAsync(login);

            var user = new User
            {
                Login = login,
                Password = BCrypt.Net.BCrypt.HashPassword(password, BcryptRounds),
                Name = $"{firstName} {lastName}",
                Role = d.Role,
            };
            await userRepository.SaveAsync(user);

            var person = new T { Title = data.Title, LastName = lastName, FirstName = firstName, User = user };
            return await d.Dao.SaveAsync(person);
        });
    }

    // -----------------------------------------------------------------------
    // Aktualisieren: die Person UND ihr Konto (der Anzeigename "firstName LASTNAME"
    // muss mitziehen; Login und Passwort ändern sich nur, wenn sie
    // eingegeben wurden).
    // -----------------------------------------------------------------------
    private Task<T> EditPersonAsync<T>(PersonDescriptor<T> d, int id, PersonData data)
        where T : Person, new() =>
        TransactionAsync(async () =>
        {
            var person = await d.Dao.FindByIdAsync(id) ?? throw new BusinessException(d.NotFoundKey);

            // optimistisches Sperren: entspricht die Version in der Datenbank nicht mehr der des
            // Formulars, hat jemand diesen Datensatz in der Zwischenzeit geändert - wir lehnen ab,
            // statt seine Änderungen stillschweigend zu überschreiben.
            // (Erfolgt die gleichzeitige Änderung NACH diesem Lesen, so erkennt es
            // die Klausel "WHERE version = ..." des UPDATE.)
            if (data.Version is not null && data.Version != person.Version)
            {
                throw new BusinessException("ERRORS.CONCURRENT_UPDATE");
            }

            // wir ändern lediglich die Objekte: der DbContext, der sie verfolgt,
            // sendet beim nächsten SaveChangesAsync die nötigen UPDATEs
            person.Title = data.Title;
            person.LastName = data.LastName.Trim().ToUpperInvariant();
            person.FirstName = data.FirstName.Trim();
            await CheckPersonUniqueAsync(d, person.FirstName, person.LastName, id);

            var user = person.User;
            user.Name = $"{person.FirstName} {person.LastName}";
            if (!string.IsNullOrEmpty(data.Login) && data.Login.ToLowerInvariant() != user.Login)
            {
                var login = data.Login.ToLowerInvariant();
                await CheckLoginFreeAsync(login);
                user.Login = login;
            }
            if (!string.IsNullOrEmpty(data.Password))
            {
                user.Password = BCrypt.Net.BCrypt.HashPassword(data.Password, BcryptRounds);
            }
            await userRepository.SaveAsync(user);
            return await d.Dao.SaveAsync(person);
        });

    // -----------------------------------------------------------------------
    // Löschen in EINER Transaktion, in der durch die Fremdschlüssel
    // vorgegebenen Reihenfolge:
    //   1. mögliche Ablehnung, wenn noch Termine bestehen (Arzt);
    //   2. was die Person referenziert (Zeitfenster eines Arztes, Termine
    //      eines Clients);
    //   3. die Person (sie referenziert ihr Konto);
    //   4. ihr Konto.
    // -----------------------------------------------------------------------
    private Task DeletePersonAsync<T>(PersonDescriptor<T> d, int id) where T : Person, new() =>
        TransactionAsync(async () =>
        {
            var person = await d.Dao.FindByIdAsync(id) ?? throw new BusinessException(d.NotFoundKey);
            if (d.CountAppointments is not null && await d.CountAppointments(id) > 0)
            {
                throw new BusinessException(d.HasAppointmentsKey ?? "ERRORS.INVALID_FORM");
            }
            if (d.BeforeDelete is not null)
            {
                await d.BeforeDelete(id);
            }
            await d.Dao.DeleteByIdAsync(id);
            await userRepository.DeleteByIdAsync(person.UserId);
            return true; // TransactionAsync erwartet ein Ergebnis: wir brauchen hier keines
        });

    // lehnt Vor- und Nachnamen ab, die bereits von einer ANDEREN Person desselben Typs verwendet werden
    // (currentId: die Person, die gerade aktualisiert wird und selbstverständlich
    // ihren eigenen Vor- und Nachnamen behalten darf; null beim Anlegen)
    private static async Task CheckPersonUniqueAsync<T>(PersonDescriptor<T> d, string firstName, string lastName, int? currentId)
        where T : Person, new()
    {
        var namesake = await d.Dao.FindByFirstNameLastNameAsync(firstName, lastName);
        if (namesake is not null && namesake.Id != currentId)
        {
            throw new BusinessException(d.AlreadyExistsKey);
        }
    }

    private async Task CheckLoginFreeAsync(string login)
    {
        if (await userRepository.FindByLoginAsync(login) is not null)
        {
            throw new BusinessException("ERRORS.LOGIN_TAKEN");
        }
    }
  • Zeilen 6–20: Die sechs öffentlichen Methoden delegieren mit dem jeweils passenden Deskriptor an die drei privaten generischen Methoden. Der Compiler leitet [T] aus dem Deskriptor ab: [Doctor] für [doctorDescriptor], [Client] für [clientDescriptor];
  • Zeilen 26–50: Erstellen einer Person und ihres Kontos;
  • Zeilen 28–33: Datenaufbereitung außerhalb einer Transaktion. [Trim] entfernt führende und nachgestellte Leerzeichen aus der Zeichenfolge; der Nachname wird großgeschrieben. Standardmäßig ist der Login gleich dem Namen und immer in Kleinbuchstaben; standardmäßig ist das Passwort gleich dem Login: Dies sind die Kontoregeln des SQL-Skripts;
  • Zeilen 37–38: innerhalb der Transaktion die beiden Eindeutigkeitsregeln: keine doppelten Namen und ein frei wählbarer Login. Sie werden vor dem Schreiben in die Datenbank geprüft, um eine klare Meldung zu liefern (siehe Beispiel 28);
  • Zeilen 40–47: Das Benutzerkonto wird zuerst erstellt, da die Person darauf verweist (Fremdschlüssel). Das Passwort wird nie im Klartext gespeichert: [BCrypt.Net.BCrypt.HashPassword] berechnet seinen Hash (siehe Beispiel 25). [$"{firstName} {lastName}"] ist eine interpolierte Zeichenfolge: der angezeigte Name des Kontos;
  • Zeilen 49–50: Anschließend erzeugt die Person aufgrund der Einschränkung [new()] mit [new T] entweder einen [Doctor] oder einen [Client]. Schlägt dieser zweite Schreibvorgang fehl, macht die Transaktion auch den ersten rückgängig: Ein Konto kann nie ohne Person existieren;
  • Zeilen 59–95: Ändern der Person und ihres Kontos in einer einzigen Transaktion;
  • Zeile 63: Eine nicht gefundene Person ist eine [BusinessException] mit dem Schlüssel des Deskriptors. [?? throw] wurde in Beispiel 28 behandelt;
  • Zeilen 70–72: die optimistische Sperre (siehe Beispiel 28): Das Formular hat die Version des beim Anzeigen gelesenen Datensatzes mitgeführt; weicht die Version in der Datenbank ab, hat in der Zwischenzeit jemand den Datensatz geändert, und das System lehnt die Aktualisierung ab, statt dessen Arbeit stillschweigend zu überschreiben. Anders als bei der pessimistischen Sperre für Reservierungen wird nichts blockiert: Wir gehen davon aus, dass Konflikte selten sind, und erkennen sie lediglich. Erfolgt die gleichzeitige Änderung nach diesem Lesevorgang, erkennt sie die Bedingung [WHERE version = ...] des [UPDATE] (siehe [TranslateDatabaseError], unten);
  • Zeilen 77–80: Das gelesene Objekt wird einfach geändert: Der [DbContext] sendet beim nächsten [SaveChangesAsync] das nötige [UPDATE]. Die Namensprüfung übermittelt den Bezeichner der Person: Sie darf selbstverständlich ihren eigenen Vor- und Nachnamen behalten;
  • Zeilen 82–88: Das Konto folgt der Person (Navigationseigenschaft [User], von der DAO-Schicht geladen): Sein angezeigter Name wird neu berechnet. Der Login ändert sich nur, wenn er eingegeben wurde und vom aktuellen abweicht; in diesem Fall muss er verfügbar sein;
  • Zeilen 90–92: Das Passwort ändert sich nur, wenn es eingegeben wurde; es wird dann gehasht;
  • Zeilen 94–95: Speichern des Kontos und der Person. Unser [DbContext] erhöht die Versionsnummer jeder geänderten Entität (siehe [Data/RdvMedecinsDbContext.cs]);
  • Zeilen 107–121: Löschen innerhalb einer einzigen Transaktion, in der von den Fremdschlüsseln vorgegebenen Reihenfolge;
  • Zeilen 111–113: mögliche Ablehnung: Ein Arzt mit geplanten Terminen kann nicht gelöscht werden (seine Patienten würden ihre Termine verlieren, ohne benachrichtigt zu werden). [d.CountAppointments(id)] ruft die im Deskriptor gespeicherte Funktion auf;
  • Zeilen 115–117: Löschen dessen, was auf die Person verweist: die Zeitfenster eines Arztes, die Termine eines Kunden;
  • Zeilen 119–120: die Person, dann ihr Konto, auf das die Person verwies;
  • Zeile 121: [TransactionAsync] erwartet eine Funktion, die ein Ergebnis zurückgibt: Es wird eines zurückgegeben, aber niemand wird es verwenden;
  • Zeilen 127–133: Ein Namensvetter wird abgelehnt, es sei denn, es handelt sich um die Person, die gerade bearbeitet wird ([currentId], [null] bei einer Neuanlage). Die Methode ist [static]: Sie verwendet keine Felder des Objekts;
  • Zeilen 137–141: Ein bereits verwendeter Login – von einem Arzt, einem Kunden oder dem Administrator – wird abgelehnt.

11.12.4.5. Transaktionen und Eindeutigkeitsbedingungen

    // -----------------------------------------------------------------------
    // führt [work] in einer Transaktion aus:
    //   BeginTransactionAsync -> START TRANSACTION;
    //   CommitAsync            -> COMMIT, wenn alles gut gegangen ist;
    //   wird eine Ausnahme ausgelöst (auch BusinessException), committen wir nicht:
    //   "await using" schließt die Transaktion beim Verlassen des Blocks, und eine
    //   ohne COMMIT geschlossene Transaktion wird abgebrochen (ROLLBACK).
    //
    // Die Prüfungen "Login frei" und "eindeutiger Vor- und Nachname" erfolgen VOR
    // dem Schreiben, um eine klare Meldung zu geben. Aber zwei ADMINs könnten
    // im selben Augenblick denselben Login (oder denselben Arzt) speichern: in diesem
    // seltenen Fall lehnt eine SQL-Eindeutigkeitsbedingung den zweiten
    // Schreibvorgang ab - diesen SQL-Fehler übersetzen wir dann in dieselbe BusinessException.
    // -----------------------------------------------------------------------
    private async Task<R> TransactionAsync<R>(Func<Task<R>> work)
    {
        await using var transaction = await db.Database.BeginTransactionAsync();
        try
        {
            var result = await work();
            await transaction.CommitAsync();
            return result;
        }
        catch (Exception e)
        {
            // bei einem Fehler "vergisst" der DbContext alles, was er verfolgte: eine
            // im Zustand Added belassene Entität würde sonst beim nächsten
            // SaveChangesAsync derselben Anfrage erneut an die Datenbank gesendet
            db.ChangeTracker.Clear();
            if (TranslateDatabaseError(e) is { } businessError)
            {
                throw businessError;
            }
            throw; // "throw;" wirft die ursprüngliche Ausnahme erneut, mit intaktem Aufrufstapel
        }
    }

    // -----------------------------------------------------------------------
    // Datenbankfehler -> BusinessException
    //
    // - DbUpdateConcurrencyException: das UPDATE "WHERE id = ... AND version = ..."
    //   hat keine Zeile geändert (optimistisches Sperren, siehe AbstractEntity);
    // - DbUpdateException, deren Ursache (InnerException) der MySQL-Fehler
    //   ER_DUP_ENTRY (Nr. 1062) ist: eine UNIQUE-Bedingung hat das Schreiben abgewiesen. Ihre
    //   Meldung zitiert den NAMEN der Bedingung:
    //     Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name'
    //   (MySQL 8 stellt dem Namen den der Tabelle voran, MariaDB nicht). Deshalb
    //   BENENNT das SQL-Skript alle seine Bedingungen.
    // Jeder andere Fehler ist eine echte Anomalie: wir geben null zurück (nicht übersetzt).
    // -----------------------------------------------------------------------
    private static readonly Dictionary<string, string> ConstraintMessages = new()
    {
        ["unq_users_login"] = "ERRORS.LOGIN_TAKEN",
        ["unq_doctors_first_name_last_name"] = "ERRORS.DOCTOR_ALREADY_EXISTS",
        ["unq_clients_first_name_last_name"] = "ERRORS.PATIENT_ALREADY_EXISTS",
        ["unq1_appointments"] = "ERRORS.SLOT_ALREADY_BOOKED",
    };

    private static BusinessException? TranslateDatabaseError(Exception e)
    {
        // Achtung auf die Reihenfolge: DbUpdateConcurrencyException erbt von DbUpdateException
        if (e is DbUpdateConcurrencyException)
        {
            return new BusinessException("ERRORS.CONCURRENT_UPDATE");
        }
        // "Pattern Matching": ist e eine DbUpdateException,
        // deren InnerException eine MySqlException mit dem Code DuplicateKeyEntry ist?
        if (e is DbUpdateException { InnerException: MySqlException { ErrorCode: MySqlErrorCode.DuplicateKeyEntry } sqlError })
        {
            // "... for key 'doctors.unq_doctors_first_name_last_name'" -> "unq_doctors_first_name_last_name"
            var match = Regex.Match(sqlError.Message, @"for key '(?:[^'.]*\.)?([^']+)'");
            if (match.Success && ConstraintMessages.TryGetValue(match.Groups[1].Value, out var key))
            {
                return new BusinessException(key);
            }
        }
        return null;
    }
}
  • Zeile 15: Alle mehrstufigen Schreibvorgänge laufen über diese generische Methode: [R] ist der Typ des Ergebnisses der Operation ([Appointment], [Doctor], [Client], [bool]), und [Func<Task<R>>] ist der Typ einer parameterlosen asynchronen Funktion, die ein [R] zurückgibt. Dies ist die erweiterte Methode [TransactionAsync] aus Beispiel 28;
  • Zeile 17: [BeginTransactionAsync] öffnet eine Transaktion ([START TRANSACTION]). [await using var] deklariert eine Variable, die beim Verlassen des umgebenden Blocks automatisch geschlossen wird, egal was geschieht (normales Ende oder Ausnahme); die Variante [await] ermöglicht das asynchrone Schließen. Eine Transaktion, die geschlossen wird, ohne bestätigt worden zu sein, wird zurückgerollt ([ROLLBACK]);
  • Zeilen 20–22: Die Aufgabe wird ausgeführt; gelingt sie, bestätigt [CommitAsync] die Transaktion ([COMMIT]). Wird eine Ausnahme ausgelöst – auch eine [BusinessException] – [CommitAsync] wird nie erreicht: Alles, was geschrieben wurde, wird zurückgerollt;
  • Zeile 24: Beispiel 28 fing zwei bestimmte Ausnahmetypen ab; hier fangen wir alle Ausnahmen ab, um aufzuräumen, bevor wir sie erneut auslösen;
  • Zeile 29: das Aufräumen. Die Datenbank hat alles zurückgerollt, aber der [DbContext] verfolgt weiterhin Entitäten, die nichts mehr entsprechen: Zum Beispiel bleibt der Arzt, dessen Einfügen fehlgeschlagen ist, im Zustand [Added]. Da der [DbContext] während der gesamten Anfrage bestehen bleibt, würde er beim nächsten [SaveChangesAsync] dieser Anfrage erneut an die Datenbank gesendet. [ChangeTracker.Clear()] veranlasst den [DbContext], alle Entitäten zu vergessen, die er verfolgt hat;
  • Zeilen 30–32: Handelt es sich um einen bekannten Datenbankfehler, wird stattdessen die entsprechende [BusinessException] ausgelöst. [is { } businessError] ist ein Musterfilter: Er prüft, dass der Wert nicht [null] ist, und speichert ihn in der Variablen [businessError];
  • Zeile 34: Andernfalls wird die ursprüngliche Ausnahme unverändert erneut ausgelöst. [throw;] allein, innerhalb eines [catch], lässt den Aufrufstapel unangetastet (der angibt, wo der Fehler aufgetreten ist), während [throw e;] ihn zurücksetzen würde. Eine vom Auftrag ausgelöste [BusinessException] wird so unverändert an den Controller weitergereicht; jeder andere Fehler ist eine Anomalie, die eine 500-Fehlerseite erzeugt;
  • Zeilen 51–56: für jede benannte Eindeutigkeitsbedingung des SQL-Skripts ihr Übersetzungsschlüssel. Deshalb benennt das SQL-Skript alle seine Bedingungen. [new()] ohne Typnamen ist erlaubt, wenn der Typ links bereits angegeben ist; [["key"] = value] füllt das Wörterbuch;
  • Zeilen 59–77: Übersetzung eines Datenbankfehlers in eine [BusinessException] oder in [null] , wenn der Fehler nicht erkannt wird;
  • Zeilen 62–64: [UPDATE ... WHERE id = ... AND version = ...] hat keine Zeile geändert: EF Core löst eine [DbUpdateConcurrencyException] aus (optimistische Sperre; siehe Beispiel 28). Dieser Test steht an erster Stelle, weil [DbUpdateConcurrencyException] von [DbUpdateException] erbt: Stünde er weiter hinten, hätte der folgende Test sie abgefangen;
  • Zeile 68: eine Verletzung einer Eindeutigkeitsbedingung. Der [MySQL]-Fehler (Code [DuplicateKeyEntry], Nr. 1062) tritt verschachtelt in einer [DbUpdateException] auf, in deren Eigenschaft [InnerException]. Der Musterfilter prüft alles in einem einzigen Ausdruck auf zwei Ebenen: [e] ist eine [DbUpdateException], deren [InnerException] eine [MySqlException] ist, die einen [ErrorCode] hat, der [DuplicateKeyEntry] entspricht; diese [MySqlException] wird in [sqlError] abgelegt. Die [NestJS]-Version testete außerdem den Code [ER_DUP_ENTRY] eines [QueryFailedError];
  • Zeile 71: Die Fehlermeldung nennt den Namen der Bedingung, zum Beispiel [Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name']. Der reguläre Ausdruck extrahiert ihn: [(?:[^'.]*\.)?] überspringt das optionale Präfix [doctors.] (das von [MySQL] 8 geschrieben wird, nicht von [MariaDB]), und die Gruppe [([^']+)] erfasst den Namen bis zum Apostroph. Das [@] am Anfang der Zeichenfolge macht sie zu einer Verbatim-Zeichenfolge, in der [\] kein Escape-Zeichen ist;
  • Zeilen 72–74: Wurde der Name gefunden und ist er im Wörterbuch aufgeführt, speichert [TryGetValue] den Übersetzungsschlüssel in [key], und der Fehler wird zu einer [BusinessException]. Jeder andere Fehler, auch die Verletzung einer nicht im Wörterbuch enthaltenen Bedingung, bleibt unübersetzt: Das ist eine echte Anomalie.

11.13. Authentifizierung

Der Ordner [Auth] enthält in einer umfassenderen Form die Beispiele 25 bis 27: das JWT-Token in einem Cookie, Rollen, CAPTCHA und Versuchsbegrenzung. Er enthält außerdem einen „Pass“ zum Anlegen eines Kundenkontos. Der Controller [AuthController], der am Ende dieses Abschnitts besprochen wird, führt diese Bausteine für die Login-Seite zusammen.

11.13.1. Auth/ConnectedUser.cs

// =========================================================================
// Auth/ConnectedUser.cs
// -------------------------------------------------------------------------
// Was das JWT-Token enthält und wie man es wieder ausliest.
//
// In ASP.NET Core ist der Benutzer der Anfrage ein ClaimsPrincipal
// (Eigenschaft User eines Controllers, anderswo HttpContext.User): eine Liste von
// "Claims", Paaren aus Typ / Wert - genau die
// Felder des JWT-Tokens nach der Überprüfung. Die Authentifizierungs-Middleware
// füllt ihn bei JEDER Anfrage (siehe Program.cs, UseAuthentication).
//
// Die Claims unserer Tokens (siehe AuthService.SetToken):
//   sub   : die Kennung des Benutzerkontos (JWT-Konvention: "Subject")
//   login : der Login
//   name  : der Anzeigename ("Marie PELISSIER"), für die Navigationsleiste
//   role  : ADMIN, DOCTOR oder USER
// =========================================================================

using System.Security.Claims;
using RdvMedecins.Entities;

namespace RdvMedecins.Auth;

public static class JwtClaims
{
    public const string Sub = "sub";
    public const string Login = "login";
    public const string Name = "name";
    public const string Role = "role";
}

// der angemeldete Benutzer in typisierter Form
public record ConnectedUser(int UserId, string Login, string Name, Role Role);

// -------------------------------------------------------------------------
// Eine "Erweiterungsmethode": sie wird aufgerufen, als gehörte sie zu
// ClaimsPrincipal (User.CurrentUser()), obwohl sie hier definiert ist.
// -------------------------------------------------------------------------
public static class ClaimsPrincipalExtensions
{
    // der angemeldete Benutzer oder null, wenn die Anfrage nicht authentifiziert ist
    public static ConnectedUser? CurrentUser(this ClaimsPrincipal principal)
    {
        if (principal.Identity?.IsAuthenticated != true
            || !int.TryParse(principal.FindFirstValue(JwtClaims.Sub), out var userId)
            || !Enum.TryParse<Role>(principal.FindFirstValue(JwtClaims.Role), out var role))
        {
            return null;
        }
        return new ConnectedUser(
            userId,
            principal.FindFirstValue(JwtClaims.Login) ?? "",
            principal.FindFirstValue(JwtClaims.Name) ?? "",
            role);
    }
}
  • Zeilen 24–29: die Namen der Token-Claims, zu Konstanten zusammengefasst: Ein Tippfehler in [JwtClaims.Name] wird vom Compiler gemeldet, während ein Fehler in der Zeichenfolge ["name"] erst zur Laufzeit entdeckt würde;
  • Zeile 33: der angemeldete Benutzer in typisierter Form: ein ganzzahliger Bezeichner, eine Rolle vom Typ [Role] (die Aufzählung ADMIN, DOCTOR, USER aus dem Ordner [Entities]) statt der Liste von Zeichenfolgenpaaren, die die Claims bilden. Dies entspricht dem Objekt [req.user], das von der [Passport]-Strategie des [NestJS]-Projekts erzeugt wurde;
  • Zeilen 39–42: eine Erweiterungsmethode (siehe Beispiel 06) für ***[ClaimsPrincipal], den Typ der Eigenschaft ***[User] von Controllern und Views (siehe Beispiel 25). Die Seiten schreiben einfach [User.CurrentUser()];
  • Zeilen 44–48: Die Methode gibt [null] zurück, wenn die Anfrage nicht authentifiziert ist oder die Claims nicht den Erwartungen entsprechen. [Identity?.IsAuthenticated] ist gleich [null] , wenn [Identity] fehlt: Der Vergleich [!= true] behandelt diesen Fall als „nicht authentifiziert“. [int.TryParse] und [Enum.TryParse<Role>] versuchen eine Umwandlung und geben [false] zurück, wenn sie fehlschlägt, statt eine Ausnahme auszulösen; das Ergebnis wird in der von [out var] deklarierten Variablen gespeichert;
  • Zeilen 50–54: [FindFirstValue] liefert den Wert des ersten Claims des angeforderten Typs oder [null]; der Operator [??] ersetzt ihn dann durch eine leere Zeichenfolge.

11.13.2. Auth/AuthService.cs

// =========================================================================
// Auth/AuthService.cs
// -------------------------------------------------------------------------
// Die Authentifizierungslogik:
//   - ValidateUserAsync()      : prüft ein Paar aus Login / Passwort;
//   - SetToken()               : erstellt das JWT-Token eines validierten Benutzers
//                                und speichert es in einem Cookie;
//   - ClearToken()             : löscht dieses Cookie (Abmeldung).
//
// Wo reist das JWT-Token?
// Beim Angular-Client hielt der JavaScript-Code des Clients das
// Token und fügte es selbst jeder Anfrage hinzu (Header "Authorization:
// Bearer ..."). Ein Browser, der gewöhnliche HTML-Seiten anzeigt, kann das nicht:
// Damit er das Token bei jeder Anfrage von sich aus vorlegt,
// muss es in einem COOKIE gespeichert sein. Die Optionen dieses Cookies sind für die
// Sicherheit wichtig:
//   - HttpOnly : das JavaScript der Seite kann das Cookie nicht lesen (ein
//     eingeschleustes Skript könnte das Token also nicht stehlen);
//   - SameSite=Lax : der Browser sendet das Cookie NICHT bei einem POST von
//     einer anderen Website. Da alle Aktionen, die Daten ändern,
//     POSTs sind, kann eine präparierte Seite auf einer anderen Website nichts buchen
//     oder löschen, indem sie sich als der Benutzer ausgibt
//     (sogenannter CSRF-Angriff);
//   - Secure : in der Produktion (HTTPS) reist das Cookie nie im Klartext;
//   - MaxAge : das Cookie verschwindet gleichzeitig mit dem Ablauf des Tokens.
// =========================================================================

using System.Text;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;
using RdvMedecins.Config;
using RdvMedecins.Entities;
using RdvMedecins.Repositories;

namespace RdvMedecins.Auth;

public class AuthService(UserRepository userRepository, IOptions<AuthOptions> options)
{
    // der Name des Cookies, das das Token trägt
    public const string JwtCookie = "rdvmedecins_jwt";

    private readonly AuthOptions auth = options.Value;

    // der Signaturschlüssel der Tokens, aus dem Secret von
    // appsettings.json erstellt. Wird auch zum ÜBERPRÜFEN der Tokens verwendet (siehe Program.cs).
    public static SymmetricSecurityKey SigningKey(AuthOptions auth)
    {
        var bytes = Encoding.UTF8.GetBytes(auth.JwtSecret);
        if (bytes.Length < 32)
        {
            // HMAC-SHA256 verlangt einen Schlüssel von mindestens 256 Bit: wir sagen das
            // lieber beim Start deutlich als beim ersten Login
            throw new InvalidOperationException("Auth:JwtSecret must be at least 32 characters long (see appsettings.json).");
        }
        return new SymmetricSecurityKey(bytes);
    }

    // null, wenn der Login nicht existiert oder das Passwort falsch ist.
    // BCrypt.Verify hasht das eingegebene Passwort mit dem im gespeicherten Hash
    // enthaltenen "Salt" und vergleicht dann die beiden Ergebnisse.
    public async Task<User?> ValidateUserAsync(string login, string password)
    {
        var user = await userRepository.FindByLoginAsync(login);
        if (user is null)
        {
            return null;
        }
        return BCrypt.Net.BCrypt.Verify(password, user.Password) ? user : null;
    }

    // -----------------------------------------------------------------------
    // erstellt das JWT-Token von [user] und legt es in einem Cookie ab.
    // Das Token wird mit dem geheimen Schlüssel SIGNIERT (HMAC-SHA256): der Browser
    // kann es lesen (es ist nicht verschlüsselt), aber nicht ändern - jede
    // Änderung würde die Signatur ungültig machen.
    // -----------------------------------------------------------------------
    public void SetToken(HttpResponse response, User user)
    {
        var descriptor = new SecurityTokenDescriptor
        {
            Claims = new Dictionary<string, object>
            {
                [JwtClaims.Sub] = user.Id,
                [JwtClaims.Login] = user.Login,
                [JwtClaims.Name] = user.Name,
                [JwtClaims.Role] = user.Role.ToString(),
            },
            Expires = DateTime.UtcNow.AddSeconds(auth.JwtExpiresInSeconds),
            SigningCredentials = new SigningCredentials(SigningKey(auth), SecurityAlgorithms.HmacSha256),
        };
        var token = new JsonWebTokenHandler().CreateToken(descriptor);

        response.Cookies.Append(JwtCookie, token, new CookieOptions
        {
            HttpOnly = true,
            SameSite = SameSiteMode.Lax,
            Secure = auth.CookieSecure,
            MaxAge = TimeSpan.FromSeconds(auth.JwtExpiresInSeconds),
            Path = "/",
        });
    }

    public static void ClearToken(HttpResponse response) =>
        response.Cookies.Delete(JwtCookie, new CookieOptions { Path = "/" });
}

Kommentieren wir diesen Code:

  • Zeile 38: Der Service erhält per Injection die DAO-Klasse mit den Benutzerkonten ([UserRepository], besprochen bei der DAO-Schicht) und die Authentifizierungskonfiguration. [IOptions<AuthOptions>] stellt den Abschnitt [Auth] der Datei [appsettings.json] in Form eines Objekts [AuthOptions] (Ordner [Config]) bereit: Seine Eigenschaft [Value] enthält den geheimen Schlüssel, die Lebensdauer des Tokens und die Option [CookieSecure]. Der Service wird in [Program.cs] ebenso als [Scoped] registriert wie die DAO-Klasse, die er verwendet (siehe Kapitel 6);
  • Zeile 41: der Name des Cookies, das das Token trägt;
  • Zeilen 47–56: der Signaturschlüssel (siehe Beispiel 25). Neu: Ein zu kurzer Schlüssel wird mit einer klaren Ausnahme abgelehnt. Die Methode ist statisch: Sie hängt nur von ihrem Parameter ab und wird beim Start der Anwendung von [JwtAuthentication] (nächste Datei) aufgerufen, zu einem Zeitpunkt, an dem noch keine Services existieren. Da die Längenprüfung an dieser Stelle erfolgt, verhindert eine fehlerhafte Konfiguration den Start der Anwendung, statt dass die erste Anmeldung fehlschlägt;
  • Zeilen 62–69: das Konto, wenn Benutzername und Passwort stimmen; andernfalls [null] (siehe Beispiel 25). Die Methode ist asynchron: Die Kontosuche ist eine Datenbankabfrage (siehe Kapitel 9);
  • Zeilen 78–92: das Token, erzeugt wie in Beispiel 25. Es enthält die Konto-ID, den Benutzernamen, den in der Navigationsleiste angezeigten Namen und die Rolle; seine Lebensdauer wird durch die Konfiguration bestimmt (standardmäßig zwei Stunden);
  • Zeilen 94–100: das Cookie, mit den Optionen aus Beispiel 25 ([HttpOnly], [SameSite = Lax]) und zwei weiteren: [Secure], in der Produktion aktiviert (die Site wird über [HTTPS] ausgeliefert), verhindert, dass der Browser das Cookie über eine unverschlüsselte Verbindung sendet; [Path = "/"] stellt sicher, dass es bei jeder Anfrage an die Site mitgeschickt wird. [MaxAge] löscht das Cookie, wenn das Token abläuft;
  • Zeilen 104–105: Das Abmelden löscht das Cookie. Damit der Browser das zu löschende Cookie erkennt, muss der Pfad ([Path]) dem des Speicherorts entsprechen. Die Methode ist statisch: Sie wird auch vom Handler [JwtBearer] (nächste Datei) und vom Exception-Filter [HtmlExceptionFilter] (Ordner [Web]) verwendet, denen keine Instanz von [AuthService] zur Verfügung steht.

11.13.3. Auth/JwtAuthentication.cs

// =========================================================================
// Auth/JwtAuthentication.cs
// -------------------------------------------------------------------------
// Die Konfiguration der Authentifizierung per JWT-Token, aufgerufen aus
// Program.cs (builder.Services.AddJwtAuthentication(...)).
//
// Der "Handler" JwtBearer von ASP.NET Core tut bei jeder Anfrage das, was
// die Strategie 'jwt' von Passport und JwtAuthGuard in NestJS taten:
//   1. das Token finden;
//   2. seine Signatur und sein Ablaufdatum prüfen;
//   3. daraus den Benutzer ableiten (HttpContext.User, siehe ConnectedUser.cs).
//
// Drei Anpassungen an eine HTML-Anwendung dank der "Events" des
// Handlers (Funktionen, die er zu bestimmten Zeitpunkten aufruft):
//   - OnMessageReceived : das Token wird aus einem COOKIE gelesen und nicht aus
//     dem Header "Authorization: Bearer ...";
//   - OnChallenge : wird eine geschützte Seite ohne gültiges Token angefordert,
//     würde JwtBearer mit 401 antworten - was zu einem JavaScript-Client passt. Ein
//     Browser muss dagegen auf die Login-Seite ZURÜCKGESCHICKT werden;
//   - (403: unzureichende Rolle) hier ist nichts zu tun: die leere 403-Antwort wird
//     von UseStatusCodePagesWithReExecute in eine Fehlerseite umgewandelt
//     (siehe Program.cs und Controllers/ErrorController.cs).
// =========================================================================

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using RdvMedecins.Config;
using RdvMedecins.Web;

namespace RdvMedecins.Auth;

public static class JwtAuthentication
{
    public static IServiceCollection AddJwtAuthentication(this IServiceCollection services, AuthOptions auth)
    {
        services
            .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(options =>
            {
                // wir behalten die Claim-Namen des Tokens unverändert ("role", "sub"...)
                // statt sie in lange Namen im Microsoft-Stil zu übersetzen
                options.MapInboundClaims = false;

                options.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuerSigningKey = true,
                    IssuerSigningKey = AuthService.SigningKey(auth),
                    ValidateLifetime = true,
                    // ein abgelaufenes Token wird sofort abgelehnt (standardmäßig wird
                    // für Uhrenabweichungen eine Toleranz von 5 Minuten gewährt)
                    ClockSkew = TimeSpan.Zero,
                    // unsere Tokens haben weder Aussteller (iss) noch Zielgruppe (aud)
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    // welcher Claim den Namen und welcher die Rolle enthält:
                    // [Authorize(Roles = "ADMIN")] vergleicht den Claim "role"
                    NameClaimType = JwtClaims.Name,
                    RoleClaimType = JwtClaims.Role,
                };

                options.Events = new JwtBearerEvents
                {
                    // 1. das Token befindet sich im Cookie
                    OnMessageReceived = context =>
                    {
                        context.Token = context.Request.Cookies[AuthService.JwtCookie];
                        return Task.CompletedTask;
                    },

                    // 2. geschützte Seite ohne gültiges Token -> Login-Seite
                    OnChallenge = context =>
                    {
                        // HandleResponse(): "ich kümmere mich um die Antwort", JwtBearer
                        // schreibt daher sein 401 nicht
                        context.HandleResponse();
                        // ein Cookie war vorhanden, ist aber nicht mehr gültig: die Sitzung ist abgelaufen
                        if (context.Request.Cookies.ContainsKey(AuthService.JwtCookie))
                        {
                            AuthService.ClearToken(context.Response);
                            Flash.Put(context.HttpContext, FlashType.Danger, "ERRORS.SESSION_EXPIRED");
                        }
                        context.Response.Redirect("/login");
                        return Task.CompletedTask;
                    },
                };
            });

        return services;
    }
}

In Beispiel 25 wurde die Konfiguration von [JwtBearer] in [Program.cs] geschrieben. Hier ist sie in einer Erweiterungsmethode abgelegt, die [Program.cs] in einer einzigen Zeile aufruft: [builder.Services.AddJwtAuthentication(authOptions)]. Kommentieren wir diesen Code:

  • Zeilen 32–34: die Erweiterungsmethode (siehe Beispiel 06). Sie erhält direkt ein [AuthOptions]-Objekt, das [Program.cs] aus der Konfiguration gelesen hat: Beim Registrieren der Services steht Dependency Injection noch nicht zur Verfügung, daher können wir kein [IOptions<AuthOptions>] anfordern;
  • Zeilen 37–42: das Authentifizierungsschema [JwtBearer], das die Namen der Claims des Tokens speichert (siehe Beispiel 25);
  • Zeilen 44–54: die bei jedem Token durchgeführten Prüfungen: die Signatur mit dem von [AuthService.SigningKey] erzeugten Schlüssel und das Ablaufdatum. Neu gegenüber Beispiel 25: [ClockSkew = TimeSpan.Zero]. Standardmäßig akzeptiert [JwtBearer] ein Token nach seinem Ablauf noch fünf Minuten lang, um eine geringfügige Abweichung zwischen den Uhren des Servers, der das Token erzeugt, und des Servers, der es prüft, auszugleichen. Hier ist es derselbe Server: Ein abgelaufenes Token wird sofort abgelehnt;
  • Zeilen 57–58: Der Claim [name] ergibt [User.Identity.Name], der Claim [role] ist derjenige, den [[Authorize(Roles = "ADMIN")]] und [User.IsInRole] prüfen (siehe Beispiel 26);
  • Zeilen 64–67: Das Token wird aus dem Cookie gelesen, nicht aus dem Header [Authorization] (siehe Beispiel 25);
  • Zeilen 71–82: Eine Anfrage nach einer geschützten Seite ohne gültiges Token leitet auf die Login-Seite um (siehe Beispiel 25). Neu (Zeilen 77–80): Enthielt die Anfrage ein Token-Cookie, war der Benutzer angemeldet, sein Token ist aber abgelaufen (oder wurde manipuliert). Wir löschen dieses nun nutzlose Cookie und zeigen eine Flash-Meldung an (siehe Beispiel 20; die Klasse [Flash] wird beim Ordner [Web] besprochen): Die Login-Seite zeigt „Ihre Sitzung ist abgelaufen“ an, statt den Benutzer rätseln zu lassen, warum er dort gelandet ist. Die Meldung ist ein Übersetzungsschlüssel (siehe Beispiel 22).

Eine Antwort 403 Forbidden (unzureichende Rolle) erfordert kein Ereignis: Wie in Beispiel 26 wird die leere Antwort von [UseStatusCodePagesWithReExecute] in eine Fehlerseite umgewandelt. Im [NestJS]-Projekt war diese Aufgabe auf die Strategien [Passport] und [jwt] (Token lesen und prüfen), den Guard [JwtAuthGuard] (ein Token verlangen) und den Exception-Filter (die Ablehnung in eine Umleitung umwandeln) verteilt; hier genügen der Handler [JwtBearer], seine Ereignisse und das Attribut [[Authorize]] .

11.13.4. Auth/InvalidSessionException.cs

// =========================================================================
// Auth/InvalidSessionException.cs
// -------------------------------------------------------------------------
// Das Token ist gültig, aber das darin bezeichnete Konto existiert nicht mehr: es wurde
// seit dem Login gelöscht (vom Patienten selbst in einem anderen
// Tab oder vom ADMIN). Wir behandeln diesen Fall wie eine abgelaufene Sitzung:
// HtmlExceptionFilter löscht das Cookie und schickt zurück zur Login-Seite
// (das Äquivalent der UnauthorizedException von NestJS).
// =========================================================================

namespace RdvMedecins.Auth;

public class InvalidSessionException() : Exception("the account of the connected user no longer exists");
  • Zeile 13: Ein Token kann gültig sein (korrekt signiert, nicht abgelaufen), obwohl das Konto, auf das es verweist, seit der Anmeldung gelöscht wurde. Die Seiten des Patienten erkennen dies, indem sie den mit dem Konto verknüpften Kunden suchen (Methode [ConnectedPatientAsync] in der Datei [Web/Utils.cs]), und lösen dann diese Ausnahme aus; der Exception-Filter [HtmlExceptionFilter] (zu Filtern siehe Beispiel 24) fängt sie ab, löscht das Cookie und leitet mit der Meldung „Sitzung abgelaufen“ auf die Login-Seite um. Die Klasse hat einen primären Konstruktor ohne Parameter, der seine Meldung an den Konstruktor der Elternklasse [Exception] weiterreicht.

11.13.5. Auth/CaptchaService.cs

// =========================================================================
// Auth/CaptchaService.cs
// -------------------------------------------------------------------------
// Ein CAPTCHA ("Test zur Unterscheidung von Mensch und Roboter"), vom
// Server selbst erzeugt, ohne externen Dienst: einige verzerrte Zeichen,
// durch Striche verwürfelt, in einem SVG-Bild. Ein Mensch liest sie ohne
// Mühe; ein Roboter, der nur in einer Schleife Formulare sendet,
// kann das nicht.
//
// Das NestJS-Projekt verwendete die Bibliothek svg-captcha. Hier keine
// Bibliothek: das Bild wird von der Klasse CaptchaDrawing (unten) aus
// einer kleinen, von Hand geschriebenen Vektor-"Schrift" gezeichnet. Ein wichtiger
// Punkt: jedes Zeichen wird mit STRICHEN (<path>) gezeichnet, niemals
// als Text (<text>) geschrieben - sonst müsste ein Roboter nur den Quellcode
// des Bildes lesen.
//
// So funktioniert es:
//   1. Generate() zeichnet einen zufälligen Text, wandelt ihn in ein Bild um und speichert die
//      richtige Antwort IM SPEICHER DES SERVERS unter einer zufälligen Kennung;
//   2. die Seite zeigt das Bild an und legt die Kennung in einem versteckten Feld des
//      Formulars ab (die Antwort selbst verlässt den Server nie);
//   3. Verify(id, input) vergleicht die Eingabe mit der erwarteten Antwort und
//      VERGISST dann dieses CAPTCHA: jedes Bild wird nur einmal verwendet, ein Roboter kann
//      keine bereits gefundene Antwort wiederholen.
//
// SINGLETON-Service (eine einzige Instanz für den gesamten Server, siehe
// Program.cs), von mehreren Anfragen PARALLEL verwendet: daher das
// ConcurrentDictionary, ein Dictionary, das mehrere Threads gleichzeitig lesen
// und ändern können, ohne es zu beschädigen.
//
// Akzeptierte Einschränkung: der Speicher eines einzigen Prozesses. Bei mehreren Servern
// hinter einem Load Balancer wäre ein gemeinsamer Speicher nötig.
// =========================================================================

using System.Collections.Concurrent;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

namespace RdvMedecins.Auth;

// Id : kommt in das versteckte Feld "captchaId" des Formulars
// Svg : das Bild, unverändert in die Seite einzufügen
public record Captcha(string Id, string Svg);

public class CaptchaService
{
    // Gültigkeitsdauer eines Bildes: Sie haben 10 Minuten, um das Formular auszufüllen
    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(10);

    // Speicherschutz: darüber hinaus vergessen wir die ältesten CAPTCHAs
    private const int MaxCaptchas = 10_000;

    // Kennung -> (erwartete Antwort, Ablaufdatum)
    private readonly ConcurrentDictionary<string, (string Text, DateTime Expires)> pending = new();

    public Captcha Generate()
    {
        Purge();
        var text = CaptchaDrawing.RandomText(5); // 5 Zeichen
        var id = Guid.NewGuid().ToString();
        pending[id] = (text, DateTime.UtcNow + Lifetime);
        return new Captcha(id, CaptchaDrawing.Svg(text));
    }

    // true, wenn [input] die richtige Antwort auf das CAPTCHA [id] ist (ohne Beachtung
    // der Groß-/Kleinschreibung). Das CAPTCHA wird in jedem Fall verbraucht.
    // TryRemove ist ATOMAR: legen zwei Anfragen im selben Augenblick dasselbe
    // CAPTCHA vor, entfernt es nur eine - die andere scheitert.
    public bool Verify(string? id, string? input)
    {
        if (id is null || input is null || !pending.TryRemove(id, out var expected))
        {
            return false;
        }
        return expected.Expires > DateTime.UtcNow
            && string.Equals(expected.Text, input.Trim(), StringComparison.OrdinalIgnoreCase);
    }

    private void Purge()
    {
        var now = DateTime.UtcNow;
        foreach (var (id, captcha) in pending)
        {
            if (captcha.Expires <= now || pending.Count >= MaxCaptchas)
            {
                pending.TryRemove(id, out _);
            }
        }
    }
}

// -------------------------------------------------------------------------
// Das Zeichnen des SVG-Bildes (150 x 50 Pixel).
// -------------------------------------------------------------------------
internal static class CaptchaDrawing
{
    private const int Width = 150;
    private const int Height = 50;

    // Die "Schrift": jedes Zeichen ist eine Liste von Strichen, jeder Strich eine
    // Folge von Punkten (x, y) in einem Raster von 4 x 6 (y zeigt nach unten).
    // Zeichen, die zu leicht miteinander zu verwechseln sind: ausgeschlossen (0 O, 1 I L).
    private static readonly Dictionary<char, double[][]> Font = new()
    {
        ['A'] = [[0, 6, 2, 0, 4, 6], [0.8, 3.8, 3.2, 3.8]],
        ['B'] = [[0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3], [0, 0, 3, 0, 4, 1, 4, 2, 3, 3]],
        ['C'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5]],
        ['D'] = [[0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0]],
        ['E'] = [[4, 0, 0, 0, 0, 6, 4, 6], [0, 3, 3, 3]],
        ['F'] = [[4, 0, 0, 0, 0, 6], [0, 3, 3, 3]],
        ['G'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5]],
        ['H'] = [[0, 0, 0, 6], [4, 0, 4, 6], [0, 3, 4, 3]],
        ['J'] = [[4, 0, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['K'] = [[0, 0, 0, 6], [4, 0, 0, 3.5], [1.3, 2.6, 4, 6]],
        ['M'] = [[0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6]],
        ['N'] = [[0, 6, 0, 0, 4, 6, 4, 0]],
        ['P'] = [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3]],
        ['Q'] = [[1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0], [2.5, 4.5, 4, 6.3]],
        ['R'] = [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3], [2, 3, 4, 6]],
        ['S'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['T'] = [[0, 0, 4, 0], [2, 0, 2, 6]],
        ['U'] = [[0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0]],
        ['V'] = [[0, 0, 2, 6, 4, 0]],
        ['W'] = [[0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0]],
        ['X'] = [[0, 0, 4, 6], [4, 0, 0, 6]],
        ['Y'] = [[0, 0, 2, 3, 4, 0], [2, 3, 2, 6]],
        ['Z'] = [[0, 0, 4, 0, 0, 6, 4, 6]],
        ['2'] = [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6]],
        ['3'] = [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3], [3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['4'] = [[3, 6, 3, 0, 0, 4, 4, 4]],
        ['5'] = [[4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['6'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3]],
        ['7'] = [[0, 0, 4, 0, 1.5, 6]],
        ['8'] = [[1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3]],
        ['9'] = [[4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5]],
    };

    private static readonly char[] Alphabet = [.. Font.Keys];

    // einige dunkle Farben, auf dem hellen Hintergrund gut lesbar
    private static readonly string[] Colors = ["#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b"];

    // RandomNumberGenerator: ein "kryptografischer" Zufallszahlengenerator,
    // unvorhersehbar (anders als Random, dessen Folge erraten werden könnte)
    public static string RandomText(int length) =>
        new(Enumerable.Range(0, length).Select(_ => Alphabet[RandomNumberGenerator.GetInt32(Alphabet.Length)]).ToArray());

    private static double RandomBetween(double min, double max) =>
        min + (max - min) * RandomNumberGenerator.GetInt32(1_000_001) / 1_000_000.0;

    public static string Svg(string text)
    {
        var svg = new StringBuilder();
        svg.Append($"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{Width}\" height=\"{Height}\" viewBox=\"0 0 {Width} {Height}\">");
        svg.Append($"<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");

        // die Zeichen: jedes vergrößert, geneigt, verschoben, und jeder Punkt
        // leicht zufällig verschoben
        var step = (Width - 20) / (double)text.Length;
        for (var i = 0; i < text.Length; i++)
        {
            var scale = RandomBetween(4.6, 5.6); // Größe einer Rastereinheit in Pixeln
            var angle = RandomBetween(-0.35, 0.35); // Drehung im Bogenmaß (etwa ±20°)
            var cx = 10 + step * (i + 0.5) + RandomBetween(-3, 3); // Mittelpunkt des Zeichens
            var cy = Height / 2.0 + RandomBetween(-4, 4);
            var color = Colors[RandomNumberGenerator.GetInt32(Colors.Length)];
            var d = new StringBuilder();
            foreach (var stroke in Font[text[i]])
            {
                for (var k = 0; k < stroke.Length; k += 2)
                {
                    // Rasterpunkt, auf (2, 3) zentriert, verzerrt, gedreht, platziert
                    var x = (stroke[k] - 2 + RandomBetween(-0.2, 0.2)) * scale;
                    var y = (stroke[k + 1] - 3 + RandomBetween(-0.2, 0.2)) * scale;
                    var px = cx + x * Math.Cos(angle) - y * Math.Sin(angle);
                    var py = cy + x * Math.Sin(angle) + y * Math.Cos(angle);
                    d.Append(k == 0 ? 'M' : 'L').Append(Number(px)).Append(' ').Append(Number(py)).Append(' ');
                }
            }
            svg.Append($"<path d=\"{d.ToString().TrimEnd()}\" fill=\"none\" stroke=\"{color}\" stroke-width=\"{Number(RandomBetween(2.2, 3))}\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>");
        }

        // 3 Verwürfelungsstriche: Kurven, die das Bild durchqueren
        for (var n = 0; n < 3; n++)
        {
            var color = Colors[RandomNumberGenerator.GetInt32(Colors.Length)];
            svg.Append($"<path d=\"M{Number(RandomBetween(0, 20))} {Number(RandomBetween(5, 45))} " +
                       $"C{Number(RandomBetween(30, 60))} {Number(RandomBetween(0, 50))} {Number(RandomBetween(90, 120))} {Number(RandomBetween(0, 50))} " +
                       $"{Number(RandomBetween(130, 150))} {Number(RandomBetween(5, 45))}\" fill=\"none\" stroke=\"{color}\" stroke-width=\"1.3\"/>");
        }

        svg.Append("</svg>");
        return svg.ToString();
    }

    // eine Zahl mit Dezimalpunkt, unabhängig von der Sprache des Servers
    // (auf Französisch würde ToString() "12,5" schreiben - für SVG unlesbar)
    private static string Number(double value) => value.ToString("0.#", CultureInfo.InvariantCulture);
}

Die Datei enthält zwei Klassen: die Service-Klasse, die bis auf eine Schutzmaßnahme mit der aus Beispiel 27 identisch ist, und die Klasse [CaptchaDrawing], die das Bild erzeugt und bereits in Beispiel 27 besprochen wurde (Datei [Auth/CaptchaDrawing.cs]). Gehen wir diesen Code durch:

  • Zeile 44: ein CAPTCHA, wie es die Seite erhält: der Bezeichner, der in einem versteckten Formularfeld abgelegt wird, und das [SVG]-Bild;
  • Zeilen 49–52: Ein Bild ist zehn Minuten lang gültig, und die Zahl der ausstehenden CAPTCHAs ist begrenzt. Bei jeder Anzeige der Login-Seite wird ein CAPTCHA im Speicher abgelegt; ohne Obergrenze würde ein Bot, der diese Seite millionenfach aufruft, ohne je zu antworten, irgendwann den Speicher des Servers erschöpfen;
  • Zeile 55: ID → (erwartete Antwort, Ablaufdatum). Das Paar ist ein Tupel , dessen Elemente benannt sind ([Text], [Expires]). Der Service ist ein Singleton, das von gleichzeitigen Anfragen genutzt wird: daher das [ConcurrentDictionary] (siehe Beispiel 27);
  • Zeilen 57–63: das Aufräumen, danach ein zufällig erzeugter Text aus fünf Zeichen, der unter einem zufälligen Bezeichner ([Guid.NewGuid()], nicht zu erraten) gespeichert und angezeigt wird;
  • Zeilen 70–77: die Überprüfung, identisch mit der in Beispiel 27: Das CAPTCHA wird in jedem Fall verbraucht ([TryRemove]), dann prüft das System, dass es nicht abgelaufen ist und dass der eingegebene Text ohne Leerzeichen korrekt ist, unabhängig von der Groß- und Kleinschreibung. [TryRemove] ist atomar: Legen zwei Anfragen zeitgleich dasselbe CAPTCHA vor, entfernt es nur eine;
  • Zeilen 80–87: Abgelaufene CAPTCHAs werden verworfen; ist die Obergrenze erreicht, werden auch gültige CAPTCHAs entfernt, bis die Anzahl unter die Obergrenze fällt. Ein [ConcurrentDictionary] kann während seiner Durchlaufung geändert werden, was bei einem gewöhnlichen [Dictionary] nicht zulässig ist (siehe [AttemptLimiterService], unten). Er behält jedoch die Einfügereihenfolge nicht bei: Die auf diese Weise entfernten CAPTCHAs sind nicht unbedingt die ältesten, während die [Map] des [NestJS]-Projekts es erlaubte, zuerst die ältesten zu entfernen. Dieser Fall tritt nur bei einem Angriff auf: Die Näherung genügt;
  • Zeile 96: das Zeichnen des Bildes. [internal]: Die Klasse ist nur innerhalb der Anwendung selbst sichtbar;
  • Zeilen 104–136: die „Schriftart“: für jedes Zeichen eine Liste von Strichen, wobei jeder Strich eine Folge von (x, y)-Koordinaten in einem Raster von 4 × 6 ist. Die eckigen Klammern [[...]] sind Collection-Ausdrücke ([C#] 12), eine kompakte Schreibweise für Arrays;
  • Zeile 139: die verwendbaren Zeichen, also die Schlüssel der Schriftart. [..] spreizt eine Collection in eine andere;
  • Zeilen 146–147 und 149–150: Die Zufallsauswahl verwendet [RandomNumberGenerator], einen kryptografischen Generator, dessen Ausgaben unvorhersehbar sind;
  • Zeilen 152–194: Das Bild ist ein [SVG]-Text, zusammengesetzt in einem [StringBuilder] (eine Zeichenfolge, die erweitert wird, ohne bei jedem hinzugefügten Element neu geschrieben zu werden). Jedes Zeichen (Zeilen 160–181) wird zu einem [<path>]-Pfad: Jeder Punkt des Rasters wird leicht verschoben, vergrößert, gedreht und an seine Position im Bild gesetzt, mit zufällig gewählter Farbe und Strichstärke. Die Zeichen sind Linien, niemals Text: Ein Bot kann sie im Code des Bildes nicht lesen. Drei Störkurven durchqueren dann das Bild (Zeilen 185–190);
  • Zeile 199: Die Zahlen in [SVG] werden mit Dezimalpunkt geschrieben. [CultureInfo.InvariantCulture] erzwingt diese Schreibweise unabhängig von der Sprache des Servers: Im Französischen würde [ToString()] ein Komma verwenden (siehe Kapitel 5).

11.13.6. Auth/AttemptLimiterService.cs

// =========================================================================
// Auth/AttemptLimiterService.cs
// -------------------------------------------------------------------------
// Zweite Verteidigungslinie gegen Roboter (die erste ist das CAPTCHA): wir ZÄHLEN
// die Versuche und SPERREN oberhalb eines Schwellenwerts für eine gewisse Zeit.
//
//   - Login: nach LoginMaxFailures Fehlversuchen (falsches CAPTCHA oder falsches
//     Passwort) für denselben Login von derselben IP-Adresse wird dieses Paar
//     LoginBlockMinutes Minuten lang gesperrt. Dieselbe IP-Adresse wird ebenfalls
//     gesperrt, wenn sie 5-mal so viele Fehlversuche ansammelt, alle Logins zusammen (ein
//     Roboter, der Tausende verschiedener Logins ausprobiert);
//   - Anlegen von Konten: höchstens RegistrationMaxPerHour Konten pro
//     Stunde von derselben IP-Adresse.
//
// Achtung im Kursraum: oft gehen alle Rechner über dieselbe IP-Adresse
// ins Internet. Deshalb gilt die Login-Sperre zuerst für das Paar (IP, Login) - ein
// Student, der sich bei seinem Passwort vertippt, sperrt seine Nachbarn nicht - und
// deshalb sind die Schwellenwerte in appsettings.json einstellbar
// (Abschnitt "Protection").
//
// Singleton-Service, von parallelen Requests aufgerufen: Alle
// Operationen auf den Zählern erfolgen unter einem Lock, was garantiert,
// dass jeweils nur ein Thread einen Zähler liest UND ändert.
// =========================================================================

using Microsoft.Extensions.Options;
using RdvMedecins.Config;

namespace RdvMedecins.Auth;

public class AttemptLimiterService(IOptions<ProtectionOptions> options)
{
    private class Counter
    {
        public int Count; // im aktuellen Zeitfenster gezählte Versuche
        public DateTime Start; // Beginn des Zählfensters
        public DateTime BlockedUntil; // DateTime.MinValue, wenn nicht gesperrt
    }

    private static readonly TimeSpan OneHour = TimeSpan.FromHours(1);

    private readonly Dictionary<string, Counter> counters = [];
    private readonly Lock syncLock = new(); // der Lock-Typ ab .NET 9+, gedacht für "lock"

    private readonly int maxLoginFailures = options.Value.LoginMaxFailures;
    private readonly TimeSpan loginBlockDuration = TimeSpan.FromMinutes(options.Value.LoginBlockMinutes);
    private readonly int maxRegistrations = options.Value.RegistrationMaxPerHour;

    // ──────────────────────────────────────────────────────────────── Login

    // Anzahl der verbleibenden Sperrminuten (0 = der Versuch ist erlaubt)
    public int LoginBlockMinutes(string ip, string login)
    {
        lock (syncLock)
        {
            return Math.Max(RemainingMinutes(LoginKey(ip, login)), RemainingMinutes(IpKey(ip)));
        }
    }

    public void LoginFailure(string ip, string login)
    {
        lock (syncLock)
        {
            Count(LoginKey(ip, login), maxLoginFailures, loginBlockDuration, loginBlockDuration);
            Count(IpKey(ip), maxLoginFailures * 5, loginBlockDuration, loginBlockDuration);
        }
    }

    // ein erfolgreicher Login setzt den Zähler DIESES Logins zurück
    public void LoginSuccess(string ip, string login)
    {
        lock (syncLock)
        {
            counters.Remove(LoginKey(ip, login));
        }
    }

    // ──────────────────────────────────────────────────────────────── Registrierung

    public int RegistrationBlockMinutes(string ip)
    {
        lock (syncLock)
        {
            return RemainingMinutes($"registration|{ip}");
        }
    }

    // Zeitfenster von einer Stunde; sobald das Kontingent erreicht ist, Sperre bis zum Ende der Stunde
    public void RegistrationSuccess(string ip)
    {
        lock (syncLock)
        {
            Count($"registration|{ip}", maxRegistrations, OneHour, OneHour);
        }
    }

    // ──────────────────────────────────────────────────────────────── gemeinsame Mechanik
    // (die privaten Methoden werden immer unter dem Lock aufgerufen)

    private int RemainingMinutes(string key)
    {
        if (!counters.TryGetValue(key, out var c))
        {
            return 0;
        }
        var remaining = c.BlockedUntil - DateTime.UtcNow;
        return remaining > TimeSpan.Zero ? (int)Math.Ceiling(remaining.TotalMinutes) : 0;
    }

    // zählt einen Versuch; wird die Schwelle innerhalb des Zeitfensters erreicht, wird gesperrt
    private void Count(string key, int max, TimeSpan window, TimeSpan block)
    {
        var now = DateTime.UtcNow;
        Purge(now);
        if (!counters.TryGetValue(key, out var c) || now - c.Start > window)
        {
            c = new Counter { Count = 0, Start = now, BlockedUntil = DateTime.MinValue };
            counters[key] = c;
        }
        c.Count++;
        if (c.Count >= max)
        {
            c.BlockedUntil = now + block;
            c.Count = 0; // nach der Sperre beginnen wir wieder bei null
            c.Start = c.BlockedUntil;
        }
    }

    // Zähler, die nicht mehr nützlich sind (weder gesperrt noch aktuell), werden verworfen
    private void Purge(DateTime now)
    {
        if (counters.Count < 1000)
        {
            return;
        }
        foreach (var (key, c) in counters.ToList())
        {
            if (c.BlockedUntil < now && now - c.Start > OneHour)
            {
                counters.Remove(key);
            }
        }
    }

    private static string LoginKey(string ip, string login) => $"login|{ip}|{login.Trim().ToLowerInvariant()}";

    private static string IpKey(string ip) => $"ip|{ip}";
}

Im Vergleich zu Beispiel 27 schützt der Limiter zwei Vorgänge (die Anmeldung und das Anlegen eines Kontos); die Sperre bei der Anmeldung gilt für das Paar (IP-Adresse, Login), und die Schwellenwerte sind in [appsettings.json] konfigurierbar. Gehen wir diesen Code durch:

  • Zeile 31: [IOptions<ProtectionOptions>] liefert den Abschnitt [Protection] der Datei [appsettings.json] (Ordner [Config]): die Anzahl der erlaubten fehlgeschlagenen Anmeldeversuche (standardmäßig 5), die Dauer der Sperre (15 Minuten) und die Anzahl der pro Stunde angelegten Konten (10);
  • Zeilen 33–37: ein Zähler: die Anzahl der Versuche, der Beginn des Zählfensters und das Ende der Sperre ([DateTime.MinValue], das frühestmögliche Datum, wenn keine Sperre besteht). Dies ist eine verschachtelte, private Klasse: Sie existiert nur für diesen Service. Es ist eine Klasse, kein [record] und keine Struktur: Ein aus dem Wörterbuch gelesener Zähler wird an Ort und Stelle geändert;
  • Zeilen 42–43: ein gewöhnliches [Dictionary], geschützt durch eine Sperre (siehe Beispiel 27). Ein [ConcurrentDictionary] würde nicht genügen: Das Zählen eines Versuchs umfasst das Lesen eines Zählers, seine Änderung und gegebenenfalls seinen Austausch, und diese gesamte Abfolge von Operationen muss ausgeführt werden, ohne dass eine andere Anfrage dazwischenfunkt. Jede öffentliche Methode führt ihre Aufgabe daher innerhalb eines [lock (syncLock)]-Blocks aus;
  • Zeilen 45–47: die Schwellenwerte, einmalig gelesen. Der Parameter des primären Konstruktors kann zum Initialisieren der Felder verwendet werden;
  • Zeilen 52–56: die verbleibende Sperrzeit für einen Anmeldeversuch: die längere der beiden möglichen Sperrzeiten, die des Paares (IP-Adresse, Login) und die der IP-Adresse allein;
  • Zeilen 60–65: Ein fehlgeschlagener Versuch wird doppelt gezählt. Für das Paar (IP-Adresse, Login): Fünf fehlgeschlagene Versuche mit demselben Login sperren diesen Login, und zwar nur von dieser Adresse aus. Für die IP-Adresse allein mit einem fünfmal höheren Schwellenwert: Auch ein Bot, der sehr viele verschiedene Logins ausprobiert, wird gesperrt. In einem Klassenraum verbinden sich oft alle Computer über dieselbe IP-Adresse mit dem Internet: Ein Schüler, der ein falsches Passwort eingibt, soll seine Nachbarn nicht blockieren, daher die Sperre nach Paar;
  • Zeilen 70–74: Eine erfolgreiche Anmeldung setzt den Zähler für genau diesen Login zurück (nicht den der IP-Adresse);
  • Zeilen 80–84 und 89–93: Beim Anlegen eines Kontos werden nur erfolgreiche Versuche gezählt: höchstens zehn Konten pro Stunde von derselben IP-Adresse. Ist das Kontingent erreicht, wird die Adresse für eine Stunde gesperrt;
  • Zeilen 100–107: die verbleibenden Minuten der Sperre, aufgerundet auf die nächste ganze Zahl ([Math.Ceiling]): Bei 20 verbleibenden Sekunden wird „1 Minute“ statt „0 Minuten“ angezeigt. Diese privaten Methoden erwerben die Sperre nicht: Sie werden immer von einer öffentlichen Methode aufgerufen, die sie bereits hält;
  • Zeilen 111–125: das Zählen. Ein unbekannter Schlüssel oder einer, dessen Zählfenster abgelaufen ist, beginnt mit einem neuen Zähler. Wird der Schwellenwert erreicht, wird der Schlüssel gesperrt, und das Zählen beginnt am Ende der Sperre wieder bei null;
  • Zeilen 130–140: das Aufräumen nicht mehr benötigter Zähler (weder gesperrt noch aktuell), das nur durchgeführt wird, wenn das Wörterbuch mehr als 1000 Einträge enthält. Wir durchlaufen eine Kopie der Einträge ([ToList()]): Ein [Dictionary] kann während seiner Durchlaufung nicht geändert werden;
  • Zeilen 145–147: das Erzeugen der Wörterbuchschlüssel. Aus dem Login werden die Leerzeichen entfernt, und er wird in Kleinbuchstaben umgewandelt: [Admin] und [admin] teilen sich denselben Zähler; ein Bot kann die Sperre nicht durch Ändern der Groß- und Kleinschreibung umgehen.

11.13.7. Auth/RegistrationPassService.cs

// =========================================================================
// Auth/RegistrationPassService.cs
// -------------------------------------------------------------------------
// Der "Pass" für die Kontoerstellung.
//
// Um die Seite "Create a patient account" zu öffnen, muss zuvor das
// CAPTCHA der Authentifizierungsseite abgetippt worden sein (siehe
// RegistrationController, POST /register/access). Der Server stellt dann
// einen Pass aus:
//   - ein zufälliger Bezeichner, gespeichert in einem HttpOnly-Cookie;
//   - 15 Minuten gültig (die Zeit zum Ausfüllen des Formulars, auch wenn es nach
//     Eingabefehlern mehrere Versuche braucht);
//   - verbraucht, sobald ein Konto erstellt wird: EIN gelöstes CAPTCHA = höchstens EIN
//     Konto. Ein Roboter kann keine Konten in Serie erstellen.
//
// Ohne gültigen Pass leiten GET und POST /register zur
// Authentifizierungsseite um: Die direkte Eingabe der URL /register erlaubt es nicht,
// das CAPTCHA zu umgehen.
//
// Wie das CAPTCHA leben die Pässe im Speicher des Prozesses.
// =========================================================================

using System.Collections.Concurrent;

namespace RdvMedecins.Auth;

public class RegistrationPassService
{
    public const string Cookie = "rdvmedecins_registration";

    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(15);
    private const int MaxPasses = 10_000;

    // id -> Ablaufdatum
    private readonly ConcurrentDictionary<string, DateTime> passes = new();

    // stellt einen neuen Pass aus; gibt dessen Bezeichner zurück
    public string Issue()
    {
        Purge();
        var id = Guid.NewGuid().ToString();
        passes[id] = DateTime.UtcNow + Lifetime;
        return id;
    }

    // true, wenn [id] ein existierender, nicht abgelaufener Pass ist
    public bool IsValid(string? id) =>
        id is not null && passes.TryGetValue(id, out var expires) && expires > DateTime.UtcNow;

    // der Pass wurde verwendet: Er wird verworfen
    public void Consume(string? id)
    {
        if (id is not null)
        {
            passes.TryRemove(id, out _);
        }
    }

    // das Cookie wird vom Browser nur an die Adressen /register... gesendet
    public static CookieOptions GetCookieOptions() => new()
    {
        HttpOnly = true,
        SameSite = SameSiteMode.Lax,
        MaxAge = Lifetime,
        Path = "/register",
    };

    private void Purge()
    {
        var now = DateTime.UtcNow;
        foreach (var (id, expires) in passes)
        {
            if (expires <= now || passes.Count >= MaxPasses)
            {
                passes.TryRemove(id, out _);
            }
        }
    }
}

Sie können über die Login-Seite ein Kundenkonto anlegen, sofern Sie das CAPTCHA gelöst haben. Das Registrierungsformular wird über nachfolgende Anfragen angezeigt und abgeschickt: Diese Anfragen müssen wissen, dass eine vorherige Anfrage das CAPTCHA erfolgreich gelöst hat. Dies ist die Aufgabe des Passes, der vom [RegistrationController] ausgestellt und geprüft wird (dokumentiert bei den Controllern):

  • Zeile 29: der Name des Cookies, das den Pass trägt;
  • Zeilen 31–35: Ein Pass ist fünfzehn Minuten lang gültig; ausstehende Pässe werden wie CAPTCHAs im Speicher gehalten, mit derselben zeitlichen Begrenzung;
  • Zeilen 38–43: Ein Pass ist ein zufälliger Bezeichner, der zusammen mit seinem Ablaufdatum gespeichert wird; der Controller legt ihn in einem Cookie ab;
  • Zeilen 47–48: Das Registrierungsformular wird nur mit einem gültigen Pass angezeigt – und akzeptiert. Die Überprüfung verbraucht den Pass nicht ([TryGetValue], nicht [TryRemove]): Der Benutzer kann das Formular mehrfach erneut absenden, wenn er sich bei der Eingabe geirrt hat;
  • Zeilen 51–55: Das Anlegen eines Kontos verbraucht den Pass: Das Lösen eines CAPTCHAs berechtigt zu einem Konto und nicht zu mehr;
  • Zeilen 60–65: Cookie-Optionen. [new()] erzeugt ein Objekt des von der Methode deklarierten Typs ([CookieOptions]). Die Option [Path = "/register"] beschränkt das Senden des Cookies auf URLs, die mit [/register] beginnen: Andere Anfragen tragen es nicht unnötig mit sich;
  • Zeilen 68–75: der Aufräumvorgang, identisch mit dem des CAPTCHA.

11.13.8. Controllers/AuthController.cs

// =========================================================================
// Controllers/AuthController.cs
// -------------------------------------------------------------------------
// Die NICHT geschützten Routen des Logins:
//   GET  /        leitet zur Startseite der Rolle weiter (oder zu /login)
//   GET  /login   zeigt das Login-Formular an (mit seinem CAPTCHA)
//   POST /login   prüft Versuchslimit, CAPTCHA, Login / Passwort
//   POST /logout  löscht das Token-Cookie
//
// Ein MVC-Controller erbt von Controller und gibt ein IActionResult zurück:
// View(...) zeigt eine Seite an, Redirect(...) leitet um...
// [HttpGet("login")] / [HttpPost("login")]: "attribute routing",
// das Äquivalent zu @Get('login') / @Post('login').
//
// Schutz vor Robotern, in dieser Reihenfolge:
//   1. zu viele aktuelle Fehlversuche für diesen Login von dieser IP-Adresse?
//      -> sofortige Ablehnung, ohne das Passwort überhaupt anzusehen;
//   2. falsche Antwort auf das CAPTCHA? -> Ablehnung (zählt als Fehlversuch);
//   3. erst dann die Überprüfung des Passworts.
// Das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs prüfen wir NIE:
// Ein Roboter kann daher durch Beharrlichkeit nichts lernen.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Models;

namespace RdvMedecins.Controllers;

public class AuthController(
    AuthService authService,
    CaptchaService captchaService,
    AttemptLimiterService limiter) : Controller
{
    // die Startseite jeder Rolle, direkt nach dem Login
    public static string HomePage(Role role) => role == Role.USER ? "/my-area" : "/schedule";

    [HttpGet("/")]
    public IActionResult Home()
    {
        // User: der Benutzer der Anfrage, aus dem Token von der
        // Authentifizierungs-Middleware rekonstruiert (siehe Auth/ConnectedUser.cs)
        var user = User.CurrentUser();
        return Redirect(user is not null ? HomePage(user.Role) : "/login");
    }

    // GET /login[?login=xxx]: Der optionale Parameter füllt das Login-Feld
    // vor (verwendet direkt nach der Erstellung eines Kontos, siehe RegistrationController)
    [HttpGet("login")]
    public IActionResult ShowLogin(string? login)
    {
        // bereits angemeldet (Token noch gültig): direkt zur Startseite
        var user = User.CurrentUser();
        if (user is not null)
        {
            return Redirect(HomePage(user.Role));
        }
        return Form(login is null ? "" : login[..Math.Min(login.Length, 30)]);
    }

    // die Parameter der Action werden mit den gleichnamigen Formularfeldern
    // gefüllt (Model Binding); [FromForm] legt fest, dass sie im
    // Body der POST-Anfrage gesucht werden
    [HttpPost("login")]
    public async Task<IActionResult> LogIn(
        [FromForm] string? login,
        [FromForm] string? password,
        [FromForm] string? captchaId,
        [FromForm] string? captcha)
    {
        login = (login ?? "").Trim();
        password ??= "";
        var ip = IpAddress(HttpContext);

        // 1. zu viele aktuelle Fehlversuche?
        var minutes = limiter.LoginBlockMinutes(ip, login);
        if (minutes > 0)
        {
            return Form(login, "ERRORS.TOO_MANY_ATTEMPTS", new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }

        // 2. das CAPTCHA
        if (!captchaService.Verify(captchaId, captcha))
        {
            limiter.LoginFailure(ip, login);
            return Form(login, "ERRORS.WRONG_CAPTCHA");
        }

        // 3. das Passwort
        var user = login != "" && password != "" ? await authService.ValidateUserAsync(login, password) : null;
        if (user is null)
        {
            limiter.LoginFailure(ip, login);
            return Form(login, "LOGIN.ERROR");
        }

        limiter.LoginSuccess(ip, login);
        authService.SetToken(Response, user);
        return Redirect(HomePage(user.Role));
    }

    // Logout per POST (und nicht per einfachem GET-Link): Eine fremde Website kann
    // den Benutzer nicht ohne sein Wissen abmelden (siehe SameSite, AuthService)
    [HttpPost("logout")]
    public IActionResult LogOut()
    {
        AuthService.ClearToken(Response);
        return Redirect("/login");
    }

    // die IP-Adresse des Besuchers. Hinter einem Reverse-Proxy (nginx...) müsste die
    // UseForwardedHeaders-Middleware aktiviert werden, um die des
    // Besuchers und nicht die des Proxys zu erhalten.
    public static string IpAddress(HttpContext http) => http.Connection.RemoteIpAddress?.ToString() ?? "unknown";

    // das Formular, immer mit einem NEUEN CAPTCHA (jedes Bild wird nur einmal verwendet)
    private ViewResult Form(string login, string? error = null, IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Login", new LoginModel
        {
            PageTitle = "LOGIN.TITLE",
            Login = login, // wir zeigen das eingegebene Login erneut an, nie das Passwort
            Captcha = captchaService.Generate(),
            Error = error,
            ErrorParams = errorParams,
        });
}

Kommentieren wir diesen Code:

  • Zeilen 31–34: Der Controller erhält die drei Services, die er benötigt. Keine Attribute [[Authorize]]: Seine Seiten sind ohne Anmeldung zugänglich;
  • Zeile 37: Die Startseite hängt von der Rolle ab: „Mein Bereich“ für einen Patienten, der Terminkalender für die anderen;
  • Zeilen 39–45: Die Wurzel der Site leitet auf die rollenspezifische Startseite oder auf die Login-Seite um. Die Authentifizierungs-Middleware läuft für alle Anfragen, ob geschützt oder nicht: Enthält das Cookie ein gültiges Token, ist [User] auch hier gefüllt. Das [NestJS]-Projekt dagegen musste das Token selbst prüfen (Methode [readToken]), da die Token-Prüfung auf diese Route nicht angewendet wird;
  • Zeilen 50–59: Ein bereits angemeldeter Benutzer wird auf seine Startseite umgeleitet. Der optionale Parameter [login], der aus der URL stammt (siehe Beispiel 07), füllt das Feld nach dem Anlegen eines Kontos vor. [login[..n]] (Bereichsoperator) behält die ersten [n] Zeichen: Seine Länge wird auf 30 begrenzt, denn Daten aus der Anfrage werden nie ohne Vorsichtsmaßnahmen verwendet;
  • Zeilen 65–70: die Felder des Login-Formulars (siehe Beispiel 11), einschließlich der CAPTCHA-ID, die über ein verstecktes Feld übermittelt wird, und der Eingabe des Benutzers. Alle sind als [string?] deklariert: Ein fehlendes Feld ergibt [null], und die Action entscheidet, was damit geschieht;
  • Zeilen 72–74: Ein fehlender Login wird zu einer leeren Zeichenfolge; [password ??= ""] wirkt sich nur dann auf die leere Zeichenfolge aus, wenn [password] gleich [null] ist;
  • Zeilen 77–80: 1. Ein gesperrtes Paar wird gar nicht erst verarbeitet: Weder das CAPTCHA noch das Passwort wird geprüft. Der Fehler ist ein Übersetzungsschlüssel mit einem Parameter: der Anzahl der Minuten, die zu warten sind;
  • Zeilen 84–87: 2. das CAPTCHA. Ein falsches CAPTCHA zählt als Fehlschlag (siehe Beispiel 27);
  • Zeilen 91–95: 3. Erst dann wird das Passwort geprüft. Ein leerer Benutzername oder ein leeres Passwort wird der rechenaufwendigen [bcrypt]-Berechnung nicht unterzogen. Unbekannter Benutzername oder falsches Passwort: dieselbe bewusst vage Meldung (siehe Beispiel 25) und ein weiterer Fehlschlag;
  • Zeilen 98–100: Erfolg: Zähler auf null zurückgesetzt, Token im Cookie gespeichert, Umleitung auf die Startseite der Rolle;
  • Zeilen 105–109: Abmelden per POST (siehe Beispiel 25);
  • Zeile 115: die IP-Adresse des Clients, bereitgestellt von der Netzwerkverbindung ([RemoteIpAddress], die [null] sein kann, daher [?.] und [??]). Die Methode ist öffentlich und statisch: [RegistrationController] und [PatientAreaController] verwenden sie ebenfalls für den Limiter. Hinter einem zwischengeschalteten Server (einem Reverse-Proxy wie [nginx]) wäre diese Adresse die des Proxys: Der Kommentar nennt die in diesem Fall zu aktivierende Middleware;
  • Zeilen 118–125: die Login-Seite, stets mit einem neuen CAPTCHA: Jedes Bild wird nur einmal verwendet. Ihr Modell [LoginModel] (Ordner [Models]) enthält den Seitentitel (einen Übersetzungsschlüssel), den eingegebenen Benutzernamen (niemals das Passwort), das CAPTCHA und etwaige Fehlermeldungen samt Übersetzungsschlüssel und Parametern. [error] und [errorParams] sind optionale Parameter: Sie haben den Standardwert [null] , wenn der Aufruf sie nicht angibt.

11.14. Die Web-Schicht: gemeinsame Services

Bevor wir zu den Controllern und Views kommen, hier das, was ihnen gemeinsam ist: die Übersetzung, die Elternklasse der Views, Flash-Meldungen, der Exception-Filter, der Cache für die Listen der Ärzte und Kunden, die Aufbereitung von Formularen für die erneute Anzeige und einige Hilfsfunktionen. Alle diese Dateien liegen im Ordner [Web]. Er vereint die meisten Techniken der Beispiele 16 bis 24.

11.14.1. Web/Translator.cs

// =========================================================================
// Web/Translator.cs
// -------------------------------------------------------------------------
// Französische / englische Übersetzung der Oberfläche.
//
// Die Wörterbücher sind DIESELBEN Dateien wie die des NestJS-Projekts
// (i18n/fr.json, i18n/en.json), nur einmal beim Start gelesen. Eine
// Razor-View übersetzt einen Schlüssel mit @T("KEY") (siehe Web/ViewPage.cs).
//
// ASP.NET Core bietet auch ein eigenes System (IStringLocalizer und
// .resx-Dateien); die Beibehaltung der JSON-Dateien erlaubt es, die
// Wörterbücher mit den anderen Versionen der Anwendung zu teilen.
//
// DIE AKTUELLE SPRACHE: Sie wird von der Lokalisierungs-Middleware von ASP.NET Core
// (UseRequestLocalization, siehe Program.cs) bei jeder Anfrage ermittelt,
// anhand eines Cookies, und in CultureInfo.CurrentUICulture abgelegt.
// =========================================================================

using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;

namespace RdvMedecins.Web;

public partial class Translator
{
    public static readonly string[] Languages = ["fr", "en"];
    public const string DefaultLanguage = "en";

    // Sprache -> (vollständiger Schlüssel "LOGIN.TITLE" -> Text)
    private readonly Dictionary<string, Dictionary<string, string>> dictionaries = [];

    public Translator(IWebHostEnvironment environment)
    {
        foreach (var language in Languages)
        {
            var path = Path.Combine(environment.ContentRootPath, "i18n", $"{language}.json");
            using var document = JsonDocument.Parse(File.ReadAllText(path));
            var dictionary = new Dictionary<string, string>();
            Flatten(document.RootElement, "", dictionary);
            dictionaries[language] = dictionary;
        }
    }

    // die Sprache der aktuellen Anfrage: "fr" oder "en"
    public static string CurrentLanguage()
    {
        var language = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
        return Languages.Contains(language) ? language : DefaultLanguage;
    }

    // -----------------------------------------------------------------------
    // Translate("DOCTORS.ADDED", { ["name"] = "Marie PELISSIER" })
    //   -> sucht "DOCTORS.ADDED" im Wörterbuch der aktuellen Sprache
    //      und ersetzt {name} durch dessen Wert. Ein Schlüssel, der in der angeforderten
    //      Sprache fehlt, wird in der Standardsprache gesucht; fehlt er überall, wird
    //      der Schlüssel selbst angezeigt (ein Versäumnis fällt so sofort auf).
    // -----------------------------------------------------------------------
    public string Translate(string? key, IReadOnlyDictionary<string, string>? messageParams = null)
    {
        if (string.IsNullOrEmpty(key))
        {
            return "";
        }
        var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key)
                    ?? dictionaries[DefaultLanguage].GetValueOrDefault(key)
                    ?? key;
        if (messageParams is null || messageParams.Count == 0)
        {
            return text;
        }
        return Parameter().Replace(text, m => messageParams.TryGetValue(m.Groups[1].Value, out var value) ? value : m.Value);
    }

    // { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
    private static void Flatten(JsonElement node, string prefix, Dictionary<string, string> result)
    {
        foreach (var property in node.EnumerateObject())
        {
            var key = prefix == "" ? property.Name : $"{prefix}.{property.Name}";
            if (property.Value.ValueKind == JsonValueKind.Object)
            {
                Flatten(property.Value, key, result);
            }
            else
            {
                result[key] = property.Value.GetString() ?? "";
            }
        }
    }

    // der reguläre Ausdruck {name}, einmalig vom
    // C#-Compiler kompiliert ([GeneratedRegex] "source generator")
    [GeneratedRegex(@"\{(\w+)\}")]
    private static partial Regex Parameter();
}

Dies ist der Übersetzungsservice aus Beispiel 22, in [Program.cs] als Singleton registriert: Die Wörterbücher [i18n/fr.json] und [i18n/en.json] sind dieselben Dateien wie in der Version [NestJS] und werden nur einmal beim Start gelesen. Es gibt nur einen Unterschied:

  • Zeilen 65–67: Ein im französischen Wörterbuch fehlender Schlüssel wird im englischen Wörterbuch nachgeschlagen ([DefaultLanguage]); fehlt er überall, wird der Schlüssel selbst angezeigt. Die beiden [??]-Operatoren werden verkettet: Der erste Wert, der nicht [null] ist, wird genommen.

11.14.2. Web/ViewPage.cs

// =========================================================================
// Web/ViewPage.cs
// -------------------------------------------------------------------------
// Die Basisklasse ALLER Razor-Views der Anwendung (siehe
// Views/_ViewImports.cshtml: @inherits ViewPage<TModel>).
//
// Eine .cshtml-View wird in eine C#-Klasse kompiliert, Kind von RazorPage<TModel>.
// Durch das Einfügen unserer eigenen Klasse geben wir allen Views, was sie
// unabhängig von der Seite brauchen:
//   - @T("KEY")          : die Übersetzung eines Schlüssels (das Äquivalent des
//                          Handlebars-Helpers {{t 'KEY'}});
//   - Language           : "fr" oder "en";
//   - CurrentUser        : der angemeldete Benutzer, für die Navigationsleiste;
//   - FlashMessage       : die Flash-Nachricht der Anfrage;
//   - CurrentPath        : die angeforderte URL (aktives Menü der Navigationsleiste).
// In NestJS lief diese Information über res.locals.
// =========================================================================

using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;
using RdvMedecins.Auth;

namespace RdvMedecins.Web;

public abstract class ViewPage<TModel> : RazorPage<TModel>
{
    // [RazorInject]: Die Eigenschaft wird per Dependency Injection gefüllt,
    // wie es die @inject-Direktive in einer View tun würde
    [RazorInject]
    public Translator Translator { get; set; } = null!;

    // -----------------------------------------------------------------------
    // @T("BOOKING_DIALOG.SLOT", ("time", "8:00 - 8:20"))
    // Die Parameter sind "Tupel" (Name, Wert): eine kompakte Syntax,
    // um Wertepaare zu schreiben.
    // Der zurückgegebene Text wird dann von Razor MASKIERT (< wird zu &lt;): Ein
    // von einem Benutzer eingegebener Name kann daher kein HTML in die Seite einschleusen.
    // -----------------------------------------------------------------------
    public string T(string? key, params (string Name, object? Value)[] messageParams) =>
        Translator.Translate(key, messageParams.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));

    // dasselbe, mit den Parametern einer Flash-Nachricht oder einer BusinessException
    public string T(string? key, IReadOnlyDictionary<string, string>? messageParams) => Translator.Translate(key, messageParams);

    public string Language => Translator.CurrentLanguage();

    public ViewUser? CurrentUser => ViewUser.Of(Context.User.CurrentUser());

    public FlashMessage? FlashMessage => Flash.Read(Context);

    public string CurrentPath => Context.Request.Path.Value ?? "/";

    // "active", wenn die aktuelle Seite unter diesem Pfad liegt (Menü der Navigationsleiste)
    public string Active(string prefix) => CurrentPath.StartsWith(prefix, StringComparison.Ordinal) ? "active" : "";
}

// -------------------------------------------------------------------------
// der angemeldete Benutzer, wie die Views ihn sehen
// -------------------------------------------------------------------------
public record ViewUser(string Login, string Name, string Role, bool IsAdmin, bool IsPatient)
{
    public static ViewUser? Of(ConnectedUser? u) =>
        u is null
            ? null
            : new ViewUser(
                u.Login,
                u.Name,
                u.Role.ToString(),
                IsAdmin: u.Role == Entities.Role.ADMIN, // ADMIN: Menüs Ärzte / Patienten
                IsPatient: u.Role == Entities.Role.USER); // USER: Menü Mein Bereich
}

Gehen wir diesen Code durch:

  • Zeile 25: die Elternklasse aller Views, festgelegt durch die Direktive [@inherits] in [Views/_ViewImports.cshtml], wie in Beispiel 22. Sie erfüllt denselben Zweck wie [res.locals] in der Version [NestJS]: Sie stellt jeder View bereit, was alle Seiten benötigen;
  • Zeilen 29–30: der Übersetzungsservice, der in die Eigenschaft injiziert wird (siehe Beispiel 22);
  • Zeilen 39–40: die Methode [T] aus Beispiel 22: [@T("KEY", ("name", value))]. Der ausgegebene Text wird von [Razor] maskiert: Ein von einem Benutzer eingegebener Name kann kein HTML in die Seite einschleusen;
  • Zeile 43: eine zweite Version von [T], die direkt ein Wörterbuch akzeptiert: In dieser Form werden die Parameter einer Flash-Meldung oder einer [BusinessException] übergeben. Zwei Methoden mit demselben Namen, die sich in ihren Parametern unterscheiden, sind überladene Methoden: Der Compiler wählt anhand der Argumente die richtige aus;
  • Zeile 45: die aktuelle Sprache ([fr] oder [en]) für das Attribut [lang] der Seite und für FR / EN;
  • Zeile 47: der angemeldete Benutzer für die Navigationsleiste oder [null] , wenn es keinen gibt. [Context.User] ist der Benutzer der Anfrage, von der Authentifizierungs-Middleware aus dem JWT-Token rekonstruiert (siehe Kapitel 8); die Methode [CurrentUser()] (Datei [Auth/ConnectedUser.cs]) extrahiert daraus das Konto. In der Version [NestJS] war ein Interceptor erforderlich, um [req.user] nach den Guards in [res.locals] zu kopieren; hier wird die Eigenschaft berechnet, wenn die View sie liest, also lange nach der Authentifizierung;
  • Zeile 49: die Flash-Meldung der Anfrage (siehe [Web/Flash.cs], unten);
  • Zeilen 51–54: der Pfad der angeforderten URL und die Methode, die [active] zurückgibt, wenn die aktuelle Seite unterhalb eines bestimmten Pfades liegt: So hebt die Navigationsleiste den aktuellen Menüpunkt hervor, zum Beispiel [@Active("/my-")] (siehe Beispiel 16). [StringComparison.Ordinal] vergleicht Zeichen für Zeichen, unabhängig von der Sprache;
  • Zeilen 60–70: der angemeldete Benutzer, wie ihn die Views sehen: Login, Name, Rolle und zwei boolesche Werte, [IsAdmin] und [IsPatient], die den Views Rollenvergleiche ersparen. Die statische Methode [Of] erzeugt dieses Objekt aus dem angemeldeten Konto oder gibt [null] zurück; der Operator [? :] wählt zwischen beiden. Die Argumente [IsAdmin:] und [IsPatient:] sind benannt: Der Parametername steht vor dem Wert, was den Aufruf lesbarer macht.

11.14.3. Web/Flash.cs

// =========================================================================
// Web/Flash.cs
// -------------------------------------------------------------------------
// Die "Flash"-Nachrichten: eine Nachricht, die EINMAL auf der
// NÄCHSTEN Seite angezeigt wird. Sie ist die natürliche Ergänzung des Musters
// "Post / Redirect / Get", das alle Formulare der Anwendung verwenden: Ein erfolgreicher POST
// baut keine Seite auf, sondern leitet (302) auf eine GET-Seite um - lädt
// der Benutzer diese Seite dann neu (F5), sendet der Browser das
// Formular nicht ein zweites Mal. Die Nachricht muss die
// Umleitung jedoch überleben.
//
// In NestJS hatten wir es selbst programmiert (ein kurzlebiges Cookie).
// ASP.NET Core MVC bietet es standardmäßig: TempData. Ein in
// TempData gespeicherter Wert bleibt erhalten (standardmäßig in einem verschlüsselten Cookie), bis
// eine folgende Anfrage ihn LIEST; dann wird er gelöscht.
// =========================================================================

using System.Text.Json;
using Microsoft.AspNetCore.Mvc.ViewFeatures;

namespace RdvMedecins.Web;

public enum FlashType
{
    Success, // Bootstrap-Klasse alert-success: oben auf der Seite
    Danger, // ein Fehler: unten auf der Seite (siehe Views/Shared/_Errors.cshtml)
}

// Key: Übersetzungsschlüssel; Params: seine Parameter ({name}, {login}...)
public record FlashMessage(FlashType Type, string Key, Dictionary<string, string>? Params = null);

public static class Flash
{
    private const string Key = "flash";

    // -----------------------------------------------------------------------
    // legt eine Flash-Nachricht ab, die von der NÄCHSTEN Seite angezeigt wird.
    // Wir gehen über ITempDataDictionaryFactory (und nicht über die TempData-Eigenschaft
    // eines Controllers), um eine Nachricht von ÜBERALL ablegen zu können:
    // von einem Controller, aber auch von der JWT-Authentifizierung (abgelaufene Sitzung, siehe
    // Auth/JwtAuthentication.cs), die außerhalb von MVC läuft.
    // -----------------------------------------------------------------------
    public static void Put(HttpContext http, FlashType type, string key, Dictionary<string, string>? messageParams = null)
    {
        var tempData = TempDataOf(http);
        // TempData kann nur einfache Werte speichern: Wir speichern die
        // Nachricht als JSON-Text
        tempData[Key] = JsonSerializer.Serialize(new FlashMessage(type, key, messageParams));
        // Save(): schreibt das Cookie sofort (außerhalb von MVC würde es
        // niemand für uns tun)
        tempData.Save();
    }

    // -----------------------------------------------------------------------
    // liest (und löscht damit) die Flash-Nachricht der Anfrage. Die Seite darf
    // sie mehrfach anfordern (die Erfolgsmeldung wird oben angezeigt, die
    // Fehlermeldung unten): Wir halten sie in HttpContext.Items, einem Dictionary,
    // das für die Dauer der Anfrage lebt.
    // -----------------------------------------------------------------------
    public static FlashMessage? Read(HttpContext http)
    {
        if (http.Items.TryGetValue(Key, out var alreadyRead))
        {
            return alreadyRead as FlashMessage;
        }
        FlashMessage? message = null;
        if (TempDataOf(http)[Key] is string json)
        {
            try
            {
                message = JsonSerializer.Deserialize<FlashMessage>(json);
            }
            catch (JsonException)
            {
                // nicht lesbare Nachricht: wir ignorieren sie
            }
        }
        http.Items[Key] = message;
        return message;
    }

    private static ITempDataDictionary TempDataOf(HttpContext http) =>
        http.RequestServices.GetRequiredService<ITempDataDictionaryFactory>().GetTempData(http);
}

Kommentieren wir diesen Code:

  • Zeilen 23–26: die beiden Meldungsarten: eine Erfolgsmeldung, die oben auf der Seite angezeigt wird (Partial View [_Flash.cshtml]), und eine Fehlermeldung, die unten angezeigt wird (Partial View [_Errors.cshtml]);
  • Zeile 30: Eine Flash-Meldung besteht aus einem Übersetzungsschlüssel und seinen Parametern, nicht aus vorab übersetztem Text; sie wird auf der nächsten Seite in deren Sprache übersetzt;
  • Zeile 32: eine statische Klasse, die nur Funktionen enthält (siehe [Web/Utils.cs]). [TempData] (siehe Beispiel 20) erledigt den Großteil der Arbeit: Es speichert den Wert in einem verschlüsselten Cookie bis zur nächsten Anfrage und löscht ihn, sobald er gelesen wurde. In der [NestJS]-Version wurde dieses kurzlebige Cookie von Hand programmiert;
  • Zeilen 43–51: setzt eine Meldung. [TempData] kann nur einfache Werte speichern (Text, Zahlen): Die Meldung wird als JSON-Text gespeichert ([JsonSerializer.Serialize]). Die Methode erhält den [HttpContext] und nicht die Eigenschaft [TempData] eines Controllers: Sie kann daher von außerhalb von MVC aufgerufen werden, zum Beispiel von der JWT-Authentifizierung, wenn eine Sitzung abgelaufen ist (siehe [Auth/JwtAuthentication.cs]). Außerhalb von MVC würde niemand [TempData] am Ende der Anfrage speichern: [Save()] schreibt das Cookie sofort;
  • Zeilen 60–79: liest die Meldung der Anfrage. Das Lesen von [TempData] markiert sie als verbraucht; die Seite fordert sie jedoch zweimal an (oben für einen Erfolg, unten für einen Fehler). Der erste Aufruf speichert das Ergebnis daher in [HttpContext.Items], dem Wörterbuch im Anfragebereich (siehe Kapitel 6), aus dem der zweite Aufruf es abruft (Zeile 62);
  • Zeilen 71–73: [Deserialize] rekonstruiert das Objekt [FlashMessage] aus JSON. Ein unlesbarer Text darf die Seite nicht scheitern lassen: Die Ausnahme wird abgefangen und die Meldung ignoriert;
  • Zeilen 82–83: das [TempData] der Anfrage, bezogen vom Service [ITempDataDictionaryFactory]. [RequestServices] bietet aus einer statischen Klasse, die keine Services über ihren Konstruktor erhalten kann, Zugriff auf Dependency Injection.

11.14.4. Web/HtmlExceptionFilter.cs

// =========================================================================
// Web/HtmlExceptionFilter.cs
// -------------------------------------------------------------------------
// Wie aus Fehlern HTML-Seiten werden. Drei Mechanismen
// von ASP.NET Core teilen sich die Arbeit (siehe Program.cs):
//
//   1. dieser MVC-Exception-Filter: eine InvalidSessionException (seit dem Login
//      gelöschtes Konto) -> zurück zur Login-Seite;
//   2. UseStatusCodePagesWithReExecute("/error/{0}"): jede 400-,
//      403- oder 404-Antwort OHNE Inhalt (return BadRequest(), unzureichende Rolle, unbekannte
//      Seite...) wird durch die entsprechende Fehlerseite ersetzt;
//   3. UseExceptionHandler("/error/500"): jede andere Exception (eine echte
//      Anomalie) wird ins Server-Log geschrieben, und der Benutzer
//      sieht die Fehlerseite 500 - nie den Aufrufstapel.
//
// In NestJS erledigte ein einziger Filter (HtmlExceptionFilter) all dies.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using RdvMedecins.Auth;

namespace RdvMedecins.Web;

public class HtmlExceptionFilter : IExceptionFilter
{
    public void OnException(ExceptionContext context)
    {
        if (context.Exception is InvalidSessionException)
        {
            AuthService.ClearToken(context.HttpContext.Response);
            Flash.Put(context.HttpContext, FlashType.Danger, "ERRORS.SESSION_EXPIRED");
            context.Result = new RedirectResult("/login");
            context.ExceptionHandled = true;
        }
        // die anderen Exceptions werden hier nicht behandelt: Sie steigen
        // bis zu UseExceptionHandler auf (Seite 500)
    }
}

Kommentieren wir diesen Code:

  • Zeile 25: Ein Exception-Filter, wie in Beispiel 24, als globaler Filter in [Program.cs] hinzugefügt. In der Version [NestJS] wandelte ein einziger Filter alle Fehler in HTML-Seiten um. Hier teilen sich zwei Middleware-Komponenten des Frameworks die Arbeit, konfiguriert in [Program.cs]: [UseStatusCodePagesWithReExecute] ersetzt Antworten 400, 403 und 404 ohne Inhalt durch die entsprechende Fehlerseite (siehe Beispiel 24), und [UseExceptionHandler("/error/500")] fängt alle übrigen Ausnahmen ab: Der Fehler wird samt Aufrufstapel im Serverprotokoll festgehalten, der Benutzer sieht jedoch nur die 500-Fehlerseite, da diese Details einem Angreifer helfen könnten;
  • Zeilen 29–34: Der Filter behandelt nur ein Szenario: Das Konto des angemeldeten Benutzers wurde seit der Anmeldung gelöscht, obwohl sein Token noch gültig ist (siehe [Web/Utils.cs] weiter unten). Das Token-Cookie wird gelöscht, eine Flash-Meldung „Sitzung abgelaufen“ wird angezeigt, und der Benutzer wird zur Anmeldeseite umgeleitet. Die übrigen Ausnahmen werden nicht als behandelt markiert: Sie gelangen weiter zu [UseExceptionHandler].

11.14.5. Web/ApplicationModel.cs

// =========================================================================
// Web/ApplicationModel.cs
// -------------------------------------------------------------------------
// Der Cache / die Fassade, die bereits im JSON-Server vorhanden ist (Äquivalent der
// Klasse [ApplicationModel] des Spring-Projekts): Die Listen der Ärzte und
// Clients werden einmal beim Start gelesen und dann aus dem Speicher bereitgestellt.
//
// Diese Listen können sich ÄNDERN (der ADMIN fügt Ärzte und Clients hinzu,
// bearbeitet und löscht sie): Jeder Schreibzugriff läuft daher über diese Fassade,
// die die betroffene Liste anschließend neu lädt. Das ist der ganze Sinn eines
// EINZIGEN Einstiegspunkts in die Geschäftsschicht: Die Regel "Schreiben =>
// Cache neu laden" steht nur hier.
//
// Wichtiger Unterschied zu NestJS: die LEBENSDAUER der Objekte.
//   - In NestJS waren alle Services Singletons.
//   - Hier lebt der DbContext - und damit die Repositories und die Geschäftsschicht -
//     für die Dauer EINER HTTP-Anfrage (Lebensdauer "scoped", siehe Program.cs).
//   - Der Cache muss aber von einer Anfrage zur nächsten bestehen bleiben.
// Wir trennen daher die beiden Rollen:
//   - ListCache (Singleton): die beiden Listen, sonst nichts;
//   - ApplicationModel (scoped): die Fassade, die die Geschäftsschicht der
//     aktuellen Anfrage nutzt und den Cache aktualisiert.
// =========================================================================

using RdvMedecins.Domain;
using RdvMedecins.Entities;
using RdvMedecins.Business;

namespace RdvMedecins.Web;

// -------------------------------------------------------------------------
// Der Cache selbst, von allen Anfragen gemeinsam genutzt (Singleton).
//
// ASP.NET Core verarbeitet die Anfragen PARALLEL, auf mehreren Threads (Node
// hat dagegen nur einen). Wir ändern daher nie eine Liste an Ort und Stelle: Wir
// ERSETZEN sie vollständig durch eine neue. Das Austauschen einer Referenz ist atomar;
// "volatile" garantiert, dass alle Threads die neue Liste sofort sehen.
// -------------------------------------------------------------------------
public class ListCache
{
    private volatile IReadOnlyList<Doctor> doctors = [];
    private volatile IReadOnlyList<Client> clients = [];

    public IReadOnlyList<Doctor> Doctors
    {
        get => doctors;
        set => doctors = value;
    }

    public IReadOnlyList<Client> Clients
    {
        get => clients;
        set => clients = value;
    }
}

// -------------------------------------------------------------------------
// Die Fassade (scoped): derselbe Vertrag wie die Geschäftsschicht (IBusiness).
// -------------------------------------------------------------------------
public class ApplicationModel(IBusiness business, ListCache cache) : IBusiness
{
    // initiales Laden der beiden Listen, einmal beim Start aufgerufen
    // (siehe Program.cs). Ist die Datenbank nicht erreichbar, stoppt die Exception den
    // Server mit einer eindeutigen Meldung - klarer als ein Start "leer".
    public async Task LoadAsync()
    {
        await ReloadDoctorsAsync();
        await ReloadClientsAsync();
    }

    private async Task ReloadDoctorsAsync() => cache.Doctors = await business.GetAllDoctorsAsync();

    private async Task ReloadClientsAsync() => cache.Clients = await business.GetAllClientsAsync();

    // ──────────────────────────────────────────────── Lesezugriffe aus dem Cache

    public Task<List<Doctor>> GetAllDoctorsAsync() => Task.FromResult(cache.Doctors.ToList());

    public Task<List<Client>> GetAllClientsAsync() => Task.FromResult(cache.Clients.ToList());

    // der Arzt, dessen Benutzerkonto [userId] ist - dient dazu, für einen
    // angemeldeten Arzt dessen eigenen Terminkalender vorauszuwählen
    public Doctor? GetDoctorByUserId(int userId) => cache.Doctors.FirstOrDefault(d => d.UserId == userId);

    // ──────────────────────────────────────────────── einfache Delegationen

    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) => business.GetAllSlotsAsync(doctorId);

    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) => business.GetDoctorDayAppointmentsAsync(doctorId, day);

    public Task<Client?> GetClientByIdAsync(int id) => business.GetClientByIdAsync(id);

    public Task<Doctor?> GetDoctorByIdAsync(int id) => business.GetDoctorByIdAsync(id);

    public Task<Appointment?> GetAppointmentByIdAsync(int id) => business.GetAppointmentByIdAsync(id);

    public Task<Slot?> GetSlotByIdAsync(int id) => business.GetSlotByIdAsync(id);

    public Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day) =>
        business.GetDoctorDayScheduleAsync(doctorId, day);

    // kein Cache hier: Es kommt auf die aktuellsten Daten an (ein Patient,
    // der gerade sein Konto bearbeitet oder gelöscht hat)
    public Task<Client?> GetClientByUserIdAsync(int userId) => business.GetClientByUserIdAsync(userId);

    public Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId) => business.GetClientUpcomingAppointmentsAsync(clientId);

    public Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client) => business.AddAppointmentAsync(day, slot, client);

    public Task DeleteAppointmentAsync(Appointment appointment) => business.DeleteAppointmentAsync(appointment);

    // ──────────────────────────────────────────────── Schreibzugriffe => Neuladen

    public async Task<Doctor> AddDoctorAsync(PersonData data)
    {
        var doctor = await business.AddDoctorAsync(data);
        await ReloadDoctorsAsync();
        return doctor;
    }

    public async Task<Doctor> EditDoctorAsync(int id, PersonData data)
    {
        var doctor = await business.EditDoctorAsync(id, data);
        await ReloadDoctorsAsync();
        return doctor;
    }

    public async Task DeleteDoctorAsync(int id)
    {
        await business.DeleteDoctorAsync(id);
        await ReloadDoctorsAsync();
    }

    public async Task<Client> AddClientAsync(PersonData data)
    {
        var client = await business.AddClientAsync(data);
        await ReloadClientsAsync();
        return client;
    }

    public async Task<Client> EditClientAsync(int id, PersonData data)
    {
        var client = await business.EditClientAsync(id, data);
        await ReloadClientsAsync();
        return client;
    }

    public async Task DeleteClientAsync(int id)
    {
        await business.DeleteClientAsync(id);
        await ReloadClientsAsync();
    }
}

Listen von Ärzten und Clients werden auf fast jeder Seite angezeigt (Dropdown-Listen des Terminkalenders, Verwaltungsseiten). Statt sie bei jeder Anfrage aus der Datenbank abzurufen, werden sie im Speicher gehalten: Es handelt sich um Daten mit Anwendungsbereich (siehe Kapitel 6). In der Version mit [NestJS] übernahm ein einzelner Service diese Rolle, der wie alle [NestJS]-Services ein Singleton war. In [ASP.NET Core] ist das nicht möglich: Die Geschäftsschicht verwendet [DbContext], der nur für die Dauer einer Anfrage existiert ([Scoped]-Service; siehe Kapitel 9), und ein Singleton kann keinen [Scoped]-Service entgegennehmen. Wir trennen daher die beiden Rollen in zwei Klassen.

Kommentieren wir diesen Code:

  • Zeile 39: der Cache selbst, als Singleton registriert ([AddSingleton<ListCache>()] in [Program.cs]). Er enthält nur die beiden Listen;
  • Zeilen 41–42: [ASP.NET Core] verarbeitet Anfragen parallel auf mehreren Threads ([threads]), während [Node.js] nur einen hat. Eine gemeinsam genutzte Liste darf daher niemals verändert werden, während eine andere Anfrage sie durchläuft. Die gewählte Regel ist einfach: Wir verändern nie eine Liste, sondern ersetzen sie durch eine neue. Das Ersetzen einer Referenz erfolgt in einer einzigen Operation, und das Schlüsselwort [volatile] stellt sicher, dass alle Threads die neue Liste sofort sehen. [IReadOnlyList] erlaubt nur das Lesen: Der Compiler verbietet das Hinzufügen oder Entfernen eines Elements;
  • Zeile 60: die Fassade, registriert als [Scoped]-Service ([AddScoped<ApplicationModel>()]). Sie erhält die Geschäftsschicht der aktuellen Anfrage und den gemeinsamen Cache. Sie implementiert dieselbe Schnittstelle [IBusiness] wie die Geschäftsschicht: Für die Controller ist sie die Geschäftsschicht, und sie ist die einzige, die sie erhalten;
  • Zeilen 65–68: das initiale Laden der beiden Listen. Es wird einmal von [Program.cs] aufgerufen, bevor der Server startet. Ein [Scoped]-Service existiert nur innerhalb eines Gültigkeitsbereichs: [Program.cs] erstellt zu diesem Zweck einen ([CreateScope]). Ist die Datenbank nicht erreichbar, beendet die Ausnahme die Anwendung mit einer eindeutigen Meldung, was besser ist, als einen Server mit leeren Listen zu starten;
  • Zeilen 71–73: Neuladen einer Liste: Die gesamte Liste wird aus der Datenbank gelesen und ersetzt die im Cache befindliche;
  • Zeilen 77–79: Die Listen werden aus dem Speicher geliefert. Die Schnittstelle [IBusiness] deklariert eine asynchrone Methode: [Task.FromResult] erstellt eine bereits abgeschlossene Task, die das Ergebnis enthält. [ToList()] liefert eine Kopie der Liste: Der Aufrufer kann sie ändern, ohne den Cache zu beeinflussen;
  • Zeile 83: der einem Konto zugeordnete Arzt, aus dem Cache abgerufen: Ein angemeldeter Arzt sieht sofort seinen eigenen Terminkalender;
  • Zeilen 87–110: Die übrigen Anfragen werden unverändert an die Geschäftsschicht weitergeleitet;
  • Zeile 104: Ein einem Konto zugeordneter Client wird absichtlich nicht im Cache gesucht; ein Patient, der soeben sein Konto geändert oder gelöscht hat, muss so angezeigt werden, wie er in der Datenbank steht;
  • Zeilen 114–151: Auf jede Schreiboperation, die Ärzte oder Clients betrifft, folgt eine Aktualisierung der betreffenden Liste. Da dieser Service der einzige Zugangspunkt der Controller zur Geschäftsschicht ist, wird die Regel „Schreiben = Cache aktualisieren“ nur hier umgesetzt, und der Cache kann nicht veralten. Lehnt die Geschäftsschicht die Operation ab ([BusinessException]), beendet die Ausnahme die Methode, bevor der Cache neu geladen wird, da dieser Schritt dann nicht mehr nötig ist.

11.14.6. Web/Validation.cs

// =========================================================================
// Web/Validation.cs
// -------------------------------------------------------------------------
// Was nötig ist, um ein abgelehntes Formular ERNEUT anzuzeigen: die Eingabefehler
// Feld für Feld und die rot zu umrandenden Felder.
// =========================================================================

using Microsoft.AspNetCore.Mvc.ModelBinding;
using RdvMedecins.Models;

namespace RdvMedecins.Web;

public static class Validation
{
    // -----------------------------------------------------------------------
    // ModelState (von MVC beim Binding des Formulars gefüllt) -> das
    // Dictionary Feld -> Nachrichtenschlüssel, das nur die erste
    // Nachricht jedes Feldes behält: { "LastName": "ERRORS.LASTNAME_REQUIRED", ... }
    // -----------------------------------------------------------------------
    public static Dictionary<string, string> ErrorsOf(ModelStateDictionary modelState)
    {
        var errors = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        foreach (var (field, entry) in modelState)
        {
            if (entry.Errors.Count > 0)
            {
                var message = entry.Errors[0].ErrorMessage;
                errors[field] = string.IsNullOrEmpty(message) ? "ERRORS.INVALID_FORM" : message;
            }
        }
        return errors;
    }

    // -----------------------------------------------------------------------
    // die von jedem fachlichen "Eingabe"-Fehler (ein Duplikat) betroffenen Formularfelder:
    // Sie werden rot umrandet, die Nachricht steht unten auf der Seite
    // -----------------------------------------------------------------------
    public static readonly Dictionary<string, string[]> BusinessErrorFields = new()
    {
        ["ERRORS.LOGIN_TAKEN"] = ["login"],
        ["ERRORS.DOCTOR_ALREADY_EXISTS"] = ["firstName", "lastName"],
        ["ERRORS.PATIENT_ALREADY_EXISTS"] = ["firstName", "lastName"],
    };

    // -----------------------------------------------------------------------
    // bereitet ein Formularmodell für seine (erneute) Anzeige vor:
    //   errors       : Nachricht unter jedem von der Validierung abgelehnten Feld
    //   error        : DIE Fehlermeldung der Seite, unten auf der Seite angezeigt;
    //                  standardmäßig "The form contains errors.", wenn
    //                  es Feldfehler gibt
    //   otherFields  : rot zu umrandende Felder OHNE eigene Nachricht
    // -----------------------------------------------------------------------
    public static T Prepare<T>(
        T model,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) where T : FormView
    {
        model.Errors = errors ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        model.InvalidFields = new HashSet<string>(model.Errors.Keys.Concat(otherFields ?? []), StringComparer.OrdinalIgnoreCase);
        model.Error = error ?? (model.Errors.Count > 0 ? "ERRORS.INVALID_FORM" : null);
        model.ErrorParams = errorParams;
        return model;
    }
}

Kommentieren wir diesen Code:

  • Zeilen 20–31: Wandelt [ModelState] (siehe Beispiele 07 und 19) in ein einfaches Wörterbuch „Feld → Meldungsschlüssel“ um. Nur die erste Meldung jedes Feldes wird beibehalten: Unter dem Feld wird eine einzelne Meldung angezeigt. Das Wörterbuch ignoriert die Groß- und Kleinschreibung (Zeile 22): [ModelState] benennt die Felder nach den Eigenschaften ([LastName], [Login]), während die Views sie nach den HTML-Feldern ([lastName], [login]) anfordern;
  • Zeilen 27–28: Vorsichtshalber erhält ein Fehler ohne Meldung (etwa einer, der durch eine Ausnahme verursacht wurde) die generische Meldung [ERRORS.INVALID_FORM];
  • Zeilen 38–42: Bestimmte Fehler der Geschäftsschicht betreffen bestimmte Felder: ein bereits vergebener Benutzername oder ein Arzt oder Client mit demselben Namen. Diese Felder werden rot hervorgehoben, die Meldung wird am Seitenende angezeigt. Die Syntax [["key"] = value] füllt das Wörterbuch bereits bei seiner Erstellung;
  • Zeilen 53–64: bereitet ein Formular-Template für die Anzeige oder erneute Anzeige vor: die Meldungen unter den Feldern ([Errors]), die rot zu umrahmenden Felder ([InvalidFields]: diejenigen mit einer Meldung sowie die [otherFields]-Felder, Zeile 61), die Meldung am Seitenende und ihre Parameter. Fehlt eine ausdrückliche Meldung, führen Feldfehler zur Meldung „Das Formular enthält Fehler“ (Zeile 62). Die Methode ist generisch: Die Einschränkung [where T : FormView] (Zeile 58) akzeptiert jedes Modell, das von [FormView] abgeleitet ist (siehe [Models/ViewModels.cs]), und sie gibt das Modell mit seinem exakten Typ zurück, bereit zur Übergabe an [View]. Die Parameter haben Standardwerte ([= null]): Der Aufrufer gibt nur die an, die er benötigt.

11.14.7. Web/Utils.cs

// =========================================================================
// Web/Utils.cs
// -------------------------------------------------------------------------
// Kleine Hilfsfunktionen der Web-Schicht:
//   - Labels   : "Mme Alice DURAND";
//   - WebDates : Datumsangaben "yyyy-MM-dd", Uhrzeiten "8:05", Tage "Wednesday 23 September 2026";
//   - Input    : Lesen einer vom Browser gesendeten positiven ganzen Zahl;
//   - Patient  : der Patient (Entität Client) des angemeldeten Benutzers.
//
// "static"-Klassen: Sie enthalten nur Funktionen, wir erzeugen nie
// ein Objekt dieser Klassen.
// =========================================================================

using System.Globalization;
using System.Security.Claims;
using RdvMedecins.Auth;
using RdvMedecins.Entities;

namespace RdvMedecins.Web;

public static class Labels
{
    // "Mme Alice DURAND"
    public static string Label(Person p) => $"{p.Title} {p.FirstName} {p.LastName}";
}

public static class WebDates
{
    // das Format der Datumsangaben in den URLs und im Feld <input type="date">
    public const string IsoFormat = "yyyy-MM-dd";

    // true, wenn [day] ein existierendes Datum im Format yyyy-MM-dd ist
    // ("2026-02-30" wird abgelehnt)
    public static bool IsValidDate(string? text, out DateOnly day) =>
        DateOnly.TryParseExact(text, IsoFormat, CultureInfo.InvariantCulture, DateTimeStyles.None, out day);

    public static string Iso(DateOnly day) => day.ToString(IsoFormat, CultureInfo.InvariantCulture);

    // "8:05" statt "8:5"
    public static string FormatTime(int h, int m) => $"{h}:{m:00}";

    public static string Time(Slot s) => $"{FormatTime(s.StartHour, s.StartMinute)} - {FormatTime(s.EndHour, s.EndMinute)}";

    // "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", je nach
    // Sprache der Anfrage (CultureInfo.CurrentCulture, von der
    // Lokalisierungs-Middleware gesetzt - siehe Program.cs)
    public static string FormatDay(DateOnly day) =>
        day.ToString("dddd d MMMM yyyy", CultureInfo.CurrentCulture);
}

public static class Input
{
    // "3" -> 3 ; "", "abc", "-2", null -> null
    public static int? PositiveInteger(string? value) =>
        int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var n) && n > 0 ? n : null;
}

public static class Patient
{
    // -----------------------------------------------------------------------
    // Der Patient (Entität Client), der dem angemeldeten Benutzer entspricht.
    //
    // Das JWT-Token enthält nur die ID des KONTOS (users.id). Für eine
    // Rolle USER finden wir den zugehörigen Client über die Spalte clients.user.
    //
    // Gibt es keinen, wurde das Konto seit dem Login gelöscht,
    // während sein Token noch gültig ist: Wir behandeln das wie eine
    // abgelaufene Sitzung (siehe InvalidSessionException).
    // -----------------------------------------------------------------------
    public static async Task<Client> ConnectedPatientAsync(ApplicationModel application, ClaimsPrincipal user)
    {
        var currentUser = user.CurrentUser() ?? throw new InvalidSessionException();
        return await application.GetClientByUserIdAsync(currentUser.UserId) ?? throw new InvalidSessionException();
    }
}

Gehen wir diesen Code durch:

  • Zeile 24: der Name eines Arztes oder eines Clients: „Mme Alice DURAND“. Der Parameter hat den Typ [Person], die Elternklasse der Entitäten [Doctor] und [Client]: Dieselbe Funktion wird für beide verwendet;
  • Zeile 30: das Datumsformat in den URL-Entitäten und im [<input type="date">]-Feld;
  • Zeilen 34–35: wahr, wenn der Text ein existierendes Datum im Format [yyyy-MM-dd] ist; [2026-02-30] wird abgelehnt (siehe Beispiel 12). Das Ergebnis wird im Parameter [out day] zurückgegeben. [CultureInfo.InvariantCulture] macht die Analyse unabhängig von der Sprache der Anfrage;
  • Zeile 37: die Umkehroperation: ein Datum in den Text [yyyy-MM-dd];
  • Zeilen 40–42: eine Uhrzeit im Format [8:05] (das Format [00] verlangt zwei Ziffern für die Minuten) und die Zeit eines Zeitfensters: [8:00 - 8:20];
  • Zeilen 47–48: ein ausgeschriebener Tag gemäß der Sprachumgebung der Anfrage, wie sie von der Lokalisierungs-Middleware bestimmt wird (siehe Beispiel 22): „mercredi 23 septembre 2026“ oder „Wednesday 23 September 2026“;
  • Zeilen 54–55: ein vom Browser gesendeter Bezeichner (in der URL oder in einem Formularfeld): eine streng positive ganze Zahl oder [null]. [NumberStyles.None] akzeptiert nur Ziffern: keine Vorzeichen, Leerzeichen oder Tausendertrennzeichen. Der Controller muss lediglich auf [null] prüfen;
  • Zeilen 70–73: der dem angemeldeten Benutzer zugeordnete Patient (Entität [Client]). Das JWT-Token enthält nur die Konto-ID; wir suchen den zu diesem Konto gehörenden Client. Existiert er nicht mehr, wurde das Konto seit der Anmeldung des Benutzers gelöscht: [InvalidSessionException] wird vom oben beschriebenen Filter [HtmlExceptionFilter] verarbeitet, der zur Anmeldeseite umleitet. [?? throw] löst eine Ausnahme aus, wenn der Wert auf der linken Seite [null] ist (siehe Kapitel 9).

11.15. Formular- und View-Templates

Zwei Arten von Klassen transportieren Daten zwischen Browser, Controllern und Views: Formulare, die vom Model Binding anhand dessen befüllt werden, was der Browser sendet, und View-Modelle, die von den Controllern für die Views vorbereitet werden. Erstere entsprechen den DTO-Objekten in der Version mit [NestJS], letztere den an [res.render] übergebenen Objekten.

11.15.1. Models/Forms.cs

// =========================================================================
// Models/Forms.cs
// -------------------------------------------------------------------------
// Die Felder der "Personen"-Formulare und ihre Einschränkungen. Drei
// Formulare teilen sich dieselben Identitätsfelder (Anrede, Vorname, Nachname):
//
//   PersonFields                  Anrede, Vorname, Nachname
//    ├─ PersonForm                + OPTIONALES Login / Passwort, Version
//    │                              (der ADMIN fügt einen Arzt / Client hinzu oder bearbeitet ihn)
//    ├─ RegistrationForm          + ERFORDERLICHES Login / Passwort / Bestätigung
//    │                              (ein Patient erstellt sein Konto)
//    └─ MyAccountForm             + Login, optionales neues Passwort,
//                                   ERFORDERLICHES AKTUELLES Passwort, Version
//                                   (ein Patient bearbeitet sein Konto)
//
// MODEL BINDING: Wenn eine Controller-Action einen
// Parameter einer dieser Klassen erhält, erzeugt ASP.NET Core MVC das Objekt und
// füllt jede Eigenschaft mit dem gleichnamigen Formularfeld (unabhängig
// von der Groß-/Kleinschreibung: Das Feld "lastName" füllt die Eigenschaft LastName).
//
// VALIDIERUNG: Gleich danach prüft MVC die Attribute [Required],
// [MaxLength]... (Standard-Namespace System.ComponentModel.DataAnnotations,
// das Äquivalent zu class-validator) und legt die Fehler in ModelState ab.
// Der Controller muss nur noch ModelState.IsValid testen.
//
// Die Fehlermeldungen sind Übersetzungs-SCHLÜSSEL (siehe i18n/*.json).
//
// EINGABEBEREINIGUNG (das Äquivalent zu @Transform von class-transformer):
//   - MVC wandelt ein leeres Feld bereits in null um;
//   - die Setter unten entfernen überflüssige Leerzeichen und setzen das
//     Login in Kleinbuchstaben. Ein Passwort wird dagegen nicht "bereinigt" (die
//     Leerzeichen können Teil davon sein).
// Alle Eigenschaften sind "nullable" (string?): Ein Feld kann in dem, was der
// Browser sendet, immer fehlen; erst [Required] verlangt es.
// =========================================================================

using System.ComponentModel.DataAnnotations;

namespace RdvMedecins.Models;

public static class InputRules
{
    public static readonly string[] Titles = ["Mr", "Mme", "Melle"];

    // Login: Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich - höchstens 30 Zeichen
    public const string LoginFormat = "^[a-z0-9._-]{1,30}$";

    // Mindestlänge eines von einem Patienten GEWÄHLTEN Passworts
    public const int PasswordMin = 6;

    // "  dupont " -> "dupont" ; "   " -> null
    public static string? Clean(string? value) => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
}

// -------------------------------------------------------------------------
// Ein "selbstgebasteltes" Validierungsattribut: Der Wert muss zu einer Liste gehören.
// Es genügt, von ValidationAttribute zu erben und IsValid zu schreiben.
// -------------------------------------------------------------------------
public class OneOfAttribute(params string[] values) : ValidationAttribute
{
    // null wird hier akzeptiert: Es ist Aufgabe von [Required], ihn zu verlangen
    public override bool IsValid(object? value) => value is null || values.Contains(value as string);
}

// ──────────────────────────────────────────────────────────────── gemeinsame Basis
public class PersonFields
{
    [Required(ErrorMessage = "ERRORS.INVALID_TITLE")]
    [OneOf("Mr", "Mme", "Melle", ErrorMessage = "ERRORS.INVALID_TITLE")]
    public string? Title { get; set; }

    // maximale Längen = die der SQL-Spalten (VARCHAR(20))
    private string? firstName;

    [Required(ErrorMessage = "ERRORS.FIRSTNAME_REQUIRED")]
    [MaxLength(20, ErrorMessage = "ERRORS.FIRSTNAME_TOO_LONG")]
    public string? FirstName
    {
        get => firstName;
        set => firstName = InputRules.Clean(value);
    }

    private string? lastName;

    [Required(ErrorMessage = "ERRORS.LASTNAME_REQUIRED")]
    [MaxLength(20, ErrorMessage = "ERRORS.LASTNAME_TOO_LONG")]
    public string? LastName
    {
        get => lastName;
        set => lastName = InputRules.Clean(value);
    }
}

// ──────────────────────────────────────────────────────────────── ADMIN
public class PersonForm : PersonFields
{
    private string? login;

    // optional (siehe PersonData, Business/IBusiness.cs)
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    // optional; höchstens 72 Zeichen (darüber hinaus ignoriert bcrypt den Rest)
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    // verstecktes Feld des Bearbeitungsformulars (optimistisches Sperren).
    // int?: Ein fehlendes oder leeres Feld ergibt null; ein Text, der keine
    // Zahl ist, ergibt einen Binding-Fehler (siehe Program.cs, ModelBindingMessageProvider)
    public int? Version { get; set; }
}

// ──────────────────────────────────────────────────────────────── Registrierung eines Patienten
public class RegistrationForm : PersonFields
{
    private string? login;

    [Required(ErrorMessage = "ERRORS.LOGIN_REQUIRED")]
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    [Required(ErrorMessage = "ERRORS.PASSWORD_REQUIRED")]
    [MinLength(InputRules.PasswordMin, ErrorMessage = "ERRORS.PASSWORD_TOO_SHORT")]
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    [Required(ErrorMessage = "ERRORS.CONFIRMATION_REQUIRED")]
    public string? Confirmation { get; set; }
}

// ──────────────────────────────────────────────────────────────── "Manage my account"
public class MyAccountForm : PersonFields
{
    private string? login;

    [Required(ErrorMessage = "ERRORS.LOGIN_REQUIRED")]
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    // optional: leer = Passwort unverändert
    [MinLength(InputRules.PasswordMin, ErrorMessage = "ERRORS.PASSWORD_TOO_SHORT")]
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    public string? Confirmation { get; set; }

    // das AKTUELLE Passwort, erforderlich für jede Änderung des Kontos
    [Required(ErrorMessage = "ERRORS.CURRENT_PASSWORD_REQUIRED")]
    public string? CurrentPassword { get; set; }

    public int? Version { get; set; }
}

Besprechen wir diesen Code:

  • Zeile 43: mögliche Anreden;
  • Zeile 46: das Format eines Benutzernamens, beschrieben durch einen regulären Ausdruck: 1 bis 30 Zeichen, bestehend aus Kleinbuchstaben, Ziffern, Punkt, Bindestrich und Unterstrich;
  • Zeile 49: die Mindestlänge eines von einem Patienten gewählten Passworts. Dies ist eine Konstante ([const]), daher kann sie als Argument eines Attributs verwendet werden, etwa von [[MinLength(InputRules.PasswordMin)]] weiter unten;
  • Zeile 52: Bereinigung einer Eingabe: Leerzeichen am Anfang und Ende werden entfernt, und ein Feld, das nur aus Leerzeichen besteht, wird zu [null], ist also ungültig;
  • Zeilen 59–62: ein von uns geschriebenes Validierungsattribut: Der Wert muss in einer Liste vorkommen. Dazu genügt es, es von [ValidationAttribute] abzuleiten und [IsValid] neu zu definieren. [null] wird akzeptiert: Ein fehlendes Feld abzulehnen ist die Aufgabe von [[Required]]. Wir verwenden es unter dem Namen [[OneOf]]: Per Konvention kann das Suffix [Attribute] weggelassen werden;
  • Zeile 66: die Identitätsfelder, die allen drei Formularen gemeinsam sind. Alle Eigenschaften haben den Typ [string?]: Ein Feld kann in den vom Browser gesendeten Daten immer fehlen, und [[Required]] verlangt es. Fehlermeldungen sind Übersetzungsschlüssel (siehe Beispiel 22);
  • Zeilen 68–70: die Anrede, die erforderlich ist und aus der Liste ausgewählt wird. Die Werte werden in [[OneOf(...)]] wiederholt: Das Argument eines Attributs muss zur Kompilierzeit bekannt sein, was beim Array [InputRules.Titles] nicht der Fall ist (ein [static readonly]-Feld, das zur Laufzeit erstellt wird);
  • Zeilen 73–80 und Zeilen 83–90: Vor- und Nachname, die erforderlich sind und bis zu 20 Zeichen lang sein dürfen (die Breite der SQL-Spalten). Diese Eigenschaften haben einen Rumpf: Ihr Wert wird in einem privaten Feld gespeichert, und [set] bereinigt ihn beim Durchlaufen. Da das Model Binding die Eigenschaften vor der Validierung setzt, wird der bereinigte Wert validiert. Dies entspricht dem [@Transform] in der Version mit [NestJS]; [ASP.NET Core MVC] wandelt ein leeres Feld bereits automatisch in [null] um;
  • Zeile 95: das ADMIN-Formular zum Hinzufügen oder Bearbeiten eines Arztes oder eines Clients. Die Klasse erbt die Identitätsfelder und deren Validierungsattribute;
  • Zeilen 97–104: der Login, der hier optional ist, aber im richtigen Format vorliegen muss, falls vorhanden (Zeile 100); er wird bereinigt und in Kleinbuchstaben umgewandelt. [?.] ruft [ToLowerInvariant] nur auf, wenn der Wert nicht [null] ist;
  • Zeilen 108–109: das Passwort, ebenfalls optional, mit höchstens 72 Zeichen: Der Algorithmus [bcrypt], der es verschlüsselt, ignoriert alle darauf folgenden Zeichen. Ein Passwort wird nicht bereinigt: Leerzeichen gehören zum Passwort;
  • Zeile 114: die Version des Datensatzes in einem versteckten Feld des Aktualisierungsformulars (optimistische Sperre; siehe Beispiel 28). Ein fehlendes oder leeres Feld ergibt [null]; Text, der keine Zahl ist, erzeugt einen Bindungsfehler, dessen Meldung in [Program.cs] konfiguriert wird (siehe Beispiel 19);
  • Zeile 118: Ein Patient erstellt ein Konto: Benutzername, Passwort (6 bis 72 Zeichen, Zeile 131) und Bestätigung (Zeilen 135–136) sind erforderlich. Die Prüfung, ob das Passwort mit seiner Bestätigung übereinstimmt, betrifft zwei Felder: Sie wird vom Validator vorgenommen ([Controllers/RegistrationController.cs]);
  • Zeile 140: Ein Patient ändert sein Konto. Das neue Passwort ist optional (Zeile 153): Bleibt es leer, ändert sich das Passwort nicht; seine Bestätigung (Zeile 157) ist daher hier nicht erforderlich. Das aktuelle Passwort ist hingegen für jede Änderung erforderlich (Zeilen 160–161), und die Version des Datensatzes wird in einem versteckten Feld gespeichert (Zeile 163).

11.15.2. Models/ViewModels.cs

// =========================================================================
// Models/ViewModels.cs
// -------------------------------------------------------------------------
// Die "View-Modelle": das, was jeder Controller an seine View übergibt
// (return View("...", model)), in einer TYPISIERTEN C#-Klasse. In einer
// Razor-View deklariert @model ScheduleModel den Typ des Modells: Der Compiler
// prüft dann jedes @Model.Xxx der View - ein Tippfehler ist ein
// Kompilierfehler und kein leerer Bereich auf der Seite.
//
// Eine Regel, die schon bei Handlebars galt: keine Logik in den Views. Die
// Controller bereiten Daten vor, die BEREITS formatiert sind ("Mme Marie
// PELISSIER", "8:00 - 8:20", Selected = true...) und bereits nach der
// Rolle des Benutzers gefiltert wurden; die Views platzieren sie lediglich im HTML.
// =========================================================================

namespace RdvMedecins.Models;

// -------------------------------------------------------------------------
// was ALLEN Seiten gemeinsam ist, vom Layout gelesen
// (Views/Shared/_Layout.cshtml)
// -------------------------------------------------------------------------
public abstract class ViewModel
{
    // Übersetzungsschlüssel des Seitentitels (<title>)
    public string PageTitle { get; set; } = "APP.TITLE";

    // DIE Fehlermeldung der Seite, unten auf der Seite angezeigt
    // (siehe Views/Shared/_Errors.cshtml); null = kein Fehler
    public string? Error { get; set; }

    public IReadOnlyDictionary<string, string>? ErrorParams { get; set; }
}

// eine Option einer Dropdown-Liste (Arzt, Patient)
public record OptionView(int Id, string Label, bool Selected);

// ──────────────────────────────────────────────────────────────── Login
public class LoginModel : ViewModel
{
    public string Login { get; set; } = "";
    public required Auth.Captcha Captcha { get; set; }
}

// ──────────────────────────────────────────────────────────────── Terminkalender
public class ScheduleRowView
{
    public int SlotId { get; init; }
    public string Time { get; init; } = ""; // "8:00 - 8:20"
    public bool Free { get; init; }
    public string? Patient { get; init; } // angezeigter Name für einen gebuchten Slot; null = "Booked"
    public bool Mine { get; init; } // der Termin des angemeldeten Patienten
    public bool Bookable { get; init; } // Schaltfläche "Book" anzeigen?
    public string BookUrl { get; init; } = "";
    public int? AppointmentId { get; init; } // nur gefüllt, wenn die Schaltfläche "Cancel" angezeigt wird
}

public record ScheduleView(string Doctor, string Day, List<ScheduleRowView> Rows);

public class BookingView
{
    public int SlotId { get; init; }
    public string Time { get; init; } = "";
    // ADMIN / DOCTOR: die Liste der auswählbaren Patienten
    public List<OptionView> Clients { get; init; } = [];
    // USER: Der Patient ist der Benutzer selbst
    public string? Patient { get; init; }
}

public class ScheduleModel : ViewModel
{
    public List<OptionView> Doctors { get; set; } = [];
    public int? DoctorId { get; set; }
    public string Day { get; set; } = ""; // "yyyy-MM-dd"
    public ScheduleView? Schedule { get; set; }
    public BookingView? Booking { get; set; }
    public string BackUrl { get; set; } = "/schedule"; // der angezeigte Terminkalender, ohne Buchungsdialog
    // Patient, der bereits einen bevorstehenden Termin hat: die Nachricht, die erklärt,
    // warum es keine Schaltfläche "Book" gibt
    public string? Info { get; set; }
}

// ──────────────────────────────────────────────────────────────── "Personen"-Formulare

// die in den Formularfeldern angezeigten Werte (nie das Passwort)
public class PersonValues
{
    public string Title { get; set; } = "Mr";
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string Login { get; set; } = "";
    public int? Version { get; set; }
}

// was das gemeinsame Partial _PersonFields.cshtml verwendet (Anrede, Vorname, Nachname)
public abstract class FormView : ViewModel
{
    public PersonValues Values { get; set; } = new();

    // Feld -> Schlüssel der UNTER diesem Feld angezeigten Nachricht (Eingabefehler)
    public Dictionary<string, string> Errors { get; set; } = new(StringComparer.OrdinalIgnoreCase);

    // rot zu umrandende Felder (Bootstrap-Klasse is-invalid): die mit
    // einer Nachricht, plus gegebenenfalls weitere (doppelter Vor- + Nachname, vergebenes Login...)
    public HashSet<string> InvalidFields { get; set; } = new(StringComparer.OrdinalIgnoreCase);

    public string? ErrorOf(string field) => Errors.GetValueOrDefault(field);

    public string InvalidClass(string field) => InvalidFields.Contains(field) ? "is-invalid" : "";

    public IEnumerable<(string Value, bool Selected)> Titles =>
        InputRules.Titles.Select(t => (t, t == Values.Title));
}

public class PersonFormModel : FormView
{
    public bool Creating { get; set; } // true: hinzufügen; false: bearbeiten
    public string Action { get; set; } = ""; // URL des POST
    public string ListUrl { get; set; } = "";
}

public class RegistrationModel : FormView
{
    public int PasswordMin => InputRules.PasswordMin;
}

public class MyAccountModel : FormView
{
    public int PasswordMin => InputRules.PasswordMin;
}

// ──────────────────────────────────────────────────────────────── Listen der Ärzte / Clients

// die für jeden Personentyp spezifischen Übersetzungsschlüssel
public record PersonKeys(
    string Title, // "Doctors"
    string Add, // "Add a doctor"
    string Edit, // "Edit a doctor"
    string Empty, // "No doctors."
    string ConfirmDelete, // "Delete this doctor, their time slots and their user account?"
    string Added, // "Doctor {name} has been added (login: {login})."
    string Edited,
    string Deleted);

public record PersonView(string Title, string FirstName, string LastName, string Login, string EditUrl, string DeleteUrl);

public class PersonListModel : ViewModel
{
    public required PersonKeys Keys { get; set; }
    public string AddUrl { get; set; } = "";
    public List<PersonView> Persons { get; set; } = [];
}

// ──────────────────────────────────────────────────────────────── Patientenbereich
public record AppointmentView(int Id, string Day, string Time, string Doctor, string ScheduleUrl);

public class AreaModel : ViewModel
{
    public string Patient { get; set; } = "";
    public List<AppointmentView> Appointments { get; set; } = [];
}

// ──────────────────────────────────────────────────────────────── Fehlerseite
public class ErrorModel : ViewModel
{
    public int Code { get; set; }
    public string Message { get; set; } = "ERRORS.SERVER_ERROR";
}

Die View-Templates folgen der bereits bei [Handlebars] angewandten Regel: keine Logik in den Views. Die Controller bereiten bereits formatierte Daten („Mme Marie PELISSIER“, „8:00 – 8:20“) vor, die schon nach der Rolle des Benutzers gefiltert sind; die Views setzen diese Daten lediglich in das HTML ein. Jede View deklariert den Typ ihres Templates ([@model ScheduleModel], siehe Beispiel 13): Der Compiler prüft jedes [@Model.Xxx], und ein Tippfehler führt zu einem Kompilierfehler.

Kommentieren wir diesen Code:

  • Zeilen 22–31: was allen Seiten gemeinsam ist, wie es das Template [_Layout.cshtml] liest: der Übersetzungsschlüssel für den Seitentitel (Zeile 25) und die Fehlermeldung der Seite, die unten zusammen mit ihren Parametern angezeigt wird. Die Klasse ist abstrakt: Jede Seite hat ihr eigenes Template, das von ihr abgeleitet ist;
  • Zeile 35: eine Option einer Dropdown-Liste (ein Arzt, ein Patient), bereits als ausgewählt oder nicht ausgewählt markiert (siehe Beispiel 18);
  • Zeilen 38–41: die Anmeldeseite: der bereits eingegebene Benutzername und das anzuzeigende CAPTCHA. Das Schlüsselwort [required] verlangt, dass die Person, die das Objekt erstellt, der Eigenschaft einen Wert zuweist; andernfalls entsteht ein Kompilierfehler;
  • Zeilen 45–54: ein Eintrag im Terminkalender, also ein Zeitfenster. Der Controller hat bereits alles bestimmt: ob der Name des Patienten angezeigt wird (ein Patient kann die Namen anderer nicht sehen), ob die Schaltfläche „Buchen“ angezeigt wird und ob die Schaltfläche „Stornieren“ angezeigt wird ([AppointmentId] ist gesetzt). Den Eigenschaften [init] kann nur bei der Erstellung des Objekts ein Wert zugewiesen werden;
  • Zeile 57: Der Terminkalender eines Arztes für einen einzelnen Tag: der Name des Arztes, der ausgeschriebene Tag und die Zeilen;
  • Zeilen 59–66: das Terminfenster: die Liste der Patienten für ADMIN und die Ärzte oder nur der Name des angemeldeten Patienten;
  • Zeilen 69–79: die Seite des Terminkalenders: die Liste der Ärzte, der ausgewählte Arzt und Tag, der Terminkalender ([null] solange kein Arzt ausgewählt ist), das Buchungsfenster (falls vorhanden), die URL des Terminkalenders ohne dieses Fenster (Zeile 76) und die Meldung, die einem Patienten erklärt, warum er keinen Termin buchen kann;
  • Zeilen 85–91: die in den Feldern eines Formulars „Person“ angezeigten Werte, niemals das Passwort: Ein Passwort wird nicht an den Browser zurückgesendet;
  • Zeile 95: die Elternklasse der Templates der drei Formulare „Person“, diejenige, die von [Validation.Prepare] verlangt wird: die Feldwerte, die Meldungen unter den Feldern (Zeile 100) und die rot hervorzuhebenden Felder (Zeile 104). Ein [HashSet] ist eine Menge: Jedes Element kommt nur einmal vor, und der Mitgliedschaftstest ist schnell;
  • Zeilen 106–108: zwei Methoden für Views: die Meldung eines Feldes (oder [null]) und die [Bootstrap]-Klasse [is-invalid], die ein Feld rot umrahmt. Die Views heißen zum Beispiel [@Model.InvalidClass("login")];
  • Zeilen 110–111: die Optionen der Anredeliste, wobei die ausgewählte Option markiert ist (siehe Beispiel 18). Jede Option ist ein Tupel [(Value, Selected)];
  • Zeilen 114–118: das ADMIN-Formular, das zum Hinzufügen und Ändern von Einträgen dient (siehe Beispiel 28): der Modus, die URL zum Absenden des Formulars und die URL der Liste für die Zurück-Schaltfläche;
  • Zeilen 121–128: die Formulare für Registrierung und Kontoverwaltung; sie übergeben der View die Mindestlänge des Passworts, die als Parameter [{min}] für die Fehlermeldung des Feldes und, bei der Registrierung, für den Hilfetext verwendet wird;
  • Zeilen 134–142: Die Verwaltungsseiten für Ärzte und Clients sind dieselben Views; nur ihre Texte unterscheiden sich. Dieser [record] enthält die für jede Art von Person spezifischen Übersetzungsschlüssel;
  • Zeilen 144–150: eine Zeile in der Liste der Ärzte oder Clients mit den Adressen ihrer Schaltflächen „Bearbeiten“ und „Löschen“ sowie das Template der Listenseite;
  • Zeilen 154–159: der Patientenbereich: sein Name und seine bevorstehenden Termine, jeweils mit einem Link zum Tageskalender;
  • Zeilen 163–166: die Fehlerseite: der HTTP-Code und der Meldungsschlüssel, der standardmäßig der eines Serverfehlers ist.

11.16. Die Web-Schicht: die Controller

Controller sind der sichtbare Teil der Web-Schicht: Jeder empfängt die Anfragen einer Gruppe von Seiten, liest deren Parameter, befragt die Geschäftsschicht (stets über den Service [ApplicationModel]), wählt dann eine View aus und übergibt ihr ein typisiertes Modell oder leitet die Anfrage um. Alle POST-Formulare folgen dem Muster Post/Redirect/Get (siehe Beispiel 20); alle Meldungen sind Übersetzungsschlüssel, die von der View übersetzt werden. Der Anmeldecontroller, [AuthController], wurde bei der Authentifizierung besprochen.

11.16.1. Controllers/LanguageController.cs

// =========================================================================
// Controllers/LanguageController.cs
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: die beiden Schaltflächen FR / EN der Navigationsleiste.
// Nicht geschützte Route: Der Sprachwechsel muss schon
// vor dem Login möglich sein.
//
// Die Wahl wird in DEM Cookie der Lokalisierungs-Middleware
// von ASP.NET Core gespeichert (CookieRequestCultureProvider, siehe Program.cs): Bei jeder
// folgenden Anfrage liest diese Middleware es wieder ein und legt die Sprache der Anfrage fest
// (CultureInfo.CurrentCulture / CurrentUICulture). Anschließend kehren wir zur
// Seite zurück, von der wir kamen.
// =========================================================================

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

public class LanguageController : Controller
{
    [HttpGet("language/{language}")]
    public IActionResult Change(string language)
    {
        if (!Translator.Languages.Contains(language))
        {
            return NotFound(); // -> Fehlerseite 404 (siehe Program.cs)
        }
        Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            // Cookie-Wert: "c=en|uic=en" (Sprache der Formate, Sprache der Texte)
            CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)),
            new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true, Path = "/" });
        return Redirect(OriginPage());
    }

    // die vorherige Seite, gemäß dem HTTP-Header "Referer", den der
    // Browser sendet. Wir behalten nur deren Pfad (/schedule?...): Eine Umleitung auf eine
    // vollständige, von der Anfrage gelieferte Adresse würde es erlauben,
    // den Benutzer auf eine andere Website zu schicken (die sogenannte Sicherheitslücke "Open Redirect").
    private string OriginPage()
    {
        var referer = Request.Headers.Referer.ToString();
        if (!Uri.TryCreate(referer, UriKind.Absolute, out var url))
        {
            return "/";
        }
        return url.AbsolutePath.StartsWith("/language/", StringComparison.Ordinal) ? "/" : url.PathAndQuery;
    }
}

Dies ist, bis auf eine Zeile, der Controller aus Beispiel 22: dieselbe Route [/language/{language}], dasselbe Cookie der Lokalisierungs-Middleware, dieselbe Rückkehr zur ursprünglichen Seite über den Header [Referer]. Zwei Klarstellungen:

  • Zeile 34: Die Option [Path = "/"] macht das Cookie für alle Adressen der Website gültig, unabhängig von der Seite, von der aus die Sprache gewechselt wurde;
  • Zeile 49: Ist die ursprüngliche Seite selbst eine Seite [/language/...], wird der Benutzer zur Wurzel der Website umgeleitet statt zurück auf diese Seite, was den Browser in eine Schleife geraten ließe.

11.16.2. Controllers/ScheduleController.cs

Die Hauptseite der Anwendung und der funktionsreichste Controller. Gehen wir ihn Abschnitt für Abschnitt durch.

11.16.2.1. Die URL-Dateien der Seite

// =========================================================================
// Controllers/ScheduleController.cs
// -------------------------------------------------------------------------
// Die Seite des Terminkalenders: Auswahl eines Arztes und eines Tages, Terminkalender dieses
// Arztes an diesem Tag, Buchung und Stornierung von Terminen.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               die Seite
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        dieselbe Seite, mit
//                                                          geöffnetem Buchungsdialog
//                                                          für Slot 7
//   POST /schedule/book                                    erstellt einen Termin
//   POST /schedule/cancel                                  storniert einen Termin
//
// Die ganze Seite wird durch ihre URL beschrieben: Sie kann neu geladen und
// als Lesezeichen gespeichert werden, und die Schaltfläche "Zurück" des Browsers
// funktioniert - ohne eine einzige Zeile JavaScript.
//
// Was jeder sieht und tun kann:
//
//   | Rolle         | angezeigter gebuchter Slot        | Book               | Cancel  |
//   |─────────────|───────────────────────────────────|────────────────────|─────────|
//   | ADMIN, DOCTOR | Name des Patienten                | für einen Patienten| ja      |
//   |               |                                   | aus einer Liste    |         |
//   | USER (Patient)| "Booked", oder IHR Name, wenn es  | für sich selbst,   | nein (*)|
//   |               | ihr eigener Termin ist            | wenn kein          |         |
//   |               |                                   | bevorstehender Termin |      |
//
//   (*) Der Patient storniert seinen Termin auf seiner Seite "My area".
//
// VERTRAULICHKEIT: Für einen Patienten wird der Name der ANDEREN Patienten nicht
// einfach von der View ausgeblendet - er wird nie in das an die View
// übergebene Modell gelegt. Das an den Browser gesendete HTML enthält ihn daher nicht,
// auch nicht versteckt (ein einfaches "Seitenquelltext anzeigen" würde ihn sonst verraten).
//
// Keine Buchung in der Vergangenheit: Die Schaltfläche "Book" erscheint nur
// für heute und die folgenden Tage (und die Geschäftsschicht würde sie ohnehin
// ablehnen).
//
// [Authorize] auf der Klasse: Alle Actions erfordern einen angemeldeten
// Benutzer (das Äquivalent zu @UseGuards(JwtAuthGuard)). [Authorize(Roles =
// "...")] auf einer Action verlangt zusätzlich eine der aufgeführten Rollen (RolesGuard +
// @Roles). Ohne gültiges Token: zurück zu /login; unzureichende Rolle: Seite 403.
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize]
[Route("schedule")]
public class ScheduleController(ApplicationModel application) : Controller
{
    // was der Controller über den Benutzer weiß, um zu entscheiden, was angezeigt wird
    private record Rights(
        bool Manager, // ADMIN oder DOCTOR
        Client? Patient, // der angemeldete Client (Rolle USER), sonst null
        bool PatientCanBook); // USER ohne bevorstehenden Termin
  • Zeilen 7–12: die Routen der Seite. Beachten Sie, dass das Buchungsfenster nicht von [JavaScript] geöffnet wird: Es ist ein URL-Parameter ([book=7]), der den Server anweist, die Seite mit geöffnetem Fenster darzustellen. Die Schaltfläche „Buchen“ ist daher einfach ein Link. Die gesamte Seite wird durch ihre URL beschrieben: Sie können sie neu laden, als Lesezeichen speichern oder die Schaltfläche „Zurück“ des Browsers verwenden;
  • Zeilen 18–28: was jede Rolle sieht und tun kann. Diese Tabelle ist die „Spezifikation“ der Seite: Der Rest des Controllers setzt sie um;
  • Zeilen 30–33: die Datenschutzregel, auf die wir noch zurückkommen: Die Namen anderer Patienten werden nicht von der View ausgeblendet; sie werden nie an den Browser gesendet;
  • Zeilen 55–57: [[Authorize]] an der Klasse: Alle Aktionen erfordern einen angemeldeten Benutzer, unabhängig von seiner Rolle (siehe Beispiel 25). [[Route("schedule")]] ist das Präfix aller Routen des Controllers (siehe Beispiel 02). Der Controller erhält den Service [ApplicationModel] per Injektion (siehe Beispiel 06) über seinen primären Konstruktor: Die in Klammern hinter dem Klassennamen geschriebenen Parameter sind in allen seinen Methoden zugänglich;
  • Zeilen 60–63: was der Controller über den angemeldeten Benutzer weiß, einmal pro Anfrage berechnet (siehe [RightsAsync] weiter unten). Ein privater [record], innerhalb der Klasse deklariert: Er wird nur von dieser Klasse verwendet. [Manager] ist wahr für einen ADMIN oder einen DOCTOR; [Patient] wird nur für einen Client (Rolle USER) befüllt.

11.16.2.2. GET /schedule

    // -----------------------------------------------------------------------
    // GET /schedule
    // Die URL-Parameter werden roh gelesen (Request.Query), um einen
    // FEHLENDEN Parameter von einem LEEREN (?doctorId=) zu unterscheiden.
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public async Task<IActionResult> Show()
    {
        string? error = null;
        var user = User.CurrentUser()!;
        var rights = await RightsAsync(user);

        // der Tag: der aus der URL, wenn er gültig ist, sonst heute
        var day = Dates.Today();
        if (Request.Query.TryGetValue("day", out var rawDay))
        {
            if (WebDates.IsValidDate(rawDay, out var requestedDay))
            {
                day = requestedDay;
            }
            else
            {
                error = "ERRORS.INVALID_DATE";
            }
        }
        var dayBookable = day >= Dates.Today();

        // der Arzt: der aus der URL; fehlt er, bei einem angemeldeten Arzt dieser selbst
        var doctorId = Input.PositiveInteger(Request.Query["doctorId"]);
        if (!Request.Query.ContainsKey("doctorId") && user.Role == Role.DOCTOR)
        {
            doctorId = application.GetDoctorByUserId(user.UserId)?.Id;
        }

        var doctors = (await application.GetAllDoctorsAsync())
            .Select(d => Option(d, d.Id == doctorId))
            .ToList();

        // der Terminkalender, wenn ein Arzt gewählt ist (und das Datum gültig)
        ScheduleView? schedule = null;
        if (doctorId is int id && error is null)
        {
            var doctorSchedule = await application.GetDoctorDayScheduleAsync(id, day);
            if (doctorSchedule is null)
            {
                error = "ERRORS.DOCTOR_NOT_FOUND";
            }
            else
            {
                var rows = doctorSchedule.DoctorDaySlots.Select(dds =>
                {
                    var (slot, appointment) = (dds.Slot, dds.Appointment);
                    var free = appointment is null;
                    // der Termin des angemeldeten Patienten?
                    var mine = appointment is not null && rights.Patient is not null && appointment.ClientId == rights.Patient.Id;
                    return new ScheduleRowView
                    {
                        SlotId = slot.Id,
                        Time = WebDates.Time(slot),
                        Free = free,
                        // DER Vertraulichkeitspunkt: Ein Patient erhält nur den Namen
                        // SEINES Termins; für die anderen null (die View zeigt "Booked" an)
                        Patient = appointment is not null && (rights.Manager || mine) ? Labels.Label(appointment.Client) : null,
                        Mine = mine,
                        Bookable = free && dayBookable && (rights.Manager || rights.PatientCanBook),
                        BookUrl = ScheduleUrl(id, day, slot.Id),
                        AppointmentId = appointment is not null && rights.Manager ? appointment.Id : null,
                    };
                }).ToList();
                schedule = new ScheduleView(Labels.Label(doctorSchedule.Doctor), WebDates.Iso(day), rows);
            }
        }
  • Zeilen 6–7: die Route [GET /schedule] (Präfix des Controllers, gefolgt von einer leeren Zeichenfolge). Die Aktion hat keine Parameter: Sie liest die URL automatisch als [Request.Query] (siehe Beispiel 05). Das Model Binding würde einen Parameter [int? doctorId] in [null] umwandeln, egal ob er fehlt oder leer ist; diese beiden Fälle müssen jedoch unterschieden werden (siehe unten);
  • Zeilen 10–11: der angemeldete Benutzer und seine Berechtigungen. [CurrentUser()] ist eine Erweiterungsmethode (siehe Beispiel 06), definiert in [Auth/ConnectedUser.cs]: Sie liest die Claims des Tokens und wandelt sie in ein typisiertes Objekt um. [!] teilt dem Compiler mit, dass das Ergebnis nicht [null] ist: Das ist sicher, da [[Authorize]] nicht authentifizierte Anfragen herausgefiltert hat;
  • Zeilen 14–26: der angeforderte Tag, falls gültig; andernfalls heute. [TryGetValue] liefert [false] , wenn der Parameter [day] fehlt: In diesem Fall wird der heutige Tag ohne Meldung geliefert. Ist er vorhanden, aber ungültig ([day=2026-02-30]), wird eine Fehlermeldung erzeugt. Reservierungen sind erst ab heute möglich ([dayBookable]);
  • Zeilen 29–32: der angeforderte Arzt. [Input.PositiveInteger] (Ordner [Web]) liefert eine streng positive ganze Zahl oder [null] , wenn der Wert fehlt, leer oder ungültig ist. Fehlt der Parameter [doctorId] in der URL, sieht ein angemeldeter Arzt seinen eigenen Terminkalender: Das ist seine Startseite. Ist er leer ([doctorId=], die Option „-- Arzt auswählen --“ der Liste), wird kein Terminkalender angezeigt;
  • Zeilen 35–37: die Optionen der Dropdown-Liste der Ärzte, aus dem Cache von [ApplicationModel] gelesen; die Option des angeforderten Arztes wird ausgewählt (siehe die Funktion [Option] am Ende der Datei und Beispiel 18);
  • Zeilen 40–46: Der Terminkalender wird nur berechnet, wenn ein Arzt ausgewählt und das Datum gültig ist. [doctorId is int id] prüft, dass der Wert (vom Typ [int?]) nicht [null] ist, und speichert ihn in einer neuen Variablen [id] vom Typ [int]. Eine unbekannte Arzt-ID löst eine Meldung aus, keine Fehlerseite;
  • Zeilen 50–56: Der von der Geschäftsschicht berechnete Terminkalender (ein [DoctorDaySchedule]-Objekt aus dem Ordner [Domain]) wird in Array-Elemente umgewandelt, eines pro Zeitfenster. [var (slot, appointment) = ...] zerlegt ein Wertepaar in zwei Variablen. [mine] bestimmt, ob der Termin dem angemeldeten Patienten gehört;
  • Zeilen 58–59: Die View erhält nur bereits formatierte Daten ([8:00 - 8:20]); sie muss nichts mehr berechnen;
  • Zeile 63: die Datenschutzkontrolle der Anwendung. Der Name des Patienten wird nur für einen Administrator oder für den Patienten, dem der Termin gehört, in das Modell aufgenommen. Für alle anderen enthält das Modell [null], und die View zeigt „Gebucht“ an. Der Name wird nicht einfach von der View ausgeblendet: Er wird nie an den Browser gesendet, und „Seitenquelltext anzeigen“ würde ihn nicht preisgeben;
  • Zeilen 65–67: was die View anzeigen muss, wie vom Controller bestimmt: die Schaltfläche „Buchen“ (freies Zeitfenster, Datum nicht in der Vergangenheit und Benutzer zur Reservierung berechtigt), ihr Link (die URL der Seite mit [book]) und die Schaltfläche „Stornieren“ ([AppointmentId] wird nur für einen Administrator gesetzt). Die View trifft keine Entscheidungen: Sie befolgt diese Anweisungen;
  • Zeile 70: der vollständige Terminkalender: der Arzt, der Tag, die Zeilen.

11.16.2.3. Das Terminfenster und das View-Template

        // der Buchungsdialog: nur, wenn der angeforderte Slot von diesem
        // Benutzer buchbar ist
        BookingView? booking = null;
        var slotId = Input.PositiveInteger(Request.Query["book"]);
        var row = schedule?.Rows.FirstOrDefault(r => r.SlotId == slotId && r.Bookable);
        if (row is not null)
        {
            booking = new BookingView
            {
                SlotId = row.SlotId,
                Time = row.Time,
                Clients = rights.Manager
                    ? (await application.GetAllClientsAsync()).Select(c => Option(c, false)).ToList()
                    : [],
                Patient = rights.Patient is not null ? Labels.Label(rights.Patient) : null,
            };
        }

        return View("Schedule", new ScheduleModel
        {
            PageTitle = "SCHEDULE.PAGE_TITLE",
            Doctors = doctors,
            DoctorId = doctorId,
            Day = WebDates.Iso(day),
            Schedule = schedule,
            Booking = booking,
            BackUrl = doctorId is int dId ? ScheduleUrl(dId, day) : "/schedule",
            Info = rights.Patient is not null && !rights.PatientCanBook ? "SCHEDULE.ALREADY_BOOKED_INFO" : null,
            Error = error,
        });
    }
  • Zeilen 3–5: das Zeitfenster, für das die URL eine Reservierung anfordert ([book=7]). Es muss im angezeigten Terminkalender vorkommen und von diesem Benutzer buchbar sein: Eine manuell erstellte URL (ein vergangenes Zeitfenster, ein bereits gebuchtes Zeitfenster oder ein Zeitfenster eines anderen Arztes) öffnet das Fenster nicht. [schedule?.Rows] ergibt [null], wenn [schedule] [null] ist (Operator [?.]);
  • Zeilen 6–15: das Template des Fensters. Ein Administrator wählt einen Patienten aus einer Liste aus (alle Clients, aus dem Cache gelesen); ein Patient reserviert für sich selbst: Das Fenster zeigt einfach seinen Namen an. [[]] ist eine leere Liste;
  • Zeilen 19–29: das Template der Seite. Ihre Klassen ([ScheduleModel], [ScheduleView], [ScheduleRowView], [BookingView], [OptionView]) sind in [Models/ViewModels.cs] definiert; [PageTitle] und [Error] sind von ihrer gemeinsamen Elternklasse [ViewModel] abgeleitet. [PageTitle] ist wie alle Texte ein Übersetzungsschlüssel;
  • Zeile 27: die Adresse des angezeigten Terminkalenders ohne das Buchungsfenster – dies ist die Adresse der Schaltfläche, die das Fenster schließt;
  • Zeile 28: eine Informationsmeldung für Patienten, die bereits einen bevorstehenden Termin haben: Sie erklärt, warum sie keine Schaltfläche „Buchen“ sehen.

11.16.2.4. POST /schedule/book

    // -----------------------------------------------------------------------
    // POST /schedule/book   Felder: doctorId, day, slotId, clientId
    //
    // Für einen Patienten (USER) wird das Feld clientId IGNORIERT: Er bucht immer
    // für sich selbst. Einem vom Browser gesendeten Feld zu vertrauen,
    // würde es einem gerissenen Patienten erlauben, im Namen eines anderen zu buchen.
    //
    // Muster "Post / Redirect / Get": Was auch immer das Ergebnis ist, wir bauen hier
    // keine Seite auf - wir legen eine Flash-Nachricht ab und leiten
    // auf den Terminkalender um (siehe Web/Flash.cs).
    // -----------------------------------------------------------------------
    [HttpPost("book")]
    [Authorize(Roles = "ADMIN,DOCTOR,USER")]
    public async Task<IActionResult> Book(
        [FromForm] string? doctorId,
        [FromForm] string? day,
        [FromForm] string? slotId,
        [FromForm] string? clientId)
    {
        if (!ReadScheduleRequest(doctorId, day, out var docId, out var requestedDay)
            || Input.PositiveInteger(slotId) is not int sltId)
        {
            return BadRequest(); // -> Seite "invalid request" (siehe Program.cs)
        }

        Client? client;
        if (User.IsInRole(nameof(Role.USER)))
        {
            client = await Patient.ConnectedPatientAsync(application, User);
        }
        else
        {
            if (Input.PositiveInteger(clientId) is not int cliId)
            {
                // kein Patient gewählt: Wir öffnen den Buchungsdialog erneut
                Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CHOOSE_PATIENT");
                return Redirect(ScheduleUrl(docId, requestedDay, sltId));
            }
            client = await application.GetClientByIdAsync(cliId);
        }

        var slot = await application.GetSlotByIdAsync(sltId);
        if (client is null)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.PATIENT_NOT_FOUND");
        }
        else if (slot is null || slot.DoctorId != docId)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.SLOT_NOT_FOUND");
        }
        else
        {
            try
            {
                // die Regeln (nicht in der Vergangenheit, nur ein bevorstehender Termin pro
                // Patient, freier Slot) werden von der Geschäftsschicht geprüft
                await application.AddAppointmentAsync(requestedDay, slot, client);
                Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.BOOKED");
            }
            // "when": ein Exception-Filter. Dieselbe Regel, aber eine Nachricht in der 2.
            // Person, wenn der Patient selbst bucht ("You
            // already have..." statt "This patient...")
            catch (BusinessException e) when (e.Key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" && User.IsInRole(nameof(Role.USER)))
            {
                Flash.Put(HttpContext, FlashType.Danger, "SCHEDULE.ALREADY_BOOKED_INFO");
            }
            // jede andere BusinessException wird zu einer Flash-Nachricht; die anderen
            // Exceptions (echte Anomalien) werden nicht abgefangen: Seite 500
            catch (BusinessException e)
            {
                Flash.Put(HttpContext, FlashType.Danger, e.Key, new Dictionary<string, string>(e.Params));
            }
        }
        return Redirect(ScheduleUrl(docId, requestedDay));
    }
  • Zeilen 12–13: [[Authorize(Roles = ...)]] an der Aktion wird zum [[Authorize]] der Klasse hinzugefügt: Alle drei Rollen können Reservierungen vornehmen (siehe Beispiel 26). Hier erlegt dieses Attribut keine weiteren Einschränkungen auf; es dokumentiert die Regel und würde sie schützen, falls eine vierte Rolle hinzukäme;
  • Zeilen 15–18: die Felder des Formulars im Reservierungsfenster (siehe Beispiel 11). Sie werden als Zeichenfolgen empfangen und dann sorgfältig umgewandelt;
  • Zeilen 20–23: Der Arzt und der Tag sind versteckte Felder im Formular; sie ermöglichen dem Benutzer die Rückkehr zum angezeigten Terminkalender. Sind sie ungültig, stammt die Anfrage nicht von unserer Seite: Sie wurde manuell erstellt. [BadRequest()] liefert eine Antwort 400 ohne Inhalt, die die Middleware [UseStatusCodePagesWithReExecute] in eine Fehlerseite umwandelt (siehe Beispiel 24). [is not int sltId] ist das Gegenteil von [is int]: wahr, wenn der Wert [null] ist; andernfalls [sltId] erhält den Wert;
  • Zeilen 27–29: Für einen Patienten wird das Feld [clientId] ignoriert – das System reserviert immer für den Patienten selbst. Sich auf dieses vom Browser gesendete Feld zu verlassen, würde einem böswilligen Patienten erlauben, eine Reservierung im Namen eines anderen vorzunehmen. [Patient.ConnectedPatientAsync] (Ordner [Web]) identifiziert den Client anhand des Tokens; [nameof(Role.USER)] ist die Zeichenfolge ["USER"], vom Compiler geprüft;
  • Zeilen 33–39: Ein Verwalter, der keinen Patienten ausgewählt hat, wird zum Buchungsfenster umgeleitet (URL mit [book]), begleitet von einer Fehlermeldung als Pop-up. [Flash.Put] (Ordner [Web]) speichert die Meldung in [TempData] (siehe Beispiel 20);
  • Zeilen 42–49: Der Patient muss existieren, und das Zeitfenster muss existieren und zum Arzt im Terminkalender gehören: Sie können kein Zeitfenster eines Arztes für einen anderen buchen;
  • Zeilen 57–58: Die Geschäftsregeln (nicht in der Vergangenheit, Zeitfenster frei, nur ein bevorstehender Termin pro Patient) werden von der Geschäftsschicht geprüft, die bei einer Ablehnung eine [BusinessException] auslöst;
  • Zeilen 63–65: [when] fügt [catch] eine Bedingung hinzu: Es ist ein Exception-Filter [C#]. Dieser Block fängt die [BusinessException] nur ab, wenn die Bedingung wahr ist: Für einen Patienten wird die Meldung „dieser Patient hat bereits einen Termin“ durch eine Meldung in der zweiten Person ersetzt. Andernfalls gelangt die Ausnahme zum nächsten [catch];
  • Zeilen 69–71: Jede andere [BusinessException] wird zu einer Flash-Meldung, zusammen mit ihrem Schlüssel und ihren Parametern ([e.Params] ist ein schreibgeschütztes Wörterbuch: Es wird eine Kopie des von [Flash.Put] erwarteten Typs angelegt). Die anderen Ausnahmen werden nicht abgefangen: Es sind echte Fehler, die zu einer Fehlerseite 500 führen;
  • Zeile 74: das PRG-Schema: Unabhängig vom Ergebnis wird eine Flash-Meldung gesetzt und der Benutzer zum Terminkalender umgeleitet, der die Meldung anzeigt. In der Version mit [NestJS] übernahm eine Hilfsfunktion die Umwandlung dieser Geschäftsfehler; hier genügen die beiden [catch]-Blöcke.

11.16.2.5. POST /schedule/cancel

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   Felder: appointmentId, doctorId, day
    // (ein Patient storniert SEINEN Termin von "My area" aus, nicht von hier)
    // -----------------------------------------------------------------------
    [HttpPost("cancel")]
    [Authorize(Roles = "ADMIN,DOCTOR")]
    public async Task<IActionResult> Cancel([FromForm] string? appointmentId, [FromForm] string? doctorId, [FromForm] string? day)
    {
        if (!ReadScheduleRequest(doctorId, day, out var docId, out var requestedDay)
            || Input.PositiveInteger(appointmentId) is not int id)
        {
            return BadRequest();
        }
        var appointment = await application.GetAppointmentByIdAsync(id);
        if (appointment is null)
        {
            // bereits storniert (von jemand anderem oder durch Doppelklick)
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.APPOINTMENT_NOT_FOUND");
        }
        else
        {
            await application.DeleteAppointmentAsync(appointment);
            Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.CANCELLED");
        }
        return Redirect(ScheduleUrl(docId, requestedDay));
    }
  • Zeilen 5–7: Die Stornierung ist Administratoren vorbehalten; ein Patient storniert seinen Termin in „Mein Bereich“ (siehe [PatientAreaController]). Ein Patient, der diese Anfrage sendet, erhielte eine Seite 403;
  • Zeilen 9–12: dieselben Prüfungen wie bei der Reservierung;
  • Zeilen 14–18: Ein bereits stornierter Termin (durch Doppelklick oder durch einen anderen Administrator) löst eine Fehlermeldung aus, keine Fehlerseite;
  • Zeilen 22–25: das Löschen, gefolgt vom PRG-Schema.

11.16.2.6. Berechtigungen und Hilfsfunktionen

    // -----------------------------------------------------------------------
    // wer ist angemeldet, und was darf er auf dieser Seite tun?
    // -----------------------------------------------------------------------
    private async Task<Rights> RightsAsync(ConnectedUser user)
    {
        if (user.Role != Role.USER)
        {
            return new Rights(Manager: true, Patient: null, PatientCanBook: false);
        }
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var upcoming = await application.GetClientUpcomingAppointmentsAsync(patient.Id);
        return new Rights(Manager: false, patient, PatientCanBook: upcoming.Count == 0);
    }

    // ───────────────────────────────────────────────────────────────── Hilfsfunktionen

    // die versteckten Felder doctorId / day, beiden POST-Formularen gemeinsam
    private static bool ReadScheduleRequest(string? rawDoctorId, string? rawDay, out int doctorId, out DateOnly day)
    {
        doctorId = Input.PositiveInteger(rawDoctorId) ?? 0;
        return WebDates.IsValidDate(rawDay, out day) && doctorId > 0;
    }

    private static string ScheduleUrl(int doctorId, DateOnly day, int? book = null)
    {
        var url = $"/schedule?doctorId={doctorId}&day={WebDates.Iso(day)}";
        return book is null ? url : $"{url}&book={book}";
    }

    private static OptionView Option(Person p, bool selected) => new(p.Id, Labels.Label(p), selected);
}
  • Zeilen 4–12: Ein Administrator hat alle Berechtigungen; ein Patient kann eine Reservierung vornehmen, wenn er keine bevorstehenden Termine hat. Die benannten Argumente ([Manager: true]) machen den Aufruf des [record]-Konstruktors lesbar;
  • Zeilen 18–21: das Lesen der beiden versteckten Felder, die den POST-Formularen gemeinsam sind. Die [out]-Parameter sind zusätzliche Ergebnisse der Methode: Sie gibt einen booleschen Wert zurück (sind die Felder gültig?) und über ihre [out]-Parameter die umgewandelten Werte. So arbeitet auch [int.TryParse];
  • Zeilen 24–27: die URL des Terminkalenders eines Arztes an einem bestimmten Tag, gegebenenfalls mit geöffnetem Buchungsfenster. Alle Umleitungen der Controller erzeugen sie über diese Funktion: Die URLs der Seite sind an einer einzigen Stelle geschrieben;
  • Zeile 30: eine Option einer Dropdown-Liste (ID, Beschriftung, Auswahl), sowohl für einen Arzt als auch für einen Client: Der Parameter hat den Typ [Person], die Elternklasse beider Entitäten.

11.16.3. Controllers/PersonsControllerBase.cs

// =========================================================================
// Controllers/PersonsControllerBase.cs
// -------------------------------------------------------------------------
// Die Verwaltung der Ärzte und die der Clients (dem ADMIN vorbehalten) sind
// IDENTISCH: gleiche Liste, gleiches Formular, gleiche Regeln. Statt
// dieselben Actions zweimal zu schreiben, schreiben wir sie einmal in dieser
// ABSTRAKTEN und GENERISCHEN Klasse, von der DoctorsController
// ([Route("doctors")]) und ClientsController ([Route("clients")]) erben. Jede
// Unterklasse muss nur ihre "Konfiguration" liefern: welche Methoden
// aufzurufen und welche Beschriftungen anzuzeigen sind.
//
// Die HIER platzierten Routen ([HttpGet("add")]...) werden vererbt und
// ergänzen die Route der Unterklasse. Wir erhalten so für jede:
//
//   GET  /doctors                    Liste
//   GET  /doctors/add                leeres Formular
//   POST /doctors/add                Erstellung
//   GET  /doctors/{id}/edit          vorausgefülltes Formular
//   POST /doctors/{id}/edit          Aktualisierung
//   POST /doctors/{id}/delete        Löschung
//
// (und dieselben URLs unter /clients). Auch die Views sind gemeinsam:
// Views/Persons/List.cshtml und Views/Persons/Form.cshtml.
//
// Eine abstrakte Klasse wird von MVC nie für einen Controller gehalten: Nur
// ihre konkreten Unterklassen sind es.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

// was jede Unterklasse liefern muss
public record PersonsConfig<T>(
    string Url, // "/doctors" oder "/clients"
    PersonKeys Keys,
    Func<Task<List<T>>> List,
    Func<int, Task<T?>> Find,
    Func<PersonData, Task<T>> Add,
    Func<int, PersonData, Task<T>> Edit,
    Func<int, Task> Delete) where T : Person;

public abstract class PersonsControllerBase<T>(ApplicationModel application) : Controller where T : Person
{
    protected ApplicationModel Application { get; } = application;

    protected abstract PersonsConfig<T> Config { get; }

    // -----------------------------------------------------------------------
    // GET /doctors (oder /clients)
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public async Task<IActionResult> List()
    {
        var persons = await Config.List();
        return View("~/Views/Persons/List.cshtml", new PersonListModel
        {
            PageTitle = Config.Keys.Title,
            Keys = Config.Keys,
            AddUrl = $"{Config.Url}/add",
            Persons = persons
                .Select(p => new PersonView(p.Title, p.FirstName, p.LastName, p.User?.Login ?? "",
                    $"{Config.Url}/{p.Id}/edit", $"{Config.Url}/{p.Id}/delete"))
                .ToList(),
        });
    }

    // -----------------------------------------------------------------------
    // GET /doctors/add
    // -----------------------------------------------------------------------
    [HttpGet("add")]
    public IActionResult AddForm() => ShowForm(null, new PersonValues());

    // -----------------------------------------------------------------------
    // POST /doctors/add
    // [form] wurde von MVC gefüllt UND validiert: ModelState sagt, ob die
    // Eingabe korrekt ist.
    // -----------------------------------------------------------------------
    [HttpPost("add")]
    public async Task<IActionResult> Add(PersonForm form)
    {
        if (!ModelState.IsValid)
        {
            return ShowForm(null, EnteredValues(form), Validation.ErrorsOf(ModelState));
        }
        try
        {
            var person = await Config.Add(Data(form));
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Added, MessageParams(person));
            return Redirect(Config.Url);
        }
        catch (BusinessException e)
        {
            return ShowBusinessError(null, EnteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // GET /doctors/{id}/edit
    // {id:int}: eine "Route Constraint" - /doctors/abc/edit passt auf
    // keine Route (Seite 404)
    // -----------------------------------------------------------------------
    [HttpGet("{id:int}/edit")]
    public async Task<IActionResult> EditForm(int id)
    {
        var person = await Config.Find(id);
        if (person is null)
        {
            return NotFound();
        }
        return ShowForm(id, new PersonValues
        {
            Title = person.Title,
            FirstName = person.FirstName,
            LastName = person.LastName,
            Login = person.User?.Login ?? "",
            Version = person.Version,
        });
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/edit
    // -----------------------------------------------------------------------
    [HttpPost("{id:int}/edit")]
    public async Task<IActionResult> Edit(int id, PersonForm form)
    {
        if (!ModelState.IsValid)
        {
            return ShowForm(id, EnteredValues(form), Validation.ErrorsOf(ModelState));
        }
        try
        {
            var person = await Config.Edit(id, Data(form));
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Edited, MessageParams(person));
            return Redirect(Config.Url);
        }
        catch (BusinessException e)
        {
            return ShowBusinessError(id, EnteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/delete
    // (die Bestätigung "Are you sure?" wird vom Browser vor dem
    // Senden des Formulars abgefragt, siehe wwwroot/js/app.js)
    // -----------------------------------------------------------------------
    [HttpPost("{id:int}/delete")]
    public async Task<IActionResult> Delete(int id)
    {
        var person = await Config.Find(id);
        try
        {
            await Config.Delete(id);
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Deleted, MessageParams(person));
        }
        catch (BusinessException e)
        {
            Flash.Put(HttpContext, FlashType.Danger, e.Key, new Dictionary<string, string>(e.Params));
        }
        return Redirect(Config.Url);
    }

    // ───────────────────────────────────────────────────────────────── private Methoden

    // null-ID: Erstellungsformular; sonst: Bearbeitungsformular
    private ViewResult ShowForm(
        int? id,
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null)
    {
        var creating = id is null;
        return View("~/Views/Persons/Form.cshtml", Validation.Prepare(
            new PersonFormModel
            {
                PageTitle = creating ? Config.Keys.Add : Config.Keys.Edit,
                Creating = creating,
                Action = creating ? $"{Config.Url}/add" : $"{Config.Url}/{id}/edit",
                ListUrl = Config.Url,
                Values = values,
            },
            errors, error, otherFields));
    }

    // eine fachliche Regel hat den Schreibzugriff abgelehnt: Wir zeigen das Formular erneut an,
    // mit der Eingabe des Benutzers und der Nachricht der Geschäftsschicht
    private IActionResult ShowBusinessError(int? id, PersonValues values, BusinessException e)
    {
        if (e.Key is "ERRORS.DOCTOR_NOT_FOUND" or "ERRORS.PATIENT_NOT_FOUND")
        {
            // zwischenzeitlich von einem anderen ADMIN gelöscht: zurück zur Liste
            Flash.Put(HttpContext, FlashType.Danger, e.Key);
            return Redirect(Config.Url);
        }
        // die Nachricht steht unten auf der Seite; die betroffenen Felder, falls vorhanden, werden
        // rot umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
        return ShowForm(id, values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
    }

    // was der Benutzer eingegeben hat (Passwort ausgenommen: Wir senden es nie an den Browser zurück)
    private static PersonValues EnteredValues(PersonForm f) => new()
    {
        Title = f.Title ?? "",
        FirstName = f.FirstName ?? "",
        LastName = f.LastName ?? "",
        Login = f.Login ?? "",
        Version = f.Version,
    };

    // das validierte Formular -> die von der Geschäftsschicht erwarteten Daten
    private static PersonData Data(PersonForm f) => new()
    {
        Title = f.Title!,
        LastName = f.LastName!,
        FirstName = f.FirstName!,
        Login = f.Login,
        Password = f.Password,
        Version = f.Version,
    };

    // {name} und {login} der Nachrichten "hinzugefügt / aktualisiert / gelöscht"
    private static Dictionary<string, string> MessageParams(Person? person) => person is null
        ? new() { ["name"] = "", ["login"] = "" }
        : new() { ["name"] = $"{person.FirstName} {person.LastName}", ["login"] = person.User?.Login ?? "" };
}

Die Verwaltung von Ärzten und Clients ist identisch. Statt zwei ähnliche Controller zu schreiben, schreiben wir ihre Aktionen einmal in einer abstrakten, generischen Elternklasse. Kommentieren wir diesen Code:

  • Zeilen 15–20: die Routen für die Ärzte; dieselben gibt es unter [/clients];
  • Zeilen 22–23: Auch die Views werden gemeinsam genutzt (Ordner [Views/Persons]);
  • Zeilen 25–26: MVC akzeptiert als Controller nur konkrete Klassen: Nur [DoctorsController] und [ClientsController] empfangen Anfragen;
  • Zeilen 38–45: die von jeder Unterklasse bereitgestellte Konfiguration: die Basis-URL, die Texte (Übersetzungsschlüssel, gruppiert in [record] und [PersonKeys] aus [Models/ViewModels.cs]) und die Funktionen, die zum Auflisten, Suchen, Hinzufügen, Ändern und Löschen aufzurufen sind. [Func<int, Task<T?>>] ist der Typ einer Funktion, die einen [int] entgegennimmt und eine [Task<T?>] zurückgibt: So werden Methoden in Eigenschaften gespeichert, um später aufgerufen zu werden. [where T : Person] ist eine Einschränkung des generischen Typs: [T] ist entweder [Doctor] oder [Client], zwei von [Person] abgeleitete Klassen; der Code kann daher [p.FirstName] oder [p.User] verwenden, die allen Personen gemeinsam sind;
  • Zeile 47: die Elternklasse, die generisch ist (siehe die Klasse [ViewPage<TModel>] in Beispiel 22) und abstrakt. Sie erhält [ApplicationModel] über ihren primären Konstruktor und reicht es über die geschützte Eigenschaft [Application] ([protected]: nur für Unterklassen sichtbar) an ihre Unterklassen weiter;
  • Zeile 51: eine abstrakte Eigenschaft: Jede Unterklasse muss sie definieren;
  • Zeilen 56–69: die Liste. Die an den Methoden einer Elternklasse gesetzten Routenattribute werden vererbt: Kombiniert mit dem [[Route("doctors")]] der Unterklasse ergeben sie [GET /doctors]. Für jede Person enthält das Modell die URL ihrer Schaltflächen „Bearbeiten“ und „Löschen“. [p.User?.Login ?? ""]: der Login des zugehörigen Kontos oder eine leere Zeichenfolge, wenn die Person kein Konto hat;
  • Zeile 60: Die View wird über ihren vollständigen Pfad angegeben. Würde nur ihr Name verwendet, suchte MVC sie im Ordner des Controllers ([Views/Doctors] oder [Views/Clients], siehe Beispiel 13), obwohl sie von beiden gemeinsam genutzt wird;
  • Zeilen 75–76: das leere Formular;
  • Zeilen 83–98: das Hinzufügen in drei Schritten, wie in Beispiel 28. Der Parameter [form] wurde vor dem Aufruf von MVC befüllt und validiert (siehe Beispiel 19): Eine ungültige Eingabe zeigt das Formular erneut an, mit den eingegebenen Werten und einer Meldung unter jedem fehlerhaften Feld; eine gültige Eingabe wird an die Geschäftsschicht übergeben, dann wird der Browser mit einer Flash-Meldung zur Liste umgeleitet (PRG); eine Ablehnung durch die Geschäftsschicht (ein Namensvetter, ein bereits verwendeter Login) zeigt das Formular erneut an;
  • Zeilen 107–121: das vorausgefüllte Änderungsformular. Die Routeneinschränkung [:int] (siehe Beispiel 02) akzeptiert nur einen ganzzahligen Bezeichner: [/doctors/abc/edit] entspricht keiner Route und führt zu einer Seite 404 ([ParseIntPipe] aus [NestJS] führte zu einem Fehler 400). Auch eine nicht vorhandene Person führt zu einer 404. Die Versionsnummer, ein verstecktes Feld des Formulars, dient der optimistischen Sperre (siehe Beispiel 28);
  • Zeilen 128–143: die Aktualisierung, nach demselben Muster wie das Einfügen;
  • Zeilen 152–165: das Löschen. Die Person wird vorher abgerufen, um ihren Namen in der Bestätigungsmeldung anzuzeigen. Eine Ablehnung durch die Geschäftsschicht (z. B. ein Arzt mit Terminen) führt zu einer Flash-Fehlermeldung auf der Listenseite;
  • Zeilen 171–188: das Formular für die Erstellung ([id] entspricht [null]), wie für die Änderung: Nur der Titel und die Absendeadresse ([Action]) ändern sich. [Validation.Prepare] (Ordner [Web]) befüllt das Template mit den feldspezifischen Fehlermeldungen, der Meldung am Seitenende und den rot hervorzuhebenden Feldern;
  • Zeilen 193–203: Eine Person, die inzwischen (von einem anderen Administrator) gelöscht wurde, wird erneut aufgelistet; andere Geschäftsfehler zeigen das Formular erneut an, mit der Meldung am Seitenende und den betroffenen, rot hervorgehobenen Feldern ([Validation.BusinessErrorFields] ordnet jedem Fehlercode die zugehörigen Felder zu: [firstName] und [lastName] bei einem Namensvetter). [is "A" or "B"] vergleicht einen Wert mit mehreren Konstanten;
  • Zeilen 207–213: die erneut anzuzeigenden Werte – niemals das Passwort;
  • Zeilen 217–224: die an die Geschäftsschicht übermittelten Daten. Die [!]-Felder bergen kein Risiko: Die Validierung hat das Vorhandensein dieser Felder geprüft;
  • Zeilen 228–230: die Parameter [{name}] und [{login}] in den Erfolgsmeldungen: Vor- und Nachname der Person sowie ihr Login.

11.16.4. Controllers/DoctorsController.cs

// =========================================================================
// Controllers/DoctorsController.cs
// -------------------------------------------------------------------------
// Verwaltung der Ärzte (nur Rolle ADMIN). Alle Actions werden
// von PersonsControllerBase geerbt: Hier bleibt nur noch zu sagen, WAS
// aufzurufen und WELCHE Beschriftungen anzuzeigen sind.
//
// [Authorize(Roles = "ADMIN")] auf der KLASSE gilt für alle ihre
// Actions, auch die geerbten.
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "ADMIN")]
[Route("doctors")]
public class DoctorsController(ApplicationModel application) : PersonsControllerBase<Doctor>(application)
{
    protected override PersonsConfig<Doctor> Config => new(
        Url: "/doctors",
        Keys: new PersonKeys(
            Title: "DOCTORS.TITLE",
            Add: "DOCTORS.ADD",
            Edit: "DOCTORS.EDIT",
            Empty: "DOCTORS.EMPTY",
            ConfirmDelete: "DOCTORS.DELETE_CONFIRM",
            Added: "DOCTORS.ADDED",
            Edited: "DOCTORS.UPDATED",
            Deleted: "DOCTORS.DELETED"),
        List: Application.GetAllDoctorsAsync,
        Find: Application.GetDoctorByIdAsync,
        Add: Application.AddDoctorAsync,
        Edit: Application.EditDoctorAsync,
        Delete: Application.DeleteDoctorAsync);
}
  • Zeilen 20–22: ADMIN vorbehalten. Das an der Klasse gesetzte Attribut gilt für alle ihre Aktionen, auch für geerbte. Der Controller erbt von [PersonsControllerBase<Doctor>]: Der Typ der Elternklasse, [T], wird zu [Doctor]. Sein primärer Konstruktor reicht [application] an den Konstruktor der Elternklasse weiter. (In [TypeScript] musste ein expliziter Konstruktor geschrieben werden, damit [NestJS] wusste, was zu injizieren ist; hier ist das nicht nötig);
  • Zeilen 24–34: die Konfiguration. [override] definiert die abstrakte Eigenschaft der Elternklasse neu; [=>] macht daraus eine berechnete Eigenschaft, die das Objekt bei jedem Lesen erstellt. Die benannten Argumente ([Url:], [Keys:] ...) machen die Liste lesbar;
  • Zeilen 35–39: die aufzurufenden Funktionen, bei denen es sich um Methoden von [ApplicationModel] handelt. [Application.GetAllDoctorsAsync], ohne Klammern geschrieben, ruft die Methode nicht auf: Es verweist auf sie, und der Compiler wandelt es in einen Wert des erwarteten Typs [Func] um.

11.16.5. Controllers/ClientsController.cs

// =========================================================================
// Controllers/ClientsController.cs
// -------------------------------------------------------------------------
// Verwaltung der Clients (der PATIENTEN der Praxis), nur Rolle ADMIN.
// Gleiches Prinzip wie DoctorsController (siehe dessen Kommentare).
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "ADMIN")]
[Route("clients")]
public class ClientsController(ApplicationModel application) : PersonsControllerBase<Client>(application)
{
    protected override PersonsConfig<Client> Config => new(
        Url: "/clients",
        Keys: new PersonKeys(
            Title: "CLIENTS.TITLE",
            Add: "CLIENTS.ADD",
            Edit: "CLIENTS.EDIT",
            Empty: "CLIENTS.EMPTY",
            ConfirmDelete: "CLIENTS.DELETE_CONFIRM",
            Added: "CLIENTS.ADDED",
            Edited: "CLIENTS.UPDATED",
            Deleted: "CLIENTS.DELETED"),
        List: Application.GetAllClientsAsync,
        Find: Application.GetClientByIdAsync,
        Add: Application.AddClientAsync,
        Edit: Application.EditClientAsync,
        Delete: Application.DeleteClientAsync);
}

Derselbe Controller für Clients: andere Route, andere Übersetzungsschlüssel, andere Methoden von [ApplicationModel].

11.16.6. Controllers/RegistrationController.cs

// =========================================================================
// Controllers/RegistrationController.cs
// -------------------------------------------------------------------------
// "Create a patient account": Ein Patient, der noch kein Konto hat,
// erstellt es selbst. NICHT geschützte Routen (wir haben per
// Definition noch kein Konto):
//
//   POST /register/access     Schaltfläche "Create a patient account" der
//                             Authentifizierungsseite: prüft das CAPTCHA
//                             DIESER Seite und öffnet dann das Formular
//   GET  /register            das Formular
//   POST /register            die Erstellung, dann zurück zur Login-Seite
//
// Der Ablauf wird durch EIN CAPTCHA vor Robotern geschützt, das der
// Authentifizierungsseite:
//   1. Die Schaltfläche "Create a patient account" sendet das Login-Formular
//      an /register/access; wird das CAPTCHA korrekt abgetippt, stellt der Server
//      einen Pass aus (siehe Auth/RegistrationPassService.cs);
//   2. ohne gültigen Pass leitet /register zur
//      Authentifizierungsseite um - die direkte Eingabe der URL nützt nichts;
//   3. der Pass wird bei der Erstellung verbraucht: Ein gelöstes CAPTCHA
//      erlaubt die Erstellung EINES Kontos;
//   4. zusätzlich ist die Anzahl der pro Stunde und IP-Adresse erstellten Konten
//      begrenzt (siehe Auth/AttemptLimiterService.cs).
//
// Das erstellte Konto ist genau das, welches der ADMIN über die Seite
// "Patienten" erstellen würde (dieselbe Methode der Geschäftsschicht: AddClientAsync),
// nur dass der Patient sein Login und Passwort WÄHLT (erforderlich,
// mit Bestätigung).
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Route("register")]
public class RegistrationController(
    ApplicationModel application,
    CaptchaService captchaService,
    AttemptLimiterService limiter,
    RegistrationPassService passes) : Controller
{
    // -----------------------------------------------------------------------
    // POST /register/access   Felder: captchaId, captcha (die der
    // Authentifizierungsseite; Login und Passwort, ebenfalls gesendet, werden ignoriert)
    // -----------------------------------------------------------------------
    [HttpPost("access")]
    public IActionResult Access([FromForm] string? captchaId, [FromForm] string? captcha)
    {
        var ip = AuthController.IpAddress(HttpContext);

        // zu viele kürzlich von dieser Adresse erstellte Konten: Weiter geht es nicht
        var minutes = limiter.RegistrationBlockMinutes(ip);
        if (minutes > 0)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.TOO_MANY_ACCOUNTS", new() { ["minutes"] = minutes.ToString() });
            return Redirect("/login");
        }

        // fehlendes oder falsches CAPTCHA: zurück zur Authentifizierungsseite, mit
        // einem neuen Bild (ein Fehlschlag zählt als Login-Fehlversuch)
        if (!captchaService.Verify(captchaId, captcha))
        {
            limiter.LoginFailure(ip, "");
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CAPTCHA_BEFORE_ACCOUNT");
            return Redirect("/login");
        }

        // korrektes CAPTCHA: Wir stellen den Pass aus und öffnen das Formular
        Response.Cookies.Append(RegistrationPassService.Cookie, passes.Issue(), RegistrationPassService.GetCookieOptions());
        return Redirect("/register");
    }

    // -----------------------------------------------------------------------
    // GET /register
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public IActionResult Form()
    {
        if (!HasPass())
        {
            return BackToLogin();
        }
        return Show(new PersonValues());
    }

    // -----------------------------------------------------------------------
    // POST /register
    // Der Parameter [form] wird vor dem Aufruf von MVC gefüllt und VALIDIERT:
    // Das Ergebnis der Validierung steht in ModelState.
    // -----------------------------------------------------------------------
    [HttpPost("")]
    public async Task<IActionResult> Create(RegistrationForm form)
    {
        if (!HasPass())
        {
            return BackToLogin();
        }
        var ip = AuthController.IpAddress(HttpContext);
        var values = new PersonValues
        {
            Title = form.Title ?? "Mr",
            FirstName = form.FirstName ?? "",
            LastName = form.LastName ?? "",
            Login = form.Login ?? "",
        };

        // 1. zu viele kürzlich von dieser Adresse erstellte Konten?
        var minutes = limiter.RegistrationBlockMinutes(ip);
        if (minutes > 0)
        {
            return Show(values, null, "ERRORS.TOO_MANY_ACCOUNTS", null, new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }

        // 2. alle Eingabefehler auf einmal (Felder + Bestätigung):
        //    Der Benutzer korrigiert sie alle in einem Zug
        var errors = Validation.ErrorsOf(ModelState);
        if (!errors.ContainsKey("password") && !errors.ContainsKey("confirmation") && form.Password != form.Confirmation)
        {
            errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER";
        }
        if (errors.Count > 0)
        {
            return Show(values, errors);
        }

        // 3. die Erstellung (Client + USER-Konto, in einer Transaktion)
        try
        {
            // "!": Wir sichern dem Compiler zu, dass diese Werte nicht null sind -
            // was stimmt, da die Validierung ([Required]) erfolgreich war
            await application.AddClientAsync(new PersonData
            {
                Title = form.Title!,
                LastName = form.LastName!,
                FirstName = form.FirstName!,
                Login = form.Login,
                Password = form.Password,
            });
        }
        catch (BusinessException e)
        {
            // Login oder Vorname + Nachname bereits vergeben: Der Pass bleibt gültig
            return Show(values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
        }

        // 4. der Pass wurde verwendet: Er erlaubt nicht die Erstellung eines 2. Kontos
        passes.Consume(Request.Cookies[RegistrationPassService.Cookie]);
        Response.Cookies.Delete(RegistrationPassService.Cookie, new CookieOptions { Path = "/register" });
        limiter.RegistrationSuccess(ip);

        // 5. zurück zur Login-Seite, Login vorausgefüllt
        Flash.Put(HttpContext, FlashType.Success, "REGISTRATION.DONE", new() { ["login"] = form.Login! });
        return Redirect($"/login?login={Uri.EscapeDataString(form.Login!)}");
    }

    // ───────────────────────────────────────────────────────────────── private Methoden

    private bool HasPass() => passes.IsValid(Request.Cookies[RegistrationPassService.Cookie]);

    // kein gültiger Pass: zurück zur Authentifizierungsseite
    private RedirectResult BackToLogin()
    {
        Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CAPTCHA_BEFORE_ACCOUNT");
        return Redirect("/login");
    }

    // das Formular; es wird nie ein Passwort an den Browser zurückgesendet
    private ViewResult Show(
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Registration", Validation.Prepare(
            new RegistrationModel { PageTitle = "REGISTRATION.TITLE", Values = values },
            errors, error, otherFields, errorParams));
}

Kommentieren wir diesen Code:

  • Zeilen 14–24: Schutz vor Bots in vier Schritten. Das CAPTCHA und der Versuchsbegrenzer wurden in Beispiel 27 eingeführt;
  • Zeilen 40–45: Der Controller hat nicht das Attribut [[Authorize]]; seine Seiten sind für alle offen. Er erhält vier Services per Injektion;
  • Zeilen 51–52: Die Schaltfläche „Patientenkonto erstellen“ auf der Anmeldeseite sendet das Anmeldeformular an diese Adresse (Attribut [formaction]; siehe Beispiel 20). Es werden nur die CAPTCHA-Felder gelesen;
  • Zeile 54: die IP-Adresse des Browsers, über eine statische Methode von [AuthController];
  • Zeilen 57–61: Von dieser Adresse aus wurden in der letzten Stunde zu viele Konten erstellt: Der Benutzer wird zur Anmeldeseite umgeleitet, mit einer Pop-up-Meldung, die die Anzahl der zu wartenden Minuten angibt. [new() { ["minutes"] = ... }] erstellt das Wörterbuch der Meldungsparameter: Sein Typ wird aus dem Parameter von [Flash.Put] abgeleitet;
  • Zeilen 66–70: Ein fehlendes oder falsches CAPTCHA zählt als fehlgeschlagener Anmeldeversuch (mit leerem Benutzernamen): Ein Bot kann nicht unbegrenzt weiterprobieren. Die Rückkehr zur Anmeldeseite zeigt ein neues Bild an;
  • Zeilen 74–75: Das CAPTCHA ist korrekt: Ein Pass (siehe [Auth/RegistrationPassService.cs]) wird in einem Cookie gespeichert, und der Browser wird zum Formular umgeleitet;
  • Zeilen 81–88: das Formular, nur mit gültigem Pass. Die Adresse [/register] direkt einzugeben ist zwecklos;
  • Zeilen 96–97: die Erstellung. Das Formular [RegistrationForm] (Ordner [Models]) wurde von MVC gebunden und validiert;
  • Zeilen 99–101: Der Pass wird erneut geprüft: Die POST-Anfrage könnte gesendet worden sein, ohne das Formular zu durchlaufen;
  • Zeilen 104–109: die im Fehlerfall erneut anzuzeigenden Werte, ohne das Passwort. Die Standardanrede ist [Mr];
  • Zeilen 113–116: die Zeitbegrenzung, die bei der Erstellung erneut geprüft wird;
  • Zeilen 121–128: Eingabefehler, Feld für Feld (siehe Beispiel 19). Die Übereinstimmung zwischen dem Passwort und seiner Bestätigung – die zwei Felder betrifft – wird hier manuell geprüft; sie wird nur getestet, wenn diese beiden Felder ansonsten korrekt sind. Alle Fehler werden gemeinsam gemeldet: Der Benutzer korrigiert sie alle auf einmal;
  • Zeilen 136–148: Erstellung des Clients und seines Kontos USER mit der Methode der Geschäftsschicht, die auch ADMIN verwendet. Ist ein Benutzername oder eine Kombination aus Vor- und Nachname bereits vergeben, wird das Formular erneut angezeigt, wobei die betreffenden Felder rot hervorgehoben sind; der Pass bleibt gültig;
  • Zeilen 152–154: Der Pass wurde verwendet: Er wird serverseitig verbraucht, und sein Cookie wird gelöscht. Um ein Cookie zu löschen, müssen Sie denselben Pfad ([Path]) angeben wie bei seiner Erstellung: Das Pass-Cookie wird nur an Adressen [/register...] gesendet. Die Erstellung wird schließlich auf das stündliche Limit angerechnet;
  • Zeilen 157–158: Rückkehr zur Anmeldeseite, mit vorausgefülltem Benutzernamen und einer Erfolgsmeldung. [Uri.EscapeDataString] kodiert den Benutzernamen, damit er in eine URL aufgenommen werden kann;
  • Zeile 163: Der Pass wird aus dem Cookie der Anfrage gelesen;
  • Zeilen 166–169: Ist kein Pass vorhanden, Rückkehr zur Anmeldeseite mit einer Meldung;
  • Zeilen 173–181: Das von [Validation.Prepare] vorbereitete Formular ist dasselbe wie bei Ärzten und Clients. [errorParams] dient für die Parameter der Meldung am Seitenende (die Anzahl der Minuten).

11.16.7. Controllers/PatientAreaController.cs

// =========================================================================
// Controllers/PatientAreaController.cs
// -------------------------------------------------------------------------
// Die PERSÖNLICHEN Seiten des Patienten (Rolle USER), die er direkt
// nach dem Login sieht:
//
//   GET  /my-area                  Startseite: [Manage my account],
//                                  [View a schedule] und sein bevorstehender Termin
//   POST /my-area/cancel           storniert SEINEN Termin
//   GET  /my-account               Formular zum Bearbeiten seines Kontos
//   POST /my-account               Aktualisierung
//   POST /my-account/delete        Löschung des Kontos (und seiner Termine)
//
// Goldene Regel dieses Controllers: Der betroffene Patient ist IMMER der aus dem
// Token (Patient.ConnectedPatientAsync), nie ein vom Browser gesendeter
// Bezeichner. Ein Patient kann daher weder sehen, noch ändern, noch stornieren, was
// einem anderen Patienten gehört, auch nicht, indem er seine Anfragen selbst fälscht.
//
// Jede Änderung oder Löschung des Kontos erfordert das AKTUELLE
// Passwort: Wer eine offen gebliebene Sitzung gefunden hat, könnte
// weder das Passwort ändern noch das Konto löschen. Fehler beim aktuellen Passwort
// zählen als Login-Fehlversuche (gleiches Limit).
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "USER")]
public class PatientAreaController(
    ApplicationModel application,
    AuthService authService,
    AttemptLimiterService limiter) : Controller
{
    // -----------------------------------------------------------------------
    // GET /my-area
    // -----------------------------------------------------------------------
    [HttpGet("my-area")]
    public async Task<IActionResult> Area()
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var appointments = await application.GetClientUpcomingAppointmentsAsync(patient.Id);
        return View("Area", new AreaModel
        {
            PageTitle = "AREA.TITLE",
            Patient = Labels.Label(patient),
            Appointments = appointments.Select(a => new AppointmentView(
                a.Id,
                WebDates.FormatDay(a.Day),
                WebDates.Time(a.Slot),
                Labels.Label(a.Slot.Doctor),
                // Link zum Terminkalender des Arztes an diesem Tag: Der Patient sieht dort seinen Namen
                $"/schedule?doctorId={a.Slot.Doctor.Id}&day={WebDates.Iso(a.Day)}")).ToList(),
        });
    }

    // -----------------------------------------------------------------------
    // POST /my-area/cancel   Feld: appointmentId
    // -----------------------------------------------------------------------
    [HttpPost("my-area/cancel")]
    public async Task<IActionResult> CancelAppointment([FromForm] string? appointmentId)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var appointment = Input.PositiveInteger(appointmentId) is int id ? await application.GetAppointmentByIdAsync(id) : null;
        // ein nicht existierender Termin und der eines ANDEREN Patienten erhalten
        // dieselbe Antwort: Wir verraten nichts über die Termine der anderen
        if (appointment is null || appointment.ClientId != patient.Id)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.APPOINTMENT_NOT_FOUND");
        }
        else
        {
            await application.DeleteAppointmentAsync(appointment);
            Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.CANCELLED");
        }
        return Redirect("/my-area");
    }

    // -----------------------------------------------------------------------
    // GET /my-account
    // -----------------------------------------------------------------------
    [HttpGet("my-account")]
    public async Task<IActionResult> AccountForm()
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        return Show(new PersonValues
        {
            Title = patient.Title,
            FirstName = patient.FirstName,
            LastName = patient.LastName,
            Login = patient.User.Login,
            Version = patient.Version,
        });
    }

    // -----------------------------------------------------------------------
    // POST /my-account
    // -----------------------------------------------------------------------
    [HttpPost("my-account")]
    public async Task<IActionResult> EditAccount(MyAccountForm form)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var values = new PersonValues
        {
            Title = form.Title ?? patient.Title,
            FirstName = form.FirstName ?? "",
            LastName = form.LastName ?? "",
            Login = form.Login ?? "",
            Version = form.Version,
        };

        var errors = Validation.ErrorsOf(ModelState);
        if (!errors.ContainsKey("password") && form.Password is not null && form.Password != form.Confirmation)
        {
            errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER";
        }
        if (errors.Count > 0)
        {
            return Show(values, errors);
        }

        // das aktuelle Passwort
        var passwordError = await CheckCurrentPasswordAsync(patient, form.CurrentPassword);
        if (passwordError is not null)
        {
            var (key, messageParams) = passwordError.Value;
            return Show(
                values,
                key == "ERRORS.WRONG_CURRENT_PASSWORD" ? new(StringComparer.OrdinalIgnoreCase) { ["currentPassword"] = key } : null,
                key,
                null,
                messageParams);
        }

        try
        {
            var client = await application.EditClientAsync(patient.Id, new PersonData
            {
                Title = form.Title!,
                LastName = form.LastName!,
                FirstName = form.FirstName!,
                Login = form.Login,
                Password = form.Password, // null = unverändert
                Version = form.Version,
            });
            // das Login und der Anzeigename stehen IM Token: Wir stellen ein
            // neues aus, sonst würde die Navigationsleiste den alten Namen behalten
            authService.SetToken(Response, client.User);
            Flash.Put(HttpContext, FlashType.Success, "MY_ACCOUNT.UPDATED");
            return Redirect("/my-area");
        }
        catch (BusinessException e)
        {
            return Show(values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
        }
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   Feld: deletePassword
    // Das Konto, der Client und ALLE seine Termine verschwinden gemeinsam,
    // dann wird der Patient abgemeldet.
    // -----------------------------------------------------------------------
    [HttpPost("my-account/delete")]
    public async Task<IActionResult> DeleteAccount([FromForm] string? deletePassword)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var passwordError = await CheckCurrentPasswordAsync(patient, deletePassword);
        if (passwordError is not null)
        {
            var (key, messageParams) = passwordError.Value;
            Flash.Put(HttpContext, FlashType.Danger, key, messageParams);
            return Redirect("/my-account");
        }
        await application.DeleteClientAsync(patient.Id);
        AuthService.ClearToken(Response);
        Flash.Put(HttpContext, FlashType.Success, "MY_ACCOUNT.DELETED");
        return Redirect("/login");
    }

    // ───────────────────────────────────────────────────────────────── private Methoden

    // null, wenn das aktuelle Passwort korrekt ist; sonst der Schlüssel der Nachricht
    // (und ihre Parameter). Der Rückgabetyp ist ein nullable "Tupel".
    private async Task<(string Key, Dictionary<string, string>? Params)?> CheckCurrentPasswordAsync(
        Client patient, string? password)
    {
        var ip = AuthController.IpAddress(HttpContext);
        var login = patient.User.Login;
        var minutes = limiter.LoginBlockMinutes(ip, login);
        if (minutes > 0)
        {
            return ("ERRORS.TOO_MANY_ATTEMPTS", new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }
        var ok = !string.IsNullOrEmpty(password) && await authService.ValidateUserAsync(login, password) is not null;
        if (!ok)
        {
            limiter.LoginFailure(ip, login);
            return ("ERRORS.WRONG_CURRENT_PASSWORD", null);
        }
        return null;
    }

    private ViewResult Show(
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Account", Validation.Prepare(
            new MyAccountModel { PageTitle = "MY_ACCOUNT.TITLE", Values = values },
            errors, error, otherFields, errorParams));
}

Gehen wir diesen Code durch:

  • Zeilen 14–17: die goldene Regel dieses Controllers: Der betreffende Patient ist immer derjenige, der dem Token zugeordnet ist, niemals ein vom Browser gesendeter Bezeichner;
  • Zeilen 35–39: Patienten vorbehalten. Der Controller hat kein [[Route]]-Attribut: Jede Aktion gibt ihre vollständige Adresse an, da sie kein gemeinsames Präfix haben ([/my-area], [/my-account]);
  • Zeilen 44–59: die Seite „Mein Bereich“. [Patient.ConnectedPatientAsync] identifiziert den Benutzer anhand des Tokens; wurde sein Konto seit der Anmeldung gelöscht, löst es eine [InvalidSessionException] aus, die der Filter [Web/HtmlExceptionFilter.cs] zur Anmeldeseite zurückleitet. Das Datum wird von [WebDates.FormatDay] gemäß der Sprache der Anfrage formatiert, die von der Lokalisierungs-Middleware festgelegt wird (siehe Beispiel 22); jeder Termin enthält einen Link zum Terminkalender des Arztes für diesen Tag;
  • Zeilen 66–82: Stornierung des Termins des Patienten. [condition ? value1 : value2] liefert hier den Termin oder [null] , wenn die ID ungültig ist. Ein nicht vorhandener Termin und einer, der einem anderen Patienten gehört (Zeile 73), erhalten dieselbe Antwort: Über die Termine anderer Patienten wird keine Information preisgegeben;
  • Zeilen 88–98: das Kontoformular, vorausgefüllt, mit der Versionsnummer (optimistische Sperre);
  • Zeilen 105–106: der Änderungsvorgang in drei Schritten: Validierung, Prüfung des aktuellen Passworts, Geschäftslogik;
  • Zeilen 109–115: die im Fehlerfall erneut anzuzeigenden Werte, niemals Passwörter;
  • Zeilen 118–125: Eingabefehler. Das neue Passwort ist optional (leer: unverändert); seine Bestätigung wird nur verglichen, wenn sie eingegeben wurde;
  • Zeilen 129–138: das aktuelle Passwort. [var (key, messageParams) = ...] zerlegt das von der Prüfung zurückgegebene Paar. Ein falsches Passwort wird unter seinem Feld und am Seitenende angezeigt; eine Sperre (zu viele Versuche) wird nur am Seitenende angezeigt, zusammen mit der Anzahl der Minuten;
  • Zeilen 143–150: die Änderung durch die Geschäftsschicht, die dieselben Regeln anwendet wie für ADMIN (Eindeutigkeit, optimistische Sperre);
  • Zeile 154: Das Token enthält den Login und den Anzeigenamen: Nach einer Änderung wird ein neues Token ausgestellt; andernfalls behielte die Navigationsleiste den alten Namen;
  • Zeilen 158–160: Eine Ablehnung durch die Geschäftsschicht zeigt das Formular erneut an, mit den betreffenden rot hervorgehobenen Feldern;
  • Zeilen 169–183: das Löschen des Kontos, das ebenfalls das aktuelle Passwort erfordert. Ein Fehler wird durch eine Pop-up-Meldung auf der Kontoseite angezeigt (PRG);
  • Zeilen 180–181: Löschen des Datensatzes, des Kontos und aller Termine (die von ADMIN verwendete Methode der Geschäftsschicht), gefolgt von der Abmeldung: Das Token-Cookie wird gelöscht;
  • Zeilen 190–191: Prüfung des aktuellen Passworts. Sie liefert [null] , wenn das Passwort korrekt ist; andernfalls liefert sie ein Tupel: ein Paar benannter Werte (den Meldungsschlüssel und seine Parameter). Das abschließende [?] macht dieses Tupel „nullable“;
  • Zeilen 195–198: Für das aktuelle Passwort gilt derselbe Begrenzer wie für die Anmeldung (siehe Beispiel 27). Wer eine offen gebliebene Sitzung findet, kann das Passwort nicht ändern, das Konto nicht löschen und nicht unbegrenzt Passwörter ausprobieren;
  • Zeilen 200–204: der Authentifizierungsvorgang selbst, abgewickelt von [AuthService]; ein fehlgeschlagener Authentifizierungsversuch zählt als fehlgeschlagener Anmeldeversuch;
  • Zeilen 209–217: das Kontoformular.

11.16.8. Controllers/ErrorController.cs

// =========================================================================
// Controllers/ErrorController.cs
// -------------------------------------------------------------------------
// Die Fehlerseite (400, 403, 404, 500).
//
// Sie wird nie über einen Link erreicht: Es sind die Middlewares
// UseStatusCodePagesWithReExecute("/error/{0}") und
// UseExceptionHandler("/error/500") (siehe Program.cs), die die
// fehlgeschlagene Anfrage mit dieser Adresse ERNEUT AUSFÜHREN, um die Seite aufzubauen, die
// statt einer leeren Antwort oder einer Exception zurückgesendet wird.
//
// [Route] ohne [HttpGet]: Die Action akzeptiert alle HTTP-Methoden - die
// erneut ausgeführte Anfrage behält ihre ursprüngliche Methode (ein abgelehnter POST bleibt ein POST).
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Models;

namespace RdvMedecins.Controllers;

public class ErrorController : Controller
{
    private static readonly Dictionary<int, string> Messages = new()
    {
        [StatusCodes.Status400BadRequest] = "ERRORS.BAD_REQUEST",
        [StatusCodes.Status403Forbidden] = "ERRORS.FORBIDDEN",
        [StatusCodes.Status404NotFound] = "ERRORS.NOT_FOUND",
    };

    [Route("error/{code:int}")]
    public IActionResult Show(int code)
    {
        // die Seite behält den ursprünglichen Fehlercode (404 bleibt 404...); ein
        // unerwarteter Code wird zu einem Fehler 500
        if (code < 400 || code > 599)
        {
            code = StatusCodes.Status500InternalServerError;
        }
        Response.StatusCode = code;
        return View("Error", new ErrorModel
        {
            PageTitle = "ERROR_PAGE.TITLE",
            Code = code,
            Message = Messages.GetValueOrDefault(code, "ERRORS.SERVER_ERROR"),
        });
    }
}

Dies ist der Controller aus Beispiel 24, mit übersetzten Meldungen:

  • Zeilen 23–28: der Meldungsschlüssel für jeden Fehlercode. [static readonly]: ein einziges Wörterbuch, das beim Laden der Klasse erstellt und nie ersetzt wird;
  • Zeilen 30–31: [[Route]], dem die HTTP-Methode fehlt, akzeptiert alle Methoden: Eine erneut ausgeführte POST-Anfrage (zum Beispiel ein Patient, der eine Administratoren vorbehaltene Stornierung versucht) bleibt eine POST-Anfrage;
  • Zeilen 35–37: ein HTTP-Code, der kein Fehler ist (eine manuell eingegebene Adresse [/error/200]), wird zu einem Fehler 500;
  • Zeile 39: Die Seite behält den ursprünglichen Fehlercode bei;
  • Zeilen 40–44: das Template der Seite. [GetValueOrDefault] liefert den dem Code zugeordneten Schlüssel oder [ERRORS.SERVER_ERROR] für jeden anderen Code (insbesondere 500).

11.17. Die Views

Die Views haben fast nichts zu entscheiden: Ihr Template wurde von den Controllern in den Klassen der Datei [Models/ViewModels.cs] vorbereitet (welche Schaltflächen angezeigt werden, welche URL-Elemente, welche Übersetzungsschlüssel). Jede View deklariert den Typ ihres Templates ([@model], siehe Beispiel 13): Ein Tippfehler in [@Model.Xxx] führt zu einem Kompilierfehler. Außerdem beginnt jede View mit einem [Razor]-Kommentar [@* ... *@] , der ihre Rolle beschreibt; diese Kommentare erscheinen nicht in den an den Browser gesendeten Seiten.

Ein Unterschied zu den Beispielen aus Kapitel 4: Die Fallstudie verwendet keine Tag Helper. Partielle Views werden mit [@await Html.PartialAsync("_Name")] eingefügt, dem Äquivalent des Tags [<partial name="_Name">] aus Beispiel 15. Ein zweites, optionales Argument liefert das Modell der partiellen View; ohne es erhält die partielle View das Modell der Seite. Die Methode ist asynchron (die partielle View muss gegebenenfalls kompiliert oder von der Festplatte gelesen werden): [await] wartet auf ihr Ergebnis.

11.17.1. Das Template und die partiellen Views

11.17.1.1. Views/_ViewImports.cshtml

@* =========================================================================
   Views/_ViewImports.cshtml
   -------------------------------------------------------------------------
   Wird vor JEDER View dieses Ordners und seiner Unterordner gelesen: die gemeinsamen
   "using"s und die Elternklasse aller Views (Web/ViewPage.cs), die ihnen
   @T("KEY"), CurrentUser, FlashMessage... bereitstellt.
   TModel bezeichnet den Modelltyp jeder View (@model ...).
   ========================================================================= *@
@using RdvMedecins
@using RdvMedecins.Models
@using RdvMedecins.Web
@inherits RdvMedecins.Web.ViewPage<TModel>
  • Zeilen 9–11: die Namespaces, deren Typen von den Views verwendet werden: die View-Templates ([RdvMedecins.Models]), die Flash-Meldungen ([RdvMedecins.Web]);
  • Zeile 12: die Elternklasse aller Views, [Web/ViewPage.cs], wie in Beispiel 22. Sie stellt ihnen die Übersetzung [@T("KEY")], die Sprache [Language], den angemeldeten Benutzer [CurrentUser], die Flash-Meldung [FlashMessage], den angeforderten Pfad [CurrentPath], und die Methode [Active] (aktiver Menüpunkt der Navigationsleiste) bereit. In der Version mit [NestJS] wurden diese Informationen über [res.locals] weitergegeben. Es gibt keine [@addTagHelper]-Direktive: Die Anwendung verwendet keine Tag Helper.

11.17.1.2. Views/_ViewStart.cshtml

@* =========================================================================
   Views/_ViewStart.cshtml
   -------------------------------------------------------------------------
   Wird vor jeder View ausgeführt: alle Seiten verwenden das gemeinsame Layout
   Views/Shared/_Layout.cshtml (hbs tat dies automatisch für
   views/layout.hbs; hier sagen wir es ausdrücklich).
   ========================================================================= *@
@{
    Layout = "_Layout";
}
  • Zeile 9: Alle Seiten verwenden das Template [Views/Shared/_Layout.cshtml] (siehe Beispiel 15). [Handlebars] verwendete automatisch [views/layout.hbs]; [Razor] verlangt, dass dies angegeben wird.

11.17.1.3. Views/Shared/_Layout.cshtml

@* =========================================================================
   Views/Shared/_Layout.cshtml
   -------------------------------------------------------------------------
   Das für alle Seiten GEMEINSAME Layout. Die vom Controller angeforderte Seite
   (Schedule.cshtml, Login.cshtml ...) wird an der Stelle
   @RenderBody() eingefügt.

   Razor ESCAPT alles, was es mit @ ausgibt (die Zeichen < > & " '
   werden zu &lt; &gt; ...): Schutz vor HTML-Injection, zum Beispiel über
   einen eingegebenen Namen. Um HTML unverändert einzufügen, muss dies
   ausdrücklich angefordert werden (@Html.Raw, siehe _Captcha.cshtml).

   Meldungen: Ein Erfolg wird OBEN auf der Seite angezeigt (_Flash), ein Fehler
   UNTEN, auf hellrosa Hintergrund (_Errors).

   Das Layout teilt das Modell der Seite: Handelt es sich um ein ViewModel (siehe
   Models/ViewModels.cs), werden Titel und Fehler der Seite daraus gelesen.
   ========================================================================= *@
@{
    var page = ViewData.Model as ViewModel;
}
<!doctype html>
<html lang="@Language">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>@T(page?.PageTitle ?? "APP.TITLE") - @T("APP.TITLE")</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-4">
    @await Html.PartialAsync("_Navbar")
    @await Html.PartialAsync("_Flash")
    @RenderBody()
    @await Html.PartialAsync("_Errors")
  </div>
  @* der Dialog "Are you sure?", ausgeblendet, solange er nicht benötigt wird *@
  @await Html.PartialAsync("_Confirmation")
  <script src="/js/app.js"></script>
</body>
</html>
  • Zeile 20: Das Template teilt sich das Seitenmodell, das über [ViewData.Model] zugänglich ist (vom Typ [object]). Alle Seiten-Templates leiten sich von der abstrakten Klasse [ViewModel] ab, die den Titelschlüssel ([PageTitle]) und den Seitenfehler ([Error]) enthält. [as ViewModel] liefert [null], wenn das Template kein [ViewModel] ist: Das Template funktioniert mit jeder Seite;
  • Zeile 23: die Sprache der Seite (siehe Beispiel 22);
  • Zeile 27: der übersetzte Titel, zum Beispiel „Terminkalender - RdvMedecins“. Anders als in Beispiel 22 wird der Schlüssel nicht von der View in [ViewData] gesetzt: Er wird vom Controller im typisierten Modell bereitgestellt. [page?.PageTitle] ergibt [null], wenn [page] gleich [null] ist, und der Operator [??] ersetzt den Schlüssel dann durch [APP.TITLE];
  • Zeilen 28–29: die Stylesheets, von [UseStaticFiles] aus dem Ordner [wwwroot] ausgeliefert: [Bootstrap] ([wwwroot/lib/bootstrap]) und das anwendungsspezifische Stylesheet;
  • Zeilen 33–36: die Navigationsleiste, die Erfolgsmeldung (oben), die angeforderte Seite ([@RenderBody()]) und der Fehlerbereich (unten);
  • Zeilen 39–40: das Bestätigungsfenster (versteckt) und sein Skript (siehe Beispiel 21), die am Seitenende geladen werden.

11.17.1.4. Views/Shared/_Navbar.cshtml

@* =========================================================================
   Views/Shared/_Navbar.cshtml - die Navigationsleiste.

   Titel, FR/EN, Rolle, Name, Logout - und ein Menü, dessen Einträge
   von der Rolle abhängen: "Doctors" und "Patients" erscheinen nur für
   den ADMIN. Das ist nur eine Anzeigeerleichterung: Der eigentliche Schutz ist
   das [Authorize(Roles = ...)] der Controller (ein USER, der /doctors
   von Hand eingibt, erhält eine 403-Seite). Ein Patient (USER) hat außerdem
   sein Menü "My area".
   ========================================================================= *@
@{
    var user = CurrentUser;
}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">@T("APP.TITLE")</span>

  @if (user is not null)
  {
    <ul class="navbar-nav me-auto">
      @if (user.IsPatient)
      {
        <li class="nav-item"><a class="nav-link @Active("/my-")" href="/my-area">@T("APP.MENU_MY_AREA")</a></li>
      }
      <li class="nav-item"><a class="nav-link @Active("/schedule")" href="/schedule">@T("APP.MENU_SCHEDULE")</a></li>
      @if (user.IsAdmin)
      {
        <li class="nav-item"><a class="nav-link @Active("/doctors")" href="/doctors">@T("APP.MENU_DOCTORS")</a></li>
        <li class="nav-item"><a class="nav-link @Active("/clients")" href="/clients">@T("APP.MENU_PATIENTS")</a></li>
      }
    </ul>
  }
  else
  {
    <div class="me-auto"></div>
  }

  <div class="d-flex align-items-center gap-2">
    @* FR / EN: einfache Links (GET /language/fr), die aktive Sprache hervorgehoben *@
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      <a class="btn @(Language == "fr" ? "btn-light" : "btn-outline-light")" href="/language/fr">FR</a>
      <a class="btn @(Language == "en" ? "btn-light" : "btn-outline-light")" href="/language/en">EN</a>
    </div>

    @if (user is not null)
    {
      <span class="badge text-bg-light text-primary">@user.Role</span>
      <span class="text-white">@user.Name</span>
      @* Logout ist ein POST: ein auf seinen Button reduziertes Formular *@
      <form method="post" action="/logout" class="m-0">
        <button type="submit" class="btn btn-sm btn-outline-light">@T("APP.LOGOUT")</button>
      </form>
    }
  </div>
</nav>
  • Zeile 12: der angemeldete Benutzer, wie von der Klasse [ViewUser] in [Web/ViewPage.cs] beschrieben (Login, Name, Rolle, [IsAdmin], [IsPatient]), abgeleitet aus dem JWT-Token. Auf öffentlichen Seiten (Anmeldung, Kontoerstellung) ist er auf [null] gesetzt;
  • Zeilen 17–31: Die Menüs hängen von der Rolle ab: „Mein Bereich“ für einen Patienten, „Ärzte“ und „Patienten“ für ADMIN. Dies dient nur dem Komfort: Die Sicherheit gewährleisten die Attribute [[Authorize(Roles = ...)]] der Controller (ein Patient, der manuell [/doctors] eingibt, erhält eine Seite 403). [Active("/doctors")] liefert [active] , wenn der angeforderte Pfad mit [/doctors] beginnt: [Bootstrap] hebt dieses Menü dann hervor. Das Präfix [/my-] deckt beide Patientenseiten ab, [/my-area] und [/my-account];
  • Zeile 34: Ohne Menüs tritt ein leerer Block an ihre Stelle ([me-auto]: automatischer rechter Rand), damit der übrige Inhalt rechts in der Leiste bleibt;
  • Zeilen 40–41: die Links FR / EN aus Beispiel 22. Der Ausdruck [@( ... )] steht in Klammern, weil er Leerzeichen enthält (siehe Beispiel 14);
  • Zeilen 44–52: die Rolle, der Name und die Abmeldeschaltfläche in einem POST-Formular (siehe Beispiel 21).

11.17.1.5. Views/Shared/_Flash.cshtml

@* =========================================================================
   Views/Shared/_Flash.cshtml - die ERFOLGSMELDUNG, die die vorherige
   Action gesetzt hat (Termin gespeichert, Arzt hinzugefügt ...) und die nur
   einmal oben auf der Seite angezeigt wird (siehe Web/Flash.cs).
   Eine FEHLER-Flash-Meldung wird dagegen unten auf der Seite von
   _Errors.cshtml angezeigt.
   ========================================================================= *@
@{
    var flash = FlashMessage;
}
@if (flash is { Type: FlashType.Success })
{
  <div class="alert alert-success" role="status">
    @T(flash.Key, flash.Params)
  </div>
}
  • Zeile 9: die von der vorherigen Aktion gesendete Flash-Meldung (siehe Beispiel 20 und [Web/Flash.cs]). Das Lesen einer Flash-Meldung löscht sie; da die Seite sie zweimal liest (hier und in [_Errors.cshtml]), speichert die Klasse [Flash] sie nach dem Lesen in [HttpContext.Items] (siehe Kapitel 6);
  • Zeile 11: [flash is { Type: FlashType.Success }] ist ein Eigenschaftsmuster: Die Bedingung ist wahr, wenn [flash] nicht [null] ist und wenn seine Eigenschaft [Type] gleich [FlashType.Success] ist. Hier wird nur eine Erfolgsmeldung angezeigt;
  • Zeile 14: Die Meldung ist ein Schlüssel; ihre möglichen Parameter ([name], [login], [minutes]) sind ein Wörterbuch, das an die zweite Form der Methode [T] übergeben wird. [role="status"]: Ein Screenreader kündigt die Meldung an, ohne den Benutzer zu unterbrechen.

11.17.1.6. Views/Shared/_Errors.cshtml

@* =========================================================================
   Views/Shared/_Errors.cshtml - der Fehlerbereich am ENDE jeder Seite,
   auf hellrosa Hintergrund (Klasse .error-zone, siehe wwwroot/css/styles.css).

   Er fasst die beiden möglichen Fehlerquellen zusammen:
     - Error: der Fehler der angezeigten Seite (abgelehntes Formular, Login oder
       Vor- und Nachname bereits vergeben, ungültiges Datum, falsches Passwort ...);
     - eine Fehler-Flash-Meldung, die die vorherige Action vor einer
       Weiterleitung gesetzt hat (Slot bereits gebucht, Löschen abgelehnt ...).

   role="alert": Ein Screenreader liest die Meldung vor, sobald die
   Seite angezeigt wird, auch wenn sie am Ende steht.
   ========================================================================= *@
@{
    var page = ViewData.Model as ViewModel;
    var error = page?.Error;
    var flash = FlashMessage;
    var flashError = flash is { Type: FlashType.Danger } ? flash : null;
}
@if (error is not null || flashError is not null)
{
  <div class="error-zone" role="alert">
    @if (error is not null)
    {
      <div>@T(error, page!.ErrorParams)</div>
    }
    @if (flashError is not null)
    {
      <div>@T(flashError.Key, flashError.Params)</div>
    }
  </div>
}
  • Zeilen 15–18: die beiden Fehlerquellen: der Fehler der angezeigten Seite (Eigenschaft [Error] des Templates: Formular abgelehnt, falsches Passwort usw.) und eine Flash-Fehlermeldung, die vor einer Umleitung angezeigt wird (Zeitfenster bereits reserviert, Löschen abgelehnt usw.);
  • Zeilen 20–22: Der Bereich wird angezeigt, wenn eine der beiden vorhanden ist. [role="alert"]: Ein Screenreader kündigt die Meldung an, sobald die Seite angezeigt wird, obwohl sie sich am Seitenende befindet. Die Klasse [error-zone] ist in [wwwroot/css/styles.css] definiert;
  • Zeile 25: Der Operator [!] teilt dem Compiler mit, dass [page] nicht [null] ist: Er kann dies nicht selbst ableiten, obwohl es sicher ist, da [error], aus [page] gelesen, es auch nicht ist.

11.17.1.7. Views/Shared/_Confirmation.cshtml

@* =========================================================================
   Views/Shared/_Confirmation.cshtml - der modale Dialog "Are you sure?".

   Er ersetzt das Feld window.confirm() des Browsers, das sich weder
   gestalten noch übersetzen lässt (seine Buttons bleiben in der Sprache des
   Browsers, nicht in der der Seite).

   Ein EINZIGER Dialog für die ganze Seite, anfangs ausgeblendet (d-none). Seine
   Beschriftungen werden hier vom Server übersetzt, wie der Rest der Seite;
   das kleine Skript wwwroot/js/app.js zeigt ihn lediglich an, setzt die
   formularspezifische Nachricht ein (Attribut data-confirmation) und sendet
   das Formular ab, wenn der Benutzer bestätigt.

   Dieselben Bootstrap-Klassen wie der Buchungsdialog (Schedule/_Booking.cshtml).
   ========================================================================= *@
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">@T("CONFIRMATION.TITLE")</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="@T("BOOKING_DIALOG.CLOSE_ARIA")"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          @* "No, go back" statt "Cancel": Die Frage lautet manchmal
             "Cancel this appointment?", und ein Button "Cancel" wäre dort mehrdeutig *@
          <button type="button" class="btn btn-secondary" data-action="no">@T("CONFIRMATION.NO")</button>
          <button type="button" class="btn btn-danger" data-action="yes">@T("CONFIRMATION.YES")</button>
        </div>
      </div>
    </div>
  </div>
</div>

Das Fenster aus Beispiel 21, mit vom Server übersetzten Beschriftungen – wie der Rest der Seite – und Barrierefreiheitsattributen:

  • Zeile 16: ein einziges Fenster für die gesamte Seite, anfangs versteckt ([d-none]);
  • Zeilen 18–19: [role="alertdialog"] kennzeichnet ein Fenster, das auf eine Antwort wartet; [aria-modal="true"] gibt an, dass der Rest der Seite inaktiv ist; [aria-labelledby] und [aria-describedby] bezeichnen den Titel und die Meldung, die ein Screenreader vorliest;
  • Zeile 24: die Schließen-Schaltfläche, die „Nein“ bedeutet ([data-action="no"]). Sie hat keinen Text: [aria-label] liefert einen Namen für Screenreader;
  • Zeilen 32–33: „Nein, zurück“ statt „Abbrechen“: Die Frage lautet manchmal „Diesen Termin stornieren?“, und eine Schaltfläche „Abbrechen“ wäre in diesem Kontext mehrdeutig.

11.17.1.8. Views/Auth/_Captcha.cshtml

@* =========================================================================
   Views/Auth/_Captcha.cshtml - das Captcha der Authentifizierungsseite
   (siehe Auth/CaptchaService.cs). Es schützt sowohl den Login als auch
   den Zugang zur Kontoerstellung (Button "Create a patient account").

   @Html.Raw(...): das SVG-Bild wird UNVERÄNDERT in die Seite eingefügt, ohne
   Maskierung. Das ist hier unbedenklich, weil dieses SVG vom Server selbst erzeugt wird
   und nichts enthält, was vom Benutzer stammt - bei Benutzereingaben würden wir das
   NIEMALS tun.

   Das versteckte Feld captchaId sagt dem Server, WELCHES Captcha zu prüfen ist; die
   richtige Antwort wird dagegen nie an den Browser gesendet.
   "Another image" lädt einfach die Seite neu (path = die aktuelle URL).
   ========================================================================= *@
@model RdvMedecins.Auth.Captcha
<div class="mb-3">
  <label class="form-label" for="captcha">@T("CAPTCHA.LABEL")</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="@T("CAPTCHA.IMAGE_ALT")">@Html.Raw(Model.Svg)</div>
    <a class="small" href="@CurrentPath">@T("CAPTCHA.NEW_IMAGE")</a>
  </div>
  <input type="hidden" name="captchaId" value="@Model.Id">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false" required
         class="form-control">
  <div class="form-text">@T("CAPTCHA.HELP")</div>
</div>
  • Zeile 15: Die partielle View hat ihr eigenes Template, das von [Auth/CaptchaService.cs] erzeugte CAPTCHA (siehe Beispiel 27): seine ID und sein Bild;
  • Zeile 19: Das SVG-Bild wird unverändert eingefügt (siehe Beispiel 14): Es wird vom Server erzeugt, ohne Eingabe des Benutzers. [role="img"] und [aria-label] machen es für Screenreader zu einem Bild;
  • Zeile 20: „Anderes Bild“ lädt einfach die aktuelle Seite neu: Ein neues CAPTCHA wird erzeugt;
  • Zeile 22: die CAPTCHA-ID in einem versteckten Feld: Sie teilt dem Server mit, welches CAPTCHA zu prüfen ist. Die richtige Antwort verlässt den Server jedoch nie;
  • Zeilen 23–24: die Eingabe. [autocomplete="off"], [autocapitalize="off"]und [spellcheck="false"] verhindern, dass der Browser die abgetippten Zeichen vorschlägt, großschreibt oder korrigiert.

11.17.1.9. Views/Shared/_PersonFields.cshtml

@* =========================================================================
   Views/Shared/_PersonFields.cshtml - die Identitätsfelder (Anrede, Vorname,
   Nachname), gemeinsam für drei Formulare: das Arzt-/Client-Formular des ADMIN,
   "Create a patient account" und "Manage my account".
   Das Partial erhält das Modell der Seite, die es einbindet (ein FormView):
   Werte, Meldung unter jedem Feld, rot umrandete Felder.

   selected="@selected": ein boolesches Attribut. Razor schreibt selected="selected",
   wenn der Wert true ist, und LÄSST das Attribut WEG, wenn er false ist.
   ========================================================================= *@
@model FormView
<div class="mb-3">
  <label class="form-label" for="title">@T("PERSONS.TITLE_LABEL")</label>
  <select id="title" name="title" class="form-select @Model.InvalidClass("title")">
    @foreach (var (value, selected) in Model.Titles)
    {
      <option value="@value" selected="@selected">@value</option>
    }
  </select>
  @if (Model.ErrorOf("title") is { } titleError)
  {
    <div class="invalid-feedback">@T(titleError)</div>
  }
</div>

<div class="row g-3 mb-3">
  <div class="col-sm-6">
    <label class="form-label" for="firstName">@T("PERSONS.FIRSTNAME_LABEL")</label>
    <input id="firstName" name="firstName" type="text" maxlength="20" required
           class="form-control @Model.InvalidClass("firstName")" value="@Model.Values.FirstName">
    @if (Model.ErrorOf("firstName") is { } firstNameError)
    {
      <div class="invalid-feedback">@T(firstNameError)</div>
    }
  </div>
  <div class="col-sm-6">
    <label class="form-label" for="lastName">@T("PERSONS.LASTNAME_LABEL")</label>
    <input id="lastName" name="lastName" type="text" maxlength="20" required
           class="form-control @Model.InvalidClass("lastName")" value="@Model.Values.LastName">
    @if (Model.ErrorOf("lastName") is { } lastNameError)
    {
      <div class="invalid-feedback">@T(lastNameError)</div>
    }
  </div>
</div>

Die Identitätsfelder (Anrede, Vorname, Nachname), die drei Formularen gemeinsam sind: Arzt oder Client von ADMIN, Kontoerstellung und Verwaltung des Patientenkontos.

  • Zeile 11: [FormView] ist die (abstrakte) Elternklasse der Templates dieser drei Formulare. Sie enthält die eingegebenen Werte ([Values]), die Fehlermeldung jedes abgelehnten Feldes ([Errors]) und die rot hervorzuhebenden Felder ([InvalidFields]). Die partielle View akzeptiert daher das Template jeder der drei Seiten;
  • Zeilen 14–19: die Liste der Anreden. [Model.Titles] liefert Tupel (Wert, ausgewählt?); [var (value, selected)] zerlegt jedes Tupel in zwei Variablen. [selected="@selected"] ist ein boolesches Attribut, das nur geschrieben wird, wenn der Wert wahr ist (siehe Beispiel 17). [InvalidClass("title")] liefert [is-invalid], wenn das Feld rot umrahmt werden soll (siehe Beispiel 19);
  • Zeilen 20–23: die Fehlermeldung des Feldes, falls vorhanden. [ErrorOf] liefert die Meldung oder [null]; die Bedingung [is { } titleError] ist wahr, wenn der Wert nicht [null] ist, und speichert ihn dann in der neuen Variablen [titleError];
  • Zeilen 26–45: Vor- und Nachname im selben Format, auf einem ausreichend breiten Bildschirm nebeneinander ([Bootstrap]-Raster: [col-sm-6]). Die Attribute [maxlength] und [required] dienen nur dem Komfort: Formulare, die diese partielle View einfügen, haben das Attribut [novalidate], und der Server übernimmt die Validierung.

11.17.1.10. Views/Schedule/_Booking.cshtml

@* =========================================================================
   Views/Schedule/_Booking.cshtml - der Buchungsdialog.

   Dieselbe Technik wie beim Angular-Client (booking-dialog): die ECHTEN Bootstrap-
   Klassen eines modalen Dialogs (.modal, .modal-backdrop ...), die
   "fest codiert" sichtbar gemacht werden (show d-block) statt durch das JavaScript
   von Bootstrap. Der Unterschied: Der SERVER entscheidet, ihn anzuzeigen
   (Parameter &book=... der URL), und das Schließen besteht darin, einem Link
   auf dieselbe Seite ohne diesen Parameter zu folgen.
   ========================================================================= *@
@model ScheduleModel
@{
    var booking = Model.Booking!;
}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="/schedule/book" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">@T("BOOKING_DIALOG.TITLE")</h5>
        <a class="btn-close" href="@Model.BackUrl" aria-label="@T("BOOKING_DIALOG.CLOSE_ARIA")"></a>
      </div>

      <div class="modal-body">
        <p>@T("BOOKING_DIALOG.SLOT", ("time", booking.Time))</p>

        @* was der Server zusätzlich zum gewählten Patienten wissen muss *@
        <input type="hidden" name="doctorId" value="@Model.DoctorId">
        <input type="hidden" name="day" value="@Model.Day">
        <input type="hidden" name="slotId" value="@booking.SlotId">

        @if (booking.Patient is not null)
        {
          @* Ein Patient bucht für sich selbst: keine Auswahlliste
             (und der Server ignoriert ohnehin jede clientId) *@
          <p class="mb-0">@T("BOOKING_DIALOG.PATIENT_LABEL"): <strong>@booking.Patient</strong></p>
        }
        else
        {
          <label class="form-label" for="clientId">@T("BOOKING_DIALOG.PATIENT_LABEL")</label>
          <select id="clientId" name="clientId" class="form-select" required autofocus>
            <option value="">@T("BOOKING_DIALOG.CHOOSE_PATIENT")</option>
            @foreach (var client in booking.Clients)
            {
              <option value="@client.Id">@client.Label</option>
            }
          </select>
        }
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="@Model.BackUrl">@T("BOOKING_DIALOG.CANCEL")</a>
        <button type="submit" class="btn btn-primary">@T("BOOKING_DIALOG.CONFIRM")</button>
      </div>
    </form>
  </div>
</div>
  • Zeile 11: Die partielle View erhält das Template der Terminkalenderseite. [Model.Booking!]: Die Seite fügt sie nur ein, wenn [Booking] nicht [null] ist, was der Operator [!] dem Compiler zusichert;
  • Zeilen 15–16: die [Bootstrap]-Klassen für ein modales Fenster und seinen grauen Hintergrund, fest codiert sichtbar gemacht ([show d-block]): Der Server entscheidet, das Fenster anzuzeigen, wenn die URL den Parameter [book] enthält. Das [JavaScript] von [Bootstrap] wird nicht verwendet (es wird nicht einmal geladen);
  • Zeile 18: Der Inhalt des Fensters ist das Reservierungsformular selbst;
  • Zeile 21: Das Schließen des Fensters folgt einem Link zum selben Terminkalender, ohne den Parameter [book] ([BackUrl], vom Controller vorbereitet);
  • Zeile 25: „Zeitfenster 8:00 - 8:20“: ein Übersetzungsparameter;
  • Zeilen 28–30: versteckte Felder: zusätzliche Informationen, die der Server neben dem ausgewählten Patienten benötigt;
  • Zeilen 32–48: Ein Patient sieht seinen Namen; ein Administrator (ADMIN, DOCTOR) wählt den Patienten aus einer Liste aus. Die erste Option hat einen leeren Wert: Mit [required] verlangt der Browser, dass ein echter Patient ausgewählt wird. [autofocus] setzt den Cursor in die Liste;
  • Zeilen 52–53: „Abbrechen“ ist ein Link, ebenso das X; „Bestätigen“ sendet das Formular ab.

11.17.2. Die Seiten

11.17.2.1. Views/Auth/Login.cshtml

@* =========================================================================
   Views/Auth/Login.cshtml - das Login-Formular.
   Ein gewöhnliches HTML-<form>: der Browser selbst sendet Login,
   Passwort und Captcha-Antwort mit POST /login, ohne JavaScript. Bei
   einem Fehlversuch sendet der Server DIESE Seite zurück, mit dem bereits eingegebenen Login, einem
   NEUEN Captcha und dem Fehler, der vom Layout am Seitenende angezeigt wird.

   @model: der Typ des View-Modells. Der Compiler prüft jedes
   @Model.Xxx (ein Tippfehler ist ein Kompilierfehler).
   ========================================================================= *@
@model LoginModel
@{
    var loginTyped = Model.Login != "";
}
<div class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">@T("LOGIN.TITLE")</h5>

      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login">@T("LOGIN.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="@Model.Login" required autofocus="@(!loginTyped)">
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">@T("LOGIN.PASSWORD_LABEL")</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required autofocus="@loginTyped">
        </div>

        @await Html.PartialAsync("_Captcha", Model.Captcha)

        <button type="submit" class="btn btn-primary w-100">@T("LOGIN.SUBMIT")</button>

        @* noch kein Konto: Ein Patient kann selbst eines anlegen.
           Es ist KEIN einfacher Link: Es ist ein zweiter Submit-Button
           DIESES Formulars, der an eine andere Adresse sendet (formaction). Der
           Server prüft dort das obige CAPTCHA, bevor er die Seite zur Kontoerstellung öffnet
           (siehe RegistrationController).
           formnovalidate: Der Browser verlangt weder Login noch Passwort
           (für die Kontoerstellung unnötig); das CAPTCHA wird vom Server
           geprüft. Enter in einem Feld löst immer den ERSTEN
           Button des Formulars aus, "Log in". *@
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="/register/access" formnovalidate>@T("LOGIN.CREATE_ACCOUNT")</button>
        <div class="form-text text-center">@T("LOGIN.CREATE_ACCOUNT_HELP")</div>
      </form>

      <div class="text-muted small mt-3">
        @T("LOGIN.DEMO_ACCOUNTS")
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - @T("LOGIN.DEMO_ADMIN")</li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - @T("LOGIN.DEMO_DOCTOR")</li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - @T("LOGIN.DEMO_USER")</li>
        </ul>
      </div>
    </div>
  </div>
</div>
  • Zeile 13: Nach einem Fehlschlag gibt der Controller diese Seite mit dem bereits eingegebenen Benutzernamen zurück;
  • Zeile 20: ein Standard-HTML-Formular: Der Browser sendet Benutzername, Passwort und CAPTCHA-Antwort selbstständig ab;
  • Zeilen 23–29: [autofocus] ist ein boolesches Attribut: Nur eines der beiden Felder erhält es. Der Cursor wird in das Feld für den Benutzernamen gesetzt oder, falls der Benutzername bereits bekannt ist, in das Passwortfeld. Die Werte von [autocomplete] ([username], [current-password]) unterstützen die Passwortmanager der Browser;
  • Zeile 32: das CAPTCHA; das zweite Argument liefert das Template der partiellen View;
  • Zeilen 45–46: Die zweite Schaltfläche sendet dasselbe Formular an [/register/access] (Attribut [formaction], siehe Beispiel 20): Dort prüft der Server das CAPTCHA, bevor er die Seite zur Kontoerstellung öffnet. [formnovalidate]: Der Browser verlangt keinen Benutzernamen und kein Passwort, da sie zum Erstellen eines Kontos nicht benötigt werden. Das Drücken der Eingabetaste in einem Feld löst immer die erste Schaltfläche des Formulars aus: „Anmelden“;
  • Zeilen 51–56: Demokonten (Passwort = Benutzername).

11.17.2.2. Views/Schedule/Schedule.cshtml

@* =========================================================================
   Views/Schedule/Schedule.cshtml - die Hauptseite (siehe ScheduleController).
   Drei Blöcke, wie die drei Komponenten des Angular-Clients:
     1. die Auswahl von Arzt und Tag  (<app-doctor-day-picker>)
     2. der Terminkalender            (<app-agenda>)
     3. der Buchungsdialog            (<app-booking-dialog>)
   Ein möglicher Fehler (ungültiges Datum, unbekannter Arzt) wird unten auf der
   Seite vom Layout angezeigt (siehe Views/Shared/_Errors.cshtml).
   ========================================================================= *@
@model ScheduleModel

@* 1. Auswahl von Arzt und Tag: ein GET-Formular, das diese Seite einfach
   mit ?doctorId=...&day=... in der URL neu lädt *@
<form method="get" action="/schedule" class="card p-3 mb-3">
  <div class="row g-2 align-items-end">
    <div class="col-sm-5">
      <label class="form-label" for="doctorId">@T("DOCTOR_DAY_PICKER.DOCTOR_LABEL")</label>
      <select id="doctorId" name="doctorId" class="form-select" required>
        <option value="">@T("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR")</option>
        @foreach (var doctor in Model.Doctors)
        {
          <option value="@doctor.Id" selected="@doctor.Selected">@doctor.Label</option>
        }
      </select>
    </div>
    <div class="col-sm-4">
      <label class="form-label" for="day">@T("DOCTOR_DAY_PICKER.DAY_LABEL")</label>
      <input id="day" name="day" type="date" class="form-control" value="@Model.Day" required>
    </div>
    <div class="col-sm-3">
      <button type="submit" class="btn btn-primary w-100">@T("DOCTOR_DAY_PICKER.VIEW_SCHEDULE")</button>
    </div>
  </div>
</form>

@* Patient, der bereits einen bevorstehenden Termin hat: Deshalb gibt es keinen Button "Book" *@
@if (Model.Info is not null)
{
  <div class="alert alert-info">
    @T(Model.Info) <a href="/my-area" class="alert-link">@T("APP.MENU_MY_AREA")</a>
  </div>
}

@* 2. der Terminkalender *@
@if (Model.Schedule is { } schedule)
{
  <div class="card p-3">
    <h5>@T("SCHEDULE.TITLE_PREFIX") @schedule.Day - @schedule.Doctor</h5>

    @if (schedule.Rows.Count > 0)
    {
      <table class="table table-hover align-middle">
        <thead>
          <tr>
            <th>@T("SCHEDULE.COLUMN_SLOT")</th>
            <th>@T("SCHEDULE.COLUMN_STATUS")</th>
            <th></th>
          </tr>
        </thead>
        <tbody>
          @foreach (var row in schedule.Rows)
          {
            <tr class="@(row.Bookable ? "free-slot" : null)">
              <td>@row.Time</td>
              <td>
                @* [Patient] wird nur gefüllt, wenn der Benutzer diesen Namen
                   sehen darf (ADMIN, DOCTOR oder der Patient für SEINEN
                   Termin) - andernfalls einfach "Booked" *@
                @if (row.Free)
                {
                  <span class="badge text-bg-success">@T("SCHEDULE.FREE")</span>
                }
                else if (row.Patient is not null)
                {
                  <span class="badge @(row.Mine ? "text-bg-primary" : "text-bg-secondary")">@row.Patient</span>
                }
                else
                {
                  <span class="badge text-bg-secondary">@T("SCHEDULE.BOOKED_BY_OTHER")</span>
                }
              </td>
              <td>
                @* die angezeigten Buttons hat der Controller festgelegt
                   (Bookable, AppointmentId), abhängig von der Rolle des Benutzers *@
                @if (row.Bookable)
                {
                  @* "Book" ist ein einfacher Link: Er öffnet diese Seite erneut
                     mit dem Buchungsdialog dieses Slots *@
                  <a class="btn btn-sm btn-outline-success" href="@row.BookUrl">@T("SCHEDULE.BOOK")</a>
                }
                @if (row.AppointmentId is not null)
                {
                  @* "Cancel" ÄNDERT Daten: Es ist daher ein POST *@
                  <form method="post" action="/schedule/cancel" class="m-0"
                        data-confirmation="@T("SCHEDULE.CANCEL_CONFIRM")">
                    <input type="hidden" name="appointmentId" value="@row.AppointmentId">
                    <input type="hidden" name="doctorId" value="@Model.DoctorId">
                    <input type="hidden" name="day" value="@Model.Day">
                    <button type="submit" class="btn btn-sm btn-outline-danger">@T("SCHEDULE.CANCEL_APPOINTMENT")</button>
                  </form>
                }
              </td>
            </tr>
          }
        </tbody>
      </table>
    }
    else
    {
      <p class="text-muted mb-0">@T("SCHEDULE.NO_SLOTS")</p>
    }
  </div>
}
else
{
  <p class="text-muted">@T("SCHEDULE.EMPTY_STATE")</p>
}

@* 3. der Buchungsdialog, nur wenn die URL &book=... enthält *@
@if (Model.Booking is not null)
{
  @await Html.PartialAsync("_Booking", Model)
}

Kommentieren wir diesen Code:

  • Zeilen 14–34: Auswahl des Arztes und des Tages: ein GET-Formular (siehe Beispiel 17), das die Seite mit [?doctorId=...&day=...] in der URL neu lädt. Jeder Arzt ist eine [OptionView], die angibt, ob er ausgewählt ist. Ein Feld [type="date"] sendet das Datum im Format [yyyy-mm-dd] (siehe Beispiel 18);
  • Zeilen 37–42: eine Meldung für einen Patienten, der bereits einen bevorstehenden Termin hat: Sie erklärt, warum die Schaltflächen „Buchen“ fehlen;
  • Zeile 45: der Terminkalender, falls angefordert. Die Bedingung [is { } schedule] prüft, dass die Eigenschaft nicht [null] ist, und speichert ihren Wert in der Variablen [schedule];
  • Zeile 48: der Titel: „Terminkalender für 2026-09-25 – Mme Marie PELISSIER“;
  • Zeile 63: Ein buchbares Zeitfenster ändert beim Überfahren mit der Maus die Farbe (Klasse [free-slot], siehe [styles.css]). Ist der Wert eines Attributs [null], schreibt [Razor] das Attribut überhaupt nicht: Die anderen Zeilen haben das Attribut [class] nicht;
  • Zeilen 69–80: drei Fälle: frei; gebucht, mit dem Namen des Patienten (blau, wenn es der Termin des angemeldeten Patienten ist, [Mine]); gebucht ohne sichtbaren Namen, „Gebucht“. Der Controller befüllt [Patient] nur, wenn der Benutzer berechtigt ist, diesen Namen zu sehen;
  • Zeilen 85–90: „Buchen“ ist ein Link: Er öffnet diese Seite erneut und zeigt das Reservierungsfenster für dieses Zeitfenster an ([BookUrl], vom Controller vorbereitet);
  • Zeilen 91–101: „Stornieren“ ändert Daten: Es ist ein POST-Formular mit Bestätigung ([data-confirmation], siehe Beispiel 21). Die versteckten Felder [doctorId] und [day] ermöglichen es dem Controller, zum selben Terminkalender umzuleiten. In der Schleife verweist [Model] immer auf das Template der Seite: Das Äquivalent von [@root] oder [Handlebars] ist nicht nötig;
  • Zeilen 110 und 116: ein Arzt ohne freie Zeitfenster oder noch kein angeforderter Terminkalender;
  • Zeilen 120–123: das Buchungsfenster, falls der Controller es vorbereitet hat.

11.17.2.3. Views/Persons/List.cshtml

@* =========================================================================
   Views/Persons/List.cshtml - die Liste der Ärzte ODER der Clients (ADMIN).
   Eine einzige View für beide: Die jeweils spezifischen Beschriftungen kommen in
   Model.Keys an (siehe DoctorsController / ClientsController).
   ========================================================================= *@
@model PersonListModel
<div class="d-flex justify-content-between align-items-center mb-3">
  <h4 class="mb-0">@T(Model.Keys.Title)</h4>
  <a class="btn btn-primary" href="@Model.AddUrl">@T(Model.Keys.Add)</a>
</div>

<div class="card p-3">
  @if (Model.Persons.Count > 0)
  {
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>@T("PERSONS.COLUMN_TITLE")</th>
          <th>@T("PERSONS.COLUMN_FIRSTNAME")</th>
          <th>@T("PERSONS.COLUMN_LASTNAME")</th>
          <th>@T("PERSONS.COLUMN_LOGIN")</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        @foreach (var person in Model.Persons)
        {
          <tr>
            <td>@person.Title</td>
            <td>@person.FirstName</td>
            <td>@person.LastName</td>
            <td><code>@person.Login</code></td>
            <td class="text-end">
              <div class="d-inline-flex gap-2">
                <a class="btn btn-sm btn-outline-primary" href="@person.EditUrl">@T("PERSONS.EDIT")</a>
                @* data-confirmation: Ein Bestätigungsdialog öffnet sich,
                   bevor das Formular gesendet wird (siehe wwwroot/js/app.js) *@
                <form method="post" action="@person.DeleteUrl" class="m-0"
                      data-confirmation="@T(Model.Keys.ConfirmDelete)">
                  <button type="submit" class="btn btn-sm btn-outline-danger">@T("PERSONS.DELETE")</button>
                </form>
              </div>
            </td>
          </tr>
        }
      </tbody>
    </table>
  }
  else
  {
    <p class="text-muted mb-0">@T(Model.Keys.Empty)</p>
  }
</div>

Eine einzige View für Ärzte und Clients:

  • Zeilen 8–9: Die für jeden Benutzer spezifischen Texte erscheinen als Schlüssel ([Model.Keys], vom Typ [PersonKeys]), bereitgestellt von [DoctorsController] oder [ClientsController]: [DOCTORS.TITLE] oder [CLIENTS.TITLE] usw.;
  • Zeilen 26–45: eine Zeile pro Person, mit zwei Schaltflächen;
  • Zeile 35: „Bearbeiten“ ist ein Link zum Formular;
  • Zeilen 38–41: „Löschen“ ist ein POST-Formular, mit Bestätigung;
  • Zeile 51: „Keine Ärzte.“ oder „Keine Patienten.“

11.17.2.4. Views/Persons/Form.cshtml

@* =========================================================================
   Views/Persons/Form.cshtml - Anlegen ODER Aktualisieren eines Arztes
   oder eines Clients (ADMIN). Model.Creating unterscheidet die beiden Fälle.

   Wird die Eingabe abgelehnt (leeres Feld, Login bereits vergeben ...), sendet
   der Controller DIESE View zurück mit:
     - den bereits eingegebenen Werten (Model.Values);
     - den fehlerhaften Feldern, rot umrandet (Bootstrap-Klasse "is-invalid");
     - unter einem von der Validierung abgelehnten Feld seiner Meldung;
     - der Fehlermeldung der Seite, die vom Layout UNTEN auf der Seite angezeigt wird
       (siehe Views/Shared/_Errors.cshtml).
   ========================================================================= *@
@model PersonFormModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3">@T(Model.PageTitle)</h5>

      @* novalidate: Wir überlassen die Validierung dem SERVER (er hat die Autorität);
         die Prüfungen des Browsers (required ...) sind nur eine Erleichterung,
         die ein Benutzer immer umgehen kann *@
      <form method="post" action="@Model.Action" novalidate>
        @if (!Model.Creating)
        {
          <input type="hidden" name="version" value="@Model.Values.Version">
        }

        @* Anrede, Vorname, Nachname: für drei Formulare gemeinsames Partial *@
        @await Html.PartialAsync("_PersonFields", Model)

        <h6 class="mt-4 text-muted">@T("PERSONS.ACCOUNT_SECTION")</h6>

        <div class="mb-3">
          <label class="form-label" for="login">@T("PERSONS.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="off"
                 class="form-control @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
          else
          {
            <div class="form-text">@T(Model.Creating ? "PERSONS.LOGIN_HELP_CREATE" : "PERSONS.LOGIN_HELP_EDIT")</div>
          }
        </div>

        <div class="mb-4">
          <label class="form-label" for="password">@T("PERSONS.PASSWORD_LABEL")</label>
          @* nie vorbelegt: Das Passwort geht nie zurück an den Browser *@
          <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                 class="form-control @Model.InvalidClass("password")">
          @if (Model.ErrorOf("password") is { } passwordError)
          {
            <div class="invalid-feedback">@T(passwordError)</div>
          }
          else
          {
            <div class="form-text">@T(Model.Creating ? "PERSONS.PASSWORD_HELP_CREATE" : "PERSONS.PASSWORD_HELP_EDIT")</div>
          }
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("PERSONS.SAVE")</button>
          <a class="btn btn-secondary" href="@Model.ListUrl">@T("PERSONS.BACK")</a>
        </div>
      </form>
    </div>
  </div>
</div>

Kommentieren wir diesen Code:

  • Zeile 17: Der Titel („Arzt hinzufügen“, „Patient bearbeiten“ usw.) ist der Schlüssel des Seitentitels, bereitgestellt vom Controller;
  • Zeile 22: Die URL wird vom Controller bereitgestellt: Dieselbe View dient sowohl zum Hinzufügen als auch zum Bearbeiten von Ärzten und Clients. [novalidate]: Der Server übernimmt die Validierung (siehe Beispiel 19);
  • Zeilen 23–25: bei einer Bearbeitung die Version des Datensatzes in einem versteckten Feld: Dies ist die optimistische Sperre aus Beispiel 28;
  • Zeile 29: die Identitätsfelder;
  • Zeilen 34–44: der Login, mit einer Fehlermeldung oder, falls keine vorhanden ist, einem Hilfetext. Der Hilfetext unterscheidet sich danach, ob es sich um ein Hinzufügen („Optional: standardmäßig der Nachname in Kleinbuchstaben.“) oder um ein Bearbeiten handelt;
  • Zeilen 48–59: das Passwort, das nie vorausgefüllt wird; es wird nie an den Browser zurückgesendet. [autocomplete="new-password"]: Der Browser schlägt nicht das gespeicherte Passwort des Administrators vor. Die Länge ist auf 72 Zeichen begrenzt, weil der Algorithmus [bcrypt] die folgenden Zeichen ignoriert;
  • Zeile 64: Der Link zurück zur Liste ist ein Hyperlink.

11.17.2.5. Views/Registration/Registration.cshtml

@* =========================================================================
   Views/Registration/Registration.cshtml - "Create a patient account" (öffentliche
   Seite, siehe RegistrationController). Dieselben Identitätsfelder wie im
   Formular des ADMIN (Partial _PersonFields), aber Login und
   Passwort sind erforderlich, mit Bestätigung.
   Hier KEIN CAPTCHA: Diese Seite wird erst erreicht, nachdem das
   CAPTCHA der Authentifizierungsseite eingegeben wurde (Button "Create a patient account").
   ========================================================================= *@
@model RegistrationModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1">@T("REGISTRATION.TITLE")</h5>
      <p class="text-muted small mb-3">@T("REGISTRATION.INTRO")</p>

      <form method="post" action="/register" novalidate>
        @await Html.PartialAsync("_PersonFields", Model)

        <h6 class="mt-4 text-muted">@T("PERSONS.ACCOUNT_SECTION")</h6>

        <div class="mb-3">
          <label class="form-label" for="login">@T("PERSONS.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
          else
          {
            <div class="form-text">@T("REGISTRATION.LOGIN_HELP")</div>
          }
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password">@T("PERSONS.PASSWORD_LABEL")</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control @Model.InvalidClass("password")">
            @if (Model.ErrorOf("password") is { } passwordError)
            {
              <div class="invalid-feedback">@T(passwordError, ("min", Model.PasswordMin))</div>
            }
            else
            {
              <div class="form-text">@T("REGISTRATION.PASSWORD_HELP", ("min", Model.PasswordMin))</div>
            }
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation">@T("ACCOUNT.CONFIRMATION_LABEL")</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control @Model.InvalidClass("confirmation")">
            @if (Model.ErrorOf("confirmation") is { } confirmationError)
            {
              <div class="invalid-feedback">@T(confirmationError)</div>
            }
          </div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("REGISTRATION.SUBMIT")</button>
          <a class="btn btn-secondary" href="/login">@T("REGISTRATION.BACK_TO_LOGIN")</a>
        </div>
      </form>
    </div>
  </div>
</div>

Erstellung eines Clientkontos, öffentliche Seite. Hier gibt es kein CAPTCHA: Diese Seite erreichen Sie nur nach Eingabe des CAPTCHA auf der Anmeldeseite.

  • Zeile 17: dieselben Identitätsfelder wie im Formular von ADMIN;
  • Zeilen 22–32: der Benutzername, der diesmal erforderlich ist;
  • Zeilen 37–47: Der Hilfetext und die Meldung „zu kurz“ haben einen Parameter, [{min}], nämlich die vom Template bereitgestellte Mindestlänge des Passworts ([PasswordMin]). Eine Meldung ohne den Parameter [{min}] ignoriert den übergebenen Wert einfach;
  • Zeilen 50–56: Passwortbestätigung;
  • Zeile 62: Rückkehr zur Anmeldeseite.

11.17.2.6. Views/PatientArea/Area.cshtml

@* =========================================================================
   Views/PatientArea/Area.cshtml - "My area": die Startseite des
   Patienten (Rolle USER), die direkt nach dem Login angezeigt wird.
     - zwei Optionen: [Manage my account] und [View a schedule];
     - sein bevorstehender Termin, falls er einen hat, mit der Möglichkeit zur Stornierung.
   ========================================================================= *@
@model AreaModel
<h4 class="mb-3">@T("AREA.HELLO", ("name", Model.Patient))</h4>

<div class="row g-3 mb-4">
  <div class="col-sm-6">
    <a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
      <h5 class="mb-1">@T("AREA.MANAGE_ACCOUNT")</h5>
      <span class="text-muted">@T("AREA.MANAGE_ACCOUNT_HELP")</span>
    </a>
  </div>
  <div class="col-sm-6">
    <a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
      <h5 class="mb-1">@T("AREA.VIEW_SCHEDULE")</h5>
      <span class="text-muted">@T("AREA.VIEW_SCHEDULE_HELP")</span>
    </a>
  </div>
</div>

<div class="card p-3">
  <h5>@T("AREA.MY_APPOINTMENT")</h5>
  @if (Model.Appointments.Count > 0)
  {
    @* normalerweise nur einer (Regel "ein bevorstehender Termin zur Zeit"),
       die Seite kann aber mehrere anzeigen *@
    for (var i = 0; i < Model.Appointments.Count; i++)
    {
      var appointment = Model.Appointments[i];
      var last = i == Model.Appointments.Count - 1;
      <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 @(last ? "" : "border-bottom")">
        <div>
          <div class="fw-semibold">@appointment.Day, @appointment.Time</div>
          <div class="text-muted">@appointment.Doctor - <a href="@appointment.ScheduleUrl">@T("AREA.SEE_IN_SCHEDULE")</a></div>
        </div>
        <form method="post" action="/my-area/cancel" class="m-0"
              data-confirmation="@T("SCHEDULE.CANCEL_CONFIRM")">
          <input type="hidden" name="appointmentId" value="@appointment.Id">
          <button type="submit" class="btn btn-outline-danger">@T("AREA.CANCEL_APPOINTMENT")</button>
        </form>
      </div>
    }
  }
  else
  {
    <p class="text-muted mb-0">@T("AREA.NO_APPOINTMENT")</p>
  }
</div>
  • Zeile 8: „Guten Tag Mr Jean MARTIN“;
  • Zeilen 12–21: Beide Optionen sind Links, die als Karten dargestellt werden (Klasse [option-card], siehe [styles.css]);
  • Zeilen 31–46: bevorstehende Termine (meist nur einer). Innerhalb eines [@if]-Blocks ist das Format [C#]: Die [for]-Schleife wird ohne [@] geschrieben. Ein Rand ([border-bottom]) trennt die Termine, außer nach dem letzten;
  • Zeilen 40–44: die Stornierung, ein POST-Formular mit Bestätigung.

11.17.2.7. Views/PatientArea/Account.cshtml

@* =========================================================================
   Views/PatientArea/Account.cshtml - "Manage my account" (Rolle USER).
   Zwei voneinander unabhängige Formulare auf derselben Seite:
     1. die Aktualisierung (Identität, Login, optional neues Passwort);
     2. das Löschen des Kontos - das auch seine Termine storniert.
   Beide verlangen das AKTUELLE Passwort.
   ========================================================================= *@
@model MyAccountModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    @* 1. Aktualisierung *@
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">@T("MY_ACCOUNT.TITLE")</h5>

      <form method="post" action="/my-account" novalidate>
        <input type="hidden" name="version" value="@Model.Values.Version">

        @await Html.PartialAsync("_PersonFields", Model)

        <h6 class="mt-4 text-muted">@T("PERSONS.ACCOUNT_SECTION")</h6>

        <div class="mb-3">
          <label class="form-label" for="login">@T("PERSONS.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password">@T("MY_ACCOUNT.NEW_PASSWORD_LABEL")</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control @Model.InvalidClass("password")">
            @if (Model.ErrorOf("password") is { } passwordError)
            {
              <div class="invalid-feedback">@T(passwordError, ("min", Model.PasswordMin))</div>
            }
            else
            {
              <div class="form-text">@T("PERSONS.PASSWORD_HELP_EDIT")</div>
            }
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation">@T("ACCOUNT.CONFIRMATION_LABEL")</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control @Model.InvalidClass("confirmation")">
            @if (Model.ErrorOf("confirmation") is { } confirmationError)
            {
              <div class="invalid-feedback">@T(confirmationError)</div>
            }
          </div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="currentPassword">@T("MY_ACCOUNT.CURRENT_PASSWORD_LABEL")</label>
          <input id="currentPassword" name="currentPassword" type="password" maxlength="72" autocomplete="current-password" required
                 class="form-control @Model.InvalidClass("currentPassword")">
          @if (Model.ErrorOf("currentPassword") is { } currentError)
          {
            <div class="invalid-feedback">@T(currentError)</div>
          }
          else
          {
            <div class="form-text">@T("MY_ACCOUNT.CURRENT_PASSWORD_HELP")</div>
          }
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("PERSONS.SAVE")</button>
          <a class="btn btn-secondary" href="/my-area">@T("MY_ACCOUNT.BACK")</a>
        </div>
      </form>
    </div>

    @* 2. Löschen *@
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">@T("MY_ACCOUNT.DELETE_TITLE")</h5>
      <p class="text-muted small">@T("MY_ACCOUNT.DELETE_HELP")</p>
      <form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="@T("MY_ACCOUNT.DELETE_CONFIRM")">
        <div class="flex-grow-1">
          <label class="form-label" for="deletePassword">@T("MY_ACCOUNT.CURRENT_PASSWORD_LABEL")</label>
          <input id="deletePassword" name="deletePassword" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">@T("MY_ACCOUNT.DELETE_SUBMIT")</button>
      </form>
    </div>

  </div>
</div>
  • Zeilen 16–76: Kontoänderung: Identität, Login, neues Passwort (optional) und seine Bestätigung;
  • Zeile 17: die Version des Client-Datensatzes (optimistische Sperre);
  • Zeilen 59–69: das aktuelle Passwort, das für jede Änderung erforderlich ist;
  • Zeilen 83–91: Löschen, mit Bestätigung. Zwei unabhängige Formulare auf derselben Seite: Jedes sendet nur seine eigenen Felder. Das Passwortfeld hat hier daher einen anderen Namen ([deletePassword]) und einen anderen Bezeichner. Dieses Formular hat nicht das Attribut [novalidate]: Der Browser verlangt das Passwort ([required]) schon vor dem Auslösen des Ereignisses [submit] – also bevor die Bestätigungsfrage gestellt wird.

11.17.2.8. Views/Shared/Error.cshtml

@* =========================================================================
   Views/Shared/Error.cshtml - die Fehlerseite (400, 403, 404, 500),
   erstellt vom ErrorController.
   ========================================================================= *@
@model ErrorModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger">@Model.Code</h1>
      <p class="lead">@T(Model.Message)</p>
      <div><a class="btn btn-primary" href="/">@T("ERROR_PAGE.BACK")</a></div>
    </div>
  </div>
</div>
  • Zeilen 9–10: Die vom [ErrorController] erzeugte Fehlerseite (400, 403, 404, 500): der HTTP-Code und die übersetzte Meldung. Da sie in [Views/Shared] liegt, wird sie unabhängig davon gefunden, welcher Controller sie anfordert.

11.18. Die Wörterbücher

Die Wörterbücher sind die aus der Version mit [NestJS], unverändert: Sie werden vom Service [Translator] gelesen (siehe Beispiel 22).

11.18.1. i18n/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {name} a été ajouté (login : {login}).",
    "UPDATED": "Le médecin {name} a été modifié.",
    "DELETED": "Le médecin {name} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {name} a été ajouté (login : {login}).",
    "UPDATED": "Le client {name} a été modifié.",
    "DELETED": "Le client {name} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {min} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {name}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
  • Die Abschnitte gruppieren die Texte nach Seite ([LOGIN], [SCHEDULE], [AREA]...) oder nach Thema ([ERRORS], [CONFIRMATION]). Einige Namen ([DOCTOR_DAY_PICKER], [BOOKING_DIALOG]) entsprechen Komponenten des Clients [Angular], dessen Wörterbücher von der Version mit [NestJS] übernommen wurden;
  • Zeile 80: ein Text mit zwei Parametern, [{name}] und [{login}], die bei der Übersetzung ersetzt werden;
  • Zeilen 98–136: Fehlermeldungen. Dies sind die Schlüssel, die von den [BusinessException]-Komponenten der Geschäftsschicht, den Validierungsattributen der Formulare ([ErrorMessage = "ERRORS.FIRSTNAME_REQUIRED"]), den Controllern und dem Exception-Filter verwendet werden. Drei davon haben einen Parameter: [{minutes}] und [{min}].

11.18.2. i18n/en.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {name} has been added (login: {login}).",
    "UPDATED": "Doctor {name} has been updated.",
    "DELETED": "Doctor {name} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {name} has been added (login: {login}).",
    "UPDATED": "Patient {name} has been updated.",
    "DELETED": "Patient {name} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {min} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {name}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

Das englische Wörterbuch hat genau dieselben Schlüssel.

11.19. Statische Dateien

Der Ordner [wwwroot] wird von [UseStaticFiles] ausgeliefert (siehe Beispiel 15). Der Ordner [wwwroot/lib/bootstrap] enthält [Bootstrap] (sein Stylesheet [css/bootstrap.min.css] und seine Lizenz), die nicht angezeigt werden.

11.19.1. wwwroot/css/styles.css

/* =========================================================================
   wwwroot/css/styles.css - einige Einstellungen zusätzlich zu Bootstrap
   (übernommen aus src/styles.css des Angular-Clients, über das NestJS-Projekt).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-zone: die Fehlermeldungen am Seitenende auf hellrosa Hintergrund
   (siehe Views/Shared/_Errors.cshtml).
   position: sticky + bottom: ist die Seite höher als das Fenster (ein
   Terminkalender mit 12 Zeitfenstern zum Beispiel), bleibt die Zone am unteren Rand des
   Fensters haften, statt unterhalb des sichtbaren Bereichs zu verschwinden - ohne je
   den Inhalt zu verdecken, wenn die Seite kurz ist.
   z-index: über dem grauen Hintergrund des Buchungsdialogs (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* hellrosa */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* die beiden großen Optionen der Seite "My area" des Patienten */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* das CAPTCHA-Bild (SVG von 150 x 50 Pixeln) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • Zeilen 10–12: Ein buchbares Zeitfenster ändert beim Überfahren mit der Maus die Farbe;
  • Zeilen 23–33: der Fehlerbereich auf hellrosa Hintergrund. [position: sticky] und [bottom: 1rem]: Ist die Seite höher als das Fenster, bleibt der Bereich am unteren Fensterrand, statt vom Bildschirm zu verschwinden; [z-index] legt ihn über den grauen Hintergrund des Buchungsfensters.
  • Zeilen 36–43: Die beiden Optionen „My area“ reagieren auf Mouseover;
  • Zeilen 46–50: der Rahmen für das CAPTCHA-Bild.

11.19.2. wwwroot/js/app.js

// =========================================================================
// wwwroot/js/app.js - das EINZIGE JavaScript der Anwendung.
// -------------------------------------------------------------------------
// Die ganze Anwendung funktioniert ohne JavaScript. Dieses Skript fügt eine
// Komfortfunktion hinzu: Bevor ein Formular gesendet wird, das das Attribut
// data-confirmation="..." trägt, fragt ein modaler Dialog "Are you sure?"
// (der Dialog selbst steht in der Seite: Views/Shared/_Confirmation.cshtml).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung gesendet - nichts geht kaputt (Prinzip "progressive enhancement").
//
// Warum nicht window.confirm()? Sein Fenster lässt sich nicht gestalten, und seine
// Schaltflächen bleiben in der Sprache des Browsers, nicht in der der Seite.
// =========================================================================

(() => {
  const modal = document.getElementById('confirmation-modal');
  if (!modal) {
    return;
  }
  const message = document.getElementById('confirmation-modal-message');
  const noButton = modal.querySelector('.modal-footer [data-action="no"]');

  let pendingForm = null; // das Formular, das bei Bestätigung durch den Benutzer gesendet wird
  let previousFocus = null; // das Element, dem beim Schließen der Fokus zurückgegeben wird

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (und nicht innerHTML): Die Nachricht wird als TEXT angezeigt,
    // nie als HTML interpretiert
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // der Fokus geht auf "No": Ein zerstreutes Drücken der Eingabetaste löscht nichts
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. wir fangen das Senden der zu bestätigenden Formulare ab
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. die Schaltflächen des Dialogs (Yes / No / Schließen-Kreuz)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() sendet das Formular, OHNE das Ereignis
      // 'submit' erneut auszulösen: keine neue Bestätigungsabfrage
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // Klick auf den grauen Hintergrund, außerhalb des Dialogs
    }
  });

  // 3. Tastatur: Escape schließt den Dialog; Tab bleibt INNERHALB des Dialogs
  //    (sonst ginge der Fokus auf die ausgegraute Seite dahinter)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

Das Skript für das Bestätigungsfenster aus Beispiel 21, erweitert um die Tastaturbehandlung. Es folgt demselben Prinzip der progressiven Erweiterung (Progressive Enhancement): Ohne [JavaScript] werden Formulare ohne Bestätigung abgeschickt, und die Anwendung funktioniert weiterhin.

  • Zeilen 16–19: Eine Seite ohne Bestätigungsfenster hat hier nichts zu tun;
  • Zeile 24: das Element, das vor dem Öffnen des Fensters den Tastatur-Fokus hatte (das Element, das die Tastatureingaben erhält): Beim Schließen des Fensters wird der Fokus dorthin zurückgegeben;
  • Zeilen 26–35: Der Fokus wird auf „No, go back“ gesetzt; ein versehentliches Drücken der Eingabetaste löscht nichts;
  • Zeilen 37–43: Das Fenster wird ausgeblendet, und der Fokus wird wiederhergestellt;
  • Zeilen 46–51: Wir fangen das Absenden von Formularen mit dem Attribut [data-confirmation] ab, wie in Beispiel 21;
  • Zeilen 54–67: „Yes“, „No“, die Schaltfläche zum Schließen und ein Klick außerhalb des Fensters. [closest('[data-action]')] findet das Element mit dem Attribut, auch wenn auf ein darin enthaltenes Element geklickt wurde. Der Operator [?.] liefert [undefined] zurück, anstatt zu scheitern, wenn kein Element gefunden wird;
  • Zeilen 71–86: Die Esc-Taste schließt das Fenster; die Tabulatortaste (und Umschalt+Tab) wechselt den Fokus zwischen den Schaltflächen im Fenster, anstatt ihn auf die abgedunkelte Seite dahinter wandern zu lassen.