AI Assisted Coding

Hier soll es explizit nicht um Vibe Coding gehen. Bei AI Assisted Coding geht es darum, Programmiertätigkeiten zu automatisieren und dem Entwickler Arbeit abzunehmen. Dieser bleibt im Lead und gibt genau vor, was das erwartete Ergebnis ist und wie dieses zu erreichen ist.

Code Completion

Eine einfache Form von KI-gestützter Entwicklung ist die Möglichkeit der Codevervollständigung. Diese geht deutlich über die zuvor bereits etablierten Varianten der Autovervollständigung von einzelnen Zeilen hinaus. Dadurch, dass dem KI-Modell Kontextwissen über die Codebasis zugänglich ist, ist das automatische Generieren von ganzen Codeblöcken problemlos möglich. Bei repetitiven Aufgaben wie dem Herunterschreiben von Mapping-Methoden oder CRUD-Operationen erspart dies viel Tipparbeit. Je generischer die Anforderung ist, desto besser sind die Ergebnisse. Viel wiederkehrender Code findet sich in den Trainingsmengen der KI-Modelle.

Auch das Umsetzen von bekannten Algorithmen funktioniert aufgrund der Trainingsdaten sehr gut. Häufig muss man nur eine Methodensignatur schreiben und erhält umgehend den Autovervollständigungs-Vorschlag.

Repetitive Task

Aufgaben, die in einer Codebasis immer wieder anfallen, lassen sich gut mit KI-gestützter Entwicklung umsetzen. So kann man den Code etwa für CRUD-Operationen und Datenbankzugriffe problemlos generieren lassen. Die initiale Umsetzung sollte man von Hand ausführen. Hier arbeitet man alle für seinen Bedarf notwendigen technischen Details aus. Bei nachfolgenden Aufgaben kann man dem LLM diese Blaupause als Referenz mitgeben, an der es sich orientieren soll.

Prompt: Implement a database repository “RolesRepository” for the entity “userrole”. Use the existing implementation of “UsersRepository” as a reference.

Auch Namen für Klassen oder Methoden kann man in seinem Prompt definieren. Je mehr Vorgaben man einem LLM gibt, desto geringer ist die Wahrscheinlichkeit für Halluzinationen.

Refactorings

Bei Refactorings, die über reines Renaming hinausgehen, kann eine KI viele Aufgaben übernehmen. Mit klaren Vorgaben, was anzupassen ist und was nicht und einem überschaubaren Scope, trifft man sehr schnell das gewünschte Ergebnis. Durch eine hohe Testabdeckung bleibt sichergestellt, das die Funktionalität nach dem Refactoring nicht gebrochen ist.

Vorgehen

Um erfolgreich Arbeit an einen KI-Agenten abgeben zu können, müssen die Anforderungen klar formuliert sein. Neben den reinen fachlichen Anforderungen, die z.B. in einer Userstory festgehalten werden, muss man auch technische Details beschreiben. Was zuvor möglicherweise nur implizites Wissen aller Beteiligter war, die an einem Softwareprojekt mitwirken, muss nun explizit aufgeschrieben und dem LLM zugänglich gemacht werden.

Auch Entwickler müssen mehr Zeit in das Verfassen von Task investieren, um diese sinnvoll von einer KI umsetzen zu lassen. Auch hier empfiehlt es sich, sehr kleinschrittig vorzugehen. Userstories werden in viele kleine technische Task heruntergebrochen, die einen sehr beschränkten Scope haben. Diese kann man seiner KI dann zum Abarbeiten übergeben. Durch das Herunterbrechen auf kleine Task reduziert man auch den Blast-Radius, den eine KI hinterlässt, wenn sie anfängt, in dutzenden Dateien Änderungen vorzunehmen. Nachdem die KI dann alle Task einen nach dem anderen umgesetzt und zu jedem Task dedizierte Tests geschrieben hat, kann sie einen Pull-Request stellen. Als Entwicklungs-Team muss man danach die PRs reviewen und vor allem die Qualität des generierten Codes sicherstellen. Auch hier gilt weiterhin die Anforderung, dass der Code nicht nur korrekt sondern auch wartbar sein muss. Auch zukünftig werden wir mehr Quellcode lesen als schreiben, vielleicht in noch viel größerem Maße als bisher.

Neben den Task kann man einer KI technische wie fachliche Informationen über ein Softwaresystem in einer AGENTS.md-Datei zur Verfügung stellen. Diese wird bei jedem Prompt implizit eingelesen und bei der Generierung der Antwort berücksichtigt.

Grenzen von AI Coding

Was nicht funktioniert sind One-Shots zum Umsetzen ganzer Features oder gar das Generieren ganzer Systeme. Auch wenn dabei Ergebnisse herauskommen, sind diese zu weit weg von dem gewünschten Ziel, der Architektur oder auch nur den Coding-Guidelines, die man im Team verfolgt.

Mitunter ist es auch zeitlich kein Vorteil, eine KI auf ein Problem zu werfen. Im Agentic Mode kann eine KI durchaus eine Stunde mit einer einzelnen Aufgabe verbringen, die ein erfahrener Entwickler mit dem entsprechenden Wissen über das Projekt in wenigen Minuten problemlos hätte umsetzen können. Auch die Zeit, die das formulieren von guten Prompts einnimmt, sollte man nicht vernachlässigen.

Coding ist nicht das Bottleneck

Die reine Schreiben von Quellcode ist nicht der limitierende Faktor bei der Entwicklung von Software. Bereits ohne KI liegt die Coding-Zeit von Senior Entwicklern bei 30-40%. Daher ist der Einsatz von künstlicher Intelligenz nicht der Heilsbringer, den manche vielleicht in ihr sehen. Aber sie verschiebt die Arbeit von Entwicklern, noch weiter weg vom Coding in Richtung Planung, Vorbereitung und Review.

Für erfahrene Entwickler sehe ich in AI Developer Tools ein gutes Werkzeug, um einfachere und repetitive Aufgaben automatisiert umsetzen zu lassen. Für Junior Devs ist es daher umso wichtiger, sich nicht auf reines Prompting und Vibe Coding zu verlassen, sondern eben jene Erfahrung und Expertise aufzubauen, um sinnvoll mit Hilfe von KI Software zu entwickeln.

Ein weiteres nützliches Tool im Testing-Werkzeugkasten sind Snapshot Tests. Snapshot Tests machen genau das, was der Name vermuten lässt: Sie erstellen einen Snapshot von einem Testergebnis. Damit lässt sich das Verhalten eines Systems einfrieren und gegen unerwünschte Änderungen und Regression absichern.

Der Beispielcode zu diesem Blog-Post ist auf Github verfügbar:

https://github.com/davull/demo-snapshot-testing-in-csharp

Die hier gezeigten Beispiele verwenden das Nuget-Package Snapshooter. Das Vorgehen ist aber problemlos auf andere Libraries übertragbar.

Warum Snapshot Testing?

Snapshot Tests frieren das Verhalten eines Systems zum Zeitpunkt der Testausführung ein. Beim ersten Ausführen eines Snapshot Tests wird das Ergebnis einer zu testenden Funktionalität in eine Datei geschrieben und dient nun als Referenz für spätere Testausführungen. Weit das Ergebnis von dem Inhalt der Referenzdatei ab, gilt der Test als fehlgeschlagen.

Die Unterschiede kann man sich optisch sehr einfach in einem Diff-Tool anschauen und schnell entscheiden, ob es sich um erwartete oder unerwartete Änderungen handelt. Hat man die Änderungen geprüft und sieht diese als valide an, übernimmt man die aktualisierte Datei als neue Referenz.

{
  "Date": "2025-12-01",
  "TemperatureC": 18,
--  "TemperatureF": 59,
++  "TemperatureF": 64,
--  "Summary": ""
++  "Summary": "Mild"
}

Ein weiterer Vorteil ist, dass man den Inhalt großer Datenobjekte einfach visuell überprüfen kann. Möchte man mehrere Properties eines Rückgabeobjektes überprüfen, schreibt man klassischerweise mehrere Assert-Statements:

[Test]
public void GetForecast_Should_ReturnCorrectValues()
{
    var tomorrow = new DateOnly(2025, 12, 02);
    const int temperatureC = 18;
    
    var forecast = WeatherForecastProvider.GetForecast(tomorrow , temperatureC);
    
    Assert.That(forecast.Date, Is.EqualTo(tomorrow));
    Assert.That(forecast.Summary, Is.EqualTo("Mild"));
    Assert.That(forecast.TemperatureC, Is.EqualTo(18));
    Assert.That(forecast.TemperatureF, Is.EqualTo(64));
}

Nutzt man hingegen eine Snapshot-Test, kann man mit einem Aufruf von MatchSnapshot() sämtliche Properties des Objektes festhalten.

[Test]
public void GetForecast_Should_MatchSnapshot()
{
    var tomorrow = new DateOnly(2025, 12, 02);
    const int temperatureC = 18;
    
    var forecast = WeatherForecastProvider.GetForecast(tomorrow , temperatureC);
    forecast.MatchSnapshot();
}

In der entsprechenden Snapshot-Datei __snapshots__/WeatherForecastProviderTests.GetForecast_Should_MatchSnapshot.snap findet man die JSON-Repräsentation des Objektes und kann mit einem Blick sehen, ob die Properties die erwarteten Werte enthalten.

{
  "Date": "2025-12-02",
  "TemperatureC": 18,
  "TemperatureF": 64,
  "Summary": "Mild"
}

Snapshot Testing im Backend

Im Bereich der JavaScript Frontend-Frameworks ist Snapshot Testing bereits seit geraumer Zeit verbreitet, etwas um den HTML-Output von Render-Funktionen zu prüfen.

Aber auch Webseiten mit SSR oder API-Endpunkte lassen sich mittels Snapshot Testing effektiv überprüfen.

private readonly CustomWebApplicationFactory _factory = new();

[Test]
public async Task GetWeatherForecast_Should_MatchSnapshot()
{
    var client = _factory.CreateClient();
    var response = await client.GetAsync("/WeatherForecast");
    var content = await response.Content.ReadAsStringAsync();

    content.MatchSnapshot();
}

Stellt ein API-Aufruf keine Pure Function dar, ändern sich manche Return-Werte, unabhängig vom gegebenen Input. So zum Beispiel das heutige Datum. Kann man diese in seinem Testsetup, etwas über FakeTimeProvider, nicht steuern, so kann man die Werte aus dem Snapshot-Resultat herausfiltern.

content.MatchSnapshot(o => o.ExcludeField("$[*].date"));

HTML Snapshots

HTML-Seiten lassen sich auf die gleiche Weise testen. Hier bietet es sich an, den HTML Output vor dem Snapshot-Vergleich etwas aufzuräumen, um Änderungen an zufällige Werten nicht zu berücksichtigen. Dazu zählen etwa dynamische IDs, Anti Forgery Tokens oder automatisch generierte CSS-Klassen.

public static string PrepareMarkup(string markup)
{
    var replacements = new Dictionary<string, string>
    {
        {
          """
          <input name="__RequestVerificationToken" type="hidden" value="[\d\w-]+" \/>
          """,
          """
          <input name="__RequestVerificationToken" type="hidden" value="<replaced>" />
          """
        },
        {
          @"\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b",
          "00000000-0000-0000-0000-000000000000"
        },
        // ...
    };

    foreach (var (pattern, replacement) in replacements)
    {
        markup = Regex.Replace(markup, pattern, replacement);
    }

    return markup;
}

Erstellt man auf einer derartigen Höhe Snapshots von ganzen Webseiten, bekommt man unerwünschte Änderungen am generierten Output zuverlässig mit und erhält effektive Regressionstests.

Arbeiten mit Legacy Code

Code ohne Tests ist bekanntlich Legacy Code. Um nun aber schnell und effektiv mit einer Legacy Codebasis arbeiten zu können, bieten sich Snapshot Tests förmlich an. Sie ermöglichen es, das bestehende Verhalten der Anwendung festzuhalten. Somit ist ein Sicherheitsnetz aufgespannt, dass uns das Ändern der Codebasis erlaubt und unerwartet Änderungen aufdeckt. Für Webanwendungen ist das Testen von HTTP- und API-Endpunkten einfach umzusetzen. Bei Desktop-Anwendungen oder native Mobile Apps muss man eine Ebene unter der UI ansetzen. So kann man etwa vor dem Umsetzen von Codeänderungen einen Snapshot eines ViewModels erstellen.

Hat man die Möglichkeit, wiederholbare Integrationstests mit externen Ressourcen wie einer Datenbank zu erstellen, kann auch deren Inhalt das Ziel eines Snapshot Tests sein.

[Test]
public async Task Table_User_Should_MatchSnapshot()
{
    // Prepare database

    // Do testing operation

    var user = Repository.GetUsers();
    users.MatchSnapshot();
}

Wie man in einem agilen Projektumfeld mit einem solchen Task-Board arbeitet, um nicht nur Output sondern Outcome zu liefern und nicht in ein blosses Status-Reporting verfällt, zeige ich in diesem Blogbeitrag.

Die meisten Software-Teams, die in Iterationen arbeiten, nutzen ein Task-Board in irgendeiner Form. Diese verfügen über mehrere Spalten, die den aktuellen Status einer Aufgabe repräsentieren. Im einfachsten Fall genügen drei Spalten TODO, DOING und DONE. Je nach Projekt-Setup können am Anfang noch weitere Spalten für die Design- und Refinement-Phasen stehen. Am anderen Ende können Spalten für das Testing oder die Abnahme durch den/die Product Owner oder andere Personen eingefügt werden. Zusätzlich hat man die Möglichkeit, jedem Item auf dem Board eine Person zuzuweisen, die gerade an der entsprechenden Aufgabe arbeitet.

Shared Ownership

Das gesamte Team ist für die Erfüllung der Aufgaben zuständig. Daher werden User Stories (oder Bugs oder Issues) keiner einzelnen Person zugewiesen. Das Team committed sich zu Begin einer Iteration auf einen Arbeitsumfang, den es bewältigen will und kann. Sobald eine neue Aufgabe angegangen wird, wird diese auf konkrete zu erledigende Task heruntergebrochen. Auch während der Umsetzen können weitere Task hinzukommen, sobald sich herausstellt, das weitere Arbeiten notwendig sind. Diese Sub-Task werden nun von einzelnen Personen bearbeitet und diesen auch im Board zugeordnet. An einer Story können so durchaus mehrere Personen parallel arbeiten. So behält man den Überblick, welche Aufgaben wie viele Personen bindet.

Damit ist jeder im Team für die Erfüllung der aktuell aktiven Aufgaben verantwortlich. Es gibt im gesamten Prozess keine “meine” und “deine” Stories. Ist man mit seinem aktuellen Task fertig, kann man sich einer anderen Story anschliessen. Erst, wenn kein weiteres parallels Arbeiten sinnvoll möglich ist, beginnt man mit der Umsetzung einer neuen Story.

Priorisieren

Wie entscheide ich, welchen Task ich als nächstes angehe? Durch die Shared Ownership für den gesamten Iterations-Umfang, habe ich keine “eigenen” Stories, die ich abzuarbeiten habe. Um nicht wahllos mit der nächsten Story zu beginnen, ist es wichtig, die aktuell auf dem Board stattfindenden Arbeiten zu priorisieren. Stories, die weiter rechts auf dem Board liegen, sind wichtiger als solche weiter links. Diese sind also immer von höherer Priorität. Befindet sich eine Story in der Spalte TESTING, nehme ich mir diese vor und teste sie. Anstatt einer Spalte TESTING kann man auch einfach einen Sub-Task aufs Board legen. Befindet sich eine Story in der Spalte DOING, arbeite ich an dieser Story mit. Erst wenn keine Stories mehr auf der rechten Seite des Boards übrig sind und kein paralleles Arbeiten an aktiven Stories möglich ist, wird mit der Arbeit an einer neuen Aufgabe begonnen.

Im Kanban-Framework gibt es dafür das Work in Progress Limit.

Der Hintergrund dieses Vorgehens ist einfach: User Stories, die nicht fertig, also im Status DONE sind, haben für das Produkt keinen Mehrwert. Eine abgeschlossene Story ist wertvoller als fünf angefangene. Auch ein “fast fertig” ist kein “fertig”.

Stop Starting, Start Finishing

Walk the Board

Oben haben wir gesehen, dass wir unser Task-Board von rechts nach links abarbeiten. Dies gilt auch für unsere täglichen Sync-Meetings mit dem/der Product Owner. Wir gehen das Board von rechts nach links durch, klären welche Arbeiten umgesetzt sind und abgenommen werden können. Hier genügt es, wenn eine Person über das Board führt. Es muss sich nicht jeder zu seinen aktuellen Tätigkeiten äussern. Es geht nicht darum, zu rechtfertigen, womit man den letzten Arbeitstag verbracht hat oder zu zeigen, wie weit man mit seiner “eigenen” Story gekommen ist. Treten Probleme auf, wird als Team diskutiert, wie man zu einer Lösung kommt.

Mit diesem Vorgehen schafft man es, auch in stressigen Situationen den Fokus zu bewahren und für eine kontinuierliche Weiterentwicklung des Produktes zu sorgen.

Da ich Mastodon selbst gerne als News-Quelle und Aggregator verschiedener Blogs nutze, habe ich eine Anwendung geschrieben, die RSS-Feeds automatisch im Fediverse veröffentlicht.

Der Quellcode sowie die Anleitung zur Verwendung sind auf Github verfügbar: https://github.com/davull/FeedToMastodon

Eine laufende Instanz der Anwendung veröffentlicht Posts von einigen News-Feeds auf https://feedmirror.social

Feed To Mastodon

Feed To Mastodon ist eine .NET Anwendung, die neue Feed-Einträge automatisch auf Mastodon postet. Unterstützt werden dabei RSS, Atom und RDF-Feeds. Die Anwendung kann lokal kompiliert und ausgeführt oder als vorkonfiguriertes Docker-Image genutzt werden.

Die Anwendung kann beliebig viele Feeds behandeln. Für jeden Feed kann ein separater Mastodon-Account verwendet werden.

