Sport-Fest API Dokumentation

📊 Überblick

ChampionChecker ist eine digitale Lösung zur Organisation und Auswertung des jährlichen Sportfests der BBSOVG Magdeburg. Die bisherige papierbasierte Verwaltung wird durch eine moderne Webanwendung ersetzt, die eine effizientere Organisation, Echtzeit-Auswertung und bessere Zusammenarbeit zwischen Lehrkräften und Wettkampfleitern ermöglicht. Diese Dokumentation beschreibt die mit .NET 9 entwickelte Backend-API, die als zentrale Schnittstelle zur Speicherung, Verarbeitung und Bereitstellung von Sportfest-Daten dient.

---

🛠️ 1. Projektaufbau

Technologie-Stack

• Framework: .NET 9 mit C#
• Hosting: Azure
• Datenbank: Azure SQL mit Entity Framework Core

Anwendungskonfiguration

• In Program.cs werden alle wichtigen Anwendungskonfigurationen vorgenommen.
• ConnectionString:
  • Entwicklungsumgebung: Gespeichert in appsettings.json (nicht im Repository enthalten).
  • Produktionsumgebung: Wird von Azure bereitgestellt, um Anwendungsgeheimnisse zu schützen.

Dependency Injection (DI)

• In Program.cs werden alle Klassen und Repositories dem DI-Container hinzugefügt.
• Ermöglicht die flexible Nutzung von Abhängigkeiten wie DbContext oder Logger in verschiedenen Klassen.

Datenbankzugriff (Entity Framework Core)

• DbContext: ChampionCheckerDbContext repräsentiert die Datenbank.

• Identity-DbContext: ChampionCheckerIdentityDbContext verwaltet die Authentifizierung und Autorisierung.

• Model-Validierung: Die Validität der einzelnen Models wird durch das Setzen von Data-Annotation-Attributen definiert (z. B. [Required], [MinLength]). Vor der Ausführung der Controller-Endpunkte wird durch das [ValidateModelAttribute] das Model auf diese Kriterien geprüft.

• Beziehungen: Konfigurationen (1:1, 1:n, n:m) im Configuration-Ordner.

• Migrations:

  • Entity Framework Core ermöglicht es, Änderungen am Datenbankschema nachzuvollziehen und gezielt anzuwenden.
  • Eine Migration speichert Änderungen wie neue Tabellen, Spalten oder Beziehungen in einer Versionshistorie.
  • Die Up-Methode enthält neue Änderungen (z. B. Hinzufügen einer Spalte), während die Down-Methode den vorherigen Zustand wiederherstellen kann.
  • Durch dotnet ef migrations add <MigrationName> wird eine neue Migration erstellt, und mit dotnet ef database update wird sie in die Datenbank übertragen.
  • Dieses Konzept erlaubt eine kontrollierte Weiterentwicklung der Datenbankstruktur, ohne bestehende Daten zu verlieren.

• Visualisierung des Datenbankschemas (ChampionCheckerDbContext)

• Visualisierung des Schemas für Nutzer, Autorisierung und Authentifizierung (ChampionCheckerIdentityDbContext)

Repository-Muster

• Kapselt den Datenbankzugriff, um Trennung von Logik und Persistenz zu gewährleisten.
• Beispiel:

  var classes = _dbContext.Classes.ToList();

• SaveChanges() speichert Änderungen in der Datenbank.

Controller für Klassenverwaltung

• Endpunkte für Klassen:
  • Alle Klassen abrufen: GET api/class
  • Datenformat: JSON

Patch-Anfragen

• JSON Patch-Dokumente werden für Teil-Updates genutzt (JSON Patch).

---

🔒 2. Authentifizierung und Autorisierung

Authentifizierung

• Wird durch AuthRepository und AuthController verwaltet.
• Basierend auf ASP.NET Core Identity (UserManager, SignInManager).

Setzen des Cookies

• Erfolgreiches Login setzt ein Authentifizierungs-Cookie "ChampionCheckerCookie", das die Sitzung verwaltet.
• Beim Logout wird das Cookie gelöscht.

Rollenverwaltung

• Rollen werden bei der Registrierung zugewiesen.
• Über GetUserRole im AuthController abrufbar.

---

📂 3. DTOs, Validierung & Fehlerbehandlung

DTOs (Data Transfer Objects)

• Nur notwendige Daten werden an Clients gesendet.
• Mapping zwischen Model und DTO erfolgt in AutoMapper.cs.

Fehlerbehandlung

• Globale Fehlerbehandlung in ErrorHandler.cs.
• Nicht behandelte Exceptions werden zentral abgefangen.

---

📊 4. Performance & Benchmarks

• Benchmarks für Repositories im separaten Benchmark-Projekt.

---

🛠️ 5. CI/CD Pipeline

Was ist CI/CD?

• Continuous Integration/Continuous Deployment (CI/CD) automatisiert den Entwicklungsprozess.
• Code-Änderungen durchlaufen automatisierte Tests und Deployment-Schritte.

CI/CD Workflow

• Die Pipeline main_championchecker.yml wird bei jedem Commit ausgeführt.
• Enthält Schritte für Build, Test und Deployment in Azure.

---

📝 6. Unit Tests

Test-Struktur

• xUnit wird für Unit Tests verwendet.
• Tests nutzen eine In-Memory-Datenbank zur Simulation von CRUD-Operationen.

Testaufbau

• Namensschema: Methode_Szenario_Ergebnis.
• Arrange – Act – Assert-Muster:
  1. Arrange: Testumgebung vorbereiten.
  2. Act: Methode aufrufen.
  3. Assert: Erwartetes Ergebnis prüfen.

Beispiel für einen Test

[Fact]
public void CreateStudent_ValidData_ReturnsSuccess()
{
    // Arrange
    var dbContext = GetInMemoryDbContext();
    var repository = new StudentRepository(dbContext);

    // Act
    var result = repository.Create(new Student { Name = "Noah", Age = 23 });

    // Assert
    Assert.NotNull(result);
    Assert.Equal("Noah", result.Name);
}