Stabilize BizTalk inventory collection and diagnostics

2026-07-28 10:55:57 +02:00
parent 439427cc17
commit d1e10920c9
11 changed files with 1008 additions and 172 deletions
@@ -38,13 +38,13 @@ Administrative cmd.exe
              +-- SystemCollector
              |     +-- Windows WMI
              |     +-- BizTalk Registry
-              |     +-- Management SQL/DB
+              |     +-- MSBTS_GroupSetting für Management SQL/DB
              |
              +-- BizTalkWmiCollector
+              |     +-- ExplorerOM: vollständige Anwendungsliste
              |     +-- root\MicrosoftBizTalkServer
-              |     +-- Anwendungen und Artefakte
-              |     +-- Adapter, Hosts und Handler
-              |     +-- SAP-Endpunkt-Fallback
+              |     +-- optionale Artefakte, Adapter, Hosts und Handler
+              |     +-- optionaler SAP-Endpunkt-Fallback
              |
              +-- BindingExportCollector
              |     +-- BTSTask ExportBindings /GroupLevel
@@ -62,7 +62,13 @@ Administrative cmd.exe
                    +-- atomare Ausgabe
 ```

-Das Programm referenziert keine `Microsoft.BizTalk.*`-Assembly. Dadurch besteht das Deployment nur aus EXE, Konfiguration, Startskript und Dokumentation. Die BizTalk-Integration erfolgt über die offiziell vorhandenen Verwaltungsoberflächen WMI und `BTSTask.exe`.
+Das Programm besitzt keine compile-time-Referenz auf eine
+`Microsoft.BizTalk.*`-Assembly. Dadurch besteht das Deployment nur aus EXE,
+Konfiguration, Startskript und Dokumentation. Die lokal mit den
+BizTalk-Verwaltungskomponenten installierte
+`Microsoft.BizTalk.ExplorerOM.dll` wird zur Laufzeit aus GAC beziehungsweise
+Installationspfad geladen. Die übrige BizTalk-Integration erfolgt über WMI und
+`BTSTask.exe`.

 ## 3. Datenquellen

@@ -85,7 +91,30 @@ Ermittelt werden unter anderem:

 Kommandozeilenparameter überschreiben automatisch ermittelte Management-DB-Werte.

-### 3.2 BizTalk-WMI
+### 3.2 BizTalk-Gruppe und ExplorerOM
+
+Die Management-Datenbank wird zunächst aus Registry und lokalem
+`MSBTS_GroupSetting` ermittelt. Kommandozeilenparameter haben Vorrang. Die
+verwendete WQL-Abfrage wird mit Laufzeit und Datensatzanzahl protokolliert:
+
+```sql
+SELECT Name,MgmtDbServerName,MgmtDbName FROM MSBTS_GroupSetting
+```
+
+Die vollständige Anwendungsliste wird anschließend über
+`Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer` und integrierte
+Windows-Authentifizierung aus der BizTalk Management Database gelesen. Es werden
+keine ändernden ExplorerOM-Methoden aufgerufen. Die Connection String wird nicht
+protokolliert.
+
+Dieser Aufbau vermeidet die nicht verlässlich vorhandene WMI-Klasse
+`MSBTS_Application`, die je nach Installation mit `Invalid class` abbrechen kann.
+ExplorerOM-Assemblyname, Version und Dateipfad werden protokolliert. Wenn
+`MSBTS_GroupSetting` nicht gelesen werden kann, darf das automatisch oder per
+`--management-server`/`--management-database` ermittelte Datenbankziel weiterhin
+für ExplorerOM verwendet werden.
+
+### 3.3 Optionale BizTalk-WMI-Daten

 Primärer Namespace:

@@ -93,11 +122,6 @@ Primärer Namespace:
 root\MicrosoftBizTalkServer
 ```

-Pflichtquelle:
-
- `MSBTS_Application`
- `MSBTS_GroupSetting` wird zusätzlich zur sicheren Erkennung von Management SQL Server und Datenbank verwendet
-
 Optionale beziehungsweise versionsabhängige Artefaktklassen:

 - `MSBTS_Orchestration`
@@ -115,13 +139,16 @@ Optionale beziehungsweise versionsabhängige Artefaktklassen:
 - `MSBTS_HostSetting`
 - `MSBTS_HostInstance`

-Eine fehlende optionale Klasse erzeugt einen Hinweis, verhindert aber nicht die Anwendungsliste oder den Word-Bericht.
+Eine fehlende optionale Klasse erzeugt einen Hinweis, verhindert aber nicht die
+ExplorerOM-Anwendungsliste oder den Word-Bericht. Ist der gesamte BizTalk-WMI-
+Namespace für diese Zusatzdaten nicht erreichbar, wird der WMI-Teil übersprungen;
+die zuvor geladene Anwendungsliste bleibt erhalten.

 Zum Schutz vor ungewöhnlich großen Artefaktmengen begrenzt `MaxArtifactDetailsPerType`
 die aufgenommenen Detaildatensätze pro WMI-Klasse auf standardmäßig 5000. Die
 Anwendungsliste selbst wird nicht begrenzt.

