Fix BizTalk catalog collection and diagnostics

Readme.md

@@ -26,12 +26,18 @@ Jeder lokale Lauf erzeugt zusätzlich eine einblättrige Excel-Sicht für die je
 
 ## Erfasste Daten
 
-Das Tool liest ausschließlich:
+Das Tool verwendet zwei ausschließlich lesende, lokale BizTalk-Schnittstellen:
 
-- `MSBTS_Application` für die vollständige Anwendungsliste
-- `MSBTS_SendPort` für primäre und gegebenenfalls sekundäre Send-Endpunkte
-- `MSBTS_ReceivePort` nur zur Zuordnung einer Receive Location zur Anwendung
-- `MSBTS_ReceiveLocation` für Receive-Endpunkte
+- WMI-Klasse `MSBTS_GroupSetting` im Namespace
+  `root\MicrosoftBizTalkServer`, um Server und Name der BizTalk-Management-Datenbank
+  der lokalen BizTalk-Gruppe zu ermitteln;
+- das lokal installierte `Microsoft.BizTalk.ExplorerOM`, um Anwendungen, Send Ports,
+  sekundäre Send-Transporte, Receive Ports und Receive Locations vollständig zu lesen.
+
+Das Explorer Object Model ist notwendig, weil es im BizTalk-WMI-Schema keine Klasse
+`MSBTS_Application` gibt. Die frühere Abfrage dieser nicht vorhandenen Klasse führte
+unmittelbar zu `Invalid class` beziehungsweise WMI-Status `InvalidClass`. Adminrechte
+ändern nicht, welche Klassen ein WMI-Provider bereitstellt.
 
 Ein Endpunkt ist:
 
@@ -48,8 +54,13 @@ Nicht erfasst werden insbesondere Adressen, Credentials, Beschreibungen, Status,
 - BizTalk Server 2020 auf Windows Server 2019
 - lokale Ausführung auf dem jeweiligen BizTalk-Server
 - .NET Framework 4.7.2 oder höher
+- lokal installierte BizTalk-Verwaltungskomponenten einschließlich
+  `Microsoft.BizTalk.ExplorerOM.dll`
 - Leserechte auf `root\MicrosoftBizTalkServer`
-- administrative `cmd.exe` empfohlen
+- Leserechte auf den BizTalk-Katalog, vorzugsweise über die konfigurierte Gruppe
+  `BizTalk Server Read Only Users` oder eine höher berechtigte BizTalk-Rolle
+- administrative `cmd.exe` ist für die Diagnose hilfreich, ersetzt aber keine
+  BizTalk- beziehungsweise SQL-Leseberechtigung
 
 Microsoft Excel, Microsoft Office, PowerShell, Internetzugriff, NuGet und ein .NET SDK werden auf dem Zielserver nicht benötigt.
 
@@ -83,6 +94,52 @@ Phase1-BizTalk-Anwendungskatalog-ACC-SERVER-20260727-150000.log
 
 Nur JSON-Dateien eines Laufs mit Exitcode `0` dürfen zusammengeführt werden. Ein unvollständiger Snapshot trägt `IsComplete: false` und wird vom Merge abgelehnt.
 
+## Konsolen- und Dateilogging
+
+Jede Logmeldung wird unmittelbar gleichzeitig auf der Konsole und in der `.log`-Datei
+ausgegeben. Der lokale Inventarlauf protokolliert unter anderem:
+
+- Computer, Betriebssystem, CLR- und Prozessarchitektur
+- Windows-Sicherheitskontext und erkannte Administratorrolle
+- WMI-Namespace, Timeout, WQL-Abfrage, Dauer und Datensatzanzahl
+- erkannte BizTalk-Gruppe sowie Management-Datenbankziel ohne Kennwort
+- geladene ExplorerOM-Assembly einschließlich Version und Pfad
+- jede Anwendung sowie Send Ports, sekundäre Transporte und Receive Locations
+- Adaptertyp und Summen je Erfassungsart
+- bei Fehlern: Ausnahmetyp, Meldung, HRESULT, WMI-Status, innere Ausnahmen und Stacktrace
+
+Die Logdatei enthält interne Namen und ist wie JSON und XLSX geschützt abzulegen.
+
+## Fehleranalyse
+
+### `Invalid class` direkt nach dem Start
+
+Dieser Fehler wurde in der früheren Version durch
+`SELECT * FROM MSBTS_Application` verursacht. `MSBTS_Application` ist keine
+BizTalk-WMI-Klasse. Die aktuelle Version verwendet diese Abfrage nicht mehr.
+
+Im neuen Log muss stattdessen zunächst diese Abfrage erscheinen:
+
+```text
+SELECT Name, MgmtDbServerName, MgmtDbName FROM MSBTS_GroupSetting
+```
+
+Tritt weiterhin `InvalidClass` auf, ist damit nicht mehr die Anwendungsklasse
+gemeint. Dann ist die lokale BizTalk-WMI-Registrierung zu prüfen. Entscheidend sind
+die protokollierten Felder `WQL`, `WMI-Status` und `HRESULT`.
+
+### ExplorerOM-Assembly fehlt
+
+Die BizTalk-Verwaltungskomponenten müssen auf dem ausführenden BizTalk-Server
+installiert sein. Das Log zeigt alle geprüften Ladewege und die gefundene
+Assemblyversion.
+
+### Zugriff auf den BizTalk-Katalog verweigert
+
+Eine administrativ gestartete `cmd.exe` allein garantiert keine Berechtigung auf den
+BizTalk-Katalog. Das ausführende Konto benötigt mindestens die passenden
+BizTalk-Leserechte. Nach einer Gruppenänderung ist eine neue Anmeldung erforderlich.
+
 ## ACC und PROD zusammenführen
 
 Beide JSON-Dateien in einen gemeinsamen, geschützten Ordner kopieren und ausführen:
@@ -164,4 +221,7 @@ Dekodieren:
 certutil -decode BizTalkApplicationCatalog-source.zip.txt BizTalkApplicationCatalog-source.zip
 ```
 
+Die `.txt`-Datei ist Base64 und enthält das vollständige Quellpaket einschließlich
+aktualisierter `Readme.md` und `Dokumentation.md`.
+
 Technische Details stehen in [Dokumentation.md](Dokumentation.md).