Reduce catalog to Phase 1 ACC/PROD view
This commit is contained in:
+213
-193
@@ -1,220 +1,240 @@
|
||||
# Technische Dokumentation: BEW BizTalk Application Catalog
|
||||
# Technische Dokumentation: BEW BizTalk Application Catalog – Phase 1
|
||||
|
||||
## 1. Zielbild
|
||||
## 1. Ziel und Abgrenzung
|
||||
|
||||
Das Werkzeug erstellt je Umgebung eine eigenständige Microsoft-Excel-Arbeitsmappe mit der vollständigen Liste der auf dem lokalen BizTalk Server 2020 installierten Anwendungen und den wichtigsten zugeordneten Kernparametern.
|
||||
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
|
||||
+-- 1 BizTalk Server 2020 / Windows Server 2019 <-- Tool lokal ausführen
|
||||
+-- 1 SQL Server für die BizTalk-Datenbanken
|
||||
|
||||
PROD
|
||||
+-- 1 BizTalk Server 2020 / Windows Server 2019 <-- Tool lokal ausführen
|
||||
+-- 1 SQL Server für die BizTalk-Datenbanken
|
||||
ACC BizTalk Server PROD BizTalk Server
|
||||
| |
|
||||
| lokales WMI | lokales WMI
|
||||
v v
|
||||
ACC JSON + lokale XLSX PROD JSON + lokale XLSX
|
||||
\ /
|
||||
\ /
|
||||
+---- Merge auf beliebigem -----+
|
||||
Windows-Rechner
|
||||
|
|
||||
v
|
||||
gemeinsame ACC/PRD-XLSX
|
||||
```
|
||||
|
||||
ACC und PROD werden getrennt inventarisiert. Da es pro Umgebung nur einen BizTalk-Knoten gibt, ist kein Node-Abgleich erforderlich.
|
||||
Der JSON-Snapshot ist das kleine Austauschformat zwischen den getrennten Erfassungen. Er enthält weder Endpunktadressen noch Credentials.
|
||||
|
||||
## 2. Architektur
|
||||
## 3. Komponenten
|
||||
|
||||
```text
|
||||
Administrative cmd.exe
|
||||
|
|
||||
+-- run-inventory.cmd ACC|PROD
|
||||
|
|
||||
+-- BizTalkApplicationCatalog.exe
|
||||
|
|
||||
+-- SystemCollector
|
||||
| +-- Win32_OperatingSystem
|
||||
| +-- lokale BizTalk Registry
|
||||
| +-- MSBTS_GroupSetting
|
||||
|
|
||||
+-- BizTalkWmiCollector
|
||||
| +-- vollständige Anwendungsliste
|
||||
| +-- Artefaktdetails
|
||||
| +-- Hosts und Handler
|
||||
| +-- Abdeckungsstatus pro Klasse
|
||||
|
|
||||
+-- XlsxReportWriter
|
||||
+-- Office Open XML / ZIP
|
||||
+-- Inline Strings, keine Shared-String-Abhängigkeit
|
||||
+-- Filter, Freeze Panes, Styles
|
||||
+-- atomarer Dateiaustausch
|
||||
CommandLineOptions
|
||||
+-- validiert lokalen Modus oder Merge-Modus
|
||||
|
||||
BizTalkWmiCollector
|
||||
+-- MSBTS_Application
|
||||
+-- MSBTS_ReceivePort
|
||||
+-- MSBTS_SendPort
|
||||
+-- MSBTS_ReceiveLocation
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Die Anwendung referenziert keine `Microsoft.BizTalk.*`-Assembly. Die einzige BizTalk-Schnittstelle ist der lokal installierte WMI-Provider. Dadurch besteht das Deployment nur aus EXE, Konfiguration, Startskript und Dokumentation.
|
||||
## 4. WMI-Datenmodell
|
||||
|
||||
## 3. Toolchain und Kompatibilität
|
||||
### 4.1 Anwendungen
|
||||
|
||||
Die Build-Baseline ist absichtlich auf die BizTalk-2020-Umgebung ausgerichtet:
|
||||
`MSBTS_Application` ist die Pflichtquelle der Anwendungsliste. Verwendet wird nur `Name` beziehungsweise `ApplicationName`.
|
||||
|
||||
- Visual Studio 2019 / Solution Version 16
|
||||
- MSBuild 16.x, insbesondere 16.11
|
||||
- klassisches MSBuild-Projektformat mit `ToolsVersion="15.0"`
|
||||
Die Abfrage muss mindestens eine Anwendung liefern. Andernfalls ist der lokale Lauf unvollständig.
|
||||
|
||||
### 4.2 Receive-Endpunkte
|
||||
|
||||
Eine `MSBTS_ReceiveLocation` zählt als ein Endpunkt. Der Adapter wird defensiv aus `AdapterName`, `TransportType` oder `PTTransportType` gelesen.
|
||||
|
||||
Da eine Receive Location abhängig vom WMI-Provider keine direkte `ApplicationName` liefern kann, wird vorher `MSBTS_ReceivePort` gelesen. Über `ReceivePortName` wird die Anwendung aufgelöst. Ein Receive Port zählt selbst nicht als Endpunkt.
|
||||
|
||||
### 4.3 Send-Endpunkte
|
||||
|
||||
Bei `MSBTS_SendPort` zählt die primäre Transportkonfiguration als ein Endpunkt. Ist eine sekundäre Transportkonfiguration vorhanden, zählt sie als zusätzlicher Endpunkt.
|
||||
|
||||
Primärer Adapter:
|
||||
|
||||
- `PTTransportType`
|
||||
- Fallback `PrimaryTransportType`
|
||||
- Fallback `AdapterName`
|
||||
- Fallback `TransportType`
|
||||
|
||||
Sekundärer Adapter:
|
||||
|
||||
- `STTransportType`
|
||||
- Fallback `SecondaryTransportType`
|
||||
|
||||
Fehlt ein gelieferter Adaptername, wird `Unbekannt` verwendet. Ein Endpunkt ohne Anwendungszuordnung macht den Lauf unvollständig, weil er sonst in der Anwendungssicht verloren ginge.
|
||||
|
||||
## 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
|
||||
|
||||
Alle vier WMI-Abfragen bilden 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`.
|
||||
|
||||
## 9. Sicherheit
|
||||
|
||||
- ausschließlich lesende lokale WMI-Abfragen
|
||||
- keine Änderungen an BizTalk-Konfiguration oder Runtime
|
||||
- keine SQL-Abfragen
|
||||
- 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 SDK-Style-Projekte
|
||||
- kein `PackageReference`
|
||||
- keine `global.json`
|
||||
- keine NuGet-Abhängigkeit
|
||||
|
||||
Damit wird nicht das installierte .NET SDK 8 oder neuer ausgewählt. Der bekannte Fehler „.NET SDK 8.x requires at least MSBuild 17.8.3“ kann bei dieser Solution nicht durch eine SDK-Auswahl entstehen.
|
||||
|
||||
## 4. Datenquellen
|
||||
|
||||
### 4.1 Pflichtquelle
|
||||
|
||||
`MSBTS_Application` liefert die Primärliste aller Anwendungen. Liefert diese Klasse keine Datensätze oder kann sie nicht gelesen werden, gilt der Pflichtabschnitt als fehlgeschlagen und der Prozess endet nach der dennoch versuchten XLSX-Erzeugung mit Exitcode `1`.
|
||||
|
||||
Aufgenommene Parameter:
|
||||
|
||||
- `Name` beziehungsweise `ApplicationName`
|
||||
- `Description`
|
||||
- `Status`
|
||||
- `IsDefault`, soweit vom Provider geliefert
|
||||
|
||||
### 4.2 Optionale Artefaktklassen
|
||||
|
||||
| WMI-Klasse | Berichtstyp |
|
||||
| --- | --- |
|
||||
| `MSBTS_Orchestration` | Orchestrierung |
|
||||
| `MSBTS_SendPort` | Send Port |
|
||||
| `MSBTS_SendPortGroup` | Send Port Group |
|
||||
| `MSBTS_ReceivePort` | Receive Port |
|
||||
| `MSBTS_ReceiveLocation` | Receive Location |
|
||||
| `MSBTS_Assembly` | Assembly |
|
||||
| `MSBTS_Schema` | Schema |
|
||||
| `MSBTS_Map` | Map |
|
||||
| `MSBTS_Pipeline` | Pipeline |
|
||||
|
||||
Die WMI-Klassen können abhängig von Installation, Providerstand und Berechtigung unterschiedliche Properties anbieten. Deshalb fragt der Collector `SELECT *` ab und liest bekannte Properties defensiv. Eine nicht vorhandene Property wird leer gelassen und beendet die Klasse nicht.
|
||||
|
||||
Receive Ports werden vor Receive Locations gelesen. Fehlt an einer Receive Location die direkte `ApplicationName`, wird die Anwendung über `ReceivePortName` bestmöglich aufgelöst.
|
||||
|
||||
### 4.3 Hosts und Handler
|
||||
|
||||
- `MSBTS_HostSetting`
|
||||
- `MSBTS_HostInstance`
|
||||
- `MSBTS_ReceiveHandler`
|
||||
- `MSBTS_SendHandler2`
|
||||
- Fallback `MSBTS_SendHandler`
|
||||
|
||||
Erfasst werden Name, Server, Status, Hosttyp, Windows-Gruppe, 32-Bit-Kennzeichen, Trusted-Kennzeichen und Adaptername, soweit vorhanden.
|
||||
|
||||
### 4.4 Systeminformationen
|
||||
|
||||
- `Win32_OperatingSystem`
|
||||
- `HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0`
|
||||
- `HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0\Administration`
|
||||
- `MSBTS_GroupSetting`
|
||||
|
||||
Registry-Werte werden in 64- und 32-Bit-Ansicht gelesen. Kommandozeilenwerte für Management Server und Datenbank überschreiben ermittelte Werte.
|
||||
|
||||
## 5. Abdeckungsmodell
|
||||
|
||||
Jede abgefragte BizTalk-WMI-Klasse erzeugt einen Datensatz im Blatt `Abdeckung`:
|
||||
|
||||
| Status | Bedeutung |
|
||||
| --- | --- |
|
||||
| `Vollständig` | Abfrage erfolgreich; die angegebene Zeilenzahl ist technisch belegt |
|
||||
| `Begrenzt` | Abfrage erfolgreich, aber das konfigurierte Zeilenlimit wurde erreicht |
|
||||
| `Nicht verfügbar` | Klasse oder Berechtigung nicht verfügbar; eine Null ist nicht fachlich bestätigt |
|
||||
| `Fehler` | Pflichtquelle lieferte kein verwertbares Ergebnis |
|
||||
|
||||
Dieses Modell verhindert die irreführende Interpretation eines fehlenden WMI-Ergebnisses als „keine Artefakte vorhanden“.
|
||||
|
||||
`MaxRowsPerArtifactType` begrenzt optional die Details pro Artefakttyp. Der Standard ist `10000`. Die Anwendungsliste aus `MSBTS_Application` wird nicht begrenzt.
|
||||
|
||||
## 6. Excel-Erzeugung
|
||||
|
||||
Die `.xlsx`-Datei ist ein OPC-/ZIP-Paket mit folgenden Kernteilen:
|
||||
|
||||
```text
|
||||
[Content_Types].xml
|
||||
_rels/.rels
|
||||
docProps/core.xml
|
||||
docProps/app.xml
|
||||
xl/workbook.xml
|
||||
xl/_rels/workbook.xml.rels
|
||||
xl/styles.xml
|
||||
xl/worksheets/sheet1.xml ... sheet10.xml
|
||||
```
|
||||
|
||||
Zelltexte werden als `inlineStr` geschrieben. Dadurch wird keine Shared-String-Tabelle im Arbeitsspeicher aufgebaut. Zahlen werden als numerische Zellen gespeichert und können in Excel direkt summiert oder gefiltert werden.
|
||||
|
||||
Der Writer:
|
||||
|
||||
1. erzeugt eine eindeutige temporäre Datei im Zielordner,
|
||||
2. schreibt und schließt alle XML-/ZIP-Teile,
|
||||
3. entfernt eine gegebenenfalls vorhandene Zieldatei gleichen Namens,
|
||||
4. verschiebt die vollständige temporäre Datei atomar auf den Zielnamen,
|
||||
5. löscht temporäre Reste auch im Fehlerfall.
|
||||
|
||||
Ein einzelner Zelltext wird auf das Excel-Limit von 32.767 Zeichen begrenzt. Nicht XML-konforme Steuerzeichen werden entfernt.
|
||||
|
||||
## 7. Resilienz
|
||||
|
||||
- `SafeCollector` isoliert voneinander unabhängige Abschnitte.
|
||||
- Jeder Abschnitt schreibt Start, Ende, Dauer und Fehler in Konsole und Log.
|
||||
- Optionale WMI-Klassen werden einzeln behandelt.
|
||||
- Timeout und maximale Detailzeilen sind in `App.config` konfigurierbar.
|
||||
- Die XLSX wird auch bei optionalen Lücken erstellt.
|
||||
- Die vollständige Anwendungsliste ist ein Pflichtabschnitt.
|
||||
- Findings erklären Lücken und nennen eine konkrete Prüfung.
|
||||
|
||||
## 8. Datenschutz und Secrets
|
||||
|
||||
Das Inventar soll keine Credentials enthalten. Bekannte Kennwort-, Secret- und Tokenmuster in Text- und Adresswerten werden durch `[REDACTED]` ersetzt. Das ersetzt keine Schutzklassifizierung: interne Adressen, Servernamen, Hostgruppen und Anwendungsbezeichnungen bleiben sensible Betriebsinformationen.
|
||||
|
||||
Es werden keine Kennwörter abgefragt, keine Bindings exportiert und keine aktiven Endpunktverbindungen getestet.
|
||||
|
||||
## 9. Build, Test und Paketierung
|
||||
|
||||
Windows-Build:
|
||||
- keine NuGet-Pakete
|
||||
- kein .NET SDK erforderlich
|
||||
|
||||
```cmd
|
||||
scripts\build-release.cmd
|
||||
```
|
||||
|
||||
Der Build:
|
||||
Der Self-Test benötigt kein BizTalk und prüft:
|
||||
|
||||
1. findet MSBuild über `vswhere.exe` oder `PATH`,
|
||||
2. baut `Release|Any CPU`,
|
||||
3. führt das Testprogramm aus,
|
||||
4. führt den Self-Test der eigentlichen EXE aus.
|
||||
- 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
|
||||
|
||||
Der Self-Test benötigt kein BizTalk. Er prüft:
|
||||
|
||||
- Secret-Redaktion
|
||||
- Erstellung aller zehn Tabellenblätter
|
||||
- Vorhandensein der erforderlichen OPC-/XLSX-Teile
|
||||
- XML-Wohlgeformtheit aller Paketbestandteile
|
||||
- erwartete Blattnamen
|
||||
- Abwesenheit des Testkennworts
|
||||
|
||||
Deployment:
|
||||
|
||||
```cmd
|
||||
scripts\package-release.cmd
|
||||
```
|
||||
|
||||
Quell-ZIP und certutil-dekodierbarer Text:
|
||||
|
||||
```cmd
|
||||
scripts\package-source.cmd
|
||||
```
|
||||
|
||||
## 10. Validierung in ACC und PROD
|
||||
## 11. Betriebsvalidierung
|
||||
|
||||
Je Umgebung:
|
||||
|
||||
1. EXE mit `--self-test` starten.
|
||||
2. Inventar in einer administrativen `cmd.exe` ausführen.
|
||||
3. Exitcode und Log prüfen.
|
||||
4. XLSX öffnen und Blatt `Abdeckung` prüfen.
|
||||
5. Zahl der Anwendungen mit der BizTalk Administration Console vergleichen.
|
||||
6. Stichproben für Ports, Orchestrierungen und Assemblies durchführen.
|
||||
7. XLSX und Log im geschützten Umgebungsordner archivieren.
|
||||
1. `--self-test` erfolgreich ausführen.
|
||||
2. Lokalen Lauf in administrativer `cmd.exe` starten.
|
||||
3. Exitcode `0` und Log prüfen.
|
||||
4. Anwendungsgesamtzahl mit der BizTalk Administration Console vergleichen.
|
||||
5. Send Ports, sekundäre Transporte und Receive Locations stichprobenartig zählen.
|
||||
6. Nur die vollständige JSON-Datei für den Merge verwenden.
|
||||
|
||||
ACC- und PROD-Dateien dürfen nicht zusammengeführt werden, ohne die Spalten `Umgebung` und `Server` beizubehalten.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user