Entwickler on dsyr.DataBridge

Architektur im Detail

Mon, 01 Jan 0001 00:00:00 +0000

Dieser Abschnitt beschreibt die dsyr.DataBridge so detailliert, dass sie ohne Lesen des Quellcodes verstanden werden kann. Er richtet sich an Entwickler, die Connectoren, Resolver oder Services erweitern, und an technische Reviewer.

Die Übersicht für Administratoren steht unter Dokumentation → Überblick → Architektur. Dort sind C4-Diagramme, Queue-Struktur und Connector-Hierarchie beschrieben. Die Seiten hier setzen darauf auf und gehen eine Ebene tiefer: Sequenzdiagramme, Bicep-Module, DI-Verdrahtung, Request- und Nachrichten-Schemata.

Seite	Inhalt
Systemkontext und Prinzipien	Zweck, Hauptfunktionen, Architekturprinzipien, Phasen, Betriebs- und Skalierungsmodell
Infrastruktur (Bicep)	Module, Ressourcen, App-Settings, Rollen, Alerts, Marketplace-Artefakte
Anwendungsarchitektur	Projekte, DI, `host.json`, Functions, Services, Connector-Basisklassen, Transformations-Pipeline, Domänenobjekte
API- und Nachrichten-Referenz	HTTP-Endpunkte mit Request/Response, Trigger-Bindungen, Service-Bus-Nachrichtenschema, Fehlerverhalten
Datenflüsse	Sequenzdiagramme für Erkennung, Verarbeitung, Response-Jobs, Fehlerpfad; Persistenz; Watermark-Logik
Abhängigkeiten	Projekt- und Azure-Abhängigkeiten, externe Systeme, architekturkritische Kopplungen
Fähigkeiten-Katalog	Alle Fähigkeiten mit ihrer technischen Umsetzung

Stand

Die Inhalte entsprechen dem Code-Stand von Version 2.3. Quellen sind src/, bicep/ und cicd/ im Repository. Wo eine Aussage eine Annahme ist, steht das im Text.

Gegen Podman debuggen

Mon, 01 Jan 0001 00:00:00 +0000

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).

Systemkontext und Prinzipien

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Die dsyr.DataBridge ist eine serverlose Datenintegrations-Bridge auf Azure Functions (.NET 10, Isolated Worker). Sie synchronisiert Datensätze nahezu in Echtzeit zwischen heterogenen Geschäftssystemen, ohne diese direkt zu koppeln. Quelle und Ziel sind über Azure Service Bus entkoppelt, Änderungen werden über Watermarks change-getrieben übertragen.

Die Bridge hält keine Fachdaten dauerhaft. Sie speichert nur Konfiguration und Synchronisationsstände in Azure Table Storage; Nachrichten liegen transient im Service Bus.

Hauptfunktionen

Funktion	Beschreibung
Change Detection	Periodisches Pollen der Quellsysteme (Timer `GetChanges`, optional Durable-Orchestrierung)
Asynchrone Entkopplung	Erkannte Änderungen landen als Nachrichten in priorisierten Queues (Low / Standard / High)
Feld-Mapping und Transformation	Konfigurierbare Zuordnung inkl. Typ-Coercion, Default-Werten, Option-Mapping, Lookups, Source-/Target-Operationen
Multi-System-Konnektivität	D365 BC, CE/Dataverse, NAV, generische REST-APIs über OpenAPI-Spezifikation, SQL-Datenbanken (MSSQL, PostgreSQL, MySQL, Oracle)
Idempotente Zielverarbeitung	Upsert/Delete über Primär-, Custom- oder Filter-Keys, mehrere Schlüssel mit Rangfolge
Aktions-Jobs	`InvokeAction` ruft benannte Nicht-CRUD-Endpunkte auf (OpenAPI `operationId`, CE `OrganizationRequest`)
Watermarking	Persistierter Stand pro Job, nur neue Änderungen werden übertragen
Response-Jobs	Rückschreiben von im Ziel erzeugten Schlüsseln in die Quelle
Diagnose und KI-Anbindung	HTTP-Endpunkte (`CheckList`, `Validate`, `JobApi`, `MappingApi`) und ein read-only MCP-Server
Selektive Telemetrie	Gepuffertes Logging pro Invocation, Dependency-Sampling, pre-aggregierte Custom Metrics
Fehlerresilienz	Backoff-Retry, Transitive-Queues, Dead-Letter-Queues, Alerts