Damit der jeweilige Mastodon Account nicht mit alten Feed-Einträgen überflutet wird, werden beim ersten Synchronisieren eines neuen Feeds die bisherigen Einträge übersprungen und nur neue Einträge veröffentlicht.

Konfiguration

Die Konfiguration der zu überwachenden Feeds erfolgt in einer .ini-Datei.

[heise.de]
feed_url = https://www.heise.de/rss/heise-atom.xml
summary_separator = [...]
mastodon_server = https://mastodon.social/
mastodon_access_token = AWWHkaIB_...

[wired.com]
feed_url = https://www.wired.com/feed/rss
mastodon_server =  https://mastodon.social/
mastodon_access_token = ABC...

...

Neben den URLs zum Feed und zum Mastodon-Server, auf dem der Ziel-Account registriert ist, ist ein Access-Token notwendig.

Der Parameter summary_separator ist optional und kann angegeben werden, um Feed-Einträge zu kürzen. Der Eintrag wird ab dem ersten Vorkommen der Trennzeichen abgeschnitten.

Wenn ein Post etwa ein […] enthält, kann der Eintrag hier gekürzt werden:

Earlier today, we reported that […]
To the post <a rel="nofollow" ...>http://news.com/123</a>

Die Konfiguration von summary_separator = […] führt zu dem gekürzten Eintrag:

Earlier today, we reported that ...

Gepostete Einträge werden in einer SQLite-Datenbank gespeichert, um doppelte Post zu vermeiden.

Mastodon Access-Token

Ein Access-Token kann über die Mastodon-Webseite unter Einstellungen -> Entwicklung -> Neue Anwendung angelegt werden. Unter Name kann ein beliebiger Text eingetragen werden, z.B. Feed to Mastodon. Unter Weiterleitungs-URI kann der Standardwert urn:ietf:wg:oauth:2.0:oob beibeibehalten werden. Unter Befugnisse muss nur write:statuses ausgewählt sein, profile kann abgewählt werden.

Nach dem Speichern kann man erneut auf die neu erstellte Anwendung klicken und das Access-Token Dein Zugriffstoken kopieren.

Parameter

Die Dateipfade zu den Konfigurations- und Datenbankdateien werden als Umgebungsvariablen hinterlegt.

Ausführung

Um Feed to Mastodon via Docker auszuführen, genügt folgender Befehl:

docker run -it --rm \
  -v "${PWD}/ftm-feed-config.ini:/app/ftm-feed-config.ini" \
  -v "${PWD}/ftm.sqlite:/app/ftm.sqlite" \
  -e "FTM_CONFIG_FILE_NAME=/app/ftm-feed-config.ini" \
  -e "FTM_DATABASE_NAME=/app/ftm.sqlite" \
  davidullrich/feed-to-mastodon:latest

Eine Docker Compose Konfiguration sieht wie folgt aus:

services:
  ftm:
    container_name: feed-to-mastodon
    image: davidullrich/feed-to-mastodon:latest
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    environment:
      - FTM_DATABASE_NAME=/app/data/ftm.sqlite
      - FTM_CONFIG_FILE_NAME=/app/data/ftm.ini
      - TZ=Europe/Berlin

Statistiken

Für die Interessierten gibt Feed to Mastodon täglich eine Statistik auf der Console aus. Diese zeigt die Anzahl der geposteten Feeds in den letzten 24 Stunden und den letzten sieben Tagen.

Statistics[0] ============================================================
Statistics[0] Total Posts per feed:    2024-11-18 00:00 - 2024-11-25 00:00
Statistics[0] ============================================================
Statistics[0]   Mashable:                                              215
Statistics[0]   Caschys Blog:                                          183
Statistics[0]   Digital Trends:                                        299
Statistics[0]   Elektroauto-News.net:                                    8
Statistics[0]   TESLARATI:                                              48
Statistics[0]   WIRED:                                                 102
Statistics[0] ------------------------------------------------------------
Statistics[0] Total:                                                   855
Statistics[0] ============================================================

Live-Beispiel

Unter https://feedmirror.social ist Feed to Mastodon mit ein paar konfigurierten Feeds in Betrieb und bringt die neuesten Artikel ins Fediverse.

Möchte man die Docker-Container nicht innerhalb des Test-Codes verwalten, bietet es sich an, die Container unabhängig von der Test-Ausführung zu starten und zu stoppen. Docker Compose und das Azure DevOps-Feature Service-Containers bieten sich hier als Alternativen an.

Der Beispielcode zu diesem Blog-Post ist auf Github verfügbar: https://github.com/davull/demo-docker-compose-test

Docker Compose

Docker Compose erlaubt es, mehrere Docker-Container in einer Datei zu definieren und zu verwalten. Diese können dann mit nur einem Befehl gestartet und gestoppt werden. Zudem lassen sich Netzwerke zwischen den Containern definieren, Speicher-Volumes erstellen und Umgebungsvariablen setzen. Für die hier genutzte Demo-Anwendung nutze ich eine MariaDB-Datenbank und einen phpMyAdmin-Container. Etwas verkürzt sieht das entsprechende Docker Compose File so aus (die gesamte Konfiguration findet sich im Github-Repository):

name: "orderapp"

services:
  order-mariadb:
    image: mariadb:11.3
    container_name: order-mariadb
    volumes:
      - order-mariadb:/var/lib/mysql
    networks:
      - order-net
    environment:
      MYSQL_ROOT_PASSWORD: "some-password"
      MYSQL_DATABASE: "orders"

  order-pma:
    image: phpmyadmin
    container_name: order-pma
    ports:
      - "9002:80"
    networks:
      - order-net

networks:
  order-net:

volumes:
  order-mariadb:

Mittels docker compose up bzw. docker compose down startet und stoppt man nun alle Container.

Möchte man einen MariaDB-Container für die Integrations-Tests seiner Anwendung nutzen, gibt es ein paar Dinge zu beachten. Man muss die Datenbank initialisieren und mit entsprechenden Testdaten befüllen. Dies kann man für xUnit etwa mittels Shared Context innerhalb seiner Test-Suite durchführen und vor jeden Test-Run ein Seeding der Datenbank durchführen. Nach dem Test-Run wird die Datenbank dann einfach wieder gelöscht.

public class DatabaseFixture : IAsyncLifetime
{
    private string _databaseName;
    
    public async Task InitializeAsync()
    {
        _databaseName = GetRandomTestDatabaseName();
        await Database.Seed(_databaseName);
    }

    public async Task DisposeAsync()
      => await Database.DeleteDatabase(_databaseName);
}

Alternativ kann man auf eine Funktion des MariaDB-Containers zurückgreifen, die es ermöglicht, beliebiger SQL-Scripte beim Starten des Containers auszuführen. Dazu mountet man einen Ordner in den Container unter /docker-entrypoint-initdb.d. Alle SQL-Dateien in diesem Ordner werden dann beim Starten des Containers ausgeführt.

services:
  order-mariadb:
    image: mariadb:11.3
    volumes:
      - ./initdb:/docker-entrypoint-initdb.d

Neben dem initialen Befüllen der Datenbank muss man nach dem Start des Containers feststellen können, ob der Datenbankserver bereits Anfragen entgegennehmen kann. Für das Ausführen der Integrationstests in einer CI/CD-Pipeline ist dies relevant, damit die Tests erst ausgeführt werden, wenn der Container auch voll funktionsfähig ist. Für Docker-Container bietet sich hier die Option der healthchecks an. MariaDB liefert bereits ein entsprechendes healthcheck.sh-Script mit aus.

services:
  order-mariadb:
    image: mariadb:11.3
    healthcheck:
      interval: 3s
      retries: 3
      test:
        [
          "CMD",
          "healthcheck.sh",
          "--su-mysql",
          "--connect",
          "--innodb_initialized",
        ]
      timeout: 30s

Docker Compose in einer Azure Pipeline

Mit dem zuvor angelegten Docker Compose File kann man die Integrations-Tests lokal und auch in einer Azure DevOps CI/CD-Pipeline ausführen. Zunächst starten wir mittels des DockerCompose@0-Tasks unsere Container:

- task: DockerCompose@0
  displayName: "Docker compose up"
  inputs:
    containerregistrytype: Container Registry
    dockerComposeFile: "./docker/docker-compose.yml"
    action: Run a Docker Compose command
    dockerComposeCommand: "up -d"
    projectName: "orderapp"

Anschliessend muss man noch mittels healthcheck auf die Betriebsbereitschaft des Datenbank-Containers warten.

Führt man seine Azure-Pipeline in einem Container-Job aus, muss man den Datenbank-Container noch mit dem Netzwerk des Pipeline-Containers verbinden. Die Umgebungsvariable $(Agent.ContainerNetwork) enthält den Namen des Netzwerks, in dem der Pipeline-Container läuft.

- task: CmdLine@2
  displayName: "Prepair containers"
  inputs:
    workingDirectory: "./docker"
    script: |
      echo -e "Connect database to network $(Agent.ContainerNetwork) ...\n"
      docker network connect $(Agent.ContainerNetwork) order-mariadb
      
      echo -e "Waiting for container to be healthy ...\n"
      until [ "$(docker inspect -f '{{.State.Health.Status}}' order-mariadb)" == "healthy" ]; do
        sleep 1
      done

Anschliessend können die Tests ausgeführt werden. Da die Konfiguration der Datenbankverbindung in der CI-Pipeline anders ist als auf dem lokalen PC oder in der Produktivumgebung, kann man diese etwa über ein .runsettings-File entsprechend setzen.

<RunSettings>
  <RunConfiguration>
      <EnvironmentVariables>
          <DB_SERVER>order-mariadb</DB_SERVER>
          <DB_PORT>3306</DB_PORT>
          <DB_NAME>orders</DB_NAME>
          <DB_USER>root</DB_USER>
          <DB_PASSWORD>some-password</DB_PASSWORD>
      </EnvironmentVariables>
  </RunConfiguration>
</RunSettings>

In dem DotNetCoreCLI@2-Task gibt man das File dann per Argument an.

- task: DotNetCoreCLI@2
  displayName: "Dotnet test"
  inputs:
    command: test
    arguments: "--settings ./src/ci-tests.runsettings"

Nach dem Test-Run werden die Container wieder gestoppt.

- task: DockerCompose@0
  displayName: "Docker compose down"
  condition: always()
  inputs:
    containerregistrytype: Container Registry
    dockerComposeFile: "./docker/docker-compose.yml"
    currentWorkingDirectory: "./docker"
    action: Run a Docker Compose command
    dockerComposeCommand: "down -v"
    projectName: "orderapp"

Azure DevOps Service-Containers

Als Alternative zum Aufsetzen und Starten von Docker-Containern mittels Docker@2- oder DockerCompose@0-Task bietet Microsoft die Möglichkeit, Container-Ressourcen als Service-Container innerhalb einer Pipeline bereitzustellen. Diese Container laufen parallel zu den Build- und Test-Jobs und können von diesen angesprochen werden. Damit eignen sich auch Service-Container zum Bereitstellen von etwa Datenbanken für Integrationstests.

Die Konfiguration der Service-Container erfolgt direkt in der .yaml-Datei der Pipeline-Definition; Für klassische Azure Pipelines steht das Feature nicht zur Verfügung. Die Syntax ähnelt sehr der von Docker Compose, wer sich hiermit auskennt, wird sich schnell zurechtfinden.

Container werden unter dem Abschnitt resources definiert und anschließend unter services exponiert (Container-Resources können auch für Container Jobs genutzt werden).

resources:
  containers:
    - container: order-mariadb
      image: mariadb:11.3
      ports:
        - 3306:3306
      env:
        MYSQL_ROOT_PASSWORD: "some-password"
        MYSQL_DATABASE: "orders"

services:
  order-mariadb: order-mariadb

Damit ist der MariaDB-Server auch schon unter der Adresse localhost:3306 erreichbar.

Nutzt man zur lokalen Entwicklung keine Docker-Container, deren Konfiguration für Integrationstests innerhalb der CI-Pipeline wiederverwenden kann, bieten Service-Container eine einfache Möglichkeit, die benötigten Ressourcen bereitzustellen.

Damit die externen Systeme auch in den Integrations-Tests reproduzierbar und vorhersehbar zur Verfügung stehen, kann man sie in Docker-Containern ausführen. Ein einfaches Setup solcher Service-Container ermöglicht die Bibliothek Testcontainers.

Der Beispielcode zu diesem Blog-Post ist auf Github verfügbar: https://github.com/davull/demo-docker-testcontainers

In einem anschließenden Blog-Post zeige ich, wie man Integrationstests mit Hilfe von Docker Compose und Azure Service-Containers umsetzen kann.

Integrationstests

Integrationstest sollen das Zusammenspiel von mehreren Komponenten eines Softwaresystems prüfen. Dies kann einzelne funktionale Einheiten betreffen aber auch einen gesamten Durchstich durch die Anwendung. So kann man für eine Web-API etwa einen HTTP-Aufruf an die Anwendung schicken, Daten in einer Datenbank manipulieren und das in einem Redis-Cache zwischengespeicherte Ergebnis wieder zurück an den Aufrufer liefern.

Das Verhalten von externen Systeme kann man nun zwar mittels Mocks versuchen nachzubilden, einen wirklichen Mehrwert liefern Integrationstests aber erst dann, wenn sie auch mit echten Systemen interagieren. Damit bewegt man sich näher an einer Produktivumgebung und kann so auch Probleme finden, die für Mocks nicht sichtbar wären.

Die meisten Systeme kann man mittlerweile in einem Docker-Container betreiben. Sollte mal kein vorkonfiguriertes Image zur Verfügung stehen, ist es zumeist einfach möglich, ein eigenes zu erstellen.

Diese Containerisierung von Anwendungen kann man sich beim Testen zu Nutze machen und vor jeden Testdurchlauf, etwas in einer CI/CD-Pipeline, die benötigten Systeme mit einem definierten Zustand starten. Nach dem Ausführen der Tests werden die Container einfach wieder gestoppt und gelöscht.

Testcontainers

Das Projekt Testcontainers bietet für viele Programmiersprachen Bibliotheken an, um das Aufsetzen und Ausführen von Docker Containern in Tests zu vereinfachen. Für .NET steht ein entsprechendes Nuget-Paket zur Verfügung: Testcontainers for .NET.

Ein Testcontainer wird einfach vor der Ausführung der Test-Methoden definiert und gestartet und danach wieder gestoppt und gelöscht. Die ContainerBuilder-Klasse bietet eine Fluent-API, um die Container zu konfigurieren.

var container = new ContainerBuilder()
    .WithImage("mariadb:11.3")
    .WithHostname("mariadb-test-container")
    .Build();

await container.StartAsync();

// run integration tests

await container.StopAsync();

Um die Tests lokal ausführen zu können, muss Docker auf dem Rechner installiert sein und der Docker-Dienst laufen.

Best practice ist es, Container-Ports auf zufällige Host-Ports zu mappen, um Konflikte mit anderen laufenden Services und Containern zu vermeiden.

var containerBuilder = new ContainerBuilder()
    .WithPortBinding(3306, assignRandomHostPort: true);

var port = container.GetMappedPublicPort(3306);

Um nach dem Start auf die Verfügbarkeit eines Dienstes innerhalb des Containers zu warten, stellt Testcontainers eine Reihe von Wait-Strategien zur Verfügung. So kann man etwa auf den Health-Status des Containers warten oder aber einen beliebigen TCP-Port auf Erreichbarkeit prüfen. Auch das Warten auf einen HTTP-Endpunkt ist möglich.

// Wait for MySQL to be ready
var containerBuilder = new ContainerBuilder()
    .WithImage("mariadb:11.3")
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilPortIsAvailable(3306));

// Wait for HTTP service to be ready
var containerBuilder = new ContainerBuilder()
    .WithImage("productservice:latest")
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilHttpRequestIsSucceeded(strategy => strategy
            .ForPort(443)
            .ForPath("/api/products")
            .WithBasicAuthentication("user", "password")));

Viele Container-Images lassen sich per Umgebungsvariablen konfigurieren. Einem Testcontainer kann man diese einfach über die Methode WithEnvironment(env) mitgeben.

var env = new Dictionary<string, string>
{
    { "MYSQL_ROOT_PASSWORD", "some-password" },
    { "MYSQL_DATABASE", "products" }
};

var containerBuilder = new ContainerBuilder()
    .WithEnvironment(env);

Vorkonfigurierte Container

Testcontainers bietet eine Reihe von vorkonfigurierten Containern an, die die Nutzung unterschiedlicher Services vereinfacht. Hier entfallen dann etwa die Angabe des Images oder ein Port-Mapping. Ein MySqlContainer bietet direkt die Möglichkeit, den passenden Connection-String für die Datenbank zu erhalten.

var container = new MySqlBuilder().Build();
var connectionString = container.GetConnectionString();

Test-Fixtures

Um die Konfiguration von Testcontainern zu zentralisieren und nicht für jeden Aufruf einer Test-Methode einen neuen Container zu erzeugen und zu starten, kann man die Möglichkeiten der unterschiedlichen Test-Frameworks nutzen, sogenannte Test-Fixtures zu erstellen.

Für xUnit kann man etwa eine Klasse DatabaseFixture erstellen, welche das Initialisieren und Starten des Containers übernimmt. Eine Klasse, die das Interface ICollectionFixture<DatabaseFixture> implementiert, kann dann steuern, welche Tests sich eine Container-Instanz teilen.

public class DatabaseFixture : IAsyncLifetime
{
    public async Task InitializeAsync()
    {
        _container = BuildContainer();
        await _container.StartAsync();
    }

    public async Task DisposeAsync()
    {
        await _container.StopAsync();
    }

    // ...
}

[CollectionDefinition(Name)]
public class DatabaseCollectionFixture : ICollectionFixture<DatabaseFixture>
{
    public const string Name = "DatabaseCollection";
}

Die entsprechenden Tests annotiert man mit dem Collection-Attribut und dem Collection-Namen, das den Fixture-Container bereitstellt.

[Collection(DatabaseCollectionFixture.Name)]
public class DatabaseTests
{
    // ...
}

