Improve ReCClient static client and documentation

Updated `ReCClientOptions` to include a warning about the `LogSuccessfulRequests` option throwing an `InvalidOperationException` if no `ILogger` is registered via DI. Added validation and thread-safety to `BuildStaticClient` using `Lazy<IServiceProvider>`.

Introduced `StaticBuildConfiguration` for callback-based configuration and detailed its properties. Clarified usage patterns, added VB.NET and C# examples, and documented validation rules.

Marked older `BuildStaticClient` overloads as `[Obsolete]` while retaining functionality. Expanded context on static client use cases and synchronous wrappers. Improved documentation clarity and consistency.

docs/ReC.Client.xwiki

@@ -118,6 +118,10 @@ services.Configure<ReCClientOptions>(opt =>
 });
 {{/code}}
 
+{{warning}}
+Wenn `LogSuccessfulRequests = true` gesetzt, aber **kein** `ILogger` über DI registriert ist, wirft der `ReCClient`-Konstruktor eine `InvalidOperationException`. Stellen Sie sicher, dass ein Logging-Provider (z. B. `services.AddLogging(...)`) registriert ist, oder lassen Sie die Option auf `false`.
+{{/warning}}
+
 == 3. Überblick über die API-Klassen ==
 
 `ReCClient` bündelt mehrere thematische API-Klassen als Eigenschaften:
@@ -369,7 +373,7 @@ Empfehlungen:
 
 == 6. Komfort-APIs: statischer Provider und synchrone Wrapper ==
 
-Neben dem empfohlenen DI-basierten Ansatz bietet **ReC.Client** absichtlich auch einen **statischen Komfort-Pfad** sowie **synchrone Wrapper** an. Diese Bestandteile sind nicht „veraltet im Sinne von eingefroren" – sie werden weiterhin gepflegt und bei Bedarf um neue Funktionen erweitert (Beispiel: der jüngst hinzugefügte optionale `Action<ReCClientOptions>`-Parameter in `BuildStaticClient`). Sie sind jedoch bewusst mit `[Obsolete]` markiert, damit Aufrufer sie nicht „aus Versehen" auswählen, sondern eine bewusste Entscheidung treffen.
+Neben dem empfohlenen DI-basierten Ansatz bietet **ReC.Client** absichtlich auch einen **statischen Komfort-Pfad** sowie **synchrone Wrapper** an. Diese Bestandteile sind nicht „veraltet im Sinne von eingefroren" – sie werden weiterhin gepflegt und bei Bedarf um neue Funktionen erweitert. Sie sind jedoch bewusst mit `[Obsolete]` markiert, damit Aufrufer sie nicht „aus Versehen" auswählen, sondern eine bewusste Entscheidung treffen.
 
 Hintergrund
 
@@ -396,64 +400,129 @@ Wann besser DI verwenden
 
 === 6.1 Statischer Client mit BuildStaticClient / Create ===
 
-`ReCClient.BuildStaticClient(...)` baut intern eine `IServiceCollection` auf, ruft `AddRecClient(...)` auf und legt einen statischen `IServiceProvider` ab. Anschließend liefert `ReCClient.Create()` Instanzen aus diesem Provider.
+`ReCClient.BuildStaticClient(...)` baut intern eine `IServiceCollection` auf, ruft `AddRecClient(...)` auf und legt einen **statischen, thread-safen `Lazy<IServiceProvider>`** an. Der eigentliche `IServiceProvider` wird **erst beim ersten Aufruf von `ReCClient.Create()`** und genau einmal gebaut.
 
-Wichtig: `BuildStaticClient` darf **nur einmal** beim Anwendungsstart aufgerufen werden.
+Wichtig:
 
