# Technische Dokumentation: BEW BizTalk Application Catalog – Phase 1

## 1. Ziel und Abgrenzung

Das Werkzeug bildet ausschließlich die Phase-1-Sicht `BizTalk Anwendungen & Adapter` ab. Das fachliche Ergebnis ist ein einblättriger ACC/PRD-Katalog mit:

1. BizTalk-Anwendung
2. Umgebung
3. Adapter-Typ und Anzahl
4. Endpunktanzahl
5. Vorkommen in ACC
6. Vorkommen in PRD
7. Hinweis bei einseitigem Vorkommen

Es ist kein technisches Vollinventar. Frühere Detailbereiche zu System, SQL, Status, Ports, Orchestrierungen, Schemas, Maps, Pipelines, Assemblies, Hosts, Handlern, Abdeckung und Findings sind nicht Bestandteil der XLSX und werden nicht mehr erhoben.

## 2. Verteilte Erfassung

ACC und PROD besitzen jeweils einen lokalen BizTalk Server 2020. Ein Prozess auf einem Server soll die andere Umgebung nicht remote abfragen.

```text
ACC BizTalk Server                 PROD BizTalk Server
        |                                  |
        | lokales WMI                      | lokales WMI
        v                                  v
  ACC JSON + lokale XLSX             PROD JSON + lokale XLSX
        \                                  /
         \                                /
          +---- Merge auf beliebigem -----+
                Windows-Rechner
                       |
                       v
             gemeinsame ACC/PRD-XLSX
```

Der JSON-Snapshot ist das kleine Austauschformat zwischen den getrennten Erfassungen. Er enthält weder Endpunktadressen noch Credentials.

## 3. Komponenten

```text
CommandLineOptions
  +-- validiert lokalen Modus oder Merge-Modus

BizTalkWmiCollector
  +-- MSBTS_Application
  +-- MSBTS_ReceivePort
  +-- MSBTS_SendPort
  +-- MSBTS_ReceiveLocation

SnapshotStore
  +-- normalisiert je Anwendung Adapterzählungen
  +-- schreibt/liest DataContract-JSON
  +-- validiert Schema, Summen, Umgebung und Vollständigkeit

XlsxReportWriter
  +-- genau ein Blatt "Phase 1"
  +-- Office Open XML ohne Office-Interop
  +-- Titel, Filter, Freeze Pane und Summenzeile
```

## 4. WMI-Datenmodell

### 4.1 Anwendungen

`MSBTS_Application` ist die Pflichtquelle der Anwendungsliste. Verwendet wird nur `Name` beziehungsweise `ApplicationName`.

Die Abfrage muss mindestens eine Anwendung liefern. Andernfalls ist der lokale Lauf unvollständig.

### 4.2 Receive-Endpunkte

Eine `MSBTS_ReceiveLocation` zählt als ein Endpunkt. Der Adapter wird defensiv aus `AdapterName`, `TransportType` oder `PTTransportType` gelesen.

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.

### 4.3 Send-Endpunkte

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.

Primärer Adapter:

- `PTTransportType`
- Fallback `PrimaryTransportType`
- Fallback `AdapterName`
- Fallback `TransportType`

Sekundärer Adapter:

- `STTransportType`
- Fallback `SecondaryTransportType`

Fehlt ein gelieferter Adaptername, wird `Unbekannt` verwendet. Ein Endpunkt ohne Anwendungszuordnung macht den Lauf unvollständig, weil er sonst in der Anwendungssicht verloren ginge.

## 5. Snapshot-Format

Das JSON enthält nur normalisierte Katalogdaten:

```json
{
  "SchemaVersion": 1,
  "EnvironmentName": "ACC",
  "ComputerName": "BIZTALK-ACC",
  "CreatedUtc": "2026-07-27T13:00:00.0000000Z",
  "IsComplete": true,
  "Applications": [
    {
      "Name": "ExampleApplication",
      "EndpointCount": 2,
      "AdapterCounts": [
        { "AdapterType": "FILE", "Count": 1 },
        { "AdapterType": "SFTP", "Count": 1 }
      ]
    }
  ]
}
```

Vor einem Merge werden geprüft:

- `SchemaVersion` ist `1`
- erwartete Umgebung ist exakt `ACC` beziehungsweise `PROD`
- `IsComplete` ist `true`
- Namen und Adaptertypen sind nicht leer
- Zählwerte sind nicht negativ
- Summe der Adapterzählungen entspricht `EndpointCount`

