GizzlerandCursor
58b7826162
Configure CertificateCheckUrl per container for curl-like TLS checks, classify Sonic permission errors, and extend setup wizard for container management. Co-authored-by: Cursor <cursoragent@cursor.com>
438 lines
14 KiB
Markdown
438 lines
14 KiB
Markdown
# Dateiübersicht nach Ordnerstruktur
|
||
|
||
Was **jede einzelne Datei** macht – inkl. Sonic Management API.
|
||
Projektroot der App: `ZA.CoreService.ESBCertificateManager/`
|
||
|
||
---
|
||
|
||
## 0. Gesamtbild (wer ruft wen)
|
||
|
||
```text
|
||
Program.cs
|
||
└─ Form1.cs (UI)
|
||
├─ Zertifikat lesen → CertificateInfo
|
||
├─ Ziele ← SonicContainerDiscovery (KnownContainers / Live)
|
||
└─ Neustart
|
||
└─ DeploymentOrchestrator
|
||
└─ RestartExecutor
|
||
└─ SonicManagementClient
|
||
└─ SonicMfApiExecutor
|
||
└─ java + Tools/SonicMfContainerTool
|
||
└─ Sonic JARs (externe API)
|
||
└─ Domain Manager tcp://…:13070
|
||
```
|
||
|
||
Konfiguration: `appsettings.json` → `AppSettingsLoader` → `AppSettings` / `SonicConnection`.
|
||
|
||
---
|
||
|
||
## 1. Projektroot (`ZA.CoreService.ESBCertificateManager/`)
|
||
|
||
### `Program.cs`
|
||
Einstiegspunkt der WinForms-App.
|
||
`ApplicationConfiguration.Initialize()` + `Application.Run(new Form1())`.
|
||
Keine Business-Logik.
|
||
|
||
### `Form1.cs`
|
||
**Gesamte Benutzeroberfläche** (Dark-Design, Sidebar, Zertifikatskarte, Grid, Buttons).
|
||
Wichtige Aufgaben:
|
||
|
||
| Bereich | Was passiert |
|
||
|---------|----------------|
|
||
| Zertifikat | Dateidialog → `X509Certificate2` → Subject/Issuer/Fingerprint/Gültigkeit anzeigen |
|
||
| Ziele | Grid aus `KnownContainers`; Button „Container laden“ → Live-Discovery |
|
||
| Prüfung | `ValidateRestartOnly` (ContainerName + SonicConnectionName) |
|
||
| Neustart | Bestätigung → `DeploymentOrchestrator.RestartOnlyAsync` → Ergebnisdialog |
|
||
| Status | Statuszeile, Fortschritt im Grid, SonicHome/Java-Anzeige |
|
||
|
||
Deploy-Button ist vorhanden im Layout, aber **ausgeblendet/deaktiviert**.
|
||
|
||
### `Form1.Designer.cs`
|
||
WinForms-Designer-Stub. `InitializeComponent()` ist praktisch leer – das Layout wird in `Form1.cs` per Code gebaut.
|
||
|
||
### `Form1.resx`
|
||
Ressourcen-Datei zum Formular (Standard WinForms). Kaum eigene Inhalte.
|
||
|
||
### `appsettings.json`
|
||
**Laufzeitkonfiguration** – die „Online“-Quelle für Sonic:
|
||
|
||
- `LogDirectory` – wohin Logs geschrieben werden
|
||
- `SonicConnections[]` – Domain, URL, User/Pass, Java, Lib-Pfad, **KnownContainers**
|
||
|
||
Beispiel-Verbindung `DE-Test` → Domain `proalpha-test`, Container `ct-ZADBService`.
|
||
|
||
### `ZA.CoreService.ESBCertificateManager.csproj`
|
||
Projektdatei: .NET 8 WinForms, NuGet (Configuration), welche Dateien nach `bin` kopiert werden (`appsettings`, `Tools`, `Assets`, `Docs`).
|
||
|
||
### `ZA.CoreService.ESBCertificateManager.csproj.user`
|
||
Lokale Visual-Studio-Benutzereinstellungen (Debugger usw.). Nicht fachlich relevant.
|
||
|
||
---
|
||
|
||
## 2. Ordner `Configuration/`
|
||
|
||
### `AppSettingsLoader.cs`
|
||
Liest `appsettings.json` über `Microsoft.Extensions.Configuration` und bindet sie an `AppSettings`.
|
||
Sucht zuerst im Output-Verzeichnis (`AppContext.BaseDirectory`), sonst im Arbeitsverzeichnis.
|
||
|
||
---
|
||
|
||
## 3. Ordner `Models/` (Datenstrukturen)
|
||
|
||
### `AppSettings.cs`
|
||
Root-Settings-Objekt:
|
||
|
||
- `LogDirectory`
|
||
- `List<SonicConnection> SonicConnections`
|
||
|
||
### `SonicConnection.cs`
|
||
Eine Sonic-/SMC-Verbindung:
|
||
|
||
| Property | Bedeutung |
|
||
|----------|-----------|
|
||
| `Name` | Alias, z. B. `DE-Test` |
|
||
| `DomainName` | z. B. `proalpha-test` |
|
||
| `ConnectionUrl` | `tcp://host:port` wie SMC |
|
||
| `Username` / `Password` | SMC-Login |
|
||
| `SonicHome` / `JavaHome` / `JavaPath` | Pfade |
|
||
| `MfClientLibPath` | Ordner mit Client-JARs |
|
||
| `KnownContainers` | Containerliste für die UI |
|
||
| `TimeoutSeconds` / `PostRestartDelaySeconds` | Timeouts |
|
||
| `ManagementModeDisplay` | Anzeigetext „MfApi …“ |
|
||
|
||
Enthält noch ältere Hilfsfelder/Enums (WinRM etc.) aus der Historie – der aktive Client nutzt nur den MfApi-Pfad.
|
||
|
||
### `DeploymentTarget.cs`
|
||
Ein **Ziel** im Grid (ein Container zum Neustarten):
|
||
|
||
- `Id`, `Name`, `Environment`, `IsActive`
|
||
- `ContainerName` – z. B. `ct-ZADBService`
|
||
- `SonicConnectionName` – Verweis auf `SonicConnection.Name`
|
||
- `RestartType` – für Neustart typischerweise `SonicContainer`
|
||
- Weitere Felder (TargetDirectory, Tls*, Xapi*) können noch im Model stehen, werden für den aktuellen Neustart-Pfad nicht mehr aktiv genutzt
|
||
|
||
### `CertificateInfo.cs`
|
||
Ergebnis der lokalen Zertifikatsprüfung:
|
||
|
||
- Subject, Issuer
|
||
- FingerprintSha256
|
||
- ValidFrom / ValidUntil
|
||
- IsCurrentlyValid
|
||
|
||
### `DeploymentRunResult.cs`
|
||
Ergebnisstrukturen nach einem Lauf:
|
||
|
||
- `DeploymentRunResult` – Gesamtlauf (Liste Zielergebnisse, Zeiten, OverallSuccess)
|
||
- `TargetStepResult` – ein Ziel (Success, StatusText, Detail, …)
|
||
- `ValidationIssue` / `PreflightValidationResult` – Vorabprüfung
|
||
- `TargetProgressUpdate` – Fortschritt für die UI
|
||
|
||
---
|
||
|
||
## 4. Ordner `Services/` (Geschäftslogik)
|
||
|
||
### `DeploymentOrchestrator.cs`
|
||
Orchestriert **nur Neustart** (kein Deploy/TLS):
|
||
|
||
1. `ValidateRestartOnly` → Preflight
|
||
2. `RestartOnlyAsync` → für jedes Ziel `RestartExecutor`
|
||
3. Schreibt Log über `RunLogger`
|
||
4. Meldet Progress an die UI
|
||
|
||
### `RestartExecutor.cs`
|
||
Mappt ein `DeploymentTarget` auf die passende `SonicConnection` und ruft
|
||
`SonicManagementClient.RestartContainerAsync(containerName)` auf.
|
||
|
||
### `PreflightValidator.cs`
|
||
Prüft vor dem Neustart:
|
||
|
||
- mindestens ein Ziel ausgewählt
|
||
- `ContainerName` gesetzt
|
||
- `SonicConnectionName` gesetzt
|
||
|
||
### `SonicManagementClient.cs`
|
||
**Dünne Fassade** zur MfApi (kein WinRM/HTTP/XApi mehr):
|
||
|
||
| Methode | Zweck |
|
||
|---------|--------|
|
||
| `CheckConnectionAsync` | Ping / Soft-Fallback KnownContainers+TCP |
|
||
| `GetContainersAsync` | Liste von Containern (API oder KnownContainers) |
|
||
| `RestartContainerAsync` | Neustart + Wartezeit `PostRestartDelaySeconds` |
|
||
|
||
### `SonicMfApiExecutor.cs`
|
||
**Brücke C# → Java.** Das ist der technische Kern „unsere Seite der API“:
|
||
|
||
1. Java 8+ finden (`JavaPath` / Suche)
|
||
2. Classpath aus allen JARs unter `MfClientLibPath` / `SonicHome\lib` bauen
|
||
3. `Tools\SonicMfContainerTool.class` laden (Version prüfen)
|
||
4. Prozess starten: `java -cp … SonicMfContainerTool ping|list|restart …`
|
||
5. Passwort über Env `ESB_SONIC_PASSWORD`
|
||
6. Erfolg bei Neustart nur wenn Output `OK:RestartInvoked` enthält
|
||
|
||
Öffentliche Methoden:
|
||
|
||
- `TestConnectionAsync` → Tool-Befehl `ping`
|
||
- `ListContainersAsync` → `list`
|
||
- `RestartAsync` → `restart`
|
||
- `ResolveRuntimePaths` → für Statuszeile in der UI
|
||
|
||
### `SonicContainerDiscovery.cs`
|
||
Baut die Zielliste:
|
||
|
||
- `BuildTargetsFromConfig()` – aus `KnownContainers` in appsettings (Start der App)
|
||
- `DiscoverAsync()` – live per `SonicManagementClient` listen + mit KnownContainers mergen
|
||
|
||
### `RunLogger.cs`
|
||
Schreibt Textdateien unter `LogDirectory` (ein Log pro Lauf). Redaktiert ggf. secrets-ähnliche Strings.
|
||
|
||
### `PathResolver.cs`
|
||
Löst relative Pfade gegen `AppContext.BaseDirectory` auf (z. B. für Logs).
|
||
|
||
---
|
||
|
||
## 5. Ordner `Tools/` (Java + Sonic-API)
|
||
|
||
Hier liegt der **eigentliche Aufruf der Sonic Management Application API**.
|
||
|
||
### `SonicMfContainerTool.java`
|
||
Kleines Java-Hilfsprogramm (Reflection, kompilierbar ohne Sonic-JARs auf dem Compile-Classpath).
|
||
|
||
**Befehle:**
|
||
|
||
| Befehl | Bedeutung |
|
||
|--------|-----------|
|
||
| `ping` | Connect + Agenten zählen |
|
||
| `list` | Containernamen der Domain ausgeben |
|
||
| `restart` | Lifecycle auf einem Container |
|
||
|
||
**Connect (API-Login):**
|
||
|
||
```text
|
||
Hashtable: ConnectionURLs, DefaultUser, DefaultPassword
|
||
→ new JMSConnectorAddress(env)
|
||
→ new JMSConnectorClient().connect(address, timeout)
|
||
```
|
||
|
||
Klassen aus Sonic-JARs:
|
||
|
||
- `com.sonicsw.mf.jmx.client.JMSConnectorAddress`
|
||
- `com.sonicsw.mf.jmx.client.JMSConnectorClient`
|
||
|
||
**Neustart – Ziel:**
|
||
|
||
```text
|
||
ObjectName = {Domain}.{Container}:ID=AGENT
|
||
Beispiel: proalpha-test.ct-ZADBService:ID=AGENT
|
||
```
|
||
|
||
**Neustart – Wege (nacheinander):**
|
||
|
||
1. **MBean.invoke** `"stop"` / `"restart"` / `"shutdown"` ← bevorzugt remote
|
||
2. **IAgentProxy** über `MFProxyFactory.createAgentProxy` (oft *unbounded*-Fehler)
|
||
3. **DomainManager**-Operationen wie `restartContainer` / `stopContainer`
|
||
|
||
Erfolg:
|
||
|
||
```text
|
||
OK:RestartInvoked method=…
|
||
INFO:ToolVersion=…
|
||
```
|
||
|
||
### `SonicMfContainerTool.class` / `SonicMfContainerTool$Args.class`
|
||
Vorkompilierter Java-8-Bytecode (major 52), den die App zur Laufzeit nutzt (ohne `javac` auf dem Zielrechner).
|
||
|
||
### `SonicMfContainerTool.jar`
|
||
Optional verpackte Variante des Tools (Classpath-Alternative).
|
||
|
||
### `verify-mfapi-classpath.bat`
|
||
Hilfsskript: prüft manuell, ob `JMSConnectorAddress` mit den JARs unter `C:\DEV\MQ10.0\lib` ladbar ist.
|
||
|
||
---
|
||
|
||
## 6. Ordner `Docs/` (Dokumentation)
|
||
|
||
### `Komplette-Erklaerung.md`
|
||
Schritt-für-Schritt: Zertifikat, Preflight, C#-Kette, Java-API, Fehlerbilder, Präsentationsskript.
|
||
|
||
### `Neustart-und-Management-API.md`
|
||
Kompaktere API-/Neustart-Erklärung inkl. „Was ist unnötig in der großen Sonic-API?“.
|
||
|
||
### `Dateiuebersicht-nach-Ordner.md`
|
||
Diese Datei – Katalog aller Projektdateien.
|
||
|
||
---
|
||
|
||
## 7. Ordner `Assets/`
|
||
|
||
### `logo.png`
|
||
UI-/Branding-Grafik.
|
||
|
||
### `TestCertificates/esb-test-cert.cer`
|
||
Beispiel-Zertifikat zum lokalen Test der Dateierkennung (kein Sonic-Deploy).
|
||
|
||
---
|
||
|
||
## 8. Ordner `Demo/`
|
||
|
||
### `Demo/Central/esb-cert.cer`
|
||
Weiteres Beispielzertifikat. Nicht Teil der Online-Neustart-Logik.
|
||
|
||
---
|
||
|
||
## 9. Sibling-Ordner `doc-10.0.10/` (neben der App, im Repo)
|
||
|
||
Produkt-Dokumentation Aurea CX Messenger / Sonic (nicht App-Code).
|
||
|
||
### `CXMessenger_2017_R3.htm`
|
||
Index der offiziellen Doku. Wichtiger Link:
|
||
|
||
- **Management Application API Reference** → `Docs2017/api/mgmt_api/`
|
||
Das ist die API-Familie, die SMC und unser Java-Tool nutzen.
|
||
|
||
### `Docs2017/api/analytics-offloader/…`
|
||
Javadoc-Stub für Analytics Offload – **nicht** der Neustart-Pfad.
|
||
|
||
### PDFs / vollständige `mgmt_api`
|
||
Im Index verlinkt; können im Checkout fehlen. Für Reviews idealerweise nachziehen.
|
||
|
||
---
|
||
|
||
## 10. Die Sonic Management Application API – detailliert
|
||
|
||
### 10.1 Was „API“ hier bedeutet
|
||
|
||
Es ist **keine REST-URL der WinForms-App**.
|
||
Es ist die **Java Management Application API** von Sonic/Aurea:
|
||
|
||
- Transport: JMS zum Domain Manager (`tcp://host:port`)
|
||
- Steuerung: JMX-ähnliche ObjectNames + Operationen
|
||
- Authentifizierung: SMC-User/Pass
|
||
|
||
Dieselbe Schicht wie der Restart in der Sonic Management Console.
|
||
|
||
### 10.2 Welche Sonic-Klassen wir wirklich brauchen
|
||
|
||
| Klasse | Aufgabe |
|
||
|--------|---------|
|
||
| `JMSConnectorAddress` | Verbindungsparameter kapseln |
|
||
| `JMSConnectorClient` | Verbinden / disconnect / invoke / queryNames |
|
||
| `MFProxyFactory` | `createAgentProxy` |
|
||
| `IAgentProxy` | typisierte Methoden stop/restart/… (remote oft eingeschränkt) |
|
||
| ObjectName `domain.container:ID=AGENT` | Ziel-Agent |
|
||
|
||
Benötigte JARs typischerweise unter `C:\DEV\MQ10.0\lib`:
|
||
|
||
- `mgmt_client.jar`
|
||
- `mfcontext.jar`
|
||
- `sonic_Client.jar`
|
||
(+ weitere Abhängigkeiten im selben Ordner)
|
||
|
||
### 10.3 Warum die Sonic-API „viele unnötige Funktionen“ hat
|
||
|
||
Die Produkt-API deckt ab:
|
||
|
||
- Messaging (Queues, Topics, Durable Subs)
|
||
- Broker-Admin
|
||
- ESB
|
||
- Metrics / Notifications
|
||
- Config / Directory
|
||
|
||
**Für unseren Use-Case reichen 3 Schritte:** Connect → Agent finden → Stop/Restart.
|
||
|
||
Der Rest der JARs/Javadoc ist Produktumfang, nicht App-Feature.
|
||
|
||
### 10.4 „Unbounded client connector“
|
||
|
||
Remote-Clients (SMC, unser Tool) sind oft **unbounded**.
|
||
Dann schlägt `IAgentProxy.restart()` fehl mit:
|
||
|
||
```text
|
||
Operation unsupported for unbounded client connector
|
||
```
|
||
|
||
Deshalb bevorzugt das Tool **MBean.invoke("stop")**.
|
||
Operativ entspricht das oft SMC-Restart: Stop + Auto-Relaunch durch Launch Daemon.
|
||
|
||
### 10.5 Sequenz eines Neustarts (API-Ebene)
|
||
|
||
```text
|
||
1. C#: RestartExecutor → SonicManagementClient → SonicMfApiExecutor
|
||
2. C#: startet java -cp Tools;lib\*.jar SonicMfContainerTool restart …
|
||
3. Java: JMSConnectorClient.connect(url, user, pass)
|
||
4. Java: ObjectName = proalpha-test.ct-ZADBService:ID=AGENT
|
||
5. Java: connector.invoke(on, "stop", …) // oder Fallback
|
||
6. Java: OK:RestartInvoked
|
||
7. C#: PostRestartDelaySeconds warten
|
||
8. UI: Erfolg/Fehler + Log
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Zertifikatsprüfung – welche Dateien
|
||
|
||
| Datei | Rolle |
|
||
|-------|--------|
|
||
| `Form1.cs` | Dateiauswahl, PFX-Passwort, Anzeige |
|
||
| `Models/CertificateInfo.cs` | Ergebnisobjekt |
|
||
| `Assets/...` / `Demo/...` | optionale Testdateien |
|
||
|
||
Ablauf:
|
||
|
||
1. Datei wählen (`.cer/.crt/.pem/.pfx`)
|
||
2. Als `X509Certificate2` laden
|
||
3. Subject/Issuer/Fingerprint/Gültigkeit berechnen
|
||
4. Anzeigen – **lokal verifiziert**
|
||
|
||
Nicht enthalten: Kopieren auf ESB, TLS-Probe gegen Live-Host, CA-Kettenprüfung.
|
||
|
||
---
|
||
|
||
## 12. Was absichtlich fehlt (gelöscht / deaktiviert)
|
||
|
||
| Früher | Status |
|
||
|--------|--------|
|
||
| `Data/targets.sample.json` + JSON-Repository | entfernt – Ziele aus KnownContainers |
|
||
| SQL-Repos / Schema | entfernt |
|
||
| WinRM / LocalCmd / stopcontainer.bat-Executor | entfernt |
|
||
| CertificateDeployer / TlsCertificateProbe | entfernt |
|
||
| XApi-Import | entfernt |
|
||
| Deploy-Button | UI ausgeblendet |
|
||
|
||
---
|
||
|
||
## 13. Schnell-Tabelle „Datei → Ein Satz“
|
||
|
||
| Datei | Ein Satz |
|
||
|-------|----------|
|
||
| `Program.cs` | Startet die App |
|
||
| `Form1.cs` | UI + Zertifikat + Neustart-Klick |
|
||
| `Form1.Designer.cs` | Leerer Designer-Stub |
|
||
| `Form1.resx` | Formular-Ressourcen |
|
||
| `appsettings.json` | Sonic-Verbindung + KnownContainers + Java/Libs |
|
||
| `*.csproj` | Build/Copy-Regeln |
|
||
| `Configuration/AppSettingsLoader.cs` | JSON → Settings-Objekt |
|
||
| `Models/AppSettings.cs` | Settings-Root |
|
||
| `Models/SonicConnection.cs` | Eine SMC-/Domain-Verbindung |
|
||
| `Models/DeploymentTarget.cs` | Ein Container-Ziel im Grid |
|
||
| `Models/CertificateInfo.cs` | Lokales Zertifikats-Ergebnis |
|
||
| `Models/DeploymentRunResult.cs` | Lauf-/Validierungs-DTOs |
|
||
| `Services/DeploymentOrchestrator.cs` | Neustart über alle Ziele |
|
||
| `Services/RestartExecutor.cs` | Ziel → SonicClient |
|
||
| `Services/PreflightValidator.cs` | Pflichtfelder prüfen |
|
||
| `Services/SonicManagementClient.cs` | Fassade ping/list/restart |
|
||
| `Services/SonicMfApiExecutor.cs` | Java-Prozess + Classpath |
|
||
| `Services/SonicContainerDiscovery.cs` | KnownContainers + Live-Liste |
|
||
| `Services/RunLogger.cs` | Datei-Logs |
|
||
| `Services/PathResolver.cs` | Relative Pfade |
|
||
| `Tools/SonicMfContainerTool.java` | Sonic Management API Aufrufe |
|
||
| `Tools/*.class` / `.jar` | Vorkompiliertes Tool |
|
||
| `Tools/verify-mfapi-classpath.bat` | Classpath-Selbsttest |
|
||
| `Docs/*.md` | Erklärungen |
|
||
| `Assets/*` | Logo / Testzertifikat |
|
||
| `Demo/*` | Demo-Zertifikat |
|
||
| `doc-10.0.10/*` | Offizielle Sonic/CX-Messenger-Doku |
|
||
|
||
---
|
||
|
||
*Ende der Dateiübersicht. Für Ablauf-Details siehe `Komplette-Erklaerung.md`.*
|