Das Projekt in dem Github-Repository zu diesem Post zeigt ein vollständiges Beispiel: https://github.com/davull/demo-docker-testcontainers

CI/CD-Pipeline

Testcontainers lassen sich in einer CI/CD-Pipeline auf die gleiche Art ausführen wie lokal. Voraussetzung ist lediglich, dass auf dem Build Server ebenfalls Docker und die Docker CLI installiert sind. Im Falle von Azure DevOps ist dies für von Microsoft gehosteten Build-Agents bereits der Fall. Nutzt man eigene Build-Container, lässt sich die Docker CLI über den Task DockerInstaller@0 installieren.

- task: DockerInstaller@0
  displayName: "Install docker cli"
  inputs:
    dockerVersion: 26.1.0

Beim Ausführen des Test-Steps werden dann die benötigten Images heruntergeladen, falls noch nicht vorhanden, und die Container gestartet.

Eine leichtgewichtige Methode, um Architektur-Entscheidungen zu dokumentieren, stellen Architectural Decision Records, kurz ADRs, dar.

Architektur-Dokumentation

Jedes Stück Software hat auch eine Software-Architektur. Ob diese aktiv herbeigeführt wird oder während der Entwicklung “passiert” ist, hängt von den Umständen und Anforderungen ab. Um Entscheidungen, die man auf dem Weg zum aktuellen Stand der Software getroffen hat, auch im Nachhinein noch nachvollziehen und ggf. bewerten zu können, ist eine Architektur-Dokumentation, oder zumindest eine Dokumentation der wichtigsten Entscheidungen, sinnvoll. Häufig werden solche Entscheidungen in einem Wiki, Confluence oder Word-Dokument festgehalten. Die Dokumentation erfolgt damit außerhalb des eigentlichen Quellcodes und unstrukturiert, was die Pflege und Aktualisierung erschwert. Mit arc42 oder Structurizr existieren Frameworks, um unterschiedliche Aspekte einer Software und deren Architektur strukturiert zu dokumentieren. Für Projekte, die keine derart umfangreiche Dokumentation benötigen, bieten sich ADRs als leichtgewichtige Lösung an.

Architectural Decision Records

Das Ziel von Architectural Decision Records ist es nicht, die gesamte Architektur einer Software zu beschreiben oder widerzuspiegeln, sondern Entscheidungen, die zu der aktuellen Architektur geführt haben, festhalten.

ADRs halten Architektur-Entscheidungen in reinen Textdateien fest und geben lediglich das Format vor. Jede Entscheidung erhält eine eigene Datei und eine fortlaufende Nummer. Für eine einfache Formatierungen wird Markdown verwendet. Die Dateien sind Teil des Quellcode-Repositories und unterliegen damit auch der Versionskontrolle. ADRs können damit auch per Pull-Request eingebracht und diskutiert werden.

Auch wenn der Name den Kontext Architektur setzt, lassen sich ADRs für eine Vielzahl von technischen und nicht-technischen Entscheidungs-Dokumentationen nutzen.

Format

Nach dem Erfinder Michael Nygard bestehen ADRs aus den folgenden Feldern:

Titel: Kurze Beschreibung der Entscheidung.

Context: Beschreibung des Kontexts, in dem die Entscheidung getroffen wurde inkl. der technologischen, politischen oder sozialen Rahmenbedingungen. Die Formulierung ist neutral und beschreibt die vorliegenden Fakten.

Decision: Beschreibt die im zuvor dargestellten Kontext getroffene Entscheidung. Die Formulierung ist aktiv und beschreibt, was getan wird: “Wir werden …”.

Status: Der Status der Entscheidung. Mögliche Werte sind proposed, accepted, deprecated oder superseded.

Consequences: Beschreibt den resultierenden Zustand nach der Entscheidung. Es werden sowohl positive als auch negative Konsequenzen aufgeführt.

Ein solches ADR-Dokument hat eine Länge von ein bis zwei Seiten. Es stellt eine Kommunikation mit zukünftigen Entwickler:innen oder uns selber dar. Daher ist es wichtig, dass die Dokumentation verständlich und nachvollziehbar ist und nicht nur eine Stichpunktliste enthält. Für den Dateinamen schlägt Nygard ein Format vor: doc/arch/adr-NNN.md. Über den eindeutigen Bezeichner kann man einzelne ADRs referenzieren, etwa wenn spätere Entscheidungen auf einer vorherigen aufbauen oder diese ersetzen.

Ob man für sein Projekt dem hier gezeigten Format folgt oder eine eigene Variante erarbeitet, ist zweitrangig. Wichtig ist, dass das Format über den Projekt-Verlauf hinweg konsistent eingehalten wird. Joel Parker Henderson hat in einem GitHub-Repository eine Reihe von ADR-Templates zusammengetragen.

Beispiel

Der ADR für die Entscheidung über den Einsatz von RabbitMQ als Message Broker könnte wie folgt aussehen:

# ADR-039: RabbitMQ als Message Broker

## Context

Wir benötigen einen Message Broker, um asynchrone Nachrichten
zwischen den einzelnen Komponenten unserer Anwendung auszu-
tauschen. Die Lösung soll ausfallsicher betrieben werden können
und Nachrichten persistent speichern. Die Lösung soll im eigenen
Rechenzentrum gehostet und von unserem Service-Team betrieben
werden. RabbitMQ ist bereits in anderen Projekten im Einsatz
und das Service-Team mit dem Betrieb vertraut.

## Decision

Wir werden RabbitMQ als Message Broker einsetzen. RabbitMQ 
erfüllt unsere Anforderungen und ist bereits im Unternehmen
etabliert. Dem Service-Team wird die Verantwortung für den
Betrieb übertragen. Wir teilen dem Service-Team das erwartete
Nachrichten-Aufkommen mit.

## Status

accepted

## Consequences

Aufgrund der Entscheidung muss im Software-Team Know-How für
den Einsatz von RabbitMQ aufgebaut werden. Das Service-Team
unterstützt das Software-Team bei der Integration. Der 
angedachte Einsatz von asynchronen Nachrichten zwischen den
Komponenten der Anwendung kann umgesetzt werden.

Mit einem solchen Dokument ist auch im Nachhinein nachvollziehbar, warum RabbitMQ und nicht etwa Azure Service Bus eingesetzt wird.

Werkzeuge

Da es sich bei ADRs um eine strukturierte Variante von Dokumentation handelt, haben sich eine Reihe von Werkzeugen etabliert.

adr-tools

Nat Pryce hat mit adr-tools ein Command Line Tool zum Arbeiten mit ADRs entwickelt. Damit ist es möglich, neue ADRs im von Michael Nygard beschriebenen Format anzulegen.

$ adr init doc/adrs
doc/adrs/0001-record-architecture-decisions.md

$ cat doc/adrs/0001-record-architecture-decisions.md

# 1. Record architecture decisions

Date: 2023-12-28

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as [described by Michael Nygard]
(http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset,
see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

Neue ADRs können mit adr new angelegt werden.

$ adr new Write Blog Post about ADRs
doc/adrs/0002-write-blog-post-about-adrs.md

Über weitere Befehle können ADRs verknüpft, aufgelistet und Inhaltsverzeichnisse generiert werden.

$ adr generate toc
# Architecture Decision Records

* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Write Blog Post about ADRs](0002-write-blog-post-about-adrs.md)

adr-viewer

adr-viewer generiert aus ADR-Dateien eine HTML-Seite. Damit kann man ADRs etwa in seine CI/CD-Pipeline integrieren und die Dokumentation automatisch aktualisieren.

$ pip install adr-viewer

$ adr-viewer --adr-path doc/adrs --output doc/adrs.html

Die generierte Seite bietet eine Übersicht über alle ADRs und ermöglicht die Navigation zwischen den einzelnen Dokumenten. Die unterschiedlichen Status werden farblich hervorgehoben.

Auch beim Refactoring von bestehendem Code können sich solche Architektur-Tests als sinnvoll erweisen.

Mit ArchUnitNET lassen sich Architektur-Regeln als Code definieren und automatisiert testen.

ArchUnitNET

ArchUnitNET ist ein .NET Port der in der Java-Welt etablierten Bibliothek ArchUnit. Mit ArchUnitNET ist es möglich, Architektur-Regeln als Unit-Test zu hinterlegen und kontinuierlich und automatisiert zu überprüfen. Die Regeln werden in C# Code geschrieben und können in einem beliebigen Test-Framework ausgeführt werden. Um ArchUnitNET zu nutzen, genügt es, seinem Projekt das entsprechende Nuget-Paket hinzuzufügen. Für eine einfache Integration in die unterschiedlichen Testframeworks stehen Pakete für xUnit, NUnit und MS-Test bereit.

Architektur-Regeln

ArchUnitNET-Test sind wie andere Unit-Tests auch aufgebaut. Es existiert eine Test-Klasse mit einer Reihe von Test-Methoden. Der besseren Performance wegen legt man eine statische Klassen-Property mit der Definition der Architektur an.

Hierzu macht man dem ArchLoader eine Reihe von Assemblies bekannt, welche den Code enthalten, der zu unserer Architektur gehören soll. Dazu kann man z.B. Marker-Klassen nutzen. ArchLoader kennt aber auch eine Reihe weiterer Methoden, etwa um Assemblies aus einem Verzeichnis zu laden.

private static readonly Assembly DataModuleAssembly = 
    typeof(DataModuleMarker).Assembly;
private static readonly Assembly BusinessModuleAssembly = 
    typeof(BusinessModuleMarker).Assembly;
private static readonly Assembly DesktopModuleAssembly = 
    typeof(DesktopModuleMarker).Assembly;

private static readonly Architecture Architecture = new ArchLoader()
    .LoadAssemblies(DataModuleAssembly, BusinessModuleAssembly, DesktopModuleAssembly)
    .Build();

Innerhalb der Architektur lassen sich nun Mengen von Klassen, Interfaces oder Methoden bilden, z.B. um Klassen in Schichten zu gruppieren. Nutzt man ein konsistentes Namensschema, kann man auch nach Namensmustern filtern und etwa alle Repository-Klassen zusammenfassen.

Bei der Definition hilft die eingängige Fluent-API von ArchUnitNET.

private readonly IObjectProvider<IType> DataLayer =
    Types().That().ResideInAssembly(DataModuleAssembly).As("Data layer");

private readonly IObjectProvider<IType> BusinessLayer =
    Types().That().ResideInAssembly(BusinessModuleAssembly).As("Business layer");

private readonly IObjectProvider<Class> RepositoryClasses =
    Classes().That().HaveNameEndingWith("Repository").As("Repository classes");

Um nun zu testen, ob alle Repository-Klassen auch wirklich im Data-Layer angesiedelt sind, schreiben wir einen Test, der eine entsprechende Regel definiert und unsere Architektur gegen diese prüft. Zur einfachen Verwendung kann man ArchRuleDefinition als static using einbinden.

using static ArchUnitNET.Fluent.ArchRuleDefinition;

[Fact]
public void RepositoryClassesShouldBeInDataLayer()
{
    var rule = Classes().That().Are(RepositoryClasses).Should().Be(DataLayer);
    rule.Check(Architecture);
}

Zum Überprüfen von gewollten oder ungewollten Abhängigkeiten zwischen Modulen genügen ebenfalls wenige Zeilen Code. Der nachfolgende Test prüft, ob irgendein Typ aus dem Desktop-Layer auf einen Typ aus dem Data-Layer zugreift.

[Fact]
public void DesktopLayerShouldNotReferenceDataLayer()
{
    var rule = Types().That().Are(DesktopLayer).Should().NotDependOnAny(DataLayer);
    rule.Check(Architecture);
}

Stellt ArchUnitNET eine Verletzung unserer Regeln fest, schlägt der Test fehl und liefert eine entsprechende Fehlermeldung.

FailedArchRuleException
"Types that are Desktop layer should not depend on Data layer" failed:
    DesktopModule.ViewModels.ProductListViewModel does depend on
    DataModule.ProductRepository

Nutzung von Code verhindern

Nicht nur die Organisation von Quellcode lässt sich so erzwingen, auch die Verwendung von bestimmten Klassen oder Methode kann man regulieren. Um sicherzustellen, dass nur aus dem Data-Layer auf eine Datenbank zugegriffen wird, schränken wir den Zugriff auf Klassen aus der Assembly Microsoft.Data.SqlClient ein, in der sich unter anderem die Klasse SqlConnection befindet. Von unseren eigenen Assemblies (ProjectAssemblies) dürfen nur aus DataLayer heraus Zugriffe auf die Datenbank-Klassen erfolgen. Damit ArchUnitNET die Assembly Microsoft.Data.SqlClient kennt, müssen wir diese explizit in unsere Architektur-Definition mit aufnehmen.

private static readonly Assembly[] ProjectAssemblies = {
    DataModuleAssembly,
    BusinessModuleAssembly,
    DesktopModuleAssembly
};

private static readonly Assembly SystemDataAssembly =
    typeof(SqlConnection).Assembly;

private static readonly Architecture Architecture = new ArchLoader()
    .LoadAssemblies(/* ... */ SystemDataAssembly)
    .Build();

[Fact]
public void OnlyDataLayerShouldUseDatabase()
{
    var types = Types()
        .That().ResideInAssembly(ProjectAssemblies[0], ProjectAssemblies[1..])
        .And()
        .AreNot(DataLayer);
    var typesNotToUse = Types().That().ResideInAssembly(SystemDataAssembly);

    var rule = types.Should().NotDependOnAny(typesNotToUse);
    rule.Check(Architecture);
}

Architektur-Refactoring

Hat man es mit einer bestehenden Code-Basis zu tun und möchte Änderungen an dieser vornehmen, kann man mittels ArchUnitNET den gewünschten Zielzustand vor den entsprechenden Maßnahmen definieren. Anschließend hat man die Möglichkeit, die bestehende Architektur Stück für Stück in die angestrebte Richtung zu ändern. Zu Beginn des Refactoring-Prozesses zeigen die jetzt noch roten Tests die Stellen an, an denen gearbeitet werden muss. Regeln, die man noch nicht umgesetzt hat, kann man derweil überspringen. Sobald alle Tests wieder aktiviert und grün sind, ist das Refactoring abgeschlossen.

[Fact(Skip = "Refactoring of DesktopLayer will be done in the next iteration")]
public void DesktopLayerShouldNotReferenceDataLayer()
{
    var rule = Types().That().Are(DesktopLayer).Should().NotDependOnAny(DataLayer);
    rule.Check(Architecture);
}

System-Ressourcen finden

Die Verwendung von nicht-deterministischen System-Ressourcen wie der aktuellen Uhrzeit kann das Schreiben von Tests erschweren. Möchte man nicht direkt in Richtung Pure Functions rafactorn, kann es helfen, eine Abstraktion wie den seit .NET 8 hinzugekommenen TimeProvide zu nutzen.

Auch hier kann ein Test uns helfen, alle Zugriffe auf DateTime.Now oder DateTime.UtcNow zu finden.

[Fact]
public void DateTimeNowShouldNotBeUsedInBusinessLayer()
{
    var types = Types().That().Are(BusinessLayer);

    var methodsNotToCall = MethodMembers()
        .That().AreDeclaredIn(typeof(DateTime))
        .And().AreStatic()
        .And().HaveNameEndingWith("get_UtcNow()")
        .Or().HaveNameEndingWith("get_Now()");

    var rule = types.Should().NotCallAny(methodsNotToCall);
    rule.Check(Architecture);
}

Ein fehlschlagender Test zeigt uns auch hier wieder an, an welcher Stelle wir ansetzen müssen.

"Types that are Business layer should not call Method members that are declared
in "System.DateTime" and are static and have name ending with "get_UtcNow()"" failed:
    BusinessModule.ProductService does call System.DateTime
    System.DateTime::get_UtcNow()

Kudos gehen hier an Andreas Lausen für seinen Beispiel-Code von der SEACON 2023.

Fazit

ArchUnitNET bietet die mächtige Möglichkeit, Architektur- und Code-Verwendungs-Regeln in Form von Unit-Tests zu definieren und automatisiert und kontinuierlich zu überprüfen. Nach kurzer Einarbeitung ist das Schreiben von neuen Regeln sehr einfach. Da sich diese Architektur-Regeln wie alle anderen Unit-Test verhalten, lassen sie sich auch in bestehende Codebasen einfügen. Das beste Vorgehen ist natürlich, sie so früh wie möglich zu definieren und zu nutzen.

Der Beispiel-Code zu diesem Post findet sich auf Github: https://github.com/davull/demo-archunit

Da es auch als fertiges Docker Image zur Verfügung steht, kann man es einfach als Azure App Service deployen. Für ein Ausrollen mittels Terraform genügt eine einfache Konfiguration.

Der Terraform-Code zu diesem Post findet sich auf Github: https://github.com/davull/uptime-kuma-azure-app-service

Azure App Service

Um einen Docker Container in Azure als Web App for Container zu betreiben, benötigen wir einen App Service, welcher in einem App Service Plan beheimatet ist. Alternativ kann man Container auch in Azure Container App oder Azure Kubernetes Service betreiben, eine Übersicht bietet Microsoft hier.

Damit die von Uptime Kuma gesammelten Daten (eine SQLite Datenbank) nicht bei jedem Neustart des Containers verloren gehen, persistieren wir sie in einem Storage Account.

Resource Group

Um die Ressourcen in Azure zu organisieren, legen wir eine neue Resource Group an. Dazu suchen wir im Azure Marketplace nach Recource Group und klicken Create.

Wir vergeben einen Namen, wählen eine Region und klicken Review + Create. Anschließend können wir unsere Services innerhalb der Resource Group anlegen.

Storage Account

Beim Anlegen des Storage Accounts wählen wir die zuvor erstellte Resource Group aus, legen Namen und Region fest und das Redundanz-Level. Für nicht-kritische Anwendungen genügt die günstigste Variante Local-redundant storage (LRS). Die übrigen Einstellungen können beibehalten werden.

Sobald unser Storage Account provisioniert ist, können wir ein File share anlegen. Als Tier wählen wir Hot, die Backup-Option können wir nach Bedarf an- oder abschalten.