JSON und XLSX werden über eine temporäre Datei geschrieben und erst nach erfolgreichem Abschluss auf den endgültigen Dateinamen verschoben.

## 6. Merge-Regeln

Anwendungsnamen werden ohne Beachtung der Groß-/Kleinschreibung verglichen. Für die Anzeige wird bei einer gemeinsamen Anwendung bevorzugt die Schreibweise aus ACC verwendet.

| Situation | Umgebung | ACC | PRD | Hinweis |
| --- | --- | --- | --- | --- |
| in beiden vorhanden | `ACC + PRD` | `✓` | `✓` | leer |
| nur ACC | `nur ACC` | `✓` | `–` | `Nur in ACC vorhanden` |
| nur PROD | `nur PRD` | `–` | `✓` | `Nur in PRD vorhanden – nicht in ACC` |

Die Endpunktanzahl einer gemeinsamen Zeile ist die Summe beider Umgebungen.

Sind die Adapterzählungen identisch, erscheint nur eine kompakte Darstellung:

```text
FILE (1x) / SFTP (1x)
```

Bei einer Abweichung bleiben beide Nachweise sichtbar:

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

Damit wird keine Übereinstimmung suggeriert, wenn lediglich die Gesamtzahl gleich ist.

## 7. Excel-Aufbau

Die Arbeitsmappe enthält genau:

```text
xl/worksheets/sheet1.xml  -> Blatt "Phase 1"
```

Das Blatt besteht aus:

- Zeile 1: zusammengeführter Titel
- Zeile 2: sieben Spaltenüberschriften
- ab Zeile 3: alphabetisch sortierte Anwendungen
- letzte Zeile: zusammengeführte Summenzeile

Der Filter umfasst nur Kopf- und Datenzeilen, nicht die Summenzeile. Die ersten beiden Zeilen sind fixiert. Zelltexte werden als `inlineStr` gespeichert. Office und COM-Interop sind nicht erforderlich.

## 8. Fehlerverhalten

Alle vier WMI-Abfragen bilden einen Pflichtabschnitt. Ein Fehler führt zu:

- Exitcode `1`
- Logeintrag
- JSON mit `IsComplete: false`
- lokaler XLSX auf Basis der bis dahin ermittelten Daten

Der Merge lehnt einen solchen JSON-Snapshot ab. Dadurch werden technische Lücken nicht als bestätigte Nullwerte in den ACC/PRD-Katalog übernommen.

Ungültige Parameter, fehlende Dateien, fehlerhaftes JSON und Schreibfehler liefern Exitcode `2`.

## 9. Sicherheit

- ausschließlich lesende lokale WMI-Abfragen
- keine Änderungen an BizTalk-Konfiguration oder Runtime
- keine SQL-Abfragen
- keine Endpunktadressen
- keine Binding-Exporte
- keine Credentials, Secrets oder Tokens
- keine Netzwerkverbindungen zu fachlichen Endpunkten

Anwendungsnamen, Servernamen und Adapterverteilungen bleiben interne Betriebsinformationen. JSON, XLSX und Log sind geschützt abzulegen.

## 10. Build und Test

Baseline:

- Visual Studio 2019 / MSBuild 16.x
- klassisches MSBuild-Projektformat
- .NET Framework 4.7.2
- C# 7.3
- keine NuGet-Pakete
- kein .NET SDK erforderlich

```cmd
scripts\build-release.cmd
```

Der Self-Test benötigt kein BizTalk und prüft:

- JSON-Schreiben und -Lesen
- Snapshot-Validierung
- ACC/PRD-Union
- Adapteraggregation
- Endpunktsummen
- ein einziges Blatt `Phase 1`
- erforderliche OPC-/XLSX-Teile
- XML-Wohlgeformtheit
- Titel- und Summen-Merges
- korrekten Filterbereich

## 11. Betriebsvalidierung

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.

Nach dem Merge:

1. Summen für ACC und PROD mit den lokalen Dateien vergleichen.
2. Anwendungen mit `nur ACC` und `nur PRD` fachlich prüfen.
3. Abweichend beschriftete ACC-/PRD-Adapterverteilungen prüfen.
4. Ergebnis geschützt archivieren.