Zielgruppen

Zielgruppe	Nutzen
Integrations-/ERP-Berater	Konfigurieren Connections, Jobs und Mappings in Table Storage, ohne Code zu deployen
Cloud-/DevOps-Engineers	Deployen via Bicep oder Marketplace, betreiben und überwachen die Function App
Entwickler	Erweitern Connectoren, Resolver und Source-Operationen in `DataBridge.Core`
KI-Assistenten	Lesen Konfiguration und Queue-Zustand über den MCP-Server

Architekturprinzipien

Prinzip	Umsetzung
Separation of Concerns	Host (Trigger) ↔ Core (Logik) ↔ Connectoren (System-Anbindung) ↔ Resolver/Mapper (Transformation)
Configuration over Code	Connections, Jobs, Mappings, Watermarks liegen in Table Storage
Lazy Initialization	Services sind DI-Singletons; die Konfiguration wird einmalig und thread-sicher beim ersten Aufruf geladen
Asynchrone Entkopplung	Service Bus zwischen Lese- und Schreibseite; jede Nachricht wird isoliert verarbeitet
Idempotenz	Upsert/Delete über definierte Target-Keys
Resilienz	Backoff, Lock-Renewal, Transitive-Queues, Dead-Letter-Queues, `DeadLetterMover`
Erweiterbarkeit	Source-Operation-Handler werden per Reflection registriert; Connectoren über `ConnectionTypes` gemappt; Resolver-Registries je Connector als statische `FrozenDictionary`
Observability first	Gepuffertes Logging, Requests und Exceptions nie gesampelt, Custom Metrics ohne Sampling

Die zwei Phasen

flowchart LR
 SRC["Quellsystem"] -->|"1. Erkennung (Pull)"| FUNC1["GetChanges<br/>oder Orchestrator + Activity"]
 FUNC1 -->|"QueueMessage"| SB[("Service Bus<br/>Low / Standard / High")]
 SB -->|"2. Verarbeitung (Push)"| FUNC2["Process*QueueItems"]
 FUNC2 -->|"Upsert / Delete / Action"| TGT["Zielsystem"]
 FUNC1 -.->|"Watermark"| WM[("watermark")]
 FUNC2 -.->|"Response-Job / Transitive / Ignored"| SB

Erkennung: GetChanges (Timer) liest Änderungen aus den Quellsystemen und enqueued sie. Die Durable-Orchestrierung ist eine Alternative, die nur per HTTP gestartet wird und im Regelbetrieb nicht läuft.
Verarbeitung: Drei Service-Bus-Trigger (je Priorität) dequeuen und schreiben ins Zielsystem.

Diese Entkopplung erlaubt unabhängige Skalierung beider Seiten und überbrückt temporäre Ausfälle des Zielsystems. Details in Datenflüsse.

Gegen echtes Azure debuggen

Mon, 01 Jan 0001 00:00:00 +0000

Hier läuft kein Podman-Stack mit — die lokal gestartete DataBridge verbindet sich direkt mit einem echten Storage Account, einem echten Service Bus Namespace und den echten Quell-/Zielsystemen (BC, CE, NAV, SQL). Das ist der klassische Weg, um ein Problem aus einer konkreten Umgebung (z. B. dsyr-wysatest) lokal nachzuvollziehen oder mit dem Debugger zu untersuchen.

`local.settings.json` vorbereiten

src/DataBridge/sample.local.settings.json nach src/DataBridge/local.settings.json kopieren (falls noch nicht vorhanden — die Datei ist in .gitignore, geht also nicht versehentlich in einen Commit).
Die Platzhalter durch echte Werte aus dem Azure Portal bzw. Key Vault ersetzen: AzureWebJobsStorage (Storage-Account-Connection-String), ExportQueueServiceBus (Service-Bus-Connection-String) sowie die Connection-Strings/Secrets der Quell- und Zielsysteme, je nachdem was getestet werden soll. Diese Werte niemals committen und nicht in Chats/Tickets einfügen.
Wenn enableManagedIdentity in der Zielumgebung aktiv ist (siehe Identity-Verbindungen bzw. SettingsService), fehlen dort Connection-Strings ganz — stattdessen AzureWebJobsStorage__accountName und ExportQueueServiceBus__fullyQualifiedNamespace setzen und lokal per az login angemeldet sein, damit DefaultAzureCredential greift. Das erfordert eine Rollenzuweisung für den eigenen Benutzer auf Storage und Service Bus (Data-Rollen, nicht nur Management), sonst schlägt der Verbindungstest beim Start fehl.