App Service Plan und Web App for Container

Um einen App Service Plan anzulegen, gehen wir analog vor. Als Operation System wählen wir Linux, der kleinste nicht kostenlose Pricing Plan Basic B1 genügt. Dieser schlägt mit ca. 13 € / Monat zu Buche. Er bietet 1.75 GB Arbeitsspeicher und 1 vCPU. Je nach Anzahl der zu überwachenden Services kann es sinnvoll sein, einen größeren Plan zu wählen. Ein Scale-Up ist aber auch später jederzeit möglich.

Nachdem nun ein App Service Plan und Storage zur Verfügung stehen, können den eigentlichen App Service anlegen. Um den Wizard zu starten, suchen wir im Azure Portal nach Web App for Containers oder Web App. Im Marketplace werden diese als unterschiedliche Einträge geführt, es handelt sich aber um den gleichen Service.

Als Publish-Methode wählen wir Docker und als Operating System Linux. Der hier gewählte Name ist auch zugleich die Subdomain, unter der der Service später verfügbar ist (<name>.azurewebsites.net).

Im nächsten Reiter Docker wechseln wir die Image Source auf Docker Hub und tragen das gewünschte Image inkl. Tag ein, z.B. louislam/uptime-kuma:latest.

Nachdem wir den Wizard abgeschlossen haben, ruft Azure das Docker Image aus dem Hub ab und starten unseren Container. Beim ersten Start von Uptime Kuma dauert es einige Zeit, bis der Service läuft und die Webseite verfügbar ist. Unter dem Eintrag Deployment Center im Reiter Logs kann man den Prozess verfolgen.

Azure File Share mounten

Damit die Datenbank von Uptime Kuma nicht bei jedem Neustart des Containers verloren geht, mounten wir das zuvor angelegte File Share in den Container. Dazu wählen wir den Punkt Configuration und wechseln in den Reiter Path mappings. Dort fügen wir einen neuen Eintrag hinzu. Hier wählen wir den zuvor angelegten Storage Account und den für das File Share erstellten Storage Container aus. Als Storage Type wählen wir Azure File. Der Pfad, unter dem das File Share im Container gemountet wird, muss /app/data lauten. Hier legt Uptime Kuma seine Anwendungsdaten ab. Nach dem Speichern wird der Container neu gestartet die Daten landen nun in unserem Storage Container.

Rufen wir nun die Website der Web App auf, begrüßt uns Uptime Kuma mit dem Setup-Dialog, in dem wir den Admin-Nutzer anlegen können.

Terraform

Als Alternative zum Azure Portal bietet es sich an, die Konfiguration unserer Anwendung in bester Infrastructure as Code-Manier mittels Terraform zu verwalten. Hierzu bemühen wir den azurerm Provider. Die verschiedenen Arten zur Authentifizierung sind in der Dokumentation beschrieben. Wir legen die gleichen Ressourcen an, wie wir es im Portal getan haben.

Die gesamte Konfigurationsdatei sieht wie folgt aus:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.79"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "rg_kuma" {
  name     = var.resource_group_name
  location = var.location
}

resource "azurerm_storage_account" "sa_kuma" {
  name                     = var.storage_account_name
  resource_group_name      = azurerm_resource_group.rg_kuma.name
  location                 = azurerm_resource_group.rg_kuma.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
  min_tls_version          = "TLS1_2"
}

resource "azurerm_storage_share" "share_kuma" {
  name                 = "kumashare"
  storage_account_name = azurerm_storage_account.sa_kuma.name
  quota                = var.storage_quota
  access_tier          = "Hot"
}

resource "azurerm_service_plan" "service_plan_kuma" {
  name                = "service-plan-kuma"
  resource_group_name = azurerm_resource_group.rg_kuma.name
  location            = azurerm_resource_group.rg_kuma.location
  os_type             = "Linux"
  sku_name            = var.service_plan_sku
}

resource "azurerm_linux_web_app" "web_app_kuma" {
  name                = var.web_app_name
  resource_group_name = azurerm_resource_group.rg_kuma.name
  location            = azurerm_resource_group.rg_kuma.location
  service_plan_id     = azurerm_service_plan.service_plan_kuma.id
  https_only          = true

  site_config {
    http2_enabled       = true
    minimum_tls_version = "1.2"

    application_stack {
      docker_image_name   = var.docker_image
      docker_registry_url = "https://index.docker.io"
    }
  }

  app_settings = {
    "DOCKER_ENABLE_CI" = "true"
  }

  storage_account {
    access_key   = azurerm_storage_account.sa_kuma.primary_access_key
    account_name = azurerm_storage_account.sa_kuma.name
    name         = "webappstorage"
    type         = "AzureFiles"
    share_name   = azurerm_storage_share.share_kuma.name
    mount_path   = "/app/data"
  }
}

Die Variablen werden in einer separaten Datei definiert.

variable "resource_group_name" {
  type = string
}

variable "storage_account_name" {
  type = string
}

variable "web_app_name" {
  type = string
}

variable "location" {
  type    = string
  default = "westeurope"
}

variable "storage_quota" {
  type    = number
  default = 50
}

variable "service_plan_sku" {
  type    = string
  default = "B1"
}

variable "docker_image" {
  type    = string
  default = "louislam/uptime-kuma:latest"
}

In einer .tfvar-Datei werde die Werte für die Variablen gesetzt.

resource_group_name  = "rg-kuma"
storage_account_name = "<your-storage-account-name>"
web_app_name         = "<your-web-app-name>"

Nun können wir mit einem einzigen Befehl die gesamte Umgebung erzeugen und auch wieder löschen.

terraform apply -var-file="terraform.tfvar"
terraform destroy -var-file="terraform.tfvar"

Wie man von einer Codebasis mit vielen solchen Indirektionen zu einer einfacheren Variante kommt, die ein Vieles an überflüssiger Komplexität entfernt, soll der folgende Artikel zeigen.

Ausgangslage

Als Ausgangspunkt für unser Refactoring nehmen wir ein fiktives Beispiel eines Online-Shops an. Der Quellcode ist auf GitHub verfügbar, für jeden Refactoring-Schritt gibt es eine eigene Branch im Repository.

Quellcode auf GitHub, Branch steps/01-initial-state

Die Anwendung besteht aus einem Applikations-Projekt und einem für dazugehörige Tests. Der Aufbau folgt nicht streng einem Architektur-Style sondern soll lediglich zeigen, welche Komponenten man bei einem solchen System erwarten könnte. Zudem beschränken wir uns hier auf die Backend-Seite unseres Online-Shops. Die Ordner-Struktur sieht wie folgt aus:

├───Refactor.Application
│   ├───Controllers
│   ├───CQRS
│   │   ├───Handlers
│   │   └───Requests
│   ├───Data
│   ├───Models
│   ├───Repositories
│   │   ├───Implementations
│   │   └───Interfaces
│   └───Services
└───Refactor.Application.Test
    ├───Controllers
    ├───CQRS
    │   └───Handlers
    ├───Repositories
    └───Services

Die Anwendung ist in C# geschrieben und verwendet ASP.NET Controller. Business-Logik ist in Service-Klassen implementiert, Domain-Modelle liegen im Ordner Models. Der Zugriff auf eine Datenbank erfolgt mittels Repository-Pattern. Die POCO-Klassen für die Datenbank sind im Ordner Data untergebracht. Für die Kommunikation zwischen Controllern und Services kommt das CQRS (Command Query Responsibility Segregation)-Pattern zum Einsatz.

Zusammengehalten werden unsere einzelnen Komponenten mittels Dependency Injection.

Abstraktion

In der Softwareentwicklung arbeitet man gerne mit Abstraktion. Ihrem eigentlichen Ziel, Komplexität und Wartungsaufwand zu reduzieren, wird sie aber oft nicht gerecht. Zudem werden häufig Abstraktionsschichten eingezogen, ohne das diese einen konkreten Nutzen bringen, aber “man macht es halt so”. Dadurch leidet nicht nur die Lesbarkeit des Codes, auch das Laufzeitverhalten kann erst nach einer Analyse der Abhängigkeiten verstanden werden. Die Abstraktionen in unserem Beispiel mögen für eine kleine Demo vielleicht künstlich erzwungen wirken, sind in realen Projekten aber durchaus immer wieder anzutreffen.

Basisklassen und Marker-Interfaces

Unsere Model-Klassen erben allesamt von einer abstrakten Basisklasse bzw. Record ModelBase welche keinerlei Implementierung mitbringt. Die Datenbank-POCOs implementieren ein Interface IData, welches zumindest eine Property Id definiert.

// ./Models
public abstract record ModelBase;

public record Customer(
    Guid Id,
    string FirstName,
    string LastName,
    string Email) : ModelBase;

// ./Data
public interface IData
{
    Guid Id { get; }
}

public record Customer(
    Guid Id,
    string FirstName,
    string LastName,
    string Email,
    bool Active) : IData;

Repository-Interfaces

Im Ordner Repositories finden sich sowohl ein generisches Interface IRepository<T> als auch spezifische Interfaces je Datenbank-Tabelle bzw. POCO-Klasse, z.B. ICustomerRepository. Dazu eine abstrakte Basisklasse AbstractRepository<T>, welche nur eins-zu-eins die Methoden des generischen Interfaces implementiert.

public interface IRepository<T> where T : IData
{
    T Get(Guid id);
    IEnumerable<T> GetAll();
    void Add(T entity);
    ...
}

public abstract class AbstractRepository<T> : IRepository<T> where T : IData
{
    protected readonly IDatabase _database;

    protected AbstractRepository(IDatabase database) => _database = database;

    public abstract T Get(Guid id);
    public abstract IEnumerable<T> GetAll();
    public abstract void Add(T entity);
    ...
}

Die Abstraktion des konkreten Datenbank-Zugriffs über ein Interface IDatabase kann sinnvoll sei, da man beim Testen externe Systeme wie eine Datenbank durch ein Mock-Objekt ersetzen kann. Im Weiteren werden wir aber eine andere Lösung für dieses Problem finden.

Die konkreten Implementierungen der Repositories sehen dann zumeist nur so aus, dass die Aufrufe an die Basisklasse oder ein IDatabase-Objekt weitergeleitet werden.

public class CustomerRepository : AbstractRepository<Customer>, ICustomerRepository
{
    public CustomerRepository(IDatabase database) : base(database) { }

    public override void Add(Customer entity) => _database.Add(entity);
    public override void Update(Customer entity) => _database.Update(entity);
    ...
}

Services und CQRS

Unsere Services sind allesamt als Interfaces und genau einer Implementierung ausgeführt; der Bedarf, mehrere Implementierungen zu haben und evtl. sogar zur Laufzeit auszutauschen besteht nicht.

Das Beispiel eines ITaxService zeigt den inflationären Einsatz von Interfaces. Das Interface definiert nur eine einzelne Methode, diese hat keinerlei Abhängigkeiten ausser ihrer direkten Methoden-Parameter.

public interface ITaxService
{
    (decimal taxAmount, decimal grossPrice) CalculateTax(
        decimal netPrice, decimal taxRate);
}

public class TaxService : ITaxService
{
    public (decimal taxAmount, decimal grossPrice) CalculateTax(
        decimal netPrice, decimal taxRate)
    {
        var taxAmount = netPrice * taxRate / 100m;
        var grossPrice = netPrice + taxAmount;

        return (taxAmount, grossPrice);
    }
}

Tests

Wie sieht nun ein (Unit-)Test für solchen Code aus? Das Testen der Methode GetOrderItems() des OrderItemService zeigt, wie viel Setup-Code bereits jetzt notwendig ist, um die Abhängigkeiten zu mocken und mit Daten zu füttern. Im Falle des ITaxService-Interfaces wird sogar die Businesslogik im Mock-Objekt implementiert.

[Test]
public void Should_Return_OrderItems()
{
    // Arrange
    var orderId = Guid.NewGuid();

    var orderItem1 = new OrderItem(Guid.NewGuid(),
        orderId, Guid.NewGuid(), 2, 19.75m);
    var orderItem2 = new OrderItem(Guid.NewGuid(),
        orderId, Guid.NewGuid(), 3, 9.66m);
    var orderItemData = new List<OrderItem> { orderItem1, orderItem2 };

    var orderItemRepository = Substitute.For<IOrderItemRepository>();
    orderItemRepository.GetByOrderId(orderId).Returns(orderItemData);

    var taxService = Substitute.For<ITaxService>();

    taxService.CalculateTax(default, default)
        .ReturnsForAnyArgs(info =>
        {
            var netPrice = info.ArgAt<decimal>(0);
            var taxRate = info.ArgAt<decimal>(1);

            var taxAmount = netPrice * taxRate / 100m;
            var grossPrice = netPrice + taxAmount;

            return (taxAmount, grossPrice);
        });

    var sut = new OrderItemService(orderItemRepository, taxService);

    // Act
    var orderItems = sut.GetOrderItems(orderId);

    // Assert
    orderItems.Should().NotBeNullOrEmpty();
    orderItems.Should().HaveCount(2);

    var firstOrderItem = orderItems.First();
    firstOrderItem.Id.Should().Be(orderItem1.Id);
    firstOrderItem.TaxRate.Should().Be(19);
    firstOrderItem.GrossPrice.Should().Be(19.75m * 1.19m);
}

Wie man bereits mit geringem Aufwand zu erheblich weniger Setup-Code für Test kommen kann, zeigt Schritt 1 unseres Refactorings.

Code-Analyse

Die Exploration unsere Anwendung mittels Sonargraph zeigt, mit wie vielen Abhängigkeiten zwischen den einzelnen Klassen wir bereits jetzt zu tun haben.

Die Codebasis besteht zu diesem Zeitpunkt aus 917 Zeilen Quellcode in 53 Dateien und weist eine Average Component Dependency ACD von 5,3 auf.

Schritt 1: Test-Dummies

Im ersten Schritt nehmen wir uns der Test-Klassen an. Eine gute Test-Suite ist die Grundlage eines sicheren Refactorings, deshalb wollen wir hier beginnen.

Getreu dem Motto new is glue verlagern wir das Instanziieren von Testdaten aus den Testmethoden heraus in Dummies aus. Zu dem Thema Dummy-Factories existiert ein dedizierter Blog Post Einfaches Test-Setup mit Dummy-Factories, daher soll hier nur kurz auf Änderungen an unserem Beispiel-Code eingegangen werden.

Quellcode auf GitHub, Branch steps/02-introduce-dummies

Wir fügen eine Klasse DataDummies hinzu, welche uns das Instanziieren von Daten-Objekten abnimmt. Zudem definieren wir ein paar statische Instanzen von Customer-Objekten, die wir in unseren Tests verwenden können.

internal static class DataDummies
{
    public static Customer JohnDoe => Customer(
        new Guid("bfbffb19-cdd4-42ac-b536-606a16d03eae"), "John",
        "Doe", "john.doe@example.com");

    public static Customer JaneDoe => Customer(
        new Guid("95a6db4a-4635-4fb3-b7f6-c206ff7272f1"), "Jane",
        "Doe", "Jane.doe@example.com", false);

    public static Customer Customer(
        Guid? id = null, string firstName = "Peter", string lastName = "Parker",
        string email = "peter.parker@example.com", bool active = true)
    {
        return new Customer(id ?? Guid.NewGuid(),
            firstName, lastName, email, active);
    }

    ...
}

Für unsere Domain-Objekte verfahren wir ebenso. Hier können wir uns zunutze machen, dass POCO-Klassen und Domain-Modelle zumeist sehr ähnlich aufgebaut sind und wir die Daten-Objekte aus DataDummies verwenden können.

internal static class ModelDummies
{
    public static Customer JohnDoe => FromData(DataDummies.JohnDoe);
    public static Customer JaneDoe => FromData(DataDummies.JaneDoe);

    public static Customer FromData(Data.Customer data)
    {
        return Customer(id: data.Id, firstName: data.FirstName,
            lastName: data.LastName, email: data.Email);
    }

    ...
}

Unser Test-Setup wird damit schon etwas einfacher und vor allem resilienter gegenüber Änderungen an den Daten-Objekten, da wir diese nur noch an einer Stelle anpassen müssen.

[Test]
public void Should_Return_OrderItems()
{
    // Arrange
    var orderId = Guid.NewGuid();

    var orderItem1 = OrderItem(price: 19.75m);
    var orderItem2 = OrderItem(price: 9.66m);
    var orderItemData = Collection(orderItem1, orderItem2);

    var orderItemRepository = Substitute.For<IOrderItemRepository>();
    orderItemRepository.GetByOrderId(orderId).Returns(orderItemData);

    ...
}

Nach diesen Vorbereitungen können wir uns dem Refactoring des Produktivcodes zuwenden.

Schritt 2: Interfaces entfernen

Im zweiten Schritt wollen überflüssige Abstraktionen durch Interfaces und Basisklassen entfernen. Häufig wird damit argumentiert, dass Test-Code sich diese zunutze machen und Abhängigkeiten, die als Interfaces ausgeführt sind, einfach durch Mocks, Stubs oder Fakes ersetzen kann. Bei externen Abhängigkeiten, etwa zu Datenbanken oder Email-Servern, ist dies sicher richtig; für selbst geschaffene Abstraktionen führt es aber zumeist nur zu unnötiger Komplexität und hohem Aufwand für das Test-Setup. Test-Mocks sind aufwendig zu pflegen und müssen Internas der echten Implementierung kennen und diese nachbauen.

Unser erster Ansatzpunkt ist der TaxService. Die Methode CalculateTax() ist bereits eine pure Funktion. Daher können wir das Interface ITaxService löschen, die Klasse und die Methode static machen und diese einfach direkt aufrufen. Es ist keine Dependency-Injection notwendig und der Test-Mock fällt ebenfalls weg.

public static class TaxService
{
    public static (decimal taxAmount, decimal grossPrice) CalculateTax(
        decimal netPrice, decimal taxRate)
    {
        ...
    }
}

Der entsprechende Git-Commit zeigt uns 43 gelöschte Zeilen.