-Variante mit Basis-URL:
+* `BuildStaticClient` darf **nur einmal** beim Anwendungsstart aufgerufen werden. Ein zweiter Aufruf – egal welcher Overload – wirft `InvalidOperationException("Static Provider is already built.")`.
+* Die Konstruktion des `IServiceProvider` ist **threadsicher** (`Lazy<T>` mit `LazyThreadSafetyMode.ExecutionAndPublication`).
+
+==== 6.1.1 Empfohlene Form: BuildStaticClient mit StaticBuildConfiguration ====
+
+Da der statische Pfad mehrere optionale Bestandteile hat (Basis-URL **oder** `HttpClient`-Konfiguration, `ReCClientOptions`, eigener `ILogger`, zusätzliche Service-Registrierungen), gibt es einen Callback-basierten Overload, der alle Optionen in einem `StaticBuildConfiguration`-Objekt bündelt:
 
 {{code language="vb.net"}}
-' Einmalig beim Anwendungsstart
-ReCClient.BuildStaticClient("https://ihre-rec-api-adresse.com/")
+Imports Microsoft.Extensions.DependencyInjection
+Imports Microsoft.Extensions.Logging
 
-' Später irgendwo im Code
+ReCClient.BuildStaticClient(
+    Sub(cfg)
+        cfg.BaseAddress = "https://ihre-rec-api-adresse.com/"
+
+        cfg.ConfigureOptions = Sub(opt)
+                                   opt.LogSuccessfulRequests = True
+                               End Sub
+
+        ' Optional: eigene zusätzliche Registrierungen, z. B. Logging-Provider
+        cfg.ConfigureServices = Sub(services)
+                                    services.AddLogging(Sub(b) b.AddConsole())
+                                End Sub
+    End Sub)
+{{/code}}
+
+{{code language="csharp"}}
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+
+ReCClient.BuildStaticClient(cfg =>
+{
+    cfg.BaseAddress = "https://ihre-rec-api-adresse.com/";
+
+    cfg.ConfigureOptions = opt =>
+    {
+        opt.LogSuccessfulRequests = true;
+    };
+
+    // Optional: additional service registrations, e.g. logging
+    cfg.ConfigureServices = services =>
+    {
+        services.AddLogging(b => b.AddConsole());
+    };
+});
+{{/code}}
+
+Eigenschaften von `StaticBuildConfiguration`:
+
+* `BaseAddress` – Basis-URI der ReC.API. **Schließt sich gegenseitig** mit `ConfigureClient` aus.
+* `ConfigureClient` – Delegate zum direkten Konfigurieren des `HttpClient` (z. B. `BaseAddress` + `Timeout` + Header). Schließt sich gegenseitig mit `BaseAddress` aus.
+* `ConfigureOptions` – Optionaler Delegate für `ReCClientOptions` (z. B. `LogSuccessfulRequests`).
+* `Logger` – Optionale `ILogger`-Instanz, die als Singleton in die interne `IServiceCollection` registriert wird.
+* `ConfigureServices` – Optionaler Delegate, mit dem der Aufrufer beliebige zusätzliche Registrierungen auf der internen `IServiceCollection` vornehmen kann (z. B. `AddLogging(...)` oder eigene Abhängigkeiten).
+
+Validierung beim Aufruf:
+
+* `BuildStaticClient` wirft `ArgumentNullException`, wenn der `configure`-Callback `null` ist.
+* `BuildStaticClient` wirft `InvalidOperationException`, wenn weder `BaseAddress` noch `ConfigureClient` gesetzt sind, **oder** wenn beide gleichzeitig gesetzt sind.
+
+Variante mit `HttpClient`-Feinkonfiguration:
+
+{{code language="vb.net"}}
+ReCClient.BuildStaticClient(
+    Sub(cfg)
+        cfg.ConfigureClient = Sub(http)
+                                  http.BaseAddress = New Uri("https://ihre-rec-api-adresse.com/")
+                                  http.Timeout = TimeSpan.FromSeconds(30)
+                              End Sub
+    End Sub)
+{{/code}}
+
+{{code language="csharp"}}
+ReCClient.BuildStaticClient(cfg =>
+{
+    cfg.ConfigureClient = http =>
+    {
+        http.BaseAddress = new Uri("https://ihre-rec-api-adresse.com/");
+        http.Timeout = TimeSpan.FromSeconds(30);
+    };
+});
+{{/code}}
+
+Nach dem `BuildStaticClient`-Aufruf liefert `ReCClient.Create()` Instanzen aus dem statischen Provider:
+
+{{code language="vb.net"}}
 Dim client As ReCClient = ReCClient.Create()
 Await client.RecActions.InvokeAsync(profilId, "batch-001")
 {{/code}}
 
 {{code language="csharp"}}