Podman überschreibt dieselbe Datei

src/DataBridge/local.settings.json ist die einzige Datei, aus der sowohl der Podman-Host-Modus als auch dieses Cloud-Setup lesen — es gibt keine zweite, von der Function-Runtime automatisch erkannte Datei. Läuft danach dev/up.sh --host/dev\up.ps1 -HostMode (siehe Debuggen → Gegen Podman), wird die Datei kommentarlos überschrieben und die gerade eingetragenen echten Zugangsdaten sind weg. Wer beides abwechselnd nutzt, siehe Podman- und Cloud-Settings parallel halten weiter unten.

Infrastruktur (Bicep)

Mon, 01 Jan 0001 00:00:00 +0000

Einstiegspunkt ist bicep/main.bicep. Das Deployment läuft im Scope einer bestehenden Resource Group (Bicep-Default, kein explizites targetScope), im Modus Incremental. Die Parameter aus Anwendersicht sind unter Installation beschrieben; hier geht es um den inneren Aufbau.

Module und Parameterfluss

flowchart TD
 MAIN["main.bicep"]

 SA["storageaccount.bicep"]
 AI["applicationinsights.bicep"]
 ASP["appserviceplan.bicep"]
 SB["servicebus.bicep"]
 ALERT["metricalerts.bicep<br/>if enableAlerts"]
 DASH["dashboard.bicep<br/>if enableGrafanaDashboard"]
 FUNC["azurefunction.bicep"]
 ROLES["roleassignments.bicep<br/>if enableManagedIdentity"]

 MAIN --> SA & AI & ASP & SB & ALERT & DASH & FUNC & ROLES

 SA -->|"id, name"| FUNC
 AI -->|"connectionString, id"| FUNC
 AI -->|"id"| DASH
 ASP -->|"id"| FUNC
 SB -->|"authorizationRuleId, name"| FUNC
 SB -->|"id"| ALERT
 FUNC -->|"principalId"| ROLES
 SA -->|"id"| ROLES
 SB -->|"id"| ROLES

Die Abhängigkeiten ergeben sich über Modul-Outputs, es gibt keine Zyklen. Zusätzlich legt main.bicep ein leeres Tracking-Deployment für die Microsoft-Partner-Attribution an.

MCP für die Testumgebung

Mon, 01 Jan 0001 00:00:00 +0000

Die DataBridge in der Podman-Testumgebung bringt denselben MCP-Server mit wie jede andere Instanz. Damit kann ein KI-Assistent die Beispiel-Jobs und -Mappings lesen und die Metadaten der Testdatenbanken abfragen, ohne dass dafür etwas in Azure laufen muss.

Zwei Server nebeneinander

Die .mcp.json im Repository definiert zwei DataBridge-Server:

Server	Ziel	URL
`databridge`	Eine Azure-Instanz (bzw. ohne Konfiguration der lokale Host)	`${DATABRIDGE_MCP_URL:-http://localhost:7062}/api/mcp?code=${DATABRIDGE_FUNCTION_KEY:-local}`
`databridge-dev`	Die Podman-Testumgebung	`http://localhost:7062/api/mcp?code=local`

{
 "mcpServers": {
 "databridge": {
 "type": "http",
 "url": "${DATABRIDGE_MCP_URL:-http://localhost:7062}/api/mcp?code=${DATABRIDGE_FUNCTION_KEY:-local}"
 },
 "databridge-dev": {
 "type": "http",
 "url": "http://localhost:7062/api/mcp?code=local"
 }
 }
}

