228 lines
8.0 KiB
Markdown
228 lines
8.0 KiB
Markdown
# 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:
|
||
|
||
```cmd
|
||
BizTalkApplicationCatalog.exe --self-test
|
||
```
|
||
|
||
ACC:
|
||
|
||
```cmd
|
||
run-inventory.cmd ACC C:\BizTalk-Doku\ACC
|
||
```
|
||
|
||
PROD:
|
||
|
||
```cmd
|
||
run-inventory.cmd PROD C:\BizTalk-Doku\PROD
|
||
```
|
||
|
||
Ergebnis eines erfolgreichen lokalen Laufs:
|
||
|
||
```text
|
||
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:
|
||
|
||
```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:
|
||
|
||
```cmd
|
||
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:
|
||
|
||
```cmd
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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.
|
||
|
||
```cmd
|
||
scripts\build-release.cmd
|
||
scripts\package-release.cmd
|
||
```
|
||
|
||
## Quellpaket als certutil-Text
|
||
|
||
```cmd
|
||
scripts\package-source.cmd
|
||
```
|
||
|
||
Erzeugt:
|
||
|
||
```text
|
||
artifacts\BizTalkApplicationCatalog-source.zip
|
||
artifacts\BizTalkApplicationCatalog-source.zip.txt
|
||
```
|
||
|
||
Dekodieren:
|
||
|
||
```cmd
|
||
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).
|