Wenden wir uns nun den Service-Klassen OrderService und OrderItemService zu. Von den per Constructor Injection bereitgestellten Abhängigkeiten (e.g. ICustomerRepository) benötigen wir nur einzelne Methoden oder gar nur den Rückgabewert einer Methode. Statt nun Repository-Klassen zu injizieren, übergeben wir Methoden-Pointer (Delegates) an die Service-Klassen. Dadurch entfallen die privaten Properties, die Klassen werden zustandslos und static und die Interfaces können entfernt werden.

Die Klasse OrderService hatte zuvor drei Abhängigkeiten.

public class OrderService : IOrderService
{
    private readonly ICustomerRepository _customerRepository;
    private readonly IOrderItemRepository _orderItemRepository;
    private readonly IOrderRepository _orderRepository;

    public OrderService(IOrderRepository orderRepository,
        ICustomerRepository customerRepository,
        IOrderItemRepository orderItemRepository)
    {
        _orderRepository = orderRepository;
        _customerRepository = customerRepository;
        _orderItemRepository = orderItemRepository;
    }

    public Order GetOrder(Guid id)
    {
        var orderData = _orderRepository.Get(id);
        return GetOrder(orderData);
    }

    private Order GetOrder(Data.Order orderData)
    {
        var customerData = _customerRepository.Get(orderData.CustomerId);
        var orderItemData = _orderItemRepository.GetByOrderId(orderData.Id);

        ...

        return orderModel;
    }
}

Nach dem Refactoring sieht die Klasse so aus:

public static class OrderService
{
    public static Order GetOrder(Guid id,
        Func<Guid, Data.Order> getOrder,
        Func<Guid, Customer> getCustomer,
        Func<Guid, IReadOnlyCollection<OrderItem>> getOrderItems)
    {
        var orderData = getOrder(id);
        var customerData = getCustomer(orderData.CustomerId);
        var orderItemData = getOrderItems(id);
        return GetOrder(orderData, customerData, orderItemData);
    }

    ...
}

Aufgerufen wird die Methode GetOrder() nun einfach, indem wir die entsprechenden Methoden der Repositories als Parameter übergeben.

var orders = OrderService.GetOrder(
    id: id,
    getOrder: _orderRepository.Get,
    getCustomer: _customerRepository.Get,
    getOrderItems: _orderItemRepository.GetByOrderId);

Unterscheiden sich die Signaturen der Methoden, können wir diese einfach per Lambda-Expression anpassen.

var orders = OrderService.GetOrder(
    id: id,
    getCustomer: id => _customerRepository.Get(id: id, activeOnly: true),
    ...

Die entsprechenden Unit-Tests vereinfachen sich ebenfalls; wir müssen keine Mock-Objekte mehr zusammenbauen, sondern müssen lediglich Methoden definieren. Als lokale Lambda-Expressions sind dies Einzeiler.

var getOrder = (Guid _) => DataDummies.Order(orderId, peterPan.Id);
var getCustomer = (Guid _) => peterPan;
var getByOrderId = (Guid _) => DataDummies.Collection(orderItem1, orderItem2);

// Act
var order = OrderService.GetOrder(orderId, getOrder, getCustomer, getByOrderId);

Alternativ kann man bei puren Funktionen anstatt einer Methode den Rückgabewert eben dieser als Parameter übergeben (Referenzielle Transparenz). Für Methoden, die Seiteneffekte haben (z.B. Datenbank-Update) oder große Datenmengen filtern, ist dies aber nicht immer sinnvoll.

var order = _orderRepository.Get(id);
var customer = _customerRepository.Get(order.CustomerId);
var orderItems = _orderItemRepository.GetByOrderId(id);

var orders = OrderService.GetOrder(order, customer, orderItems);

Dadurch, dass wir Abhängigkeiten nun nicht mehr per Dependency Injection in eine Klasse bringen, sondern per Methoden-Parameter übergeben, verschieben wir die Verantwortung für das Erzeugen und Verwalten der Abhängigkeiten an den aufrufenden Code.

Schritt 3: CQRS entfernen

Als nächstes entfernen wir das mittels MediatR umgesetzte CQRS-Pattern aus unserer Codebasis. Die Library ist großartig und CQRS ist ein mächtiges Werkzeug, wenn man tatsächlich den Bedarf hat, Commands und Queries zu trennen. In unserem Beispiel soll es aber zeigen, dass dies häufig nicht benötigt wird und vielleicht nur Premature Optimization ist, die nie zum Tragen kommt.

Statt den Quellcode, der Controller und Domain-Logik verbindet, über mehrere IRequest und IRequestHandler<> zu verteilen, fassen wir ihn in wenigen Integrations-Klassen zusammen.

Statt eines AddOrderHandler inkl. entsprechendem AddOrderRequest haben wir nun eine einzelne Methode, welche die benötigten Abhängigkeiten als Parameter übergeben bekommt und den Aufruf der Service-Klassen orchestriert.

public static class OrdersIntegration
{
    public static void AddOrder(Order order,
        ICustomerRepository customerRepository,
        IOrderItemRepository orderItemRepository,
        IOrderRepository orderRepository)
    {
        if (!order.Items.Any())
            throw new InvalidOperationException("Order must have at least one item.");

        var customerData = customerRepository.Get(order.Customer.Id);

        if (customerData.Active is false)
            throw new InvalidOperationException("Customer is not active.");

        foreach (var orderItem in order.Items)
        {
            var orderItemData = OrderItemService.AddOrderItem(orderItem, order);
            orderItemRepository.Add(orderItemData);
        }

        OrderService.AddOrder(order, orderRepository.Add);
    }

    ...
}

In einem weiteren Schritt können wir, wie zuvor für die Services, von dem injizieren von Repositories auf Methoden-Delegates umstellen. Dadurch kommen wir in die Lage, sämtliche IRepository-Interfaces entfernen zu können, da wir diese in unseren Tests nicht mehr substituieren müssen. Ein Git-Commit zeigt das exemplarisch für das IOrderRepository.

Schritt 4: Statische Repositories

Nachdem wir ein paar weitere abstrakte Basisklassen und Interfaces entfernt haben, schauen wir uns noch einmal die Repository-Klassen an. Sie weisen allesamt lediglich eine Abhängigkeit zu IDatabase auf. Die Umstellung von Constructor Injection auf Method Injection ist schnell gemacht.

- public class OrderRepository
+ public static class OrderRepository
{
-    private readonly IDatabase _database;
-    public OrderRepository(IDatabase database) => _database = database;

-    public IEnumerable<OrderData> GetOrdersByDate(
-       DateTime startDate, DateTime endDate)
-        => _database.GetAll<OrderData>()
-               .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate);


+    public static IEnumerable<OrderData> GetOrdersByDate(
+        DateTime startDate, DateTime endDate, IDatabase db)
+            => db.GetAll<OrderData>()
+                .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate);
     ...
}

Wenn wir auch hier noch einen Schritt weiter gehen und statt einer Instanz von IDatabase lediglich Delegates als Methoden-Parameter erwarten, können wir die Abhängigkeit von IDatabase ganz aus unseren Repositories entfernen.

public static class OrderRepository
{
-    public static IEnumerable<OrderData> GetOrdersByDate(
-       DateTime startDate, DateTime endDate, IDatabase db)
-        => db.GetAll<OrderData>()
-            .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate);

+    public static IEnumerable<OrderData> GetOrdersByDate(
+        DateTime startDate, DateTime endDate, 
+        Func<IEnumerable<OrderData>> getAll)
+        => getAll().Where(x => x.OrderDate >= startDate &&
+                               x.OrderDate <= endDate);

    ...
}

Alternativ kann es sich hier anbieten, anstatt der Methoden bereits die Rückgabewerte dieser an unsere Service-Methode zu übergeben. Damit sind sämtliche Seiteneffekte eliminiert und wir haben eine pure function.

public static IReadOnlyCollection<Order> GetOrdersByDate(
    DateTime startDate, DateTime endDate,
    IEnumerable<OrderData> allOrderData,
    IDictionary<Guid, CustomerData> customerData,
    ILookup<Guid, OrderItemData> orderItemData)
{
    return allOrderData
        .Where(x => x.OrderDate >= startDate && x.OrderDate <= endDate)
        .Select(order => GetOrder(order,
            customerData[order.CustomerId], orderItemData[order.Id]))
        .ToList();
}

Die aufrufende Methode ist nun für das zusammensammeln der Daten verantwortlich.

var allOrderData = db.GetAll<OrderData>();

var customerData = db.GetAll<CustomerData>()
    .ToDictionary(x => x.Id, x => x);

var orderData = db.GetAll<OrderItemData>()
    .ToLookup(x => x.OrderId);

var orders = OrderService.GetOrdersByDate(startDate, endDate,
    allOrderData, customerData, orderData);

Für externe Datenquellen wie Datenbank oder Dateien ist dieser Ansatz aufgrund des späten Filterns zumeist nicht geeignet, da er zu viele Daten lädt. Wir wollen ja nicht die gesamte Datenbank in den Speicher laden, nur um dann ein paar Datensätze zu verwenden. Für kleine Datenmengen oder Daten, die bereits im Arbeitsspeicher liegen, ist dies aber eine gute Möglichkeit, um die Komplexität zu reduzieren.

Ergebnis

Was haben wir nun mit den Refactoring-Schritten erreicht? Unsere Codebasis ist erheblich kleiner geworden, fast alle Interfaces konnten entfernt werden.

Der Dependency Graph zeigt deutlich weniger Linien. Die Anzahl der Codezeilen hat sich auf 715 (ca. 25 % weniger) reduziert, die Zahl der Dateien auf 34 (ca. 35 % weniger). Die Average Component Dependency ist von 5,3 auf 3,6 gesunken.

Neben den reinen Zahlen ist aber wichtiger, dass der Code nun einfacher zu verstehen und nachzuvollziehen ist. Man muss nicht mehr nach Interfaces und potenziellen Implementierungen suchen, um das Laufzeitverhalten nachvollziehen zu können.

Der gesamt Quellcode ist auf GitHub verfügbar.

Test-Daten

Für das Aufrufen von Methoden aus Tests heraus, müssen diese zumeist mit definierten Eingabeparametern befüttert werden. Je weiter unten in der Test-Pyramide wir uns befinden, desto synthetischer werden diese Daten sein. Die Struktur der Daten kann von einfachen primitiven Datentype wie Strings, Boolean- oder Zahlwerten bis hin zu komplexen Objektstrukturen reichen.

Sehen wir uns eine imaginäre E-Commerce-Software mit folgenden Daten-Klassen an. Die Beispiele sind in C# gehalten, lassen sich aber auf andere Programmiersprachen übertragen.

public record Address(Guid Id, string Street, string City,
  string State, string ZipCode);

public record Customer(Guid Id, string FirstName, string LastName,
  Address Address, string Email, bool Active);

public record Product(string Sku, string Name,
  string Description, decimal Price);

public record Order(string OrderNumber, DateTime OrderDate,
  Customer Customer, IEnumerable<OrderItem> Items);

public record OrderItem(Product Product, int Quantity, decimal Price);

Für eine Methode OrderService.PlaceOrder(..) könnte ein Unit-Test etwa so beginnen:

[Test]
public void Should_Place_Order()
{
    // Arrange
    var address = new Address(Guid.NewGuid(), "123 Main St",
      "Anytown", "TX", "12345");
    var customer = new Customer(Guid.NewGuid(), "John", "Doe", address,
      "john.doe@example.com", true);

    var product1 = new Product("P-001", "Product 1", "Product 1 Description", 9.99m);
    var product2 = new Product("P-002", "Product 2", "Product 2 Description", 19.99m);

    var orderItems = new[]
    {
        new OrderItem(product1, 1, product1.Price),
        new OrderItem(product2, 2, product2.Price)
    };
    var order = new Order("O-001", DateTime.UtcNow, customer, orderItems);

    // Act
    var sut = new OrderService();
    sut.PlaceOrder(order);

    // Assert
    //...
}

Bis wir aber an den Punkt kommen, unsere zu testende Methode mit den richtigen Parametern aufrufen zu können, müssen wir einige Zeilen an Setup-Code schreiben, nur um eine gültige Order zu erzeugen. Eine Order enthält einen Customer mit einer Address und eine Menge an OrderItems mit zugehörigen Products.

Dieser Code wird nicht nur sehr schnell redundant, sondern auch fehleranfällig. Wenn wir uns nun vorstellen, dass wir für jede Test-Methode eine neue Order erzeugen müssen, wird schnell klar, dass wir hier eine Menge Zeit verlieren können.

Ein weiterer Nachteil: Wenn sich an unseren Daten-Klassen etwas ändern, etwa weil ein Customer nun auch eine Telefonnummer haben muss, und wir Nicht-optionale Parameter hinzufügen, müssen wir die Constructor-Aufrufen in allen Testmethoden, die diese Daten-Instanzen erzeugen, anpassen.

Dummy-Factories

Abhilfe schafft das Anlegen von Dummy-Factories. Dies sind Klassen und Methoden, die uns nach einmaligem Schreiben in allen Tests zur Verfügung stehen und das Erzeugen von Testdaten erleichtern. Dazu wird für jede Daten-Klasse eine Dummy-Methode angelegt und wo möglich mit Default-Parametern ausgestattet. Diese können bei Bedarf in den Testmethoden für den jeweiligen Anwendungsfall passend überschrieben werden. Für verschachtelte Datenstrukturen können etwa Nullable reference types verwendet werden, welche bei Nicht-vorhandensein wiederum durch Dummies ersetzt werden.

public static class Dummies
{
    public static Address Address(
        Guid? id = null,
        string street = "123 Main St",
        string city = "Anytown",
        string state = "TX",
        string zipCode = "12345") =>
        new(id ?? Guid.NewGuid(), street, city, state, zipCode);

    public static Customer Customer(
        Guid? id = null,
        string firstName = "John",
        string lastName = "Doe",
        Address? address = null,
        string email = "john.doe@example.com",
        bool active = true) =>
        new(id ?? Guid.NewGuid(), firstName, lastName, 
          address ?? Address(), email, active);

    public static Product Product(
        string sku = "P-001",
        string name = "Product 1",
        string description = "Product 1 Description",
        decimal price = 9.99m) =>
        new(sku, name, description, price);
    
    // ...
}

Mit kleinen Hilfsmethoden kann man sich das Leben weiter erleichtern.

public static T[] Many<T>(params T[] items) => items.ToArray();

Die oben gezeigte Testmethode kann nun wie folgt aussehen:

using static Company.Webstore.Tests.Dummies;

[Test]
public void Should_Place_Order()
{
    // Arrange
    var orderItems = Many(
        OrderItem(),
        OrderItem(Product(sku: "P-002", price: 19.99m), 2));
    var order = Order(items: orderItems);

    // Act
    var sut = new OrderService();
    sut.PlaceOrder(order);

    // Assert
    //...
}

Durch das Verwenden eines using static Statements lassen sich die Dummy-Methode direkt aufrufen, ohne den Klassennamen voranstellen zu müssen.

Damit ist unser Test-Setup auf wenige relevante Zeilen reduziert.

Sollte sich nun etwas an unseren Daten-Klassen ändern, müssen wir nur noch die Dummy-Methode anpassen und die Testmethoden bleiben unberührt.

Alternativen

Zum generieren von mehr oder weniger zufälligen Test- oder Fake-Daten, existieren natürlich Libraries wie Bogus oder FsCheck. Hierbei gibt man natürlich etwas Kontrolle ab, das verwenden von Dummies ist wesentlich expliziter. Je nach Anwendungsfall kann das aber auch ein Vorteil sein und die zusätzliche Komplexität rechtfertigen.

Für HTTP-Services in Verbindung mit einem Reverse-Proxy bietet Sablier eine einfache Möglichkeit, Scale-to-Zero in der eigenen Infrastruktur umzusetzen.

Scale-to-Zero

Scale-to-Zero bezeichnet das vollständige Herunterskalieren von Workloads auf Null, so dass keine Ressourcen mehr verbraucht werden. Im Umfeld von Kubernetes existieren Lösungen wie Keda, die aber eher auf Event-basierte Anwendungsfälle abzielen und nicht primär für HTTP-Services geeignet sind. Das HTTP-Addon für Keda befindet sich aktuell im Beta-Stadium.

Das vollständige Herunterfahren von Anwendungen kann einen Vorteil bringen, wenn man sehr viele Services mit jeweils wenigen Aufrufen betreibt. Damit sinkt die Anzahl der zeitgleich laufenden Container und der Ressourcenverbrauch. Setzt man hier auf einen Cloud-Anbieter und zahlt pro Ressource oder Zeiteinheit, lassen sich so Kosten sparen.

Der Beispiel-Code für diesen Post findet sich auf Github: https://github.com/davull/demo-docker-traefik-sablier

Sablier und Traefik

Sablier ist eine leichtgewichtige Lösung, um HTTP-Services nach Bedarf zu starten und zu stoppen. Es unterstützt verschiedene Container-Provider, aktuell Docker, Docker Swarm und Kubernetes. Um auf Basis von eingehenden Anfragen die entsprechenden Container hoch- und runterzufahren, existieren Plugins für die Reverse-Proxies Traefik, Nginx und Caddy. Da Sablier als eine API definiert ist, kann es prinzipiell auch in andere Systeme integriert werden.

Quelle https://acouvreur.github.io/sablier/

Nachfolgend wird der Einsatz von Sablier mit Traefik und Docker beschrieben. Für andere Reverse-Proxies und Container-Provider erfolgt die Konfiguration aber analog.

Ausgangspunkt ist eine Traefik-Instanz und ein Workload, der über Sablier gesteuert werden soll. Die Definition der Services erfolgt mittels Docker Compose.

Das Konfigurationsfile docker-compose-traefik.yaml für Traefik enthält eine einzige Service-Beschreibung und ein Netzwerk:

version: "3"

services:
  traefik:
    container_name: traefik
    image: traefik:v2.10
    ports:
      - 80:80
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./traefik/traefik.yml:/etc/traefik/traefik.yml
      - ./traefik/dynamic_config/:/etc/traefik/dynamic_config/
      - ./traefik/log/:/etc/traefik/log/
    networks:
      - traefik
    ...
    