-// Once at application startup
-ReCClient.BuildStaticClient("https://ihre-rec-api-adresse.com/");
-
-// Later somewhere in code
 var client = ReCClient.Create();
 await client.RecActions.InvokeAsync(profileId, "batch-001");
 {{/code}}
 
-Variante mit `HttpClient`-Konfiguration:
+==== 6.1.2 Ältere Komfort-Overloads ====
+
+Aus Bequemlichkeit existieren zwei weitere Overloads, die intern an die `StaticBuildConfiguration`-Variante delegieren. Sie sind als `Obsolete` markiert mit dem Hinweis, die `Action<StaticBuildConfiguration>`-Variante zu verwenden, bleiben aber funktionsfähig:
 
 {{code language="vb.net"}}
-ReCClient.BuildStaticClient(Sub(http)
-    http.BaseAddress = New Uri("https://ihre-rec-api-adresse.com/")
-    http.Timeout = TimeSpan.FromSeconds(30)
-End Sub)
+' Variante mit Basis-URL als String
+ReCClient.BuildStaticClient("https://ihre-rec-api-adresse.com/")
+
+' Mit Options-Callback und optionalem Logger
+ReCClient.BuildStaticClient(
+    "https://ihre-rec-api-adresse.com/",
+    Sub(opt) opt.LogSuccessfulRequests = True,
+    myLogger)
 {{/code}}
 
 {{code language="csharp"}}
-ReCClient.BuildStaticClient(http =>
-{
-    http.BaseAddress = new Uri("https://ihre-rec-api-adresse.com/");
-    http.Timeout = TimeSpan.FromSeconds(30);
-});
-{{/code}}
+// Variant with base URL string
+ReCClient.BuildStaticClient("https://ihre-rec-api-adresse.com/");
 
-Optional kann zusätzlich `ReCClientOptions` über einen Callback gesetzt werden – die Signatur entspricht der von `AddRecClient`:
-
-{{code language="vb.net"}}
+// With options callback and optional logger
 ReCClient.BuildStaticClient(
     "https://ihre-rec-api-adresse.com/",
-    Sub(opt)
-        opt.LogSuccessfulRequests = True
-    End Sub)
-{{/code}}
-
-{{code language="csharp"}}
-ReCClient.BuildStaticClient(
-    "https://ihre-rec-api-adresse.com/",
-    opt =>
-    {
-        opt.LogSuccessfulRequests = true;
-    });
+    opt => opt.LogSuccessfulRequests = true,
+    myLogger);
 {{/code}}
 
 === 6.2 Synchrone Wrapper über TaskSyncExtensions ===

src/ReC.Client/ReCClient.cs

@@ -101,6 +101,53 @@ namespace ReC.Client
             return services.BuildServiceProvider();
         }, System.Threading.LazyThreadSafetyMode.ExecutionAndPublication);
 