databridge zeigt auf eine Azure-Instanz, sobald DATABRIDGE_MCP_URL und DATABRIDGE_FUNCTION_KEY gesetzt sind — üblicherweise im Block env der persönlichen .claude/settings.local.json (siehe MCP-Server → Nutzung).
databridge-dev zeigt immer auf die Testumgebung. Der Function Key ist dort fest auf local gesetzt (dev/functions-secrets/host.json), es muss also nichts konfiguriert werden.

In Claude Code erscheinen die Tools entsprechend mit den Präfixen mcp__databridge__… und mcp__databridge-dev__…. Im Prompt genügt es zu sagen, welcher Server gemeint ist, z. B. „frag über databridge-dev die Tabellen von oracle-dev ab“.

Anwendungsarchitektur

Mon, 01 Jan 0001 00:00:00 +0000

Projekte (`src/DataBridge.slnx`)

Projekt	Typ	Zweck
`DataBridge`	Azure Functions, net10.0, isolated	Host: Trigger, DI, Telemetrie-Bootstrap, Durable Functions, MCP-Endpunkt
`DataBridge.Core`	Class Library	Services, Connectoren, Resolver, Mapper, Source-Operationen, Modelle, Telemetrie
`DataBridge.Test`	xUnit v3 + Moq (Microsoft Testing Platform)	Unit-Tests; Ordnerstruktur spiegelt `DataBridge.Core`
`DeadLetterMover`	Konsolenanwendung	Requeue von Dead-Letter-Nachrichten

Dependency Injection (`Program.cs`)

FunctionsApplication.CreateBuilder(args) (moderner Einstiegspunkt statt new HostBuilder()), mit builder.UseMiddleware<InvocationContextMiddleware>(), die jede Invocation in einen InvocationContext einbettet und am Ende das gepufferte Log flusht.
Application Insights über AddApplicationInsightsTelemetryWorkerService, Adaptive Sampling deaktiviert; DependencySamplingProcessor per AddApplicationInsightsTelemetryProcessor. Der Standard-AI-Logger-Provider ist auf LogLevel.None gesetzt, einziger Pfad nach AI ist der BufferingLoggerProvider.
Alle Services sind Singletons: MetricsService, SettingsService, StorageService, ConnectionService, MappingService, JobService, WatermarkService, ServiceBusService, ProcessQueueMessageService, ProcessJobsForRetrievalInOrderService, CheckListService, InitializationService, McpToolService.
Log-Level: Kategorien DataBridge und Function auf Trace, der Puffer-Provider filtert auf Debug.

`host.json`

Bereich	Einstellung	Wert
Allgemein	`functionTimeout`	10 min
AI-Sampling	`excludedTypes`	`Request;Exception`
Durable	`hubName`	`DurableFunctionsHub`, Azure-Storage-Provider, Distributed Tracing V2
Storage Queues	`batchSize` / `maxDequeueCount`	1 / 5 (nur für Durable relevant)
Service Bus	`autoCompleteMessages`	`false`
Service Bus	`maxConcurrentCalls`	12
Service Bus	`maxAutoLockRenewalDuration`	5 min

Functions

Function	Trigger	Aufgabe
`GetChanges`	Timer `%GetChangesTimerExpression%`	Initialisiert thread-sicher über `InitializationService` und ruft `ProcessJobsForRetrievalInOrderService.Execute` auf
`ProcessStandardQueueItems`, `ProcessHighPriorityQueueItems`, `ProcessLowPriorityQueueItems`	Service Bus `sbqexport`, `sbqhighexport`, `sbqlowexport`	Verarbeiten je eine Nachricht end-to-end über `ProcessQueueMessageService.Execute`
`ExecuteJob`	HTTP POST	Stößt einen Job per Name über `ProcessJobsForRetrievalInOrderService.ExecuteByJobName` an
`ExecuteHttpRequest`	HTTP POST	Ad-hoc-HTTP-GET mit eigenem `HttpClient` (NTLM oder anonym), unabhängig von den Connectoren
`GetInfo`	HTTP GET	Assembly-Version
`CheckList`	HTTP GET	`InitializationService.CheckAsync()`: Mappings gegen Live-Metadaten der Systeme
`Validate`	HTTP GET	Erzwingt die Initialisierung, liefert das Fehlerlog
`GetJobs`, `GetJobByRowKey`	HTTP GET `job`, `job/{rowKey}`	Geladene Job-Konfiguration
`GetMappings`, `GetMappingByRowKey`	HTTP GET `mapping`, `mapping/{name}`	Geladene Mappings, Suche per Name mit Fallback auf RowKey
`Mcp`, `McpGet`	HTTP POST/GET `mcp`	MCP-Server; GET antwortet mit 405, weil SSE-Streams nicht unterstützt werden
`StartGetChangesOrchestration`, `GetChangesOrchestrator`, `GetChangesActivity`, `JobState`	HTTP, Orchestration, Activity, Entity	Optionale Durable-Variante der Erkennung