networks:
  traefik:
    name: traefik

Der Workload besteht aus drei Services (hier alle durch traefik/whoami-Images abgebildet), welche eine verteilte Anwendung simulieren sollen. Die Datei docker-compose-whoami.yaml hat folgenden Inhalt:

version: "3"

services:
  whoami:
    container_name: whoami
    image: traefik/whoami
    networks:
      - traefik
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami-router.rule=Host(`whoami.example.com`)"
      - "traefik.http.routers.whoami-router.entrypoints=web"

  whoami-nginx:
    container_name: nginx
    image: traefik/whoami
    networks:
      - traefik

  whoami-mariadb:
    container_name: mariadb
    image: traefik/whoami
    networks:
      - traefik

networks:
  traefik:
    name: traefik
    external: true

Sablier einrichten

Sablier selber kann als Docker-Container oder als Binary ausgeführt werden. Wir verwenden hier den Container und erweitern die Datei docker-compose-traefik.yaml um eine weitere Service-Beschreibung:

sablier:
  container_name: traefik-sablier
  image: acouvreur/sablier:1.3.0
  command:
    - start
    - --provider.name=docker
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  networks:
    - traefik

Sablier benötigt Zugriff auf den Docker-Host-Service, daher mounten wir den Pfad /var/run/docker.sock an die gleiche Stelle im Container. Über den Parameter --provider.name geben wir den verwendeten Container-Provider docker an.

Traefik-Plugin hinzufügen

Damit Traefik von Sablier erfährt und mit der Sablier-API kommunizieren kann, wird das Traefik-Plugin für Sablier konfiguriert. Dazu wird die Konfigurationsdatei traefik.yml um folgende Zeilen erweitert:

experimental:
  plugins:
    sablier:
      moduleName: "github.com/acouvreur/sablier"
      version: "v1.3.0"

Konfiguration vorbereiten

Damit Sablier nun die Container unseres Workloads starten und stoppen kann, müssen zwei Anpassungen vorgenommen werden.

Da Traefik keinen Zugriff mehr auf Container-Labels hat, wenn ein Container nicht mehr läuft (auf Null skaliert wurde), müssen wir zunächst die Konfiguration des Workload-Services von Container-Labels auf einen Konfigurations-Datei umstellen. Dies ist natürlich nur notwendig, wenn für die Traefik-Konfiguration auch Container-Labels genutzt wurden.

Die Labels aus dem Workload-Service werden in eine Datei dynamic_config/whoami.yaml übertragen.

Aus

# docker-compose-whoami.yaml
...
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.whoami-router.rule=Host(`whoami.example.com`)"
  - "traefik.http.routers.whoami-router.entrypoints=web"

wird

# dynamic_config/whoami.yaml
http:
  services:
    whoami-service:
      loadBalancer:
        servers:
          - url: http://whoami:80

  routers:
    whoami-router:
      rule: "Host(`whoami.example.com`)"
      service: whoami-service
      entryPoints:
        - web

Anschliessend können wir mit dem Einbringen von Sablier fortfahren.

Sablier konfigurieren

Sablier kennt zwei Arten (sogenannte Stategien), auf eine eingehende HTTP-Anfrage zu reagieren, wenn der entsprechende Container nicht läuft:

• Dynamic Strategy: Sablier liefert eine Status-Webseite aus, die dem Benutzer anzeigt, dass sein angefragter Service gerade gestartet wird und leitet ihn nach dem Start automatisch weiter bzw. lädt die Seite neu.
• Blocking Strategy: Sablier blockiert die Anfrage solange, bis der dahinterliegende Container gestartet ist und liefert dann die Antwort aus.

Die Blocking Strategy eignet sich vor allem für APIs, so dass der aufrufende Client beim ersten Zugriff auf einen heruntergefahrenen Service lediglich eine längere Antwortzeit erhält, nicht aber mit Retries und Redirects umgehen muss.

Dynamic Strategy

Um unseren Workload mit der Dynamic Strategy zu konfigurieren, legen wir zunächst eine Traefik-Middelware für Sablier an. Diese wird in der Datei dynamic_config/sablier.yaml definiert:

http:
  middlewares:
    sablier-dynamic:
      plugin:
        sablier:
          sablierUrl: http://sablier:10000
          sessionDuration: 1m
          names: whoami,nginx,mariadb
          dynamic:
            displayName: whoami
            refreshFrequency: 1s
            showDetails: true
            theme: shuffle

sablierUrl zeigt auf unseren Sablier-Container, welchen wir in der Datei docker-compose-traefik.yaml definiert haben, Port 10.000 ist der Standardport.

Der Parameter sessionDuration gibt an, wie lange ein Container gestartet bleiben soll, nachdem der letzte Zugriff auf ihn erfolgt ist. Danach wird der Container wieder heruntergefahren.

Mit names geben wir die Namen der Container an, die Sablier steuern soll. Diese Namen müssen mit den Namen der Container in unserem docker-compose-whoami.yaml-File übereinstimmen (Parameter container_name).

Unterhalb des Keys dynamic wird das Verhalten der Dynamic Strategy konfiguriert. Wir können einen Anzeigenamen (displayName) für die Statusseite angeben, die Aktualisierungsrate (refreshFrequency) der Statusseite, ob Details (showDetails) angezeigt werden sollen und welches Theme (theme) verwendet werden soll. Themes stehen mehrere zur Auswahl, es können aber auch eigene Themes definiert werden.

Nun konfigurieren wir unseren Workload so, dass er die Sablier-Middleware auch nutzt. In der Datei dynamic_config/whoami.yaml ändern wir die Definition des whoami-Routers ab und fügen die Middleware hinzu:

http:
  ...
  routers:
    whoami-router:
      rule: "Host(`whoami.example.com`)"
      service: whoami-service
      entryPoints:
        - web
      middlewares:
        - sablier-dynamic@file

Damit ist Sablier bereit, unseren Request entgegenzunehmen und den dahinterliegenden Container für uns zu starten und nach einer Minute Leerlauf wieder herunterzufahren.

Ein Hinweis zur Dynamic Strategy: Der Safari Browser auf iOS-Devices zeigt beim ersten Zugriff leider nicht die Status-Page an sondern liefert einen This side can't be reached-Fehler.

Blocking Strategy

Die Blocking Strategy wird analog zur Dynamic Strategy konfiguriert. Wir legen zunächst eine weitere Traefik-Middelware für Sablier an. Diese wird in ebenfalls der Datei dynamic_config/sablier.yaml definiert:

http:
  middlewares:
    sablier-dynamic:
      ...

    sablier-blocking:
      plugin:
        sablier:
          sablierUrl: http://sablier:10000
          sessionDuration: 1m
          names: whoami
          blocking:
            defaultTimeout: 10s

defaultTimeout gibt an, wie lange auf das Starten des Ziel-Containers gewartet werden soll, bevor die Anfrage abgebrochen wird.

In der Datei dynamic_config/whoami.yaml nutzen wir die neue Middleware:

http:
  ...
  routers:
    whoami-router:
      ...
      middlewares:
        - sablier-blocking@file

Wenn wir unseren Workload nun mit der Blocking Strategy aufrufen, erhalten wir beim ersten Zugriff eine längere Antwortzeit, da Sablier den dahinterliegenden Container erst starten muss.

Fazit

Sablier bietet eine einfache Möglichkeit, Scale-to-Zero für HTTP-Services umzusetzen. Wenn man sich einmal die notwendigen Informationen aus den verschiedenen Dokumentationen für Sablier, Traefik und dem Traefik-Plugin zusammengesucht hat, ist die Konfiguration nicht komplex. Allerdings ist die Dokumentation mitunter recht dünn und man trifft immer mal wieder auf leere Seiten.

Der Code der Beispiele mit Commits zu den einzelnen Konfigurations-Schritten findet sich auf Github https://github.com/davull/demo-docker-traefik-sablier.

Nutzt man zur Provisionierung seiner Cloud-Infrastruktur Infrastructure-as-Code Tools wie Terraform, kann man die DNS-Konfiguration natürlich auch darüber steuern. Allerdings ist man damit bei der Auswahl des DNS-Providers auf die großen Hyperscaler beschränkt.

Einfacher und mit weniger Konfigurationsaufwand erlaubt es DNSControl, die DNS-Konfiguration für dutzende große und kleine Provider als Javascript-Code zu definieren. Dadurch lässt sich die DNS-Umgebung automatisiert und reproduzierbar aufsetzen und verwalten. Die Konfiguration ist versioniert in einem Git-Repository abgelegt und kann einem Code-Review unterzogen werden, was das Vorgehen perfekt in die DevOps-Toolchain integriert.

Installation

Die Installation von DNSControl erfolgt über einen Paket-Manager wie brew oder einfach als Download des Binaries von der Github-Seite des Projekts. Das in Go geschrieben Program ist für Windows, Linux und MacOS verfügbar. Darüber hinaus existiert ein fertiges Docker-Image.

Konfiguration

DNSControl kennt DNS-Registrars und DNS-Service-Provider (DSP). Bei einem Registrar lassen sich neue Domains registrieren und die zuständigen Nameserver festlegen. Ein DSP verwaltet die DNS-Zonen und bedient DNS-Anfragen. Häufig dient ein Registrar auch zugleich als DSP. Die Konfiguration muss dennoch für beide Entitäten erfolgen.

Credentials hinterlegen

In der Datei creds.json werden die genutzten Provider und Registrars hinterlegt. Die meisten Provider benötigen Zugangsdaten in Form eines API-Key oder Ähnlichem, die genaue Syntax lässt sich der Dokumentation des jeweiligen Providers entnehmen. Einigen Provider lassen sich nur als DSP nutzen, andere nur als Registrar. Zum Erzeugen eines lokalen Zone-Files für eine BIND-Konfiguration genügt die Angabe des Typs BIND. Nutzt man keinen Registrar, kann man den Typ NONE verwenden.

Um die Zugangsdaten nicht im Klartext in der Konfigurationsdatei zu hinterlegen, kann man hier Umgebungsvariablen nutzen. Diese werden in der Form $NAME in der Konfigurationsdatei referenziert.

Das folgende Beispiel konfiguriert BIND, einen Dummy-Eintrag und Hetzner als Provider.

{
    "local": {
        "TYPE": "BIND"
    },
    "none": {
        "TYPE": "NONE"
    },
    "hetzner": {
        "TYPE": "HETZNER",
        "api_key": "$DNSCONTROL_HETZNER_API_KEY"
    }
}

Ob die Konfiguration korrekt ist, kann DNSControl mittels check-creds prüfen. Über den Command get-zones lassen sich die DNS-Zonen, die beim DNS-Provider bereits hinterlegt sind, ausgeben. Als Formate stehen unter anderem tsv (tab separated value) und das BIND-Format zone zur Verfügung. nameonly zeigt nur die Namen der Zonen an.

# Check credentials
dnscontrol check-creds hetzner

# Get all zones from provider
dnscontrol get-zones --format=nameonly hetzner - all

DNS-Zonen konfigurieren

Die Konfiguration der DNS-Zonen erfolgt per Javascript-Code, standardmäßig in der Datei dnsconfig.js. Dadurch ist man sehr flexibel was wiederkehrende Einstellungen wie DNS- oder Mail-Server angeht.

Über die Funktionen NewRegistrar() und NewDnsProvider() liesst man die konfigurierten Provider aus der creds.json Datei ein, die Einträge identifiziert man über den Namen.

Die Funktion D() definiert eine DNS-Zone. Als Parameter werden der Name der Zone, der Registrar, der DSP und eine Liste von DNS-Einträge übergeben. Für die unterschiedlichen Typen von Einträgen stehen jeweils Funktionen, sogenannte Domain Modifiers bereit, etwa A() und AAAA() für A- bzw. AAAA-Records.

var REG = NewRegistrar("none");;
var DNS = NewDnsProvider("hetzner");;

var HETZNER_NAMESERVER_RECORDS = [
    NAMESERVER("helium.ns.hetzner.de."),
    NAMESERVER("hydrogen.ns.hetzner.com."),
    NAMESERVER("oxygen.ns.hetzner.com.")
];

D("production-ready.de", REG, DnsProvider(DNS),
    A("@", "116.203.23.216"),
    A("www", "116.203.23.216"),
    AAAA("@", "2a01:4f8:c0c:bf6a::1"),
    MX("@", 10, "mail.example.com."),
    HETZNER_NAMESERVER_RECORDS
);

Zur Konstruktion von komplexeren Records stehen Builder-Funktionen bereit. Das Resultat kann einfach in die Liste der DNS-Einträge aufgenommen werden.

var CAA = CAA_BUILDER({
    label: "@",
    issue: ["letsencrypt.org"],
    iodef: "mailto:administrator@example.com",
    iodef_critical: true,
    issuewild: "none"
});

var DMARC = DMARC_BUILDER({
    policy: "none",
    subdomainPolicy: "none",
    rua: ["mailto:postmaster@example.de"],
    ruf: ["mailto:postmaster@example.de"],
    reportInterval: "7d"
});

D("example.com", REG, DnsProvider(DNS),
    A("@", "116.203.23.216"),
    ...
    CAA,
    DMARC
);

Hat man mehrere Domains zu verwalten, bietet es sich an, die Konfiguration auf mehrere Dateien aufzuteilen. Diese können in der Hauptdatei dnsconfig.js importiert werden.

require("domains/production-ready.de.js");

Vorhandene DNS-Zonen importieren

Möchte man bereits vorhandene DNS-Zonen in DNSControl überführen, kann man sich etwas Tipparbeit sparen, indem man get-zones mit dem Output-Format js nutzt und den Inhalt mittels --out [file].js in eine Datei schreiben lässt. Den generierten Code kann man nun als Ausgangspunkt für die eigene Konfiguration nutzen.

> dnscontrol get-zones --format js --out import.js hetzner - production-ready.de

var DSP_HETZNER = NewDnsProvider("hetzner");
var REG_CHANGEME = NewRegistrar("none");
D("production-ready.de", REG_CHANGEME,
        DnsProvider(DSP_HETZNER),
        DefaultTTL(3600),
        //NAMESERVER('oxygen.ns.hetzner.com.'),
        //NAMESERVER('hydrogen.ns.hetzner.com.'),
        //NAMESERVER('helium.ns.hetzner.de.'),
        A('@', '116.203.23.216'),
        A('www', '116.203.23.216'),
        ...
)

Type-Checking

Um in seinen Javascript-Dateien ein Type-Checking und Intellisense ala TypeScript zu erhalten, bietet DNSControl die nette Möglichkeit, ein TypeScript Declaration File zu generieren.

dnscontrol write-types

Am Anfang der dnsconfig.js referenziert man die Datei.

// @ts-check
/// <reference path="types-dnscontrol.d.ts" />

...

Änderungen prüfen und anwenden

Zur Validierung der Konfiguration bietet DNSControl den Befehl check. Dieser prüft die Javascript-Dateien auf Fehler, greift aber noch auf keinen DNS-Provider zu. Der Befehl preview vergleicht die aktuelle Konfiguration mit dem Stand der DNS-Zonen beim Provider und zeigt die potenziellen Änderungen an. Im folgenden Beispiel wird ein CNAME-Record hinzugefügt und ein A-Record geändert.

# Check and validate dnsconfig.js
> dnscontrol check
No errors.

# Preview changes
> dnscontrol preview
******************** Domain: production-ready.de
2 corrections (hetzner)
#1: Batch creation of records:
   + CREATE CNAME www2.production-ready.de www.production-ready.de. ttl=3600
#2: Batch modification of records:
   ± MODIFY A production-ready.de: (116.203.23.216 ttl=3600) -> (192.168.0.1 ttl=3600)
Done. 2 corrections.

Entsprechen die Änderungen dem erwarteten Ergebnis, kann man sie mittels push anwenden.

> dnscontrol push

2 corrections (hetzner)
#1: Batch creation of records:
   + CREATE CNAME www2.production-ready.de www.production-ready.de. ttl=3600
SUCCESS!
#2: Batch modification of records:
   ± MODIFY A production-ready.de: (116.203.23.216 ttl=3600) -> (192.168.0.1 ttl=3600)
SUCCESS!
Done. 2 corrections.

Damit ist man in der Lage, eine gesamte DNS-Landschaft mit einem Infrastructure-as-Code-Ansatz zuverlässig und nachvollziehbar zu verwalten.

Azure DevOps Pipeline

Um Änderungen an der DNS-Konfiguration nun nicht lokal ausführen zu müssen, bietet es sich an, eine Build-Pipeline zu erstellen. Diese kann auch zum Validieren von Pull-Requests mit DSN-Änderungen genutzt werden. Der hier gezeigte Code nutzt Azure DevOps, für andere CI/CD-Systeme sollte sich aber ein ähnlicher Ansatz finden lassen.

Hat man DNSControl auf seinem Build-Agent nicht installiert, z.B. weil man Hosted Agents von Microsoft oder eigene Docker-Basierte Agents nutzt, kann man dies mit einem einfachen CmdLine-Task erledigen. Ordner erzeugen, Datei herunterladen und entpacken und das Binary ausführbar machen.

- task: CmdLine@2
  displayName: "Install DNSControl"
  inputs:
      script: |
        mkdir -p $(Agent.TempDirectory)/bin
        cd $(Agent.TempDirectory)/bin
        wget -q https://github.com/StackExchange/dnscontrol/releases/download/v4.1.1/dnscontrol_4.1.1_linux_amd64.tar.gz -O dnscontrol.tar.gz
        tar -xf dnscontrol.tar.gz dnscontrol
        chmod +x dnscontrol

Anschließend kann man die Konfiguration validieren und die Änderungen anzeigen lassen. Den API-Key für den Provider kann man als Secret-Variable in der Pipeline-Konfiguration hinterlegen oder etwa aus einem Azure KeyVault beziehen. Bei der Verwendung einer Variable ist das explizite Mapping auf eine Umgebungsvariable wichtig, ansonsten ist der API-Key im Script nicht verfügbar.

