Architektur im Detail on dsyr.DataBridge

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.

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.

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.

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.

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

Architektur im Detail on dsyr.DataBridge

Systemkontext und Prinzipien

Zweck

Hauptfunktionen

Zielgruppen

Architekturprinzipien

Die zwei Phasen

Infrastruktur (Bicep)

Module und Parameterfluss

Anwendungsarchitektur

Projekte (src/DataBridge.slnx)

Dependency Injection (Program.cs)

host.json

Functions

API- und Nachrichten-Referenz

Authentifizierung

HTTP-Endpunkte

GET /api/GetInfo

POST /api/ExecuteJob

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

Projekte (`src/DataBridge.slnx`)

Dependency Injection (`Program.cs`)

`host.json`

`GET /api/GetInfo`

`POST /api/ExecuteJob`