diff --git a/src/presentation/DigitalData.MessagingService.Client.DependencyInjection/README.md b/src/presentation/DigitalData.MessagingService.Client.DependencyInjection/README.md new file mode 100644 index 0000000..9997eac --- /dev/null +++ b/src/presentation/DigitalData.MessagingService.Client.DependencyInjection/README.md @@ -0,0 +1,187 @@ +# DigitalData.MessagingService.Client + +Ein schlanker, eigenständiger RabbitMQ-Client zum Versenden von E-Mails über den DigitalData MessagingService – ohne eigenen DI-Container oder Hosting-Infrastruktur. + +## Installation + +``` +dotnet add package DigitalData.MessagingService.Client +``` + +## Schnellstart + +### 1. Verbindung herstellen + +Einmalig beim Anwendungsstart aufrufen – typischerweise in `Program.cs`, `Application_Start` oder dem Konstruktor des Einstiegspunkts: + +```csharp +EmailSender.ConnectRabbitMq( + url: "amqp://172.24.12.56:5672", + username: "admin", + password: "geheimespasswort" +); +``` + +```vb +EmailSender.ConnectRabbitMq( + url:="amqp://172.24.12.56:5672", + username:="admin", + password:="geheimespasswort" +) +``` + +Mit virtuellem Host: + +```csharp +EmailSender.ConnectRabbitMq( + url: "amqp://172.24.12.56:5672/meinvhost", + username: "admin", + password: "geheimespasswort" +); +``` + +```vb +EmailSender.ConnectRabbitMq( + url:="amqp://172.24.12.56:5672/meinvhost", + username:="admin", + password:="geheimespasswort" +) +``` + +> **Hinweis:** `ConnectRabbitMq` darf pro Prozess nur einmal erfolgreich aufgerufen werden. +> Ein erneuter Aufruf löst standardmäßig eine `InvalidOperationException` aus. +> Ist dieses Verhalten nicht erwünscht, kann `OnReconnect.Ignore` übergeben werden: +> +> ```csharp +> EmailSender.ConnectRabbitMq("amqp://172.24.12.56:5672", "admin", "geheimespasswort", OnReconnect.Ignore); +> ``` +> +> ```vb +> EmailSender.ConnectRabbitMq("amqp://172.24.12.56:5672", "admin", "geheimespasswort", OnReconnect.Ignore) +> ``` + +### 2. E-Mail versenden + +```csharp +EmailSender.Send(new OutgoingEmailEvent +{ + Id = Guid.NewGuid(), + Recipient = "empfaenger@beispiel.de", + Subject = "Willkommen", + Body = "

Hallo Welt!

", + IsHtml = true, + QueuedAt = DateTime.Now +}); +``` + +```vb +EmailSender.Send(New OutgoingEmailEvent With { + .Id = Guid.NewGuid(), + .Recipient = "empfaenger@beispiel.de", + .Subject = "Willkommen", + .Body = "

Hallo Welt!

", + .IsHtml = True, + .QueuedAt = DateTime.Now +}) +``` + +`Send` ist eine **Fire-and-Forget**-Methode: die Nachricht wird in die RabbitMQ-Queue eingereiht und der aufrufende Code wartet nicht auf die eigentliche Zustellung. + +### 3. Verbindungsstatus prüfen + +```csharp +if (EmailSender.IsConnected) +{ + // Verbindung wurde bereits hergestellt +} +``` + +```vb +If EmailSender.IsConnected Then + ' Verbindung wurde bereits hergestellt +End If +``` + +--- + +## URL-Format + +``` +amqp://:[/] +``` + +| Bestandteil | Beschreibung | Beispiel | +|---------------|---------------------------------------------------------|----------------| +| `host` | Hostname oder IP-Adresse des RabbitMQ-Servers | `172.24.12.56` | +| `port` | AMQP-Port (Standard: `5672`) | `5672` | +| `virtualhost` | Optionaler virtueller Host; URL-Encoding wird aufgelöst | `meinvhost` | + +Benutzername und Passwort werden **nicht** aus der URL gelesen, sondern immer separat als Parameter übergeben. Dadurch werden Klartext-Credentials in URLs vermieden. + +--- + +## RabbitMQ-Server + +| | | +|---|---| +| **AMQP** | `amqp://172.24.12.56:5672` | +| **Management UI** | http://172.24.12.56:15672 (Browser) | +| **Benutzername** | `admin` | +| **Passwort** | Im RDM-Eintrag **`sDD-VMP05-VM06 - 172.24.12.56 - RabbitMQ`** hinterlegt | + +--- + +## Voraussetzungen + +- .NET Framework 4.6.2 / 4.8 oder .NET 8+ +- Erreichbarer RabbitMQ-Server +- Exchange, Queue und Routing Key müssen auf dem Broker vorhanden sein (werden vom Server-seitigen Consumer angelegt) + +--- + +## Erweiterte Konfiguration + +Für spezielle Szenarien – etwa abweichende Exchange- oder Queue-Namen – steht ein Delegate-basierter Überload zur Verfügung: + +```csharp +EmailSender.ConnectRabbitMq(cfg => +{ + cfg.HostName = "172.24.12.56"; + cfg.Port = 5672; + cfg.UserName = "admin"; + cfg.Password = "geheimespasswort"; + cfg.VirtualHost = "/"; + // cfg.ExchangeName, cfg.QueueName, cfg.RoutingKey usw. bei Bedarf anpassen +}); +``` + +```vb +EmailSender.ConnectRabbitMq(Sub(cfg) + cfg.HostName = "172.24.12.56" + cfg.Port = 5672 + cfg.UserName = "admin" + cfg.Password = "geheimespasswort" + cfg.VirtualHost = "/" + ' cfg.ExchangeName, cfg.QueueName, cfg.RoutingKey usw. bei Bedarf anpassen +End Sub) +``` + +Dieser Überload ist für den Normalbetrieb nicht erforderlich. + +--- + +## Fehlerbehandlung + +| Situation | Verhalten | +|---|---| +| `ConnectRabbitMq` noch nicht aufgerufen, dann `Send` | `InvalidOperationException` | +| `ConnectRabbitMq` erneut aufgerufen (Standard) | `InvalidOperationException` | +| `ConnectRabbitMq` erneut aufgerufen mit `OnReconnect.Ignore` | Wird stillschweigend ignoriert | +| RabbitMQ nicht erreichbar beim ersten `Send` | Exception aus dem RabbitMQ-Client | + +--- + +## Lizenz + +Copyright © 2026 Digital Data GmbH. Alle Rechte vorbehalten. +