- task: CmdLine@2
  displayName: "Run DNSControl check"
  inputs: 
    script: $(Agent.TempDirectory)/bin/dnscontrol check

- task: CmdLine@2
  displayName: "Run DNSControl preview"
  inputs: 
    script: $(Agent.TempDirectory)/bin/dnscontrol preview
  env:
    DNSCONTROL_HETZNER_API_KEY: $(DNSCONTROL_HETZNER_API_KEY)

Entsprechen die Änderungen dem gewünschten Ergebnis, kann man diese in einem Deployment-Step anwenden.

jobs:
  - deployment: 
    displayName: "Apply DNS Update"
    environment: HETZNER_DNS_PROD
    strategy:
      runOnce:
        deploy:
          steps:
            - task: CmdLine@2
              displayName: "Run DNSControl push"
              inputs: 
                script: $(Agent.TempDirectory)/bin/dnscontrol push
              env:
                DNSCONTROL_HETZNER_API_KEY: $(DNSCONTROL_HETZNER_API_KEY)

legacy code is code without tests

– Michael Feathers

Neben den verbreiteten Ansätzen von Example-based testing oder Snapshot testing gibt es noch weitere Möglichkeiten, die uns helfen, die Korrektheit unseres Codes zu überprüfen. Einer dieser Ansätze ist Property-based testing.

Property-based testing prüft nicht einzelne Werte auf Übereinstimmung, sondern zielt auf die Verifikation von Eigenschaften ab, die unsere Implementierung aufweisen müssen. So ist für die mathematische Addition die Kommutativität eine Eigenschaft, die wir überprüfen können, ohne uns konkrete Zahlen anzuschauen. Für die Addition zweier Zahlen a und b gilt immer:

a + b = b + a

Property-based testing

Property testing oder Property-based testing (PBT) ist ein Testverfahren, dass sich in der funktionalen Programmierung etabliert hat, etwa durch das Haskell-Package QuickCheck. Prädestiniert ist es für Problemstellungen, die wesentlich einfacher zu verifizieren als zu lösen sind. Aber auch beim Testen von alltäglicheren Problemen kann es gute Dienste leisten.

Beim Property-based testing definiert man Eigenschaften, die der zu testende Code für eine Menge von Eingabedaten erfüllen muss. Eine solche Eigenschaft ist dabei nicht wie eine Property, eine Klassen-Eigenschaft, in C# zu verstehen.

Die Eigenschaft Kommutativität der mathematischen Addition lässt sich in C# als Funktion beschreiben.

Func<int, int, bool> commutativity = (int a, int b) => a + b == b + a;

Die Definition der Addition besagt, dass das Kommutativgesetz für sämtliche Kombinationen von a und b gilt, unsere Funktion commutativity also für alle Integer-Werte true zurück liefern muss.

Wenn wir unsere eigene Addition-Funktion implementieren, können wir diese Eigenschaft nutzen, um die Korrektheit unserer Implementierung zu überprüfen.

Func<int, int, bool> commutativity = (int a, int b) 
    => MathOperations.Add(a, b) == MathOperations.Add(b, a);

Example-based testing

Ein naiver Ansatz, die Korrektheit unserer Addition-Funktion zu testen, ist es, die Funktion mit ein paar Beispiel-Werten aufzurufen und die Rückgabewerte zu überprüfen, hier mittels NUnit.

[TestCase(0, 0)]
[TestCase(1, 2)]
[TestCase(999, 9999)]
public void TestCommutativity_WithExamples(int a, int b)
{
    var left = MathOperations.Add(a, b);
    var right = MathOperations.Add(b, a);

    Assert.AreEqual(left, right);
}

Da uns die konkreten Werte von a und b aber gar nicht interessieren, können wir sie auch zufällig generieren lassen. Dies können wir für beliebig viele Kombinationen aus a und b machen, hier sind es 1.000 Durchläufe. Damit haben wir statt der drei konkreten Werte nun 1.000 zufällig generierte Werte getestet und können uns bereits ein Stück sicherer sein, dass unsere Addition-Funktion korrekt arbeitet.

[Test]
public void TestCommutativity_WithRandomValues()
{
    for (var i = 0; i < 1_000; i++)
    {
        var a = Random.Shared.Next(-999, 999);
        var b = Random.Shared.Next(-123, 321);

        var left = MathOperations.Add(a, b);
        var right = MathOperations.Add(b, a);

        Assert.AreEqual(left, right);
    }
}

Allerdings bringt dieses Vorgehen auch ein paar Nachteile mit sich: Offensichtlich ist, dass es mehr Code bedarf und unser Testfall unübersichtlicher wird. Zudem sind die generierten Werte willkürlich gewählt und decken vielleicht nicht den gesamten Wertebereich ab. Ein größeres Problem ist aber, dass wir bei einem Fehler nicht wissen, mit welchen Eingabewerten der Fehler aufgetreten ist, da sie bei jedem Durchlauf zufällig generiert werden.

FsCheck

Die in F# geschriebene Bibliothek FsCheck schafft hier Abhilfe und lässt sich auch in C# verwenden. Die gute Dokumentation verwendet zumeist F#-Syntax aber zeigt auch Beispiele in C#.

Sie bietet Funktionen, um uns das Testen von Eigenschaften zu erleichtern. Ein Test in FsCheck besteht im Grunde aus folgenden drei Teilen:

> for all (x, y, ..)
> such as precondition(x, y, ...) holds 
> property(x, y, ...) is satisfied

So können wir die Eigenschaft Kommutativität mit FsCheck wie folgt testen.

[Test]
public void TestCommutativity()
{
    var property = (int x, int y)
        => MathOperations.Add(x, y) == MathOperations.Add(y, x);

    Prop.ForAll(
            Arb.From<int>(), // Parameter x
            Arb.From<int>(), // Parameter y
            property)
        .QuickCheckThrowOnFailure();
}

Noch einfacher wird es, wenn wir uns der Erweiterung FsCheck.NUnit bedienen (für XUnit existiert äquivalent FsCheck.Xunit). Anstatt [Test] bzw. [Fact] annotieren wir unsere Testmethode mit [Property] und können die Eigenschaften direkt als Parameter übergeben. FsCheck generiert automatisch Eingabewerte des entsprechenden Typs.

[Property]
public bool TestCommutativity(int x, int y)
{
    return MathOperations.Add(x, y) == MathOperations.Add(y, x);
}

Möchten wir etwas über die Verteilung der generierten Eingabewerte erfahren, können wir sie nach bestimmten Bedingungen klassifizieren. Durch den Aufruf von Classify() erhalten wir einen Wert vom Typ Property, so dass wir den Rückgabewert der Testmethode entsprechend anpassen müssen.

[Property]
public Property TestCommutativity_WithClassification(int x, int y)
{
    var property = MathOperations.Add(x, y) == MathOperations.Add(y, x);

    return property
        .Classify(x == 0, "x == 0")
        .Classify(x > 0, "x > 0")
        .Classify(x < 0, "x < 0");
}

Die entsprechende Ausgabe liefert in etwa folgendes Ergebnis:

Ok, passed 100 tests.
50% x > 0.
46% x < 0.
4% x == 0.

Möchte man zu jedem einzelnen Testcase eine Ausgabe haben, hilft die Collect()-Methode.

[Property]
public Property TestCommutativity_WithCollect(int x, int y)
{
    var property = MathOperations.Add(x, y) == MathOperations.Add(y, x);

    return property
        .Collect($"x: {x}, y: {y}");
}

Die Ausgabe liefert für jede Kombination eine Zeile inkl. Verteilung.

Ok, passed 100 tests.
2% "x: 5, y: 9".
2% "x: 0, y: 0".
2% "x: -16, y: -6".
1% "x: 9, y: 32".
1% "x: 9, y: -26".
...

Bedingungen

Kommen für einen bestimmten Testfall nicht alle Werte des Datentyps eines Eingangsparameters in Frage, können wir mittels When() eine Vorbedingung definieren. Um bei der Prüfung der Division nicht durch 0 zu teilen, schließen wir diesen Fall aus.

[Property]
public Property TestDivide(int x, int y)
{
    var property = () => MathOperations.Divide(x * y, y) == x;
    return property.When(y != 0);
}

Wichtig hierbei: Die Definition der property ist als Methode ausgeführt, um eine lazy evaluation durch FsCheck zu ermöglichen.

Generator, Shrinker, Arbitrary

Um passende Testdaten zu generieren, nutzt FsCheck Generators, Shrinker and Arbitraries. Die Klasse Gen bietet mit den drei Funktionen Choose(), Constant() und OneOf() die Basis für die Generierung von Werten. Über die Methoden Select() und Where() können die Werte transformiert und gefiltert werden.

// Generiert eine Liste von Zahlen zwischen 0 und 100, die durch 2 teilbar sind
var generator = Gen.Choose(0, 100)
    .Where(i => i % 2 == 0);

// Wählt zufällig einen der beiden Werte "ja" oder "nein" aus
var generator = Gen.OneOf(
        Gen.Constant(true),
        Gen.Constant(false))
    .Select(b => b ? "ja" : "nein");

Über die Methode Sample() liefert ein Generator eine Liste von konkreten Werten. Der erste Parameter size wirkt sich je nach Generator unterschiedliche aus, z.B. kann er den Wertebereich bestimmen. Im Fall von Gen.Choose() hat er keinen Effekt. Der zweite Parameter numberOfSamples legt die Anzahl der Elemente in der generierten Liste fest.

var sample = Gen.Choose(0, 100).Sample(0, 10);
// 22, 6, 16, 8, 27, 22, 14, 49, 42, 99

Shrinker dienen dazu, um Fehler einfacher zu finden. Sie versuchen für einen fehlgeschlagenen Testlauf den Wert zu finden, ab welchem die zu testende Property nicht mehr gilt. Der folgende Test schlägt für jeden Wert >= 20 fehl, mittels Shrinking kann FsCheck den ersten fehlschlagenden Wert 20 ausmachen.

[Property]
public bool Test_Shrink(PositiveInt value)
{
    return value.Item < 20;
}

Ausgabe:

Falsifiable, after 25 tests (2 shrinks) (StdGen (195734675,297194399)):
Original:
PositiveInt 24
Shrunk:
PositiveInt 20

Arbitraries kombinieren Generators und Shrinker und dienen als Eingabe für Property-Tests. Die Klasse Arb definiert eine Reihe von Standardimplementierungen für unterschiedliche Datentypen. Auch Generators für komplexe Typen lassen sich über sie erzeugen.

var arbitrary1 = Arb.Default.PositiveInt();
var arbitrary2 = Arb.Default.DateTime();
var arbitrary3 = Arb.Default.IPv4Address();

var arbitrary4 = Arb.From<int>()
    .Filter(i => i % 2 == 0);

// --- 

Gen<Point> generator = Arb.Generate<Point>();

// --- 

Gen<Point> generator = from x in Arb.Default.PositiveInt().Generator
                       from y in Arb.Default.NegativeInt().Generator
                       select new Point(x.Item, y.Item);

Über Eigenschaften des Property-Attributs lässt sich die Verteilung der Werte steuern.

[Property(StartSize = 0, EndSize = 10)]
public Property Test_Distribution(int value)
{
    var property = () => true;

    return property.Collect($"value: {value}");
}

Die Werte in der Mitte des Wertebereichs (hier 0, weil positive wie negative Zahlen generiert werden) werden häufiger generiert als die Werte am Rand. Für welche konkreten Werte StartSize und EndSize stehen, hängt vom Generator ab.

Ok, passed 100 tests.
18% "value: 0".
13% "value: 1".
9% "value: 2".
8% "value: -2".
7% "value: -4".
7% "value: -1".
5% "value: 5".
5% "value: 3".
5% "value: -8".
5% "value: -6".
4% "value: 4".
3% "value: 7".
2% "value: 9".
2% "value: 8".
2% "value: -7".
1% "value: 6".
1% "value: -9".
1% "value: -5".
1% "value: -3".
1% "value: -10".

Arguments exhausted after X tests

FsCheck führt standardmäßig 100 Testdurchläufe aus. Über die Eigenschaft MaxTest lässt sich die Anzahl der Durchläufe steuern. Schränkt man die validen Optionen zu sehr ein, kann es passieren, dass FsCheck keine Werte mehr generieren kann und eine Exception geworfen. Hierdurch wird vermieden, dass die Laufzeit für einzelnen Tests zu stark ansteigt.

[Property(MaxTest = 100)]
public Property Test_Exhausted(int value)
{
    var property = () => true;

    return property
        .When(value % 15 == 0);
}

Der Test schlägt mit einer Meldung fehl:

Exhausted: Arguments exhausted after 61 tests.

Nun hat man die Möglichkeit, die Anzahl der Testdurchläufe zu reduzieren. Allerdings sollte man sich auch überlegen, ob der Bedingung den gültigen Wertebereich nicht zu sehr einschränken muss. Im Beispiel ist ein int-Wert kein gut gewählter Datentyp.

Beispiel Addition

Um das bereits genannten Beispiel der Addition zu vervollständigen, testen wir nun noch die weiteren Eigenschaften Assoziativität, Identität und Inverse.

[Property]
public bool TestCommutativity(int x, int y)
{
    // x + y == y + x
    return MathOperations.Add(x, y) == MathOperations.Add(y, x);
}

[Property]
public bool TestAssociativity(int x, int y, int z)
{
    // x + (y + z) == (x + y) + z
    return MathOperations.Add(x, MathOperations.Add(y, z)) ==
           MathOperations.Add(MathOperations.Add(x, y), z);
}

[Property]
public bool TestAdditiveIdentity(int x)
{
    // x + 0 == x
    return MathOperations.Add(x, 0) == x;
}

[Property]
public bool TestAdditiveInverse(int x)
{
    // x + (-x) == 0
    return MathOperations.Add(x, -x) == 0;
}

FizzBuzz Kata

Bei dem bekannten FizzBuzz-Kata geht es darum, für eine positive Zahl einen der folgenden Strings zu erzeugen:

• “Fizz”, wenn die Zahl durch 3 teilbar ist
• “Buzz”, wenn die Zahl durch 5 teilbar ist
• “FizzBuzz”, wenn die Zahl durch 3 und 5 teilbar ist
• die Zahl selbst, sonst

Ein Property-based Test zur Überprüfung einer möglichen Lösung könnte wie folgt aussehen:

[Property]
public Property Should_Get_Fizz(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals("Fizz");

    return property.When(n.Item % 3 == 0 && n.Item % 5 != 0);
}

[Property]
public Property Should_Get_Buzz(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals("Buzz");

    return property.When(n.Item % 3 != 0 && n.Item % 5 == 0);
}

[Property(MaxTest = 10)]
public Property Should_Get_FizzBuzz(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals("FizzBuzz");

    return property.When(n.Item % 3 == 0 && n.Item % 5 == 0);
}

[Property]
public Property Should_Get_Number(PositiveInt n)
{
    var property = () => FizzBuzzer.GetFizzBuzz(n.Item).Equals(n.Item.ToString());

    return property.When(n.Item % 3 != 0 && n.Item % 5 != 0);
}

Ein kleines Beispielprojekt mit dem hier gezeigten Quellcode findet sich auf GitHub.

Um nun nicht nur die Laufzeit- sondern auch die Entwicklungs-Umgebung reproduzierbar und portierbar zu gestalten, bieten sich Development Containers an.

Development Container

Um eine Entwicklungsumgebung herzustellen, genügt heutzutage zumeist nicht mehr nur ein Texteditor oder eine IDE. Es werden Runtimes, Compiler, CLIs und verschiedenste Tools benötigt, um Software zu entwickeln. Arbeitet man in mehreren Programmiersprachen oder Projekten, kann das Setup schnell einige Stunden in Anspruch nehmen. Ein weiteres Problem tritt auf, wenn man unterschiedliche Versionen einer Software benötigt. Node.js ist hier ein Beispiel, für das es mit dem Node Version Switcher mehr einen Workaround als eine gute Lösung gibt.

Zur Lösung dieser Probleme werden schon seit langer Zeit vorkonfigurierte virtuelle Maschinen eingesetzt, die entweder lokal ausgeführt werden oder zu denen man sich über ein Remote-Protokoll wie SSH oder RDP verbinden kann. Die Developer-Experience ist in beiden Fällen aber zumeist nicht optimal.

Nutzt man für die Entwicklung Visual Studio Code, bietet sich mit der Nutzung von Devcontainern hier eine leichtgewichtige Alternative an. Neben VS Code unterstützt bislang nur Visual Studio den Einsatz von Devcontainern, und auch nur für C++ Projekte. Lässt sich der eigene Workflow aber mit diesen Einschränkungen umsetzen, sind Devcontainer eine gute Option. Netter Nebeneffekt: Die Devcontainer verhalten sich auf unterschiedlichen Computern und Betriebssystemen gleich und sind somit für die Zusammenarbeit im Team gut geeignet. Die Konfiguration lässt sich neben dem Sourcecode in einem Git-Repository ablegen und versionieren.

Devcontainer in VS Code

Voraussetzung für die Nutzung von Devcontainern in VS Code ist eine installierte Version von Docker und die Extension Dev Containers, welche direkt von Microsoft kommt. Sie stellt über die Command Palette eine Reihe von Anweisungen bereit, um Devcontainer zu erstellen und zu verwalten.

Devcontainer erstellen

Zum Erstellen eines Devcontainers genügt eine JSON-Datei devcontainer.json im Unterordner .devcontainer. Die Definition eines Containers besteht im Grunde aus drei Bereichen: Image, Features und Konfiguration. Wählt man in VS-Code den Command Dev Containers: Add Dev Container Configuration Files..., wird man durch genau diese drei Bereiche geführt.

• Image: Beschreibt das Docker-Image, welches als Ausgangspunkt für den Devcontainer dient. Hier kann ein vorkonfiguriertes Devcontainer-Image oder jedes beliebige andere Docker-Image nutzen werden. Alternativ kann man ein Dockerfile oder ein Docker Compose-File angeben, um ein eigenes Image zu erstellen.

