Fix BizTalk catalog collection and diagnostics

Dokumentation.md

@@ -21,7 +21,7 @@ ACC und PROD besitzen jeweils einen lokalen BizTalk Server 2020. Ein Prozess auf
 ```text
 ACC BizTalk Server                 PROD BizTalk Server
         |                                  |
-        | lokales WMI                      | lokales WMI
+        | WMI + ExplorerOM                  | WMI + ExplorerOM
         v                                  v
   ACC JSON + lokale XLSX             PROD JSON + lokale XLSX
         \                                  /
@@ -42,10 +42,9 @@ CommandLineOptions
   +-- validiert lokalen Modus oder Merge-Modus
 
 BizTalkWmiCollector
-  +-- MSBTS_Application
-  +-- MSBTS_ReceivePort
-  +-- MSBTS_SendPort
-  +-- MSBTS_ReceiveLocation
+  +-- lokales MSBTS_GroupSetting per WMI
+  +-- lädt Microsoft.BizTalk.ExplorerOM aus GAC/Installationspfad
+  +-- Anwendungen und Ports per BtsCatalogExplorer
 
 SnapshotStore
   +-- normalisiert je Anwendung Adapterzählungen
@@ -58,37 +57,83 @@ XlsxReportWriter
   +-- Titel, Filter, Freeze Pane und Summenzeile
 ```
 
-## 4. WMI-Datenmodell
+## 4. Datenzugriff
 
-### 4.1 Anwendungen
+### 4.1 Ursache des Fehlers `Invalid class`
 
-`MSBTS_Application` ist die Pflichtquelle der Anwendungsliste. Verwendet wird nur `Name` beziehungsweise `ApplicationName`.
+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`.
 
-Die Abfrage muss mindestens eine Anwendung liefern. Andernfalls ist der lokale Lauf unvollständig.
+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 Receive-Endpunkte
+### 4.2 Lokale Gruppenermittlung per WMI
 
-Eine `MSBTS_ReceiveLocation` zählt als ein Endpunkt. Der Adapter wird defensiv aus `AdapterName`, `TransportType` oder `PTTransportType` gelesen.
+Verwendeter Namespace:
 
-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.
+```text
+\\.\root\MicrosoftBizTalkServer
+```
 
-### 4.3 Send-Endpunkte
+Verwendete Abfrage:
 
-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.
+```sql
+SELECT Name, MgmtDbServerName, MgmtDbName FROM MSBTS_GroupSetting
+```
 
-Primärer Adapter:
+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.
 
-- `PTTransportType`
-- Fallback `PrimaryTransportType`
-- Fallback `AdapterName`
-- Fallback `TransportType`
+### 4.3 Kataloglesung per Explorer Object Model
 
-Sekundärer Adapter:
+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.
 
-- `STTransportType`
-- Fallback `SecondaryTransportType`
+Ladestrategie:
 
-Fehlt ein gelieferter Adaptername, wird `Unbekannt` verwendet. Ein Endpunkt ohne Anwendungszuordnung macht den Lauf unvollständig, weil er sonst in der Anwendungssicht verloren ginge.
+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
 
@@ -170,7 +215,8 @@ Der Filter umfasst nur Kopf- und Datenzeilen, nicht die Summenzeile. Die ersten
 
 ## 8. Fehlerverhalten
 
-Alle vier WMI-Abfragen bilden einen Pflichtabschnitt. Ein Fehler führt zu:
+Die WMI-Gruppenermittlung und die vollständige ExplorerOM-Kataloglesung bilden
+gemeinsam einen Pflichtabschnitt. Ein Fehler führt zu:
 
 - Exitcode `1`
 - Logeintrag
@@ -181,11 +227,33 @@ Der Merge lehnt einen solchen JSON-Snapshot ab. Dadurch werden technische Lücke
 
 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
-- keine Änderungen an BizTalk-Konfiguration oder Runtime
-- keine SQL-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
@@ -203,6 +271,7 @@ Baseline:
 - C# 7.3
 - keine NuGet-Pakete
 - kein .NET SDK erforderlich
+- keine compile-time-Referenz auf `Microsoft.BizTalk.ExplorerOM.dll`
 
 ```cmd
 scripts\build-release.cmd
@@ -227,10 +296,12 @@ Je Umgebung:
 
 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.
+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: