biztalk-application-catalog/Readme.md

BEW BizTalk Application Catalog – Phase 1

Das Tool erzeugt nur die für die Phase-1-Excel-Sicht benötigten Daten:

Spalte	Inhalt
BizTalk-Anwendung	Name der BizTalk-Anwendung
Umgebung	ACC + PRD, nur ACC oder nur PRD
Adapter-Typ	Adapter mit Anzahl, zum Beispiel FILE (2x) / SFTP (1x)
Anzahl Endpunkte	Summe der Endpunkte in den berücksichtigten Umgebungen
BizTalk-Anwendung in ACC	✓ oder –
BizTalk-Anwendung in PRD	✓ oder –
Hinweis	Kennzeichnung einer nur einseitig vorhandenen Anwendung

Die Arbeitsmappe enthält exakt ein Blatt namens Phase 1. Es werden keine weiteren Übersichts-, Artefakt-, Port-, Host-, Abdeckungs- oder Findings-Blätter erzeugt.

Ablauf

ACC und PROD sind getrennte BizTalk-Umgebungen. Deshalb arbeitet das Tool in zwei Schritten:

1. Auf dem lokalen ACC-BizTalk-Server wird ein ACC-JSON-Snapshot erzeugt.
2. Auf dem lokalen PROD-BizTalk-Server wird ein PROD-JSON-Snapshot erzeugt.
3. Beide JSON-Dateien werden mit demselben Tool zur gemeinsamen Excel-Sicht zusammengeführt.

Jeder lokale Lauf erzeugt zusätzlich eine einblättrige Excel-Sicht für die jeweilige Umgebung. Erst der Merge liefert den belastbaren ACC/PRD-Vergleich wie in der Zielansicht.

Erfasste Daten

Das Tool verwendet zwei ausschließlich lesende, lokale BizTalk-Schnittstellen:

• 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:

• die primäre Transportkonfiguration eines Send Ports,
• eine konfigurierte sekundäre Transportkonfiguration eines Send Ports oder
• eine Receive Location.

Receive Ports selbst sind Container und werden nicht als Endpunkt gezählt. Anwendungen ohne Endpunkt bleiben mit 0 und Adapter-Typ – in der Sicht enthalten.

Nicht erfasst werden insbesondere Adressen, Credentials, Beschreibungen, Status, Hosts, Handler, Orchestrierungen, Schemas, Maps, Pipelines, Assemblies, Betriebssystem- oder SQL-Daten.

Voraussetzungen

• 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
• 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.

Lokalen Snapshot erzeugen

Zuerst den Self-Test ausführen:

BizTalkApplicationCatalog.exe --self-test

ACC:

run-inventory.cmd ACC C:\BizTalk-Doku\ACC

PROD:

run-inventory.cmd PROD C:\BizTalk-Doku\PROD

Ergebnis eines erfolgreichen lokalen Laufs:

Phase1-BizTalk-Anwendungskatalog-ACC-SERVER-20260727-150000.json
Phase1-BizTalk-Anwendungskatalog-ACC-SERVER-20260727-150000.xlsx
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:

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:

run-merge.cmd ^
  C:\BizTalk-Doku\ACC\Phase1-BizTalk-Anwendungskatalog-ACC-SERVER-20260727-150000.json ^
  C:\BizTalk-Doku\PROD\Phase1-BizTalk-Anwendungskatalog-PROD-SERVER-20260727-151500.json ^
  C:\BizTalk-Doku\ACC-PROD

Direkter Aufruf:

BizTalkApplicationCatalog.exe ^
  --merge ^
  --acc-json C:\BizTalk-Doku\ACC\ACC.json ^
  --prod-json C:\BizTalk-Doku\PROD\PROD.json ^
  --output C:\BizTalk-Doku\ACC-PROD

Die gemeinsame Datei heißt beispielsweise:

Phase1-BizTalk-Anwendungskatalog-ACC-PROD-20260727-153000.xlsx

Bei identischer Adapterverteilung in ACC und PROD wird sie einmal angezeigt. Bei Abweichungen kennzeichnet die Zelle beide Werte, zum Beispiel:

ACC: FILE (2x) | PRD: FILE (1x) / SFTP (1x)

Anzahl Endpunkte ist im Merge die Summe aus ACC und PROD.

Optionen und Exitcodes

Option	Bedeutung
--environment ACC|PROD	lokaler Inventarlauf
--output PFAD	Zielordner
--merge	ACC- und PROD-Snapshot zusammenführen
--acc-json PFAD	vollständiger ACC-Snapshot
--prod-json PFAD	vollständiger PROD-Snapshot
--self-test	JSON-, Merge- und XLSX-Test ohne BizTalk
--help	Hilfe

Exitcode	Bedeutung
0	Snapshot beziehungsweise Merge vollständig erzeugt
1	lokaler Pflichtabschnitt unvollständig; JSON nicht mergen
2	Aufruf-, Datei-, JSON- oder XLSX-Fehler

Build

Die Solution verwendet das klassische MSBuild-Projektformat für Visual Studio 2019 / MSBuild 16.x, .NET Framework 4.7.2 und C# 7.3. Es gibt keine NuGet-Abhängigkeiten.

scripts\build-release.cmd
scripts\package-release.cmd

Quellpaket als certutil-Text

scripts\package-source.cmd

Erzeugt:

artifacts\BizTalkApplicationCatalog-source.zip
artifacts\BizTalkApplicationCatalog-source.zip.txt

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.