+        /// <summary>
+        /// Configures and builds the static <see cref="IServiceProvider"/> for creating <see cref="ReCClient"/> instances.
+        /// </summary>
+        /// <remarks>
+        /// This method should only be called once during application startup. The underlying
+        /// <see cref="IServiceProvider"/> is created lazily and thread-safely on first access via <see cref="Create"/>.
+        /// </remarks>
+        /// <param name="configure">Callback that populates a <see cref="StaticBuildConfiguration"/> instance.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="configure"/> is null.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when neither <see cref="StaticBuildConfiguration.BaseAddress"/> nor <see cref="StaticBuildConfiguration.ConfigureClient"/> is set, when both are set, or when the static provider has already been built.</exception>
+        [Obsolete("Use a local service collection instead of the static provider.")]
+        public static void BuildStaticClient(Action<StaticBuildConfiguration> configure)
+        {
+            if (configure == null)
+                throw new ArgumentNullException(nameof(configure));
+
+            var cfg = new StaticBuildConfiguration();
+            configure(cfg);
+
+            var hasBaseAddress = !string.IsNullOrWhiteSpace(cfg.BaseAddress);
+            var hasConfigureClient = cfg.ConfigureClient != null;
+
+            if (!hasBaseAddress && !hasConfigureClient)
+                throw new InvalidOperationException(
+                    $"Either {nameof(StaticBuildConfiguration.BaseAddress)} or {nameof(StaticBuildConfiguration.ConfigureClient)} must be set on {nameof(StaticBuildConfiguration)}.");
+
+            if (hasBaseAddress && hasConfigureClient)
+                throw new InvalidOperationException(
+                    $"{nameof(StaticBuildConfiguration.BaseAddress)} and {nameof(StaticBuildConfiguration.ConfigureClient)} are mutually exclusive on {nameof(StaticBuildConfiguration)}.");
+
+            Action<IServiceCollection> register = services =>
+            {
+                if (hasBaseAddress)
+                    services.AddRecClient(cfg.BaseAddress, cfg.ConfigureOptions);
+                else
+                    services.AddRecClient(cfg.ConfigureClient, cfg.ConfigureOptions);
+
+                if (cfg.Logger != null)
+                    services.AddSingleton(cfg.Logger);
+
+                cfg.ConfigureServices?.Invoke(services);
+            };
+
+            if (System.Threading.Interlocked.CompareExchange(ref _staticConfigure, register, null) != null)
+                throw new InvalidOperationException("Static Provider is already built.");
+        }
+
         /// <summary>
         /// Configures and builds the static <see cref="IServiceProvider"/> for creating <see cref="ReCClient"/> instances.
         /// </summary>
@@ -110,17 +157,21 @@ namespace ReC.Client
         /// </remarks>
         /// <param name="apiUri">The base URI of the ReC API.</param>
         /// <param name="configureOptions">An optional callback to configure <see cref="ReCClientOptions"/>.</param>
+        /// <param name="logger">An optional <see cref="ILogger"/> instance to be used by the <see cref="ReCClient"/>. When provided, it is registered as a singleton in the internal service collection.</param>
         /// <exception cref="InvalidOperationException">Thrown if the static provider has already been built.</exception>
-        [Obsolete("Use a local service collection instead of the static provider.")]
+        [Obsolete("Use BuildStaticClient(Action<StaticBuildConfiguration>) instead.")]
 #if NETFRAMEWORK
-        public static void BuildStaticClient(string apiUri, Action<ReCClientOptions> configureOptions = null)
+        public static void BuildStaticClient(string apiUri, Action<ReCClientOptions> configureOptions = null, ILogger logger = null)
 #else
-        public static void BuildStaticClient(string apiUri, Action<ReCClientOptions>? configureOptions = null)
+        public static void BuildStaticClient(string apiUri, Action<ReCClientOptions>? configureOptions = null, ILogger<ReCClient>? logger = null)
 #endif
         {
-            Action<IServiceCollection> configure = services => services.AddRecClient(apiUri, configureOptions);
-            if (System.Threading.Interlocked.CompareExchange(ref _staticConfigure, configure, null) != null)
-                throw new InvalidOperationException("Static Provider is already built.");
+            BuildStaticClient(cfg =>
+            {
+                cfg.BaseAddress = apiUri;
+                cfg.ConfigureOptions = configureOptions;
+                cfg.Logger = logger;
+            });
         }
 
         /// <summary>
@@ -132,17 +183,21 @@ namespace ReC.Client
         /// </remarks>
         /// <param name="configureClient">An action to configure the <see cref="HttpClient"/>.</param>
         /// <param name="configureOptions">An optional callback to configure <see cref="ReCClientOptions"/>.</param>