• Features: Pakete und Optionen, um Software zum Ausgangsimage hinzuzufügen und zu konfigurieren. So können Tools wie git, verschiedene CLIs oder Docker aber auch ganze Entwicklungs-Stacks für einzelne Programmiersprachen wie Go, .NET oder PHP als Feature einfach hinzugefügt werden. Es existieren einige vordefinierte Features, alternativ baut man sich eigene Features aus Shell-Scripten zusammen.

• Konfiguration: Unter Konfiguration fallen z.B. Port-Forwardings, Lifecycle-Scripte oder Anpassungen für VS Code.

Die folgende Konfiguration nutzt das Baseimage für Note.js 20 mit TypeScript, installiert zusätzlich die AWS- sowie die GitHub-CLI und führt nach dem Erstellen des Containers den Befehl yarn install aus.

{
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json",
  "name": "Node.js & TypeScript",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-20",
  "features": {
    "ghcr.io/devcontainers/features/aws-cli:1": {
      "version": "latest"
    },
    "ghcr.io/devcontainers/features/github-cli:1": {
      "installDirectlyFromGitHubRelease": true,
      "version": "latest"
    }
  },
  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "yarn install"
}

Ruft man über die VS-Code Command Palette den Befehl Dev Containers: Reopen in Container auf, wird der Devcontainer erstellt und VS Code verbindet sich mit dem Container. Das Erstellen kann einige Minuten dauern, da das Baseimage heruntergeladen und die Features installiert werden müssen. Der Root-Ordner des Projektes wird in den Container gemountet.

Nach dem Start zeigt uns VS Code den gemounteten Ordner im Explorer an und wir können mit der Entwicklung beginnen. Über das +-Icon im Terminal-Fenster kommen wir an eine Shell, die im Container läuft.

Ein eigenes Devcontainer-Image erstellen

Genügt ein vorkonfiguriertes Image in Kombination mit den zur Verfügung stehenden Features nicht, kann man sich mit Hilfe eines Dockerfiles ein maßgeschneidertes Devcontainer-Image bauen.

Für ein einfaches Ruby-Setup sieht das Dockerfile wie folgt aus:

FROM ruby:3.0-bullseye

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
  && apt-get -y install --no-install-recommends nano libvips libvips-dev libvips-tools

RUN gem install jekyll bundler

Innerhalb der devcontainer.json-Datei gibt man statt des Keywords image unterhalb von build das Dockerfile sowie den Build-Context an. Über den Features-Block werden ZSH als Default-Shell und git installiert. Zusätzlich wird VS Code angewiesen, die Extensions für Ruby sowie Github Copilot zu installiert. Über den postCreateCommand-Eintrag stellt man sicher, dass die benötigten Gems installiert werden.

{
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json",
  "name": "Ruby DevContainer",
  "build": {
    "dockerfile": "Dockerfile",
    "context": "."
  },
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {
      "installZsh": true,
      "configureZshAsDefaultShell": true,
      "installOhMyZsh": true,
      "username": "vscode",
      "userUid": "1000",
      "userGid": "1000",
      "upgradePackages": true,
      "nonFreePackages": true
    },
    "ghcr.io/devcontainers/features/git:1": {
      "version": "latest",
      "ppa": false
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "rebornix.Ruby",
        "GitHub.copilot"
      ]
    }
  },
  "forwardPorts": [],
  "postCreateCommand": "bundler install --gemfile=./Gemfile && ruby --version",
  "remoteUser": "vscode"
}

Möchte man zusätzliche Software installieren oder hat Änderungen an dem Container-Image vorgenommen, erstellt man über den Befehl Dev Containers: Rebuild and Reopen in Container einfach ein neues Image.

Mit dem aufkommen von Infrastructure As Code-Ansätzen werden nun auch zunehmend Infrastruktur-Beschreibungen in Form von Code- oder zumindest von strukturierten Textdateien hinterlegt. Damit lassen sich die Vorteile der statischen Code-Analyse auch auf Infrastruktur-Definitionen anwenden.

Analyse von Terraform-Dateien

Für die Analyse von Terraform-Definitionsdateien existiert das CLI-Tool tfsec an. Es steht unter der MIT-Lizenz als ausführbare Datei für Windows, Linux und macOS oder als Docker-Image zum Download bereit. tfsec kommt mit einem umfangreichen Set an Regeln für die großen Hyperscaler wie AWS, Azure und Google Cloud daher. Für eine selbst-gehostete Kubernetes Umgebung oder einen OpenStack-Cluster sind es allerdings bereits deutlich weniger. Zwar lassen sich über Custom Checks eigene Regel definieren, am sinnvollsten lässt sich tfsec aber vermutlich in einer managed Umgebung einsetzen.

tfsec

Im einfachsten Fall führt man tfsec im Ordner mit den Terraform-Dateien aus bzw. übergibt den Pfad als erstes Aufrufargument. tfsec durchsucht rekursiv alle Dateien mit der Endung .tf und .tfvars und gibt die Ergebnisse in der Konsole aus.

./tfsec ./terraform

Werden keine Regelverletzungen entdeckt, werden ein paar Statistiken ausgegeben und tfsec gibt Entwarnung.

  timings
  ──────────────────────────────────────────
  disk i/o             5.3983ms
  parsing              0s
  adaptation           610.2µs
  checks               3.2634ms
  total                9.2719ms

  counts
  ──────────────────────────────────────────
  modules downloaded   0
  modules processed    1
  blocks processed     11
  files read           1

  results
  ──────────────────────────────────────────
  passed               6
  ignored              0
  critical             0
  high                 0
  medium               0
  low                  0

No problems detected!

Werden Probleme festgestellt, folgen Details zur beanstandeten Datei und der genauen Position des Problems sowie Hinweise und Links zu weiteren Informationen. Der Parameter --concise-output reduziert die Ausgabe auf die wichtigsten Informationen.

> ./tfsec ./terraform --concise-output

Result #1 CRITICAL Storage account uses an insecure TLS version. 
────────────────────────────────────────────────────────────────────────────────
  ./Terraform/main.tf:55
────────────────────────────────────────────────────────────────────────────────
          ID azure-storage-use-secure-tls-policy
      Impact The TLS version being outdated and has known vulnerabilities
  Resolution Use a more recent TLS/SSL policy for the load balancer

  More Information
  - https://aquasecurity.github.io/tfsec/v1.28.1/checks/azure/storage/use-secure-tls-policy/
  - https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_account#min_tls_version
────────────────────────────────────────────────────────────────────────────────

  5 passed, 1 potential problem(s) detected.

In dem Beispiel bemängelt tfsec eine veraltete TLS-Version für einen Azure-Storage-Account.

Möchte man einzelne Regeln nicht zur Anwendung bringen, schließt man sie über den Parameter --exclude [RULE-ID] von der Prüfung aus. Auch lassen sich Beanstandungen einzelner Ressourcen oder Optionen innerhalb der Terraform-Definitionen per Kommentar ignorieren.

resource "azurerm_storage_account" "storage_account" {
  account_kind    = "StorageV2"
  account_tier    = "Standard"
  min_tls_version = "TLS1_1" #tfsec:ignore:azure-storage-use-secure-tls-policy
  ...
}

CI-Pipeline

Ein nützliches Feature von tfsec ist, dass es das Ergebnis einer Analyse in unterschiedlichen Formaten ausgeben kann. Über den Parameter --format wählt man die gewünschten Formate, darunter auch Markdown, HTML und JUnit. Mit --out legt man den Order (dieser muss existieren) und das Dateiprefix der Ausgabedateien fest. Das erste Format wird zusätzlich auf der Konsole ausgegeben.

Der folgende Aufruf erzeugt in dem Ordner ./terraform/tfsec-results die Dateien results.lovely, results.junit und results.markdown.

./tfsec ./terraform --concise-output \
    --format lovely,junit,markdown \
    --out ./terraform/tfsec-results/results

Die Ergebnisse lassen sich nun in einer CI-Pipeline weiterverarbeiten und der Build kann bei Regelverletzungen fehlschlagen.

Azure DevOps Pipeline

Nutzt man Azure DevOps Pipelines, kann man die JUnit-Datei als Test-Results veröffentlichen. So kann man tfsec einfach in vorhandene Test- und Build-Workflows integrieren und Fehler direkt in der Pipeline visualisieren.

Ich zeige hier für eine einfachere Adaption an andere CI-Systeme, wie man tfsec als Shell-Command nutzt. Daneben existiert auch eine Pipeline Extension im Visual Studio Marketplace und eine GitHub Action.

Zuerst lädt man das passende Binary für sein System herunter, setzt ggf. das Execute-Bit und legt den Ausgabe-Ordner an. Danach führt man tfsec aus. Möchte man das Ergebnis im Markdown-Format als Ergebnis des Pipeline-Laufs in der Weboberfläche sehen, kann man es über ein Logging-Command echo "##vso[task.uploadsummary]... hochladen.

In einem zweiten Task veröffentlicht man dann die JUnit-Datei als Test-Result.

- task: CmdLine@2
  displayName: "Run tfsec"
  inputs:
    workingDirectory: "$(System.DefaultWorkingDirectory)/Infrastructure/Terraform"
    script: |
      echo "Download tfsec v1.28.1 ..."
      wget -q https://github.com/aquasecurity/tfsec/releases/download/v1.28.1/tfsec-linux-amd64 -O tfsec
      chmod +x tfsec
      mkdir ./tfsec-results

      ./tfsec . --concise-output \
          --format lovely,junit,markdown \
          --out ./tfsec-results/results

      echo "##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/Infrastructure/Terraform/tfsec-results/results.markdown"

- task: PublishTestResults@2
  displayName: "Publish tfsec results"
  condition: succeededOrFailed()
  inputs:
    testResultsFormat: JUnit
    searchFolder: $(System.DefaultWorkingDirectory)/Infrastructure/Terraform/tfsec-results
    testResultsFiles: "results.junit"
    failTaskOnFailedTests: true
    testRunTitle: tfsec

Die tfsec-Results gehen mit in die Teststatistik ein.

Im Extensions-Tab wird das Ergebnis der Markdown-Datei angezeigt.

Damit hat man eine automatische und kontinuierliche Überprüfung der Terraform-Dateien in seine CI-Pipeline integriert.

Azure Kubernetes Versionen

Die unterstützen Kubernetes-Versionen sowie deren Support-Zeiträume listet Microsoft in der Dokumentation auf.

Zu beachten ist, dass ein Update immer nur innerhalb einer Minor-Version oder auf die nächste Minor-Version möglich ist. Möchte man etwa von Version 1.24 auf 1.26 updaten, muss man dies über Version 1.25 in zwei Durchgängen erledigen.

Die verfügbaren Versionen hängen von der Region ab, in der der Cluster angesiedelt ist. Über die Azure CLI lassen sich die verfügbaren Versionen für eine Region abfragen.

az aks get-versions \
  --location westeurope \
  --output table

Die Ausgabe liefert eine Liste der verfügbaren Versionen und die möglichen Upgrades.

KubernetesVersion    Upgrades
-------------------  -----------------------
1.26.3               None available
1.26.0               1.26.3
1.25.6               1.26.0, 1.26.3
1.25.5               1.25.6, 1.26.0, 1.26.3
1.24.10              1.25.5, 1.25.6
1.24.9               1.24.10, 1.25.5, 1.25.6

Auch lassen sich die verfügbaren Upgrades für einen speziellen Cluster abfragen.

az aks get-upgrades \
  --resource-group rg-aks-test \
  --name aks-test \
  --output table

Das Ergebnis zeigt genau die verfügbaren Upgrades an.

Name     ResourceGroup    MasterVersion    Upgrades
-------  ---------------  ---------------  --------------
default  rg-aks-test      1.24.10          1.25.5, 1.25.6

Terraform

Das Konfigurieren eines AKS Clusters mittels Terraform ist schnell erledigt. Über den Azure Provider legt man die entsprechende Resource azurerm_kubernetes_cluster an.

Hier konfiguriert man über kubernetes_version die Version des Control Plane und über default_node_pool.orchestrator_version die Version der Nodes.

terraform {
  required_version = ">= 0.13"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.48.0"
    }
  }
}

# Configure the Azure Provider via environment variables
provider "azurerm" {
  features {}
}

# Resource Group
resource "azurerm_resource_group" "rg" {
  name     = "rg-aks-test"
  location = "westeurope"
}

# AKS Cluster
resource "azurerm_kubernetes_cluster" "aks" {
  name                              = "aks-test"
  location                          = azurerm_resource_group.rg.location
  resource_group_name               = azurerm_resource_group.rg.name
  dns_prefix                        = "k8s"
  kubernetes_version                = "1.24.10"
  role_based_access_control_enabled = true

  default_node_pool {
    name                 = "default"
    node_count           = 2
    vm_size              = "Standard_B2s"
    orchestrator_version = "1.24.10"
  }

  identity {
    type = "SystemAssigned"
  }
}

Ein terraform apply und ein paar Minuten später steht ein AKS Cluster in der gewünschten Version zur Verfügung.

Upgrade mit Terraform

Um seinen AKS Cluster nun auf eine höhere Version zu heben, ändern man die Versionsnummern in seinem Terraform-File, am besten sowohl für das Control Plane als auch die Node Pools. Ein terraform apply stößt den Upgrade-Vorgang an. Nun werden nacheinander die einzelnen Knoten aus dem Cluster entfernt und durch aktualisierte Varianten ersetzt. Die laufenden Pods werden dabei natürlich auf die verbleibenden Knoten verteilt und bleiben weiterhin erreichbar. Der Upgrade-Vorgang kann abhängig von der Anzahl der Knoten einige Minuten bis Stunden dauern.

Solltet Ihr für die Infrastruktur-Anpassung eine CI/CD-Pipeline nutzen, achtet darauf, dass der Vorgang nicht in einen Timeout läuft.

Über die Azure CLI und im Azure Portal lässt sich der Prozess verfolgen.

az aks list -o table

az aks nodepool list \
  --resource-group rg-aks-test \
  --cluster-name  aks-test \
  --output table

Der ProvisioningState wechselt auf Upgrading.

Name     OsType    KubernetesVersion    ProvisioningState
-------  --------  -------------------  -------------------
default  Linux     1.25.6               Upgrading

Nach Abschluss des Upgrades wechselt der ProvisioningState wieder auf Succeeded und alle Knoten laufen auf der neuen Kubernetes-Version.

Neben der Anzahl der gesendeten und empfangenen Emails gibt es auch eine Grafik zu Spam und Viren.

Dank eines Patches von Sebastian van de Meer informiert Mailgraph auch darüber, ob die einliefernden Server SPF, DMARC oder DKIM unterstützen. Hierfür ist natürlich erforderlich, dass diese Mechanismen auf eurer Postfix-Instanz konfiguriert sind.

Docker Container

Um Mailgraph und dazu einen entsprechenden Webserver nicht direkt auf seinem Emailserver installieren zu müssen, kann man es natürlich in einem Docker Container betreiben.

Dazu habe ich ein Dockerfile erstellt, welches alle Abhängigkeiten enthält und sofort eingesetzt werden kann. Als Volumes gibt man den Pfad zum Mail-Logfile sowie einen Ordner zum Speichern der RRD-Dateien an. Alternativ kann man hierzu natürlich auch ein Docker Volume verwenden.

Über das -v Flag hängt man Host-Pfade oder Volumes in den Container ein: -v [Host-Path]:[Container-Path]

Die Log-Datei wird im Container unter dem Pfad /var/log/mail/mail.log erwartet, die RRD-Dateien unter /var/www/mailgraph/rrd/.

Das Image liefert standardmäßig auf Port 80 und Pfad /mailgraph die Mailgraph-Webseite aus.

docker run --rm \
  -v /var/log/mail/mail.log:/var/log/mail/mail.log \
  -v /var/data/mailgraph/rrd/:/var/www/mailgraph/rrd/ \
  davidullrich/mailgraph:latest

Ruft man nun http://localhost:80/mailgraph/ im Browser auf, bekommt man schon die ersten Grafiken angezeigt.

Docker Compose

Nutzt man zur Orchestrierung Docker Compose, sieht eine entsprechende Konfiguration etwa so aus:

version: '3'

services:
  mailgraph:
    image: davidullrich/mailgraph:latest
    hostname: mail.example.com
    volumes:
      - /var/log/mail/mail.log:/var/log/mail/mail.log
      - /var/data/mailgraph/rrd/:/var/www/mailgraph/rrd/
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped

Reverse Proxy mit Traefik

Möchte man seine Mailgraph-Webseite nicht öffentlich zugänglich sehen, kann man mittels Reverse Proxy eine Authentifizierung einrichten. Eine einfache Möglichkeit bietet Traefik, ein Reverse Proxy, der sich sehr schön in Docker Compose integrieren lässt. Hat man Traefik auf seinem System eingerichtet, ist die Konfiguration für Mailgraph über Labels sehr einfach.

version: '3'

services:
  mailgraph:
    image: davidullrich/mailgraph:latest
    hostname: mail.example.com
    volumes:
      - /var/log/mail/mail.log:/var/log/mail/mail.log
      - /var/data/mailgraph/rrd/:/var/www/mailgraph/rrd/
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mailgraph-router.rule=Host(`mail.example.com`) && PathPrefix(`/mailgraph`)"
      - "traefik.http.routers.mailgraph-router.entryPoints=websecure"
      - "traefik.http.routers.mailgraph-router.service=mailgraph-service"
      - "traefik.http.services.mailgraph-service.loadBalancer.server.scheme=http"
      - "traefik.http.services.mailgraph-service.loadBalancer.server.port=80"
      - "traefik.http.routers.mailgraph-router.middlewares=mailgraph-middleware-auth"
      - "traefik.http.middlewares.mailgraph-middleware-auth.basicauth.users=user:[password-hash]"

Dovecot-Erweiterung

Da ich als IMAP-Server Dovecot einsetze, habe ich Mailgraph um die Möglichkeit erweitert, die Anzahl der erfolgreichen und fehlgeschlagenen IMAP-Logins anzuzeigen.

Sourcecode und Docker Image

Den Sourcecode zu dem Docker Image findet ihr auf GitHub, das fertige Image im Docker Hub.