Gegen Podman debuggen

Die DataBridge lokal mit Breakpoints gegen die Podman-Testumgebung debuggen — konkret in Rider, Visual Studio und VS Code, inklusive Steuerung von GetChanges/Process*QueueItems und Einblick in den Service-Bus-Emulator.

Themen:

Voraussetzung ist die Podman-Testumgebung. Der databridge-Container würde sonst Port 7062 belegen, deshalb startet up.sh/up.ps1 alles außer der DataBridge selbst:

dev\up.ps1 -HostMode mssql process

dev/up.sh --host mssql process

--host (bzw. -HostMode) lässt sich mit allen anderen Argumenten kombinieren (Datenbanken, Mocks, getchanges, process, servicebus) und startet alles außer dem databridge-Container selbst (dafür gibt es das Profil databridge, das sonst automatisch aktiv ist). Der Befehl generiert zusätzlich src/DataBridge/local.settings.json aus der Vorlage dev/local.settings.dev.json (Azurite über UseDevelopmentStorage=true, Service-Bus-Emulator über localhost statt über den Compose-Servicenamen servicebus, sowie die Toggles aus dev/.env, siehe GetChanges/Process*QueueItems steuern).

Überschreibt local.settings.json bei jedem Aufruf

src/DataBridge/local.settings.json wird bei jedem --host/-HostMode-Aufruf neu erzeugt und dabei kommentarlos überschrieben — auch echte Zugangsdaten, die dort für Cloud-Debugging eingetragen waren, sind danach weg. Wer beides abwechselnd nutzt, siehe Podman- und Cloud-Settings parallel halten.

Damit die Connections in Azurite ebenfalls auf den Host statt auf die Compose-Servicenamen zeigen, setzt --host/-HostMode beim Seed-Container DATABRIDGE_RUNTIME=host (sonst container); seed.py ersetzt dann mssql/postgres/mysql/oracle/wiremock durch localhost mit dem passenden Host-Port aus dev/.env.

Zum Zurückwechseln auf den Container-Betrieb reicht ein Aufruf ohne --host/-HostMode — das generiert local.settings.json nicht neu, startet aber wieder den databridge-Container auf demselben Port. Die generierte Datei vorher löschen oder ignorieren, sie wird nicht mehr gelesen, solange kein lokaler Prozess läuft.

In der IDE starten

Alle drei IDEs nutzen dasselbe Projekt src/DataBridge/DataBridge.csproj und dasselbe Profil DataBridge aus src/DataBridge/Properties/launchSettings.json (startet mit --port 7062, passend zum MCP-Endpoint und zu curl-Aufrufen gegen localhost:7062).

Das richtige Run-Profil auswählen

Rider (und die anderen IDEs) legen für jede Testklasse bzw. jeden Testfall automatisch eine eigene Run-/Debug-Konfiguration an, sobald man einmal über die Gutter-Icons einen Test gestartet hat — z. B. „OpenApiConnectorAuthTests“. Diese Konfigurationen bleiben oben im Auswahlmenü stehen und werden schnell mit dem eigentlichen Funktions-Profil DataBridge verwechselt, gerade wenn Rider zuletzt einen Test als aktive Konfiguration gemerkt hat. Startet man versehentlich eine Test-Konfiguration statt DataBridge, laufen die Unit-Tests statt der Function App — sichtbar u. a. daran, dass Breakpoints in Connectoren/Services nicht mehr halten oder plötzlich Exceptions aus DataBridge.Test.* im Log auftauchen, die eigentlich von einem Test erwartet werden (z. B. ServiceClient_WithoutCredentials_ThrowsNotSupported). Vor dem Debuggen also immer kurz prüfen, dass oben rechts wirklich DataBridge (Projekt-Icon, nicht Test-Icon) ausgewählt ist.

Rider

Lösung src/DataBridge.slnx öffnen (falls noch nicht offen).
Oben rechts das Run-Profil DataBridge auswählen (Rider erkennt das Azure-Functions-Projekt automatisch und bietet das Profil aus launchSettings.json an).
Auf das Käfer-Symbol (Debug) statt Play klicken, oder Shift+F9.
Breakpoints wie gewohnt im Editor setzen (z. B. in ProcessQueueMessageService oder einem Connector).