Details zu Request und Response: API-Referenz.

Entwicklung

Mon, 01 Jan 0001 00:00:00 +0000

Dieser Bereich richtet sich an Entwickler der dsyr.DataBridge, nicht an Betreiber einer Instanz. Er beschreibt Werkzeuge aus dem Repository, die beim Entwickeln und Testen helfen und nicht Teil des ausgelieferten Produkts sind.

Architektur im Detail

Architektur im Detail

Systemkontext, Bicep-Module, DI und host.json, HTTP- und Nachrichten-Referenz, Sequenzdiagramme der Datenflüsse, Abhängigkeiten und Fähigkeiten-Katalog — eine Ebene tiefer als die Architektur-Übersicht für Administratoren.

→ Zum Abschnitt

Lokale Testumgebung

MCP für die Testumgebung

Den lokalen Container als eigenen MCP-Server databridge-dev in Claude Code nutzen — parallel zur Cloud-Instanz.

→ Zum Artikel

Podman-Testumgebung

DataBridge-Container, Azurite und wahlweise MSSQL, PostgreSQL, MySQL und Oracle — mit Beispieldaten, Connections, Jobs und Mappings, gestartet mit einem Befehl.

→ Zum Artikel

Debuggen

Die DataBridge lokal mit Breakpoints debuggen — gegen den Podman-Stack oder gegen eine echte Azure-Instanz.

→ Zum Artikel

Podman-Testumgebung

Mon, 01 Jan 0001 00:00:00 +0000

Die Testumgebung unter dev/ startet eine vollständig vorkonfigurierte DataBridge auf dem eigenen Rechner — ohne Azure-Ressourcen und ohne Kosten. Sie ist gedacht, um Connectoren gegen echte Datenbanken und gegen HTTP-Mocks (Business Central, NAV, OpenAPI) zu testen, ohne vorher Mappings und Jobs von Hand anzulegen.

Nur für Entwicklung

Die Umgebung nutzt feste Passwörter und einen festen Function Key (local). Sie ist nicht für den Betrieb gedacht und darf nicht aus dem Internet erreichbar sein.

API- und Nachrichten-Referenz

Mon, 01 Jan 0001 00:00:00 +0000

Authentifizierung

Alle HTTP-Functions verwenden AuthorizationLevel.Function. Der Funktionsschlüssel wird als Query-Parameter code oder Header x-functions-key übergeben. Es gibt keine Easy-Auth- oder Entra-Konfiguration im Deployment. Timer-, Service-Bus- und Durable-Trigger haben keinen HTTP-Endpunkt.

Routen ohne Route-Attribut folgen der Konvention /api/<FunctionName>.

HTTP-Endpunkte

`GET /api/GetInfo`

Liefert die Assembly-Version, keine Gesundheitsprüfung.

{ "Version": "2.3.2026.0926" }

`POST /api/ExecuteJob`

Stößt einen Job aus der Tabelle jobs manuell an (Erkennungsphase).

{ "JobName": "<RowKey des Jobs>" }

Ablauf: JobName prüfen → EnsureInitializedAsync → ProcessJobForRetrieval. Antwort 200 OK; Fehler propagieren als 500. Der Aufruf läuft ohne Job-Locking parallel zum Timer, siehe Datenflüsse → Watermark.

Debuggen

Mon, 01 Jan 0001 00:00:00 +0000

Für Breakpoints und Step-Through läuft die DataBridge nicht im Container, sondern lokal als Prozess in der IDE. Zwei grundsätzlich verschiedene Varianten, je nachdem wogegen die lokal laufende DataBridge sprechen soll:

Gegen Podman debuggen

