biztalk-sap-environment-inventory/Dokumentation.md

Technische Dokumentation: BEW BizTalk SAP Environment Inventory

1. Zielbild und Topologie

Das Tool erzeugt je Umgebung einen belastbaren Ist-Bericht der SAP-Adapterkonfiguration und der vollständigen BizTalk-Anwendungsliste.

ACC
  +-- 1 BizTalk Server 2020  <-- Tool lokal ausführen
  +-- 1 SQL Server           <-- BizTalk-Datenbanken

PROD
  +-- 1 BizTalk Server 2020  <-- Tool lokal ausführen
  +-- 1 SQL Server           <-- BizTalk-Datenbanken

Es gibt in ACC und PROD jeweils keinen zweiten BizTalk-Knoten, der verglichen werden müsste. Die Berichte sind getrennt zu erzeugen und anschließend gegenüberzustellen.

Aufgabenbezug:

• SAP-Adapter-Verbindungsparameter dokumentieren
• vollständige BizTalk-Anwendungsliste statt einer unvollständigen bisherigen App-Liste erzeugen
• tatsächliche Zuordnung der SAP-Verbindungen zu BizTalk-Anwendungen herstellen
• ERP-/ISU-Receive- und Send-Hosts dokumentieren
• SNC-Konfiguration, Bibliotheken und Zertifikats-/PSE-Metadaten erfassen
• IDoc-Basistypen/Erweiterungen sowie WE20/WE21 als Nachweise adressieren
• DR-Abhängigkeit zur SAP-seitigen Umschaltung nach Frankfurt sichtbar machen

2. Architektur

Administrative cmd.exe
  |
  +-- run-inventory.cmd ACC|PROD
        |
        +-- BizTalkSapEnvironmentInventory.exe
              |
              +-- SystemCollector
              |     +-- Windows WMI
              |     +-- BizTalk Registry
              |     +-- MSBTS_GroupSetting für Management SQL/DB
              |
              +-- BizTalkWmiCollector
              |     +-- ExplorerOM: Anwendungen, Assemblies, Schemas,
              |     |               Maps und Pipelines
              |     +-- root\MicrosoftBizTalkServer
              |     +-- Orchestrierungen, Ports, Adapter, Hosts und Handler
              |     +-- optionaler SAP-Endpunkt-Fallback
              |
              +-- BindingExportCollector
              |     +-- BTSTask ExportBindings /GroupLevel
              |     +-- WCF-SAP und WCF-Custom/sapBinding
              |     +-- SAP-URI und CustomProps
              |     +-- Secret-Redaktion
              |
              +-- SapRuntimeCollector
              |     +-- Adapter Pack/NCo-Installationen
              |     +-- Runtime-Dateiversion und Architektur
              |     +-- SNC/PSE/Zertifikatsmetadaten
              |
              +-- DocxReportWriter
                    +-- Office Open XML
                    +-- atomare Ausgabe

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

3.1 System und Registry

Windows-Daten stammen aus root\cimv2. BizTalk-Installations- und Managementinformationen werden in beiden Registry-Ansichten unter folgenden Schlüsseln gesucht:

HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0
HKLM\SOFTWARE\Microsoft\BizTalk Server\3.0\Administration

Ermittelt werden unter anderem:

• Produktname, Version und Edition
• Installationspfad
• BizTalk Management SQL Server
• BizTalk Management Database
• Betriebssystem, Build und Prozessarchitektur

Kommandozeilenparameter überschreiben automatisch ermittelte Management-DB-Werte.

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:

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 bereitgestellten Assemblies und deren Schemas, Transforms/Maps und Pipelines werden aus denselben Anwendungsobjekten gelesen. 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 BizTalk-WMI-Laufzeitdaten

Primärer Namespace:

root\MicrosoftBizTalkServer

Verwendete BizTalk-WMI-Klassen:

• MSBTS_Orchestration
• MSBTS_SendPort
• MSBTS_SendPortGroup
• MSBTS_ReceivePort
• MSBTS_ReceiveLocation
• MSBTS_AdapterSetting
• MSBTS_ReceiveHandler
• MSBTS_SendHandler2 bzw. MSBTS_SendHandler
• MSBTS_HostSetting
• MSBTS_HostInstance

MSBTS_Assembly, MSBTS_Schema, MSBTS_Map und MSBTS_Pipeline werden bewusst nicht abgefragt: Sie waren auf ACC nicht registriert und gehören nicht zu den dokumentierten WMI-Kernklassen. Die entsprechenden Daten stammen aus ExplorerOM.

Eine fehlende optionale Laufzeitklasse 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 je Artefakttyp auf standardmäßig 5000. Die Anwendungsliste selbst wird nicht begrenzt.

3.4 BTSTask-Gruppenbinding

Das Tool verwendet:

BTSTask.exe ExportBindings ^
  /GroupLevel ^
  /Destination:"<temporäre Datei>" ^
  /Server:"<Management SQL Server>" ^
  /Database:"<Management Database>"

/GroupLevel ist entscheidend: Ohne diesen Parameter würde BTSTask nur die Default-Anwendung exportieren und die geforderte vollständige Port-/App-Zuordnung wäre nicht gewährleistet.

Die temporäre XML-Datei wird:

1. in einem eindeutigen Temp-Pfad erzeugt,
2. mit deaktivierter DTD-/External-Entity-Auflösung gelesen,
3. ausschließlich in sichere Berichtsmodelle überführt,
4. im finally-Block gelöscht.

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

3.5 Offline-Binding

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

BizTalkSapEnvironmentInventory.exe ^
  --environment ACC ^
  --binding-file C:\Temp\ACC-GroupBindings.xml

Die Datei wird nicht verändert.

4. SAP-Endpunkterkennung

Ein Endpunkt wird als SAP-relevant erkannt, wenn mindestens eines zutrifft:

• Adaptername enthält SAP
• Adresse beginnt mit sap://
• Binding Type enthält sapBinding
• Custom Properties enthalten Microsoft.Adapters.SAP

Dadurch werden sowohl dedizierte WCF-SAP-Ports als auch WCF-Custom-Ports mit SAP Custom Binding erkannt.

5. SAP-Verbindungsparameter

5.1 SAP-URI

Beispiel:

sap://Client=100;lang=DE@A/sap.example.local/00
  ?GwHost=gateway.example.local
  &GwServ=sapgw00
  &ListenerProgramId=BIZTALK_ACC

Ausgewertete Parameter:

Gruppe	Parameter
Login	Client, Language
Application Server	Host, System Number
Message Server	Host, R/3 System Name, Gruppe
Destination	Destination Name
Gateway	GwHost, GwServ
RFC Listener	ListenerDest, ListenerGwHost, ListenerGwServ, ListenerProgramId
Routing	SAPROUTER
Security	UseSnc

5.2 Binding Properties

TransportTypeData und ReceiveLocationTransportTypeData enthalten bei WCF-Adaptern verschachtelte CustomProps und teilweise nochmals XML-kodierte Bindingkonfiguration. Der Parser verarbeitet diese Ebenen begrenzt rekursiv und erfasst unter anderem:

• BindingType
• UseSnc
• SncLibrary
• SncPartnerName
• SncMyName
• SncQop
• AffiliateApplicationName
• UserName
• Action und ActionMapping

Große Werte werden im Bericht begrenzt. Sensitive Werte werden vor Aufnahme in das Modell redigiert.

5.3 Anwendungszuordnung

Die Zuordnung erfolgt in dieser Reihenfolge:

1. ApplicationName im Gruppenbinding
2. gleichnamiger Send Port oder Receive Port aus WMI
3. keine Schätzung; stattdessen Finding

Damit wird sichtbar, welche der vollständigen BizTalk-Anwendungen tatsächlich SAP-Ports verwendet.

6. SAP NCo und Prozessarchitektur

Gesucht werden:

• installierter Microsoft BizTalk Adapter Pack/WCF LOB Adapter SDK
• SAP .NET Connector
• sapnco.dll
• sapnco_utils.dll
• SAP Cryptographic Library
• sapgenpse.exe

Für gefundene PE-Dateien werden Dateiversion, Produktversion, Änderungszeit und PE-Architektur dokumentiert. Dies unterstützt die Prüfung, ob der jeweilige 32-/64-Bit-BizTalk-Host zur installierten SAP-Laufzeit passt.

Die Erfassung durchsucht nur klar begrenzte Installations- und Konfigurationspfade bis zu einer Maximalebene. Es findet keine unbeschränkte Volltextsuche über alle Laufwerke statt.

7. SNC und Credential-Sicherheit

Der Security-Modus wird aus den Bindingparametern klassifiziert:

1. UseSnc=true → SAP SNC
2. SSO Affiliate Application vorhanden → Enterprise SSO
3. Benutzername vorhanden → SAP-Benutzer
4. sonst nicht eindeutig ableitbar

Dokumentiert werden dürfen:

• SAP-Benutzername oder SSO-Referenz
• SNC-Partner-/My-Name
• SNC-Bibliothek und QOP
• PSE-/Zertifikatspfad
• Fingerprint und Gültigkeit
• Vorhandensein eines privaten Schlüssels bei X.509-Zertifikaten

Nicht dokumentiert werden:

• Kennwörter
• PSE-Inhalte
• private Schlüssel
• Tokens
• entschlüsselbare Connection Strings

Rotation und Owner sind keine technischen Bindingeigenschaften. Sie bleiben als manueller Security-Nachweis offen.

8. IDoc, WE20 und WE21

8.1 Automatisch belegbare Indikatoren

Das Tool sucht nach SAP-/IDoc-Indikatoren in:

• Schema- und Assemblynamen
• Target Namespaces und Root Names
• WCF Actions
• SAP-Adapteroperationen

Dies kann IDoc-Basistypen wie beispielsweise ORDERS05 sichtbar machen, ist aber kein Ersatz für eine SAP-seitige Bestandsaufnahme.

8.2 SAP-seitige Pflichtnachweise

Von SAP Basis beziehungsweise dem Fachteam beizustellen:

Bereich	Benötigte Daten
WE20	Partner, Nachrichtentyp, Basistyp, Erweiterung, Empfängerport, Verarbeitungsoptionen
WE21	Portname, RFC-Destination, IDoc-Version, WE20-Zuordnung
RFC Destination	Typ, Zielsystem, Gateway, Program ID, Verbindungstest
IDoc	vollständige Liste der Basistypen und kundeneigenen Erweiterungen

Das Tool markiert diese Punkte in jedem DOCX als offen, selbst wenn einzelne Namen aus dem BizTalk-Binding abgeleitet werden konnten.

9. Disaster Recovery

Der lokale BizTalk-Bericht zeigt die aktuell konfigurierten RFC-/Gateway-/Listenerwerte. Er kann nicht entscheiden, ob und wie die RFC-Destination im SAP-System auf Frankfurt umgeschaltet wird.

Das DR-Runbook muss mindestens enthalten:

1. Owner und Freigabe für die Umschaltung
2. betroffene RFC-Destinationen
3. Zielwerte in Frankfurt
4. SNC-PSE/Bibliothek und Identität am DR-Ziel
5. Reihenfolge BizTalk/SAP
6. Verbindungstest
7. Rückschaltung
8. Dokumentation des letzten Tests

10. Resilienz

• Collector-Isolation mit eigenem Status und Zeitmessung
• WMI nur lokal über \\.\root\MicrosoftBizTalkServer
• WMI-Timeout, WQL-, Laufzeit- und Datensatzprotokollierung
• vollständige Anwendungsliste über read-only ExplorerOM statt MSBTS_Application
• Assemblies, Schemas, Maps und Pipelines über ExplorerOM statt nicht registrierter WMI-Klassen
• Reflection unterstützt auch explizit implementierte ExplorerOM-Interfaces
• 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 ohne doppelte Port-Abfragen
• Offline-Bindingmodus
• optionale Zugriffsfehler werden als Warnung protokolliert und stoppen den Lauf nicht
• begrenzte Dateisystemsuche
• Fehlerisolation bei Registry, Zertifikaten und Dateimetadaten
• XML-Parser ohne DTD/External Entities
• 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

Der Report Writer erzeugt ein standardkonformes Office-Open-XML-Paket mit:

[Content_Types].xml
_rels/.rels
docProps/core.xml
docProps/app.xml
word/document.xml
word/styles.xml
word/_rels/document.xml.rels

Alle Texte werden über XmlWriter geschrieben. Dadurch werden Host-, Anwendungs- und Portnamen als Text behandelt und können kein XML-Markup einschleusen.

12. Lauf auf ACC und PROD

Auf jedem der beiden BizTalk Server:

1. Deployment in einen lokalen Ordner kopieren.
2. Administrative cmd.exe öffnen.
3. BizTalkSapEnvironmentInventory.exe --self-test ausführen.
4. Erfassung starten.
5. Exitcode prüfen.
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:

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

PROD:

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

13. Build und Tests

Buildbaseline:

• klassisches MSBuild-Projekt
• .NET Framework 4.7.2
• C# 7.3
• Visual Studio 2019/MSBuild 16.x
• keine SDK-style-Projekte
• keine NuGet-Pakete

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

Tests prüfen:

• Secret-Redaktion in XML und SAP-URI
• Parsing eines WCF-SAP-Gruppenbindings
• SAP-Client, Host und UseSnc
• Anwendungszuordnung
• Diagnose-Logging mit HRESULT und innerer Reflection-Ausnahme
• ExplorerOM-Artefakte einschließlich expliziter Interface-Eigenschaften
• DOCX-Paketstruktur
• XML-Gültigkeit aller DOCX-Parts
• Ausschluss von Testkennwörtern

14. Bekannte Grenzen

• kein SAP-Login
• kein aktiver RFC-Ping
• keine direkte Abfrage von WE20, WE21 oder SM59
• keine Auflösung von Credential-Owner oder Rotation
• 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
• Microsoft: Security between the SAP system and the adapter