312 lines
10 KiB
Markdown
312 lines
10 KiB
Markdown
# Technische Dokumentation: BEW BizTalk Application Catalog – Phase 1
|
||
|
||
## 1. Ziel und Abgrenzung
|
||
|
||
Das Werkzeug bildet ausschließlich die Phase-1-Sicht `BizTalk Anwendungen & Adapter` ab. Das fachliche Ergebnis ist ein einblättriger ACC/PRD-Katalog mit:
|
||
|
||
1. BizTalk-Anwendung
|
||
2. Umgebung
|
||
3. Adapter-Typ und Anzahl
|
||
4. Endpunktanzahl
|
||
5. Vorkommen in ACC
|
||
6. Vorkommen in PRD
|
||
7. Hinweis bei einseitigem Vorkommen
|
||
|
||
Es ist kein technisches Vollinventar. Frühere Detailbereiche zu System, SQL, Status, Ports, Orchestrierungen, Schemas, Maps, Pipelines, Assemblies, Hosts, Handlern, Abdeckung und Findings sind nicht Bestandteil der XLSX und werden nicht mehr erhoben.
|
||
|
||
## 2. Verteilte Erfassung
|
||
|
||
ACC und PROD besitzen jeweils einen lokalen BizTalk Server 2020. Ein Prozess auf einem Server soll die andere Umgebung nicht remote abfragen.
|
||
|
||
```text
|
||
ACC BizTalk Server PROD BizTalk Server
|
||
| |
|
||
| WMI + ExplorerOM | WMI + ExplorerOM
|
||
v v
|
||
ACC JSON + lokale XLSX PROD JSON + lokale XLSX
|
||
\ /
|
||
\ /
|
||
+---- Merge auf beliebigem -----+
|
||
Windows-Rechner
|
||
|
|
||
v
|
||
gemeinsame ACC/PRD-XLSX
|
||
```
|
||
|
||
Der JSON-Snapshot ist das kleine Austauschformat zwischen den getrennten Erfassungen. Er enthält weder Endpunktadressen noch Credentials.
|
||
|
||
## 3. Komponenten
|
||
|
||
```text
|
||
CommandLineOptions
|
||
+-- validiert lokalen Modus oder Merge-Modus
|
||
|
||
BizTalkWmiCollector
|
||
+-- lokales MSBTS_GroupSetting per WMI
|
||
+-- lädt Microsoft.BizTalk.ExplorerOM aus GAC/Installationspfad
|
||
+-- Anwendungen und Ports per BtsCatalogExplorer
|
||
|
||
SnapshotStore
|
||
+-- normalisiert je Anwendung Adapterzählungen
|
||
+-- schreibt/liest DataContract-JSON
|
||
+-- validiert Schema, Summen, Umgebung und Vollständigkeit
|
||
|
||
XlsxReportWriter
|
||
+-- genau ein Blatt "Phase 1"
|
||
+-- Office Open XML ohne Office-Interop
|
||
+-- Titel, Filter, Freeze Pane und Summenzeile
|
||
```
|
||
|
||
## 4. Datenzugriff
|
||
|
||
### 4.1 Ursache des Fehlers `Invalid class`
|
||
|
||
Die ursprüngliche Implementierung führte als erste Abfrage
|
||
`SELECT * FROM MSBTS_Application` im Namespace
|
||
`root\MicrosoftBizTalkServer` aus. Das von BizTalk Server dokumentierte WMI-Schema
|
||
enthält keine Klasse `MSBTS_Application`. WMI antwortet deshalb unabhängig von
|
||
einer administrativ gestarteten Konsole mit `Invalid class`.
|
||
|
||
Auch die WMI-Portklassen bilden die fachliche Anwendungshierarchie nicht so
|
||
vollständig ab, dass damit Anwendungen ohne Ports zuverlässig erfasst werden
|
||
könnten. Der Fehler wird daher nicht nur abgefangen; der ungeeignete Zugriffsweg
|
||
wurde ersetzt.
|
||
|
||
### 4.2 Lokale Gruppenermittlung per WMI
|
||
|
||
Verwendeter Namespace:
|
||
|
||
```text
|
||
\\.\root\MicrosoftBizTalkServer
|
||
```
|
||
|
||
Verwendete Abfrage:
|
||
|
||
```sql
|
||
SELECT Name, MgmtDbServerName, MgmtDbName FROM MSBTS_GroupSetting
|
||
```
|
||
|
||
Der Punkt im Namespace erzwingt den lokalen Computer. Die Abfrage liefert den
|
||
BizTalk-Gruppennamen und das Ziel der Management-Datenbank. Der konfigurierte
|
||
WMI-Timeout wird angewendet. Kennwörter werden weder benötigt noch protokolliert.
|
||
|
||
### 4.3 Kataloglesung per Explorer Object Model
|
||
|
||
Die Assembly `Microsoft.BizTalk.ExplorerOM.dll` wird zur Laufzeit geladen. Dadurch
|
||
bleibt das Quellprojekt auf einem Build-Rechner ohne BizTalk-Assembly kompilierbar;
|
||
für den echten Inventarlauf müssen die BizTalk-Verwaltungskomponenten lokal
|
||
installiert sein.
|
||
|
||
Ladestrategie:
|
||
|
||
1. normale Typauflösung der bereits verfügbaren Assembly
|
||
2. Laden aus dem Global Assembly Cache
|
||
3. kompatible GAC-Auflösung ohne fest verdrahtete Assemblyversion
|
||
4. bekannte BizTalk-Installationsverzeichnisse unter `Program Files`
|
||
|
||
`BtsCatalogExplorer.ConnectionString` verwendet ausschließlich integrierte
|
||
Windows-Authentifizierung. Die Anwendung ruft weder `SaveChanges` noch eine andere
|
||
ändernde ExplorerOM-Methode auf.
|
||
|
||
Die Eigenschaft `Applications` liefert auch Anwendungen ohne Ports. Pro Anwendung
|
||
werden nur folgende Eigenschaften gelesen:
|
||
|
||
- `Name`
|
||
- `SendPorts`
|
||
- `SendPort.PrimaryTransport.TransportType.Name`
|
||
- `SendPort.SecondaryTransport.TransportType.Name`
|
||
- `ReceivePorts`
|
||
- `ReceivePort.ReceiveLocations`
|
||
- `ReceiveLocation.TransportType.Name`
|
||
|
||
### 4.4 Receive-Endpunkte
|
||
|
||
Eine Receive Location zählt als ein Endpunkt. Der Adaptername stammt aus
|
||
`ReceiveLocation.TransportType.Name`. Ein Receive Port ist nur ein Container und
|
||
zählt selbst nicht als Endpunkt.
|
||
|
||
### 4.5 Send-Endpunkte
|
||
|
||
Bei einem Send Port zählt die primäre Transportkonfiguration als ein Endpunkt. Ist
|
||
eine sekundäre Transportkonfiguration vorhanden, zählt sie als zusätzlicher
|
||
Endpunkt.
|
||
|
||
Fehlt ein Adaptername, wird `Unbekannt` verwendet. Die Anwendung ist durch die
|
||
Iteration innerhalb von `Application.SendPorts` beziehungsweise
|
||
`Application.ReceivePorts` eindeutig vorgegeben.
|
||
|
||
## 5. Snapshot-Format
|
||
|
||
Das JSON enthält nur normalisierte Katalogdaten:
|
||
|
||
```json
|
||
{
|
||
"SchemaVersion": 1,
|
||
"EnvironmentName": "ACC",
|
||
"ComputerName": "BIZTALK-ACC",
|
||
"CreatedUtc": "2026-07-27T13:00:00.0000000Z",
|
||
"IsComplete": true,
|
||
"Applications": [
|
||
{
|
||
"Name": "ExampleApplication",
|
||
"EndpointCount": 2,
|
||
"AdapterCounts": [
|
||
{ "AdapterType": "FILE", "Count": 1 },
|
||
{ "AdapterType": "SFTP", "Count": 1 }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Vor einem Merge werden geprüft:
|
||
|
||
- `SchemaVersion` ist `1`
|
||
- erwartete Umgebung ist exakt `ACC` beziehungsweise `PROD`
|
||
- `IsComplete` ist `true`
|
||
- Namen und Adaptertypen sind nicht leer
|
||
- Zählwerte sind nicht negativ
|
||
- Summe der Adapterzählungen entspricht `EndpointCount`
|
||
|
||
JSON und XLSX werden über eine temporäre Datei geschrieben und erst nach erfolgreichem Abschluss auf den endgültigen Dateinamen verschoben.
|
||
|
||
## 6. Merge-Regeln
|
||
|
||
Anwendungsnamen werden ohne Beachtung der Groß-/Kleinschreibung verglichen. Für die Anzeige wird bei einer gemeinsamen Anwendung bevorzugt die Schreibweise aus ACC verwendet.
|
||
|
||
| Situation | Umgebung | ACC | PRD | Hinweis |
|
||
| --- | --- | --- | --- | --- |
|
||
| in beiden vorhanden | `ACC + PRD` | `✓` | `✓` | leer |
|
||
| nur ACC | `nur ACC` | `✓` | `–` | `Nur in ACC vorhanden` |
|
||
| nur PROD | `nur PRD` | `–` | `✓` | `Nur in PRD vorhanden – nicht in ACC` |
|
||
|
||
Die Endpunktanzahl einer gemeinsamen Zeile ist die Summe beider Umgebungen.
|
||
|
||
Sind die Adapterzählungen identisch, erscheint nur eine kompakte Darstellung:
|
||
|
||
```text
|
||
FILE (1x) / SFTP (1x)
|
||
```
|
||
|
||
Bei einer Abweichung bleiben beide Nachweise sichtbar:
|
||
|
||
```text
|
||
ACC: FILE (2x) | PRD: FILE (1x) / SFTP (1x)
|
||
```
|
||
|
||
Damit wird keine Übereinstimmung suggeriert, wenn lediglich die Gesamtzahl gleich ist.
|
||
|
||
## 7. Excel-Aufbau
|
||
|
||
Die Arbeitsmappe enthält genau:
|
||
|
||
```text
|
||
xl/worksheets/sheet1.xml -> Blatt "Phase 1"
|
||
```
|
||
|
||
Das Blatt besteht aus:
|
||
|
||
- Zeile 1: zusammengeführter Titel
|
||
- Zeile 2: sieben Spaltenüberschriften
|
||
- ab Zeile 3: alphabetisch sortierte Anwendungen
|
||
- letzte Zeile: zusammengeführte Summenzeile
|
||
|
||
Der Filter umfasst nur Kopf- und Datenzeilen, nicht die Summenzeile. Die ersten beiden Zeilen sind fixiert. Zelltexte werden als `inlineStr` gespeichert. Office und COM-Interop sind nicht erforderlich.
|
||
|
||
## 8. Fehlerverhalten
|
||
|
||
Die WMI-Gruppenermittlung und die vollständige ExplorerOM-Kataloglesung bilden
|
||
gemeinsam einen Pflichtabschnitt. Ein Fehler führt zu:
|
||
|
||
- Exitcode `1`
|
||
- Logeintrag
|
||
- JSON mit `IsComplete: false`
|
||
- lokaler XLSX auf Basis der bis dahin ermittelten Daten
|
||
|
||
Der Merge lehnt einen solchen JSON-Snapshot ab. Dadurch werden technische Lücken nicht als bestätigte Nullwerte in den ACC/PRD-Katalog übernommen.
|
||
|
||
Ungültige Parameter, fehlende Dateien, fehlerhaftes JSON und Schreibfehler liefern Exitcode `2`.
|
||
|
||
### 8.1 Diagnosedaten
|
||
|
||
Fortschrittsmeldungen werden gleichzeitig auf die Konsole und in eine
|
||
UTF-8-Logdatei geschrieben. Die Detailprotokollierung umfasst:
|
||
|
||
- Laufzeit-, Betriebssystem- und Prozessarchitektur
|
||
- Windows-Identität und Administratorstatus
|
||
- WMI-Namespace und Timeout
|
||
- vollständige WQL-Anweisung, Laufzeit und Datensatzanzahl
|
||
- BizTalk-Gruppe sowie Management-DB-Server und -Name
|
||
- ExplorerOM-Assemblyname, Version und Dateipfad
|
||
- jede gelesene Anwendung und jeden gezählten Endpunkt mit Adaptertyp
|
||
- Gesamtzahlen für Anwendungen, Send Ports, sekundäre Transporte, Receive Ports
|
||
und Receive Locations
|
||
|
||
Eine Ausnahme wird mit Typ, Meldung, HRESULT in Hexadezimalschreibweise,
|
||
`ManagementException.ErrorCode`, inneren Ausnahmen und Stacktrace ausgegeben.
|
||
`TargetInvocationException` wird dabei bis zur eigentlichen Provider- oder
|
||
Datenbankausnahme aufgelöst.
|
||
|
||
## 9. Sicherheit
|
||
|
||
- ausschließlich lesende lokale WMI-Abfragen
|
||
- ausschließlich lesende Katalogabfragen über das lokale BizTalk Explorer Object Model
|
||
- keine Aufrufe von `SaveChanges` oder ändernden BizTalk-Methoden
|
||
- keine selbst formulierten SQL-Abfragen; ExplorerOM liest die Management-Datenbank
|
||
über integrierte Windows-Authentifizierung
|
||
- keine Endpunktadressen
|
||
- keine Binding-Exporte
|
||
- keine Credentials, Secrets oder Tokens
|
||
- keine Netzwerkverbindungen zu fachlichen Endpunkten
|
||
|
||
Anwendungsnamen, Servernamen und Adapterverteilungen bleiben interne Betriebsinformationen. JSON, XLSX und Log sind geschützt abzulegen.
|
||
|
||
## 10. Build und Test
|
||
|
||
Baseline:
|
||
|
||
- Visual Studio 2019 / MSBuild 16.x
|
||
- klassisches MSBuild-Projektformat
|
||
- .NET Framework 4.7.2
|
||
- C# 7.3
|
||
- keine NuGet-Pakete
|
||
- kein .NET SDK erforderlich
|
||
- keine compile-time-Referenz auf `Microsoft.BizTalk.ExplorerOM.dll`
|
||
|
||
```cmd
|
||
scripts\build-release.cmd
|
||
```
|
||
|
||
Der Self-Test benötigt kein BizTalk und prüft:
|
||
|
||
- JSON-Schreiben und -Lesen
|
||
- Snapshot-Validierung
|
||
- ACC/PRD-Union
|
||
- Adapteraggregation
|
||
- Endpunktsummen
|
||
- ein einziges Blatt `Phase 1`
|
||
- erforderliche OPC-/XLSX-Teile
|
||
- XML-Wohlgeformtheit
|
||
- Titel- und Summen-Merges
|
||
- korrekten Filterbereich
|
||
|
||
## 11. Betriebsvalidierung
|
||
|
||
Je Umgebung:
|
||
|
||
1. `--self-test` erfolgreich ausführen.
|
||
2. Lokalen Lauf in administrativer `cmd.exe` starten.
|
||
3. Im Log die erfolgreiche WMI-Abfrage `MSBTS_GroupSetting` prüfen.
|
||
4. Im Log Assemblyname, Version und Pfad von ExplorerOM prüfen.
|
||
5. Exitcode `0` und `IsComplete: true` prüfen.
|
||
6. Anwendungsgesamtzahl mit der BizTalk Administration Console vergleichen.
|
||
7. Send Ports, sekundäre Transporte und Receive Locations stichprobenartig zählen.
|
||
8. Nur die vollständige JSON-Datei für den Merge verwenden.
|
||
|
||
Nach dem Merge:
|
||
|
||
1. Summen für ACC und PROD mit den lokalen Dateien vergleichen.
|
||
2. Anwendungen mit `nur ACC` und `nur PRD` fachlich prüfen.
|
||
3. Abweichend beschriftete ACC-/PRD-Adapterverteilungen prüfen.
|
||
4. Ergebnis geschützt archivieren.
|