+        /// <param name="logger">An optional <see cref="ILogger"/> instance to be used by the <see cref="ReCClient"/>. When provided, it is registered as a singleton in the internal service collection.</param>
         /// <exception cref="InvalidOperationException">Thrown if the static provider has already been built.</exception>
-        [Obsolete("Use a local service collection instead of the static provider.")]
+        [Obsolete("Use BuildStaticClient(Action<StaticBuildConfiguration>) instead.")]
 #if NETFRAMEWORK
-        public static void BuildStaticClient(Action<HttpClient> configureClient, Action<ReCClientOptions> configureOptions = null)
+        public static void BuildStaticClient(Action<HttpClient> configureClient, Action<ReCClientOptions> configureOptions = null, ILogger logger = null)
 #else
-        public static void BuildStaticClient(Action<HttpClient> configureClient, Action<ReCClientOptions>? configureOptions = null)
+        public static void BuildStaticClient(Action<HttpClient> configureClient, Action<ReCClientOptions>? configureOptions = null, ILogger<ReCClient>? logger = null)
 #endif
         {
-            Action<IServiceCollection> configure = services => services.AddRecClient(configureClient, configureOptions);
-            if (System.Threading.Interlocked.CompareExchange(ref _staticConfigure, configure, null) != null)
-                throw new InvalidOperationException("Static Provider is already built.");
+            BuildStaticClient(cfg =>
+            {
+                cfg.ConfigureClient = configureClient;
+                cfg.ConfigureOptions = configureOptions;
+                cfg.Logger = logger;
+            });
         }
 
         /// <summary>

src/ReC.Client/StaticBuildConfiguration.cs

@@ -0,0 +1,63 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using System;
+using System.Net.Http;
+
+namespace ReC.Client
+{
+    /// <summary>
+    /// Configuration object for <see cref="ReCClient.BuildStaticClient(Action{StaticBuildConfiguration})"/>.
+    /// Groups all optional settings for the static <see cref="ReCClient"/> bootstrap path.
+    /// </summary>
+    /// <remarks>
+    /// Either <see cref="BaseAddress"/> or <see cref="ConfigureClient"/> must be set; setting both at the same time is not allowed.
+    /// </remarks>
+    public class StaticBuildConfiguration
+    {
+        /// <summary>
+        /// Base URI of the ReC API. Mutually exclusive with <see cref="ConfigureClient"/>.
+        /// </summary>
+#if NETFRAMEWORK
+        public string BaseAddress { get; set; }
+#else
+        public string? BaseAddress { get; set; }
+#endif
+
+        /// <summary>
+        /// Callback that configures the underlying <see cref="HttpClient"/>. Mutually exclusive with <see cref="BaseAddress"/>.
+        /// </summary>
+#if NETFRAMEWORK
+        public Action<HttpClient> ConfigureClient { get; set; }
+#else
+        public Action<HttpClient>? ConfigureClient { get; set; }
+#endif
+
+        /// <summary>
+        /// Optional callback to configure <see cref="ReCClientOptions"/>.
+        /// </summary>
+#if NETFRAMEWORK
+        public Action<ReCClientOptions> ConfigureOptions { get; set; }
+#else
+        public Action<ReCClientOptions>? ConfigureOptions { get; set; }
+#endif
+
+        /// <summary>
+        /// Optional logger instance to be registered as a singleton in the internal service collection.
+        /// </summary>
+#if NETFRAMEWORK
+        public ILogger Logger { get; set; }
+#else
+        public ILogger<ReCClient>? Logger { get; set; }
+#endif
+
+        /// <summary>
+        /// Optional callback for additional service registrations on the internal <see cref="IServiceCollection"/>
+        /// (e.g. <c>services.AddLogging(...)</c> or custom dependencies).
+        /// </summary>
+#if NETFRAMEWORK
+        public Action<IServiceCollection> ConfigureServices { get; set; }
+#else
+        public Action<IServiceCollection>? ConfigureServices { get; set; }
+#endif
+    }
+}