-### 3.3 BTSTask-Gruppenbinding
+### 3.4 BTSTask-Gruppenbinding

 Das Tool verwendet:

@@ -144,7 +171,7 @@ Die temporäre XML-Datei wird:

 Microsoft dokumentiert, dass Kennwörter beim Binding-Export entfernt werden. Zusätzlich redigiert das Tool sensitive Element-, Attribut- und URI-Werte.

-### 3.4 Offline-Binding
+### 3.5 Offline-Binding

 Für Diagnose- oder Berechtigungsfälle kann ein vorhandener Export verarbeitet werden:

@@ -306,8 +333,14 @@ Das DR-Runbook muss mindestens enthalten:
 ## 10. Resilienz

 - Collector-Isolation mit eigenem Status und Zeitmessung
- WMI-Timeout
+- WMI nur lokal über `\\.\root\MicrosoftBizTalkServer`
+- WMI-Timeout, WQL-, Laufzeit- und Datensatzprotokollierung
+- vollständige Anwendungsliste über read-only ExplorerOM statt
+  `MSBTS_Application`
+- dynamische ExplorerOM-Auflösung aus GAC und BizTalk-Installationspfad
+- WMI-Zusatzdaten dürfen nach erfolgreicher ExplorerOM-Erfassung ausfallen
 - Prozess-Timeout für `BTSTask`
+- live gespiegelte, secret-bereinigte BTSTask-Ausgabe
 - WMI-Fallback für SAP-Endpunkte
 - Offline-Bindingmodus
 - optionale WMI-Klassen stoppen den Lauf nicht
@@ -317,6 +350,8 @@ Das DR-Runbook muss mindestens enthalten:
 - atomare DOCX-Ausgabe
 - eindeutige Dateinamen mit Umgebung, Server und Zeitstempel
 - Exitcode `1` bei unvollständigem Pflichtabschnitt
+- vollständige Ausnahmeketten mit Typ, HRESULT, WMI-Status, inneren Ausnahmen
+  und Stacktrace auf Konsole und im Log

 ## 11. DOCX-Erzeugung ohne Office

@@ -343,10 +378,12 @@ Auf jedem der beiden BizTalk Server:
 3. `BizTalkSapEnvironmentInventory.exe --self-test` ausführen.
 4. Erfassung starten.
 5. Exitcode prüfen.
-6. DOCX und Log gemeinsam kontrollieren.
-7. Anwendungsliste gegen BizTalk Administration abgleichen.
-8. SAP-Endpunkte und Hostzuordnung prüfen.
-9. WE20-/WE21-/Credential-/DR-Findings an SAP Basis geben.
+6. Im Log `MSBTS_GroupSetting`, Datensatzanzahl und Management-Datenbankziel prüfen.
+7. ExplorerOM-Assemblyname, Version und Pfad kontrollieren.
+8. DOCX und Log gemeinsam kontrollieren.
+9. Anwendungsliste gegen BizTalk Administration abgleichen.
+10. SAP-Endpunkte und Hostzuordnung prüfen.
+11. WE20-/WE21-/Credential-/DR-Findings an SAP Basis geben.

 ACC:

@@ -382,6 +419,7 @@ Tests prüfen:
 - Parsing eines WCF-SAP-Gruppenbindings
 - SAP-Client, Host und `UseSnc`
 - Anwendungszuordnung
+- Diagnose-Logging mit HRESULT und innerer Reflection-Ausnahme
 - DOCX-Paketstruktur
 - XML-Gültigkeit aller DOCX-Parts
 - Ausschluss von Testkennwörtern
@@ -395,12 +433,15 @@ Tests prüfen:
 - keine Garantie, dass Schemanamen alle verwendeten IDoc-Erweiterungen enthalten
 - dynamisch zur Laufzeit konstruierte SAP-Adressen können im statischen Binding fehlen
 - WMI-Klassen unterscheiden sich teilweise je BizTalk-Version/CU
+- die lokal installierte ExplorerOM-Version muss zur lokalen BizTalk-Installation
+  passen
 - lokaler Ist-Stand; ACC und PROD müssen getrennt ausgeführt werden

 ## 15. Referenzen

 - Microsoft: BizTalk Server 2020 Hardware and Software Requirements
 - Microsoft: `BTSTask ExportBindings`
+- Microsoft: BizTalk Explorer Object Model
 - Microsoft: BizTalk WMI Technical Reference
 - Microsoft: WCF-SAP Port Configuration
 - Microsoft: SAP System Connection URI