Azurite, Podman-Datenbanken, Service-Bus-Emulator, WireMock — alles lokal, keine Azure-Kosten, jederzeit zurücksetzbar.

→ Zum Artikel

Gegen echtes Azure debuggen

Echter Storage Account, echter Service Bus, echte Quell-/Zielsysteme — für Probleme aus einer konkreten Umgebung.

→ Zum Artikel

Datenflüsse

Mon, 01 Jan 0001 00:00:00 +0000

Die konzeptuelle Beschreibung steht unter Wie es funktioniert. Hier folgen die Abläufe auf Klassenebene.

Erkennung (Timer)

sequenceDiagram
 autonumber
 participant Timer as GetChanges (Timer)
 participant Init as InitializationService
 participant PJ as ProcessJobsForRetrievalInOrderService
 participant Job as JobService
 participant WM as WatermarkService
 participant Conn as Source-Connector
 participant SBS as ServiceBusService
 participant SB as Service Bus

 Timer->>Init: EnsureInitializedAsync()
 Note over Init: einmalig: Storage → Connections → Mappings → Jobs
 Timer->>PJ: Execute()
 PJ->>Job: GetJobsToRun()
 Note over Job,WM: GetAllWatermarks() (Bulk) für LastCronRun
 loop je Job nach Order
 PJ->>WM: GetWatermarkByJobName(job)
 PJ->>Conn: RetrieveChangesAsync(mapping, job, watermark, filter)
 loop seitenweise
 Conn-->>PJ: QueueMessage (serialisiert)
 PJ->>SBS: AddMessageOrSendAsync(msg, priority)
 alt Batch voll (200) oder Größenlimit
 SBS->>SB: SendMessagesAsync(batch)
 end
 PJ->>PJ: lastChangeTracker = msg.ChangeTracker
 end
 PJ->>SBS: FlushBatch()
 PJ->>WM: UpdateWatermarkByJobName(newWatermark, lastCronRun)
 end

Die Serialisierung (Key-Aufbau → Feld-Mappings → Source-Operationen / Resolver) passiert im Connector (ConnectorBase.Serialize).
Die Watermark wird erst am Ende eines Jobs geschrieben. Bricht der Lauf vorher ab, wird beim nächsten Lauf erneut ab dem alten Stand gelesen; SkipOutdatedMessages fängt Doppel-Nachrichten im Ziel ab.
Bei reinem Zeitstempel-Vorrücken ohne fachliche Änderung wird JobActionType.TimeStamp verwendet.
MetricsService zählt ChangesDetected je Job.

Erkennung (Durable)

sequenceDiagram
 autonumber
 participant HTTP as StartGetChangesOrchestration
 participant Orch as GetChangesOrchestrator
 participant State as JobState (Entity)
 participant Act as GetChangesActivity
 participant Conn as Source-Connector
 participant SBS as ServiceBusService

 HTTP-->>HTTP: 202 + InstanceId
 loop je Job aus GetJobsToRun
 Orch->>State: InProgress(jobName)?
 alt in Bearbeitung
 Orch->>Orch: überspringen
 else
 Orch->>State: Add(jobName)
 loop do … while HasMoreRecord
 Orch->>Act: CallActivity(JobActivityParam)
 Act->>Conn: RetrieveChangesAsync(…, MaxBatchSize=3)
 Act->>SBS: SendMessage(record, priority)
 Act-->>Orch: Page, Cookie, Watermark, HasMoreRecord
 end
 Orch->>State: Remove(jobName)
 end
 end

Der Durable-Pfad persistiert die Watermark nicht und ist im Timer-Betrieb nicht aktiv.

Abhängigkeiten

Mon, 01 Jan 0001 00:00:00 +0000

Plattform

net10.0 in allen Projekten, ImplicitUsings und Nullable aktiv.
Azure Functions v4, Isolated Worker, OutputType=Exe.
Tests auf xUnit v3 mit Microsoft Testing Platform. Aufruf mit dotnet test --project …; das Positionsargument funktioniert nicht mehr.

Projekte

flowchart LR
 HOST["DataBridge (Host)"] --> CORE["DataBridge.Core"]
 DLM["DeadLetterMover"] --> CORE
 TEST["DataBridge.Test"] --> CORE
 TEST --> HOST