Visual Studio

src/DataBridge.slnx öffnen, DataBridge als Startprojekt setzen (Rechtsklick im Projektmappen-Explorer → Als Startprojekt festlegen, falls nicht schon aktiv).
Im Dropdown neben dem grünen Play-Pfeil das Profil DataBridge wählen.
F5 (Debuggen starten) statt Ctrl+F5.
Breakpoints wie gewohnt setzen.

VS Code

VS Code braucht die Azure Functions Core Tools (func) und die Erweiterung Azure Functions (oder C# Dev Kit), um Attach/Debug über launchSettings.json anzubieten. Ohne Erweiterung reicht auch der direkte Weg:

Terminal in src/DataBridge öffnen.
func start (nutzt automatisch local.settings.json und den Port aus host.json/der Umgebung — bei Bedarf func start --port 7062 explizit angeben).
Mit der Erweiterung C# Dev Kit: Debug: Attach to .NET Process ausführen und den laufenden func-/dotnet-Prozess auswählen. Mit der Azure Functions-Erweiterung genügt stattdessen F5 direkt im Projektordner, das startet func start automatisch im Debug-Modus.
Breakpoints wie gewohnt setzen.

Danach in jeder IDE:

Der MCP-Server databridge-dev aus .mcp.json funktioniert unverändert (http://localhost:7062/api/mcp?code=local) — func start prüft den Function Key nicht, siehe MCP für die Testumgebung.
Eine Anfrage auslösen (z. B. POST http://localhost:7062/api/ExecuteJob?code=local, per Bruno, curl oder MCP run_job) und der Breakpoint hält an.

Logging

dev/local.settings.dev.json setzt kein APPLICATIONINSIGHTS_CONNECTION_STRING — es gibt also auch im Host-Modus keine Application Insights, an die etwas gesendet werden könnte. Alles, was die DataBridge loggt, geht direkt in die Konsole des lokalen Prozesses:

Rider: das Run-Fenster (bzw. Debug-Fenster mit Breakpoints) am unteren Rand.
Visual Studio: das Ausgabefenster (Ansicht → Ausgabe, Quelle „Debug“) sowie bei F5 das Konsolenfenster der Function-Host-Runtime.
VS Code: das Terminal, in dem func start läuft, bzw. der Debug Console-Tab bei Attach.

src/DataBridge/host.json setzt für die Kategorien DataBridge und Function den Log-Level Trace — dieselbe ausführlichste Stufe wie im Container (siehe Lokale Testumgebung → Logging). Weil hier keine Application Insights mitläuft, spielen die dortigen Sampling-/Puffer-Regeln (TELEMETRY_INFO_SAMPLE_RATE, TELEMETRY_CONTROL) keine Rolle — sie wirken nur auf den Versand an Application Insights, nicht auf die Konsolenausgabe.

GetChanges/Process*QueueItems steuern

Zwei unabhängige Schalter entscheiden, ob im Host-Modus etwas automatisch verarbeitet wird:

Schalter	Argument bei `up.sh --host`/`up.ps1 -HostMode`	Wirkung
`DATABRIDGE_GETCHANGES`	`getchanges`	`AzureWebJobs.GetChanges.Disabled` in der generierten `local.settings.json`
`DATABRIDGE_PROCESS`	`process`	`AzureWebJobs.Process{Standard,High,Low}PriorityQueueItems.Disabled`

dev\up.ps1 -HostMode mssql process             # Verarbeitung an, Timer aus
dev\up.ps1 -HostMode mssql getchanges process  # beides an
dev\up.ps1 -HostMode mssql                     # beides aus – Verarbeitung nur manuell per ExecuteJob

dev/up.sh --host mssql process              # Verarbeitung an, Timer aus
dev/up.sh --host mssql getchanges process   # beides an
dev/up.sh --host mssql                      # beides aus – Verarbeitung nur manuell per ExecuteJob

Beide Toggles aktivieren automatisch das Profil servicebus (siehe Service Bus), weil ohne Emulator weder GetChanges noch Process*QueueItems sinnvoll etwas zu tun hätten. Die Durable-Functions-Kette (StartGetChangesOrchestration, GetChangesOrchestrator, GetChangesActivity, JobState) bleibt immer deaktiviert.

Weil local.settings.json bei jedem --host-Aufruf neu generiert wird, reicht ein erneutes up.sh --host … mit anderen Toggles, um umzuschalten — die IDE muss dafür neu gestartet werden (Azure-Functions-Runtime liest local.settings.json nur beim Start).

Typischer Ablauf, um einen Job Ende-zu-Ende mit Breakpoints zu verfolgen:

dev/up.sh --host mssql process (Windows: dev\up.ps1 -HostMode mssql process) — Datenbank, Verarbeitung und Service-Bus-Emulator, aber ohne Container-DataBridge.
In der IDE debuggen starten (s. o.), Breakpoint z. B. in ProcessQueueMessageService setzen.
Job manuell per ExecuteJob auslösen — Details, Job-Namen-Muster und Beispielaufruf unter Lokale Testumgebung → Einen Job manuell ausführen. IsActive: true ist dafür nicht nötig.
getchanges zusätzlich nur nötig, wenn der Timer selbst (statt ExecuteJob) die Änderungen erkennen soll — dann muss der Job vorher per update_job auf IsActive: true gesetzt werden.

Service Bus einsehen

Drei Wege, in den Service-Bus-Emulator hineinzuschauen, ohne selbst Code zu schreiben:

Web-Oberfläche servicebus-explorer (empfohlen, auch zum aktiven Testen). Läuft automatisch mit, sobald das Profil servicebus aktiv ist (also auch über getchanges/process) — kein separater Start nötig. Zeigt Queues, Nachrichtenzahlen (aktiv/dead-lettered) und einzelne Nachrichten inkl. Body in einer grafischen Oberfläche:

http://localhost:8090   (Port konfigurierbar über SERVICEBUS_EXPLORER_PORT in dev/.env)

Es handelt sich um das Community-Tool Service-Bus-Emulator-Explorer von Tom Biddulph (nicht von Microsoft, kein Bestandteil des offiziellen Emulators) — als eigener Container servicebus-explorer im Compose-Stack mitgeliefert, per fertigem Image (ghcr.io/tombiddulph/service-bus-emulator-explorer), spricht intern mit servicebus über dieselben Connection-Strings wie die DataBridge selbst.

Anders als die MCP-Diagnose-Tools kann die Web-Oberfläche auch selbst Nachrichten auf eine Queue oder ein Topic legen (eigener Body, Content-Type, Custom Properties, Session-ID) — praktisch, um Process*QueueItems gezielt mit einer handgebauten Nachricht zu testen, ohne vorher GetChanges über einen echten Job laufen zu lassen.

MCP (kein zusätzliches Werkzeug nötig, gut für Automatisierung/Scripting). Der MCP-Server databridge-dev bietet schreibgeschützte Diagnose-Tools: list_queue_statuses/get_queue_status (Nachrichtenzahlen je Queue) und peek_* für die Metadaten wartender Nachrichten (u. a. Body-Größe, keine Inhalte — siehe MCP für die Testumgebung). Das läuft über den Admin-Client auf Port 5300, den ServiceBusService beim Emulator automatisch anhängt (siehe Service Bus).

Rohes REST/AMQP, z. B. per curl. Die Management-API des Emulators liegt auf http://localhost:5300; für eigene Skripte, die weder die Weboberfläche noch MCP nutzen sollen, reicht derselbe Connection-String wie oben.

Klassischer Service Bus Explorer funktioniert nicht

Das weit verbreitete Desktop-Tool Service Bus Explorer (Community-Tool von Paolo Salvatori) unterstützt den Emulator nicht — er ist kein vollwertiger Service-Bus-Namespace und hat andere Auth-Mechanismen. Der oben verlinkte servicebus-explorer ist eigens für den Emulator gebaut.

Für den Alltag reicht MCP

Für die üblichen Fragen beim Debuggen — „ist die Nachricht überhaupt auf der Queue angekommen?“, „wie viele Nachrichten liegen in sbqignored?“ — reichen die MCP-Diagnose-Tools. Die Web-Oberfläche lohnt sich, sobald man Nachrichten manuell anschauen, selbst verschicken oder erneut zustellen will — die MCP-Tools sind bewusst rein lesend (siehe MCP-Server) und können das nicht.