NuGet-Pakete

Die Versionen werden zentral in src/Directory.Packages.props gepflegt (Central Package Management); die .csproj-Dateien referenzieren Pakete nur noch ohne Version. Ein Update passiert also an genau einer Stelle.

Fähigkeiten-Katalog

Mon, 01 Jan 0001 00:00:00 +0000

Integration und Datenfluss

Fähigkeit	Umsetzung
Change Detection (Pull)	`GetChanges` → `ProcessJobsForRetrievalInOrderService`; je Connector `RetrieveChangesAsync` (BC/NAV `$filter`, CE `RetrieveEntityChangesRequest`, SQL seitenweises SELECT, OpenAPI Query-String)
Orchestrierter Abruf	Durable: `GetChangesOrchestrator`, `GetChangesActivity`, Entity `JobState`
Asynchrone Entkopplung	Service Bus mit sieben Queues, `ServiceBusService` mit Batch bis 200
Priorisierte Verarbeitung	`JobPriorityType` → Queue; drei Trigger
Reihenfolgensteuerung	`Job.Order`
Idempotentes Schreiben	`Connector.Upsert/Delete`; `TargetKey`/`TargetKeys` mit `KeyRank`, erster Treffer gewinnt
Aktions-Jobs	`InvokeAction`: Job-`Action` ohne CRUD-Bedeutung ruft einen benannten Endpunkt
Job-eigene Pfade	`Source`/`Target` am Job überschreiben `SourceTable`/`TargetTable` des Mappings
Eingebettete Kinder	`EmbedChildren` (nur CE als Quelle)
Response-Jobs	`Upsert(..., responseMapping, job)` → Response-Nachricht
Watermarking	`WatermarkService` + `WatermarkValue`; Typen `date`, `datetime`, `string`

Konnektivität

Fähigkeit	Umsetzung
D365 Business Central	`BcConnector : HttpConnectorBase`, OAuth2 / Basic / Managed Identity
D365 CE / Dataverse	`CeConnector : ConnectorBase`, `ServiceClient` (Connection-String oder `url` + Managed Identity)
D365 NAV	`NavConnector : HttpConnectorBase`
REST über OpenAPI	`OpenApiConnector : HttpConnectorBase`, Spec aus `openApiSpecUrl`
MSSQL, PostgreSQL, MySQL, Oracle	`SqlConnectorBase<T>`, nur lesend
Auth-Varianten HTTP	Basic, OAuth2 Client Credentials mit `tokenUrl`, API-Key, Managed Identity (explizit über `authmethod`)
Key-Vault-Bezug	`keyVaultUrl` in der Connection + `DefaultAzureCredential`
Schema-Metadaten	`IConnector.GetTableNames`, `GetTableMetadata` für alle Connector-Typen
Ad-hoc-HTTP	`ExecuteHttpRequest` (nur GET)

Transformation und Mapping

Fähigkeit	Umsetzung
Feld-Mapping	`TableMapping` + `FieldMapping` aus `mappings`
Typ-Coercion	`AttributeResolver`-Familien je Systemtyp
Metadaten-basierte Resolver-Wahl	`TargetValueMapper` je Connector, statische `FrozenDictionary`-Registry mit Coverage-Tests
Default-Werte	Target-Operationen `DefaultValue`, `DefaultValueIfNullOrEmpty`, `DefaultValueMap`
Option-/Picklist-Mapping	`OptionMapping`, CE-Resolver für Picklist, MultiSelect, State/Status
Lookup-Auflösung	Source-Operation `LookupValue` mit Cache; CE mit Batch-Pre-Caching; `DoNotCreate`
CE-Beziehungen	`ActivityParty`, `LinkToRecord`
ReadFromMessage	Wert aus der Nachricht übernehmen
Virtuelle Felder	`_`-Präfix im `SourceField`, nie gegen Metadaten validiert
Erweiterbarkeit	Source-Operation-Handler per Reflection

Konfiguration und Steuerung

Fähigkeit	Umsetzung
Konfigurationsgetriebener Betrieb	Table Storage, `StorageService`, `SettingsService`
Cron je Job	`Job.Schedule`, `NCrontab.Signed`, sechs Felder
Manueller Job-Start	`ExecuteJob`
Function-Toggles	`AzureWebJobs.<Name>.Disabled`, Bicep `disabledFunctions`
Konfig-Diagnose	`CheckList`, `Validate`, `JobApi`, `MappingApi`
KI-Anbindung	MCP-Server mit read-only Tools
Self-Repair der Initialisierung	`ResetInitialization` bei Fehlern
Quell-Filter	`Job.Filter` mit `{{…}}`-Templating
Veraltete Nachrichten überspringen	`SkipOutdatedMessages` → `sbqignored`

Resilienz

Fähigkeit	Umsetzung
Backoff-Retry	`DeliveryCount² · 1000 ms`
Lock-Renewal	Hintergrund-Task alle 30 s
Konflikt-Isolation	`TransitiveException` → `sbqtransitive*`
Dead-Lettering	`maxDeliveryCount`, Fehler-Properties an der Nachricht
Requeue	`DeadLetterMover`
Kommunikationsfehler	`GetChanges` fängt `EndpointNotFoundException`, `CommunicationException`

Observability

Fähigkeit	Umsetzung
Gepuffertes Logging	`BufferingLoggerProvider`, Flush pro Invocation
Dependency-Sampling	`DependencySamplingProcessor`
Custom Metrics	`MetricsService` (`ChangesDetected`, `MessagesProcessed`)
Korrelation	`InvocationContext`, `operation_id`
Steuerung	`TELEMETRY_CONTROL`, drei Raten-Settings
Alerts	DLQ-Stufen, Queue-Länge, Action Group
Dashboard	Grafana-Dashboard aus Bicep
Version	`GetInfo`

Infrastruktur und Auslieferung

Fähigkeit	Umsetzung
Infrastructure as Code	Bicep mit Modulen und `.bicepparam`
Marketplace	`createUiDefinition.json`, generierte `mainTemplate.json`
Identitätsbasierter Zugriff	`enableManagedIdentity` + Rollen
Serverless-Skalierung	Y1 / EP1–EP3, `functionScaleLimit`
Run-from-Package	`WEBSITE_RUN_FROM_PACKAGE=1`
Container	`Dockerfile`, `compose.yml`
Versionierung	`Major.Minor.yyyy.MMdd`, manueller Bump
CI/CD	Azure Pipelines unter `cicd/`
Lokale Entwicklung	Podman-Testumgebung mit DBs und HTTP-Mocks

Qualitätssicherung

Fähigkeit	Umsetzung
Unit-Tests	`DataBridge.Test`, xUnit v3, Moq
Coverage	Microsoft Testing Platform Code Coverage
Resolver-Vollständigkeit	`*TargetValueMapperCoverageTests`
Dokumentation	Hugo/Docsy unter `docs/`, veröffentlicht per Pipeline

Entwickler on dsyr.DataBridge

Architektur im Detail

Gegen Podman debuggen

Systemkontext und Prinzipien

Zweck

Hauptfunktionen

Zielgruppen

Architekturprinzipien

Die zwei Phasen

Gegen echtes Azure debuggen

local.settings.json vorbereiten

Infrastruktur (Bicep)

Module und Parameterfluss

MCP für die Testumgebung

Zwei Server nebeneinander

Anwendungsarchitektur

Projekte (src/DataBridge.slnx)

Dependency Injection (Program.cs)

host.json

Functions

Entwicklung

Architektur im Detail

Lokale Testumgebung

Podman-Testumgebung

API- und Nachrichten-Referenz

Authentifizierung

HTTP-Endpunkte

GET /api/GetInfo

POST /api/ExecuteJob

Debuggen

Datenflüsse

Erkennung (Timer)

Erkennung (Durable)

Abhängigkeiten

Plattform

Projekte

NuGet-Pakete

Fähigkeiten-Katalog

Integration und Datenfluss

Konnektivität

Transformation und Mapping

Konfiguration und Steuerung

Resilienz

Observability

Infrastruktur und Auslieferung

Qualitätssicherung

`local.settings.json` vorbereiten

Projekte (`src/DataBridge.slnx`)

Dependency Injection (`Program.cs`)

`host.json`

`GET /api/GetInfo`

`POST /api